{"id":13759262,"url":"https://github.com/markmoxon/elite-source-code-bbc-micro-cassette","last_synced_at":"2025-05-10T09:32:20.802Z","repository":{"id":117644440,"uuid":"267068104","full_name":"markmoxon/elite-source-code-bbc-micro-cassette","owner":"markmoxon","description":"Fully documented and annotated source code for the cassette version of Elite on the BBC Micro","archived":false,"fork":true,"pushed_at":"2025-04-27T16:18:10.000Z","size":13631,"stargazers_count":454,"open_issues_count":0,"forks_count":43,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-04-27T17:27:14.493Z","etag":null,"topics":["6502","6502-assembly","acornsoft","bbc","bbc-micro","bbcmicro","elite","retrocomputing","retrogaming"],"latest_commit_sha":null,"homepage":"https://elite.bbcelite.com/cassette/","language":"Assembly","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"kieranhj/elite-beebasm","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markmoxon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-05-26T14:37:29.000Z","updated_at":"2025-04-27T16:18:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/markmoxon/elite-source-code-bbc-micro-cassette","commit_stats":null,"previous_names":["markmoxon/elite-source-code-bbc-micro-cassette"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-bbc-micro-cassette","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-bbc-micro-cassette/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-bbc-micro-cassette/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmoxon%2Felite-source-code-bbc-micro-cassette/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmoxon","download_url":"https://codeload.github.com/markmoxon/elite-source-code-bbc-micro-cassette/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253396965,"owners_count":21901960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","6502-assembly","acornsoft","bbc","bbc-micro","bbcmicro","elite","retrocomputing","retrogaming"],"created_at":"2024-08-03T13:00:49.823Z","updated_at":"2025-05-10T09:32:20.788Z","avatar_url":"https://github.com/markmoxon.png","language":"Assembly","funding_links":[],"categories":["Assembly"],"sub_categories":[],"readme":"# Fully documented source code for the cassette version of Elite on the BBC Micro\n\n**BBC Micro cassette Elite** | [BBC Micro disc Elite](https://github.com/markmoxon/elite-source-code-bbc-micro-disc) | [Acorn Electron Elite](https://github.com/markmoxon/elite-source-code-acorn-electron) | [6502 Second Processor Elite](https://github.com/markmoxon/elite-source-code-6502-second-processor) | [Commodore 64 Elite](https://github.com/markmoxon/elite-source-code-commodore-64) | [Apple II Elite](https://github.com/markmoxon/elite-source-code-apple-ii) | [BBC Master Elite](https://github.com/markmoxon/elite-source-code-bbc-master) | [NES Elite](https://github.com/markmoxon/elite-source-code-nes) | [Elite-A](https://github.com/markmoxon/elite-a-source-code-bbc-micro) | [Teletext Elite](https://github.com/markmoxon/teletext-elite) | [Elite Universe Editor](https://github.com/markmoxon/elite-universe-editor) | [Elite Compendium (BBC Master)](https://github.com/markmoxon/elite-compendium-bbc-master) | [Elite Compendium (BBC Micro)](https://github.com/markmoxon/elite-compendium-bbc-micro) | [Elite over Econet](https://github.com/markmoxon/elite-over-econet) | [!EliteNet](https://github.com/markmoxon/elite-over-econet-acorn-archimedes) | [Flicker-free Commodore 64 Elite](https://github.com/markmoxon/c64-elite-flicker-free) | [BBC Micro Aviator](https://github.com/markmoxon/aviator-source-code-bbc-micro) | [BBC Micro Revs](https://github.com/markmoxon/revs-source-code-bbc-micro) | [Archimedes Lander](https://github.com/markmoxon/lander-source-code-acorn-archimedes)\n\n![Screenshot of Elite on the BBC Micro](https://elite.bbcelite.com/images/github/Elite-BBCMicro.png)\n\nThis repository contains the original source code for the cassette version of Elite on the BBC Micro, with every single line documented and (for the most part) explained. It is literally the original source code, just heavily commented.\n\nIt is a companion to the [elite.bbcelite.com website](https://elite.bbcelite.com).\n\nSee the [introduction](#introduction) for more information, or jump straight into the [documented source code](1-source-files/main-sources).\n\n## Contents\n\n* [Introduction](#introduction)\n\n* [Acknowledgements](#acknowledgements)\n\n  * [A note on licences, copyright etc.](#user-content-a-note-on-licences-copyright-etc)\n\n* [Browsing the source in an IDE](#browsing-the-source-in-an-ide)\n\n* [Folder structure](#folder-structure)\n\n* [Flicker-free Elite](#flicker-free-elite)\n\n* [Elite Compendium](#elite-compendium)\n\n* [Building BBC Micro cassette Elite from the source](#building-bbc-micro-cassette-elite-from-the-source)\n\n  * [Requirements](#requirements)\n  * [Windows](#windows)\n  * [Mac and Linux](#mac-and-linux)\n  * [Build options](#build-options)\n  * [Updating the checksum scripts if you change the code](#updating-the-checksum-scripts-if-you-change-the-code)\n  * [Verifying the output](#verifying-the-output)\n  * [Log files](#log-files)\n  * [Auto-deploying to the b2 emulator](#auto-deploying-to-the-b2-emulator)\n  * [Building a UEF tape image](#building-a-uef-tape-image)\n\n* [Building different variants of the cassette version of Elite](#building-different-variants-of-the-cassette-version-of-elite)\n\n  * [Building the Stairway to Hell variant](#building-the-stairway-to-hell-variant)\n  * [Building the source disc variant](#building-the-source-disc-variant)\n  * [Building the text sources variant](#building-the-text-sources-variant)\n  * [Differences between the variants](#differences-between-the-variants)\n\n* [Notes on the original source files](#notes-on-the-original-source-files)\n\n  * [Fixing a bug in the source disc](#fixing-a-bug-in-the-source-disc)\n\n## Introduction\n\nThis repository contains the original source code for the cassette version of Elite on the BBC Micro, with every single line documented and (for the most part) explained.\n\nYou can build the fully functioning game from this source. [Three variants](#building-different-variants-of-the-cassette-version-of-elite) are currently supported: the tape version from the Stairway to Hell archive, the version produced by the original source discs from Ian Bell's personal website, and the version built from the text sources from the same site.\n\nThis repository is a companion to the [elite.bbcelite.com website](https://elite.bbcelite.com), which contains all the code from this repository, but laid out in a much more human-friendly fashion. The links at the top of this page will take you to repositories for the other versions of Elite that are covered by this project.\n\n* If you want to browse the source and read about how Elite works under the hood, you will probably find [the website](https://elite.bbcelite.com) a better place to start than this repository.\n\n* If you would rather explore the source code in your favourite IDE, then the [annotated source](1-source-files/main-sources) is what you're looking for. It contains the exact same content as the website, so you won't be missing out (the website is generated from the source files, so they are guaranteed to be identical). You might also like to read the section on [browsing the source in an IDE](#browsing-the-source-in-an-ide) for some tips.\n\n* If you want to build BBC Micro cassette Elite from the source on a modern computer, to produce a working game disc that can be loaded into a BBC Micro or an emulator, then you want the section on [building BBC Micro cassette Elite from the source](#building-bbc-micro-cassette-elite-from-the-source).\n\nMy hope is that this repository and the [accompanying website](https://elite.bbcelite.com) will be useful for those who want to learn more about Elite and what makes it tick. It is provided on an educational and non-profit basis, with the aim of helping people appreciate one of the most iconic games of the 8-bit era.\n\n## Acknowledgements\n\nBBC Micro Elite was written by Ian Bell and David Braben and is copyright \u0026copy; Acornsoft 1984.\n\nThe code on this site is identical to the source discs released on [Ian Bell's personal website](http://www.elitehomepage.org/) (it's just been reformatted to be more readable).\n\nThe commentary is copyright \u0026copy; Mark Moxon. Any misunderstandings or mistakes in the documentation are entirely my fault.\n\nHuge thanks are due to the original authors for not only creating such an important piece of my childhood, but also for releasing the source code for us to play with; to Paul Brink for his annotated disassembly; and to Kieran Connell for his [BeebAsm version](https://github.com/kieranhj/elite-beebasm), which I forked as the original basis for this project. You can find more information about this project in the [accompanying website's project page](https://elite.bbcelite.com/about_site/about_this_project.html).\n\nThank you to Diminished for the UEF scripts, which are part of the [Quadbike 2](https://stardot.org.uk/forums/viewtopic.php?t=26669) tape transcriber.\n\nThe following archives from Ian Bell's personal website form the basis for this project:\n\n* [BBC Micro cassette Elite sources as a disc image](http://www.elitehomepage.org/archive/a/a4080602.zip)\n* [BBC Micro cassette Elite sources as text files](http://www.elitehomepage.org/archive/a/a4080610.zip)\n\n### A note on licences, copyright etc.\n\nThis repository is _not_ provided with a licence, and there is intentionally no `LICENSE` file provided.\n\nAccording to [GitHub's licensing documentation](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/licensing-a-repository), this means that \"the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work\".\n\nThe reason for this is that my commentary is intertwined with the original Elite source code, and the original source code is copyright. The whole site is therefore covered by default copyright law, to ensure that this copyright is respected.\n\nUnder GitHub's rules, you have the right to read and fork this repository... but that's it. No other use is permitted, I'm afraid.\n\nMy hope is that the educational and non-profit intentions of this repository will enable it to stay hosted and available, but the original copyright holders do have the right to ask for it to be taken down, in which case I will comply without hesitation. I do hope, though, that along with the various other disassemblies and commentaries of this source, it will remain viable.\n\n## Browsing the source in an IDE\n\nIf you want to browse the source in an IDE, you might find the following useful.\n\n* The most interesting files are in the [main-sources](1-source-files/main-sources) folder:\n\n  * The main game's source code is in the [elite-source.asm](1-source-files/main-sources/elite-source.asm) file - this is the motherlode and probably contains all the stuff you're interested in.\n\n  * The game's loader is in the [elite-loader.asm](1-source-files/main-sources/elite-loader.asm) file - this is mainly concerned with setup and copy protection.\n\n* It's probably worth skimming through the [notes on terminology and notations](https://elite.bbcelite.com/terminology/) on the accompanying website, as this explains a number of terms used in the commentary, without which it might be a bit tricky to follow at times (in particular, you should understand the terminology I use for multi-byte numbers).\n\n* The accompanying website contains [a number of \"deep dive\" articles](https://elite.bbcelite.com/deep_dives/), each of which goes into an aspect of the game in detail. Routines that are explained further in these articles are tagged with the label `Deep dive:` and the relevant article name.\n\n* There are loads of routines and variables in Elite - literally hundreds. You can find them in the source files by searching for the following: `Type: Subroutine`, `Type: Variable`, `Type: Workspace` and `Type: Macro`.\n\n* If you know the name of a routine, you can find it by searching for `Name: \u003cname\u003e`, as in `Name: SCAN` (for the 3D scanner routine) or `Name: LL9` (for the ship-drawing routine).\n\n* The entry point for the [main game code](1-source-files/main-sources/elite-source.asm) is routine `TT170`, which you can find by searching for `Name: TT170`. If you want to follow the program flow all the way from the title screen around the main game loop, then you can find a number of [deep dives on program flow](https://elite.bbcelite.com/deep_dives/) on the accompanying website.\n\n* The source code is designed to be read at an 80-column width and with a monospaced font, just like in the good old days.\n\nI hope you enjoy exploring the inner workings of BBC Elite as much as I have.\n\n## Folder structure\n\nThere are five main folders in this repository, which reflect the order of the build process.\n\n* [1-source-files](1-source-files) contains all the different source files, such as the main assembler source files, image binaries, fonts, boot files and so on.\n\n* [2-build-files](2-build-files) contains build-related scripts, such as the checksum, encryption and crc32 verification scripts.\n\n* [3-assembled-output](3-assembled-output) contains the output from the assembly process, when the source files are assembled and the results processed by the build files.\n\n* [4-reference-binaries](4-reference-binaries) contains the correct binaries for each variant, so we can verify that our assembled output matches the reference.\n\n* [5-compiled-game-discs](5-compiled-game-discs) contains the final output of the build process: an SSD disc image that contains the compiled game and which can be run on real hardware or in an emulator.\n\n## Flicker-free Elite\n\nThis repository also includes a flicker-free version, which incorporates the backported flicker-free ship-drawing routines from the BBC Master. The flicker-free code is in a separate branch called `flicker-free`, and apart from the code differences for reducing flicker, this branch is identical to the main branch and the same build process applies.\n\nThe annotated source files in the `flicker-free` branch contain both the original Acornsoft code and all of the modifications for flicker-free Elite, so you can look through the source to see exactly what's changed. Any code that I've removed from the original version is commented out in the source files, so when they are assembled they produce the flicker-free binaries, while still containing details of all the modifications. You can find all the diffs by searching the sources for `Mod:`.\n\nFor more information on flicker-free Elite, see the [hacks section of the accompanying website](https://elite.bbcelite.com/hacks/flicker-free_elite.html).\n\n## Elite Compendium\n\nThis repository also includes a version of BBC Micro cassette Elite for the Elite Compendium, which incorporates all the available hacks in one game. The Compendium version is in a separate branch called `elite-compendium`, which is included in the [Elite Compendium (BBC Micro)](https://github.com/markmoxon/elite-compendium-bbc-micro) repository as a submodule.\n\nThe annotated source files in the `elite-compendium` branch contain both the original Acornsoft code and all of the modifications for the Elite Compendium, so you can look through the source to see exactly what's changed. Any code that I've removed from the original version is commented out in the source files, so when they are assembled they produce the Compendium binaries, while still containing details of all the modifications. You can find all the diffs by searching the sources for `Mod:`.\n\nFor more information on the Elite Compendium, see the [hacks section of the accompanying website](https://elite.bbcelite.com/hacks/elite_compendium.html).\n\n## Building BBC Micro cassette Elite from the source\n\nBuilds are supported for both Windows and Mac/Linux systems. In all cases the build process is defined in the `Makefile` provided.\n\n### Requirements\n\nYou will need the following to build BBC Micro cassette Elite from the source:\n\n* BeebAsm, which can be downloaded from the [BeebAsm repository](https://github.com/stardot/beebasm). Mac and Linux users will have to build their own executable with `make code`, while Windows users can just download the `beebasm.exe` file.\n\n* Python. The build process has only been tested on 3.x, but 2.7 might work.\n\n* Mac and Linux users may need to install `make` if it isn't already present (for Windows users, `make.exe` is included in this repository).\n\nFor details of how the build process works, see the [build documentation on bbcelite.com](https://elite.bbcelite.com/about_site/building_elite.html).\n\nLet's look at how to build BBC Micro cassette Elite from the source.\n\n### Windows\n\nFor Windows users, there is a batch file called `make.bat` which you can use to build the game. Before this will work, you should edit the batch file and change the values of the `BEEBASM` and `PYTHON` variables to point to the locations of your `beebasm.exe` and `python.exe` executables. You also need to change directory to the repository folder (i.e. the same folder as `make.bat`).\n\nAll being well, entering the following into a command window:\n\n```\nmake.bat\n```\n\nwill produce a file called `elite-cassette-sth.ssd` in the `5-compiled-game-discs` folder that contains the source disc variant, which you can then load into an emulator, or into a real BBC Micro using a device like a Gotek.\n\n### Mac and Linux\n\nThe build process uses a standard GNU `Makefile`, so you just need to install `make` if your system doesn't already have it. If BeebAsm or Python are not on your path, then you can either fix this, or you can edit the `Makefile` and change the `BEEBASM` and `PYTHON` variables in the first two lines to point to their locations. You also need to change directory to the repository folder (i.e. the same folder as `Makefile`).\n\nAll being well, entering the following into a terminal window:\n\n```\nmake\n```\n\nwill produce a file called `elite-cassette-sth.ssd` in the `5-compiled-game-discs` folder that contains the source disc variant, which you can then load into an emulator, or into a real BBC Micro using a device like a Gotek.\n\n### Build options\n\nBy default the build process will create a typical Elite game disc with a standard commander and verified binaries. There are various arguments you can pass to the build to change how it works. They are:\n\n* `variant=\u003cname\u003e` - Build the specified variant:\n\n  * `variant=sth` (default)\n  * `variant=source-disc`\n  * `variant=text-sources`\n\n* `disc=no` - Build a version to load from cassette rather than disc (the default is to build a version that loads from disc)\n\n* `protect=no` - When building for cassette with `disc=no`, the loader contains block-level tape protection code, which you can disable with this argument (the protection only works if you save the ELITEcode file to tape with corrupted block data, so if you want to create a UEF without re-implementing the Acornsoft protection system, you should use this argument)\n\n* `commander=max` - Start with a maxed-out commander (specifically, this is the test commander file from the original source, which is almost but not quite maxed-out)\n\n* `encrypt=no` - Disable encryption and checksum routines\n\n* `verify=no` - Disable crc32 verification of the game binaries\n\nSo, for example:\n\n`make variant=text-sources commander=max encrypt=no match=no verify=no`\n\nwill build an unencrypted text sources variant with a maxed-out commander, no workspace noise and no crc32 verification.\n\nThe unencrypted version should be more useful for anyone who wants to make modifications to the game code. As this argument produces unencrypted files, the binaries produced will be quite different to the binaries on the original source disc, which are encrypted.\n\nSee below for more on the verification process.\n\n### Updating the checksum scripts if you change the code\n\nIf you change the source code in any way, you may break the game; if so, it will typically hang at the loading screen, though in some versions it may hang when launching from the space station.\n\nTo fix this, you may need to update some of the hard-coded addresses in the checksum script so that they match the new addresses in your changed version of the code. See the comments in the [elite-checksum.py](2-build-files/elite-checksum.py) script for details.\n\n### Verifying the output\n\nThe default build process prints out checksums of all the generated files, along with the checksums of the files from the original sources. You can disable verification by passing `verify=no` to the build.\n\nThe Python script `crc32.py` in the `2-build-files` folder does the actual verification, and shows the checksums and file sizes of both sets of files, alongside each other, and with a Match column that flags any discrepancies. If you are building an unencrypted set of files then there will be lots of differences, while the encrypted files should mostly match (see the Differences section below for more on this).\n\nThe binaries in the `4-reference-binaries` folder were taken straight from the [cassette sources disc image](http://www.elitehomepage.org/archive/a/a4080602.zip), while those in the `3-assembled-output` folder are produced by the build process. For example, if you don't make any changes to the code and build the project with `make`, then this is the output of the verification process:\n\n```\nResults for variant: sth\n[--originals--]  [---output----]\nChecksum   Size  Checksum   Size  Match  Filename\n-----------------------------------------------------------\na88ca82b   5426  a88ca82b   5426   Yes   ELITE.bin\nf40816ec   5426  f40816ec   5426   Yes   ELITE.unprot.bin\nb17f9589   2228  b17f9589   2228   Yes   ELTA.bin\n82de44f7   2600  82de44f7   2600   Yes   ELTB.bin\nf005a7bf   2732  f005a7bf   2732   Yes   ELTC.bin\nac3476d9   2887  ac3476d9   2887   Yes   ELTD.bin\n3084f112   2663  3084f112   2663   Yes   ELTE.bin\ne46bac22   2719  e46bac22   2719   Yes   ELTF.bin\nb4ac917d   2340  b4ac917d   2340   Yes   ELTG.bin\nb1bf493e  20712  b1bf493e  20712   Yes   ELTcode.bin\n33de34f5  20712  33de34f5  20712   Yes   ELTcode.unprot.bin\n00d5bb7a     40  00d5bb7a     40   Yes   ELThead.bin\n99529ca8    256  99529ca8    256   Yes   PYTHON.bin\n49ee043c   2502  49ee043c   2502   Yes   SHIPS.bin\nc4547e5e   1023  c4547e5e   1023   Yes   WORDS9.bin\n```\n\nAll the compiled binaries match the originals, so we know we are producing the same final game as the Stairway to Hell variant.\n\n### Log files\n\nDuring compilation, details of every step are output in a file called `compile.txt` in the `3-assembled-output` folder. If you have problems, it might come in handy, and it's a great reference if you need to know the addresses of labels and variables for debugging (or just snooping around).\n\n### Auto-deploying to the b2 emulator\n\nFor users of the excellent [b2 emulator](https://github.com/tom-seddon/b2), you can include the build parameter `b2` to automatically load and boot the assembled disc image in b2. The b2 emulator must be running for this to work.\n\nFor example, to build, verify and load the game into b2, you can do this on Windows:\n\n```\nmake.bat all b2\n```\n\nor this on Mac/Linux:\n\n```\nmake all b2\n```\n\nIf you omit the `all` target then b2 will start up with the results of the last successful build.\n\nNote that you should manually choose the correct platform in b2 (I intentionally haven't automated this part to make it easier to test across multiple platforms).\n\n### Building a UEF tape image\n\nDespite this being the cassette version of BBC Micro Elite, this repository only builds disc images by default, as that's how BeebAsm works. If you want the authentic experience of loading Elite from cassette, then you can build a UEF with the following command on Windows:\n\n```\nmake.bat uef disc=no protect=no\n```\n\nor this on Mac/Linux:\n\n```\nmake uef disc=no protect=no\n```\n\nYou should now be able to load Elite from your UEF on a BBC Micro, by entering `CHAIN \"ELITE\"`. These UEF tape images will work with emulators and the TZXDuino (though you may need to unzip them before they will work with the latter).\n\nFor this to work, you will need PHP installed, and you should edit the `Makefile` (and `make.bat` on Windows) to point to PHP (specifically, you'll need to point the `PHP` variable to point to the locations of your `php` or `php.exe` binary).\n\nNote that in order for your UEF to work, you need to include the `disc=no` and `protect=no` arguments to the build (as above). This ensures that the binaries are built to load at the correct address for tape systems, and it also disables the block-level tape protection system, as this only works with specially created tape images, like the ones that Acornsoft originally released.\n\n## Building different variants of the cassette version of Elite\n\nThis repository contains the source code for three different variants of the cassette version of Elite:\n\n* The variant from the Stairway to Hell archive\n\n* The variant produced by the original source discs from Ian Bell's personal website\n\n* The variant built from the text sources from the same site\n\nBy default the build process builds the Stairway to Hell variant, but you can build a specified variant using the `variant=` build parameter.\n\n### Building the Stairway to Hell variant\n\nYou can add `variant=source-disc` to produce the `elite-cassette-from-source-disc.ssd` file containing the source disc variant, though that's the default value so it isn't necessary. In other words, you can build it like this:\n\n```\nmake.bat variant=sth\n```\n\nor this on a Mac or Linux:\n\n```\nmake variant=sth\n```\n\nThis will produce a file called `elite-cassette-sth.ssd` in the `5-compiled-game-discs` folder that contains the Stairway to Hell variant.\n\nThe verification checksums for this version are as follows:\n\n```\nResults for variant: sth\n[--originals--]  [---output----]\nChecksum   Size  Checksum   Size  Match  Filename\n-----------------------------------------------------------\na88ca82b   5426  a88ca82b   5426   Yes   ELITE.bin\nf40816ec   5426  f40816ec   5426   Yes   ELITE.unprot.bin\nb17f9589   2228  b17f9589   2228   Yes   ELTA.bin\n82de44f7   2600  82de44f7   2600   Yes   ELTB.bin\nf005a7bf   2732  f005a7bf   2732   Yes   ELTC.bin\nac3476d9   2887  ac3476d9   2887   Yes   ELTD.bin\n3084f112   2663  3084f112   2663   Yes   ELTE.bin\ne46bac22   2719  e46bac22   2719   Yes   ELTF.bin\nb4ac917d   2340  b4ac917d   2340   Yes   ELTG.bin\nb1bf493e  20712  b1bf493e  20712   Yes   ELTcode.bin\n33de34f5  20712  33de34f5  20712   Yes   ELTcode.unprot.bin\n00d5bb7a     40  00d5bb7a     40   Yes   ELThead.bin\n99529ca8    256  99529ca8    256   Yes   PYTHON.bin\n49ee043c   2502  49ee043c   2502   Yes   SHIPS.bin\nc4547e5e   1023  c4547e5e   1023   Yes   WORDS9.bin\n```\n\nNote that if you add the `disc=no` build parameter, then the build will produce binaries that are designed to be loaded from cassette rather than disc. The verification step will compare the results to the exact binaries from the UEF from the Stairway to Hell archive. These binaries have block-level tape protection enabled by default, so they will not match. You can override the block-level protection with `protect=no`.\n\n### Building the source disc variant\n\nYou can build the source disc variant by appending `variant=source-disc` to the `make` command, like this on Windows:\n\n```\nmake.bat variant=source-disc\n```\n\nor this on a Mac or Linux:\n\n```\nmake variant=source-disc\n```\n\nThis will produce a file called `elite-cassette-from-source-disc.ssd` in the `5-compiled-game-discs` folder that contains the source disc variant.\n\nThe verification checksums for this version are as follows:\n\n```\nResults for variant: source-disc\n[--originals--]  [---output----]\nChecksum   Size  Checksum   Size  Match  Filename\n-----------------------------------------------------------\na88ca82b   5426  a88ca82b   5426   Yes   ELITE.bin\nf40816ec   5426  f40816ec   5426   Yes   ELITE.unprot.bin\n0f1ad255   2228  0f1ad255   2228   Yes   ELTA.bin\ne725760a   2600  e725760a   2600   Yes   ELTB.bin\n97e338e8   2735  97e338e8   2735   Yes   ELTC.bin\n322b174c   2882  322b174c   2882   Yes   ELTD.bin\n29f7b8cb   2663  29f7b8cb   2663   Yes   ELTE.bin\n8a4cecc2   2721  8a4cecc2   2721   Yes   ELTF.bin\n7a6a5d1a   2340  7a6a5d1a   2340   Yes   ELTG.bin\n01a00dce  20712  01a00dce  20712   Yes   ELTcode.bin\n1e4466ec  20712  1e4466ec  20712   Yes   ELTcode.unprot.bin\n00d5bb7a     40  00d5bb7a     40   Yes   ELThead.bin\n99529ca8    256  99529ca8    256   Yes   PYTHON.bin\n49ee043c   2502  49ee043c   2502   Yes   SHIPS.bin\nc4547e5e   1023  c4547e5e   1023   Yes   WORDS9.bin\n```\n\n### Building the text sources variant\n\nYou can build the text sources variant by appending `variant=text-sources` to the `make` command, like this on Windows:\n\n```\nmake.bat variant=text-sources\n```\n\nor this on a Mac or Linux:\n\n```\nmake variant=text-sources\n```\n\nThis will produce a file called `elite-cassette-from-text-sources.ssd` in the `5-compiled-game-discs` folder that contains the Ian Bell disc variant.\n\nThe verification checksums for this version are as follows:\n\n```\nResults for variant: text-sources\n[--originals--]  [---output----]\nChecksum   Size  Checksum   Size  Match  Filename\n-----------------------------------------------------------\n093c73aa   5426  093c73aa   5426   Yes   ELITE.bin\n24da3246   5426  24da3246   5426   Yes   ELITE.unprot.bin\n6c109c76   2228  6c109c76   2228   Yes   ELTA.bin\ncd8bee0c   2600  cd8bee0c   2600   Yes   ELTB.bin\n20c22628   2732  20c22628   2732   Yes   ELTC.bin\n23c13c71   2885  23c13c71   2885   Yes   ELTD.bin\nce0d9ec7   2663  ce0d9ec7   2663   Yes   ELTE.bin\n5aed3c61   2719  5aed3c61   2719   Yes   ELTF.bin\n13f3eace   2340  13f3eace   2340   Yes   ELTG.bin\n8b79fe39  20710  8b79fe39  20710   Yes   ELTcode.bin\n7c24aab0  20712  7c24aab0  20712   Yes   ELTcode.unprot.bin\n00d5bb7a     40  00d5bb7a     40   Yes   ELThead.bin\n99529ca8    256  99529ca8    256   Yes   PYTHON.bin\n8f4b6f2b   2502  8f4b6f2b   2502   Yes   SHIPS.bin\nc4547e5e   1023  c4547e5e   1023   Yes   WORDS9.bin\n```\n\n### Differences between the variants\n\nYou can see the differences between the variants by searching the source code for `_STH_CASSETTE` (for features in the Stairway to Hell variant), `_SOURCE_DISC` (for features in the source disc variant) or `_TEXT_SOURCES` (for features in the text sources variant). There are only minor differences:\n\n* The text sources contain an extra call in the galactic hyperspace routine that sets the current system to the nearest system to the crosshairs, in an attempt to fix a bug in the original source disc variant (though it doesn't quite fix it properly).\n\n* The Stairway to Hell variant contains the extra call in the galactic hyperspace routine, but in a different place, and it also zeroes the distance to the current system in QQ8. This fixes the galactic hyperspace bug properly, and this full bug fix is present in all other versions of the game.\n\n* In order to fit in this extra call, the text sources and Stairway to Hell variants also contain modifications to create space for the call.\n\n* There is a small change in the TTX66 routine to reset LAS2 to 0 instead of LASCT to stop laser pulsing, as this is slightly more efficient.\n\nSee the [accompanying website](https://elite.bbcelite.com/cassette/releases.html) for a comprehensive list of differences between the variants.\n\n## Notes on the original source files\n\n### Fixing a bug in the source disc\n\nIt also turns out there are two versions of the `ELITEB` BASIC source program on the [cassette sources disc image](http://www.elitehomepage.org/archive/a/a4080602.zip), one called `$.ELITEB` and another called `O.ELITEB`. These two versions of `ELITEB` differ by just one byte in the default commander data. This byte controls whether or not the commander has a rear pulse laser. In `O.ELITEB` this byte is generated by:\n\n```\nEQUB (POW + 128) AND Q%\n```\n\nwhile in `$.ELITEB`, this byte is generated by:\n\n```\nEQUB POW\n```\n\nThe BASIC variable `Q%` is a Boolean flag that, if `TRUE`, will create a default commander with lots of cash and equipment, which is useful for testing. You can see this in action if you build an unencrypted binary with `make build`, as the unencrypted build sets `Q%` to `TRUE` for this build target.\n\nThe BASIC variable `POW` has a value of 15, which is the power of a pulse laser. `POW + 128`, meanwhile, is the power of a beam laser.\n\nGiven the above, we can see that `O.ELITEB` correctly produces a default commander with no a rear laser if `Q%` is `FALSE`, but adds a rear beam laser if `Q%` is `TRUE`. This matches the default commander from the released game, and produces the `ELTcode` executable on the same disc. The version of `ELITEB` in the [cassette sources as text files](http://www.elitehomepage.org/archive/a/a4080610.zip) matches this version, `O.ELITEB`.\n\nIn contrast, `$.ELITEB` will always produce a default commander with a rear pulse laser, irrespective of the setting of `Q%`, so it doesn't match the released version.\n\nThe `ELTB` binary file in the `4-reference-binaries` folder of this repository matches the version generated by the source disc, so we can easily tell whether any changes we've made to the code deviate from this version. However, the `ELTB` binary file on the sources disc matches the version produced by `$.ELITEB`, rather than the version produced by `O.ELITEB` - in other words, `ELTB` on the source disc is not the version generated by the source code on the same disc.\n\nThe implication is that the `ELTB` binary file on the [cassette sources disc image](http://www.elitehomepage.org/archive/a/a4080602.zip) was produced by `$.ELITEB`, while the `ELTcode` file (the released game) used `O.ELITEB`. Perhaps the released game was compiled, and then someone backed up the `ELITEB` source to `O.ELITEB`, edited the `$.ELITEB` to have a rear pulse laser, and then generated a new `ELTB` binary file. Who knows? Unfortunately, files on DFS discs don't have timestamps, so it's hard to tell.\n\n---\n\nRight on, Commanders!\n\n_Mark Moxon_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmoxon%2Felite-source-code-bbc-micro-cassette","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmoxon%2Felite-source-code-bbc-micro-cassette","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmoxon%2Felite-source-code-bbc-micro-cassette/lists"}