This repository contains the original source code for Elite on the BBC Micro, with every single line documented and (for the most part) explained.
It is a companion to the bbcelite.com website, which contains all the code from this repository, but laid out in a much more human-friendly fashion.
-
If you want to browse the source and read about how Elite works under the hood, you will probably find the website is a better place to start than this repository.
-
If you would rather explore the source code in your favourite IDE, then the annotated source 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 for some tips.
-
If you want to build 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 Elite from the source.
My hope is that this repository and the accompanying website 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.
The original 1984 source code is copyright © Ian Bell and David Braben, and the code on this site is identical to the version released by the authors on Ian Bell's personal website (it's just been reformatted to be more readable).
The commentary is copyright © Mark Moxon. Any misunderstandings or mistakes in the documentation are entirely my fault.
Huge 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, which I forked as the original basis for this repository. You can find more information about this project in the accompanying website's project page.
The following archives from Ian Bell's site form the basis for this project:
If you want to browse the source in an IDE, you might find the following useful.
-
The most interesting files are in the sources folder:
-
The main game's source code is in the elite-source.asm file - this is the motherlode and probably contains all the stuff you're interested in
-
The game's loader is in the elite-loader.asm file - this is mainly concerned with setup and copy protection
-
-
It's probably worth skimming through the notes on terminology at the start of the elite-loader.asm file, 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)
-
The source code is peppered with a number of "deep dives", each of which goes into an aspect of the game in more detail. You can find deep dives in the source files by simply searching for
Deep dive: -
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: WorkspaceandType: Macro -
If you know the name of a routine, you can find it by searching for
Name: <name>, as inName: SCAN(for the 3D scanner routine) orName: LL9(for the ship-drawing routine) -
The entry point for the main game code is routine
TT170, which you can find by searching forName: 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 deep dive in theTT170routine that has you covered -
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
I hope you enjoy exploring the inner-workings of BBC Elite as much as I have.
You will need the following to build Elite from the source:
- BeebAsm, which can be downloaded from the BeebAsm repository. Mac and Linux users will have to build their own executable with
make code, while Windows users can just download thebeebasm.exefile. - Python. Both versions 2.7 and 3.x should work.
- Mac and Linux users may need to install
makeif it isn't already present (for Windows users,make.exeis included in this repository).
For details of how the build process works, see the build documentation on bbcelite.com.
Let's look at how to build Elite from the source.
There are two main build targets available. They are:
build- An unencrypted versionencrypt- An encrypted version that exactly matches the released version of the game
The unencrypted version should be more useful for anyone who wants to make modifications to the game code. It includes a default commander with lots of cash and equipment, which makes it easier to test the game. As this target produces unencrypted files, the binaries produced will be quite different to the binaries on the original source disc, which are encrypted.
The encrypted version produces the released version of Elite, along with the standard default commander.
(Note that there is a third build target, extract, which is explained in the section below on differences between the various source files.)
Builds are supported for both Windows and Mac/Linux systems. In all cases the build process is defined in the Makefile provided.
Note that the build ends with a warning that there is no SAVE command in the source file. You can ignore this, as the source file contains a PUTFILE command instead, but BeebAsm still reports this as a warning.
For Windows users, there is a batch file called make.bat to which you can pass one of the three build targets above. 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.exe).
All being well, doing one of the following:
make.bat build
make.bat encrypt
will produce a file called elite.ssd, which you can then load into an emulator, or into a real BBC Micro using a device like a Gotek.
The 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).
All being well, doing one of the following:
make build
make encrypt
will produce a file called elite.ssd, which you can then load into an emulator, or into a real BBC Micro using a device like a Gotek.
The build process also supports a verification target that prints out checksums of all the generated files, along with the checksums of the files extracted from the original sources.
You can run this verification step on its own, or you can run it once a build has finished. To run it on its own, use the following command on Windows:
make.bat verify
or on Mac/Linux:
make verify
To run a build and then verify the results, you can add two targets, like this on Windows:
make.bat encrypt verify
or this on Mac/Linux:
make encrypt verify
The Python script crc32.py 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).
The binaries in the extracted folder were taken straight from the cassette sources disc image (though see the notes on ELTB below), while those in the 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 encrypt verify, then this is the output of the verification process:
[--extracted--] [---output----]
Checksum Size Checksum Size Match Filename
-----------------------------------------------------------
a88ca82b 5426 a88ca82b 5426 Yes ELITE.bin
0f1ad255 2228 0f1ad255 2228 Yes ELTA.bin
e725760a 2600 e725760a 2600 Yes ELTB.bin
97e338e8 2735 97e338e8 2735 Yes ELTC.bin
322b174c 2882 322b174c 2882 Yes ELTD.bin
29f7b8cb 2663 29f7b8cb 2663 Yes ELTE.bin
8a4cecc2 2721 8a4cecc2 2721 Yes ELTF.bin
7a6a5d1a 2340 7a6a5d1a 2340 Yes ELTG.bin
01a00dce 20712 01a00dce 20712 Yes ELTcode.bin
99529ca8 256 99529ca8 256 Yes PYTHON.bin
49ee043c 2502 49ee043c 2502 Yes SHIPS.bin
c4547e5e 1023 c4547e5e 1023 Yes WORDS9.bin
* * f40816ec 5426 * ELITE.unprot.bin
* * 1e4466ec 20712 * ELTcode.unprot.bin
* * 00d5bb7a 40 * ELThead.bin
All the compiled binaries match the extracts, so we know we are producing the same final game as the release version.
During compilation, details of every step are output in a file called compile.txt in the 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).
It turns out that the cassette sources as text files do not contain identical code to the binaries in the cassette sources disc image. Specifically, there are some instructions in the ELTC binary that are different to the instructions in the ELITEC.TXT source file.
You can see these differences documented in the WARP routine in the elite-source.asm file. To find this, search the file for Name: WARP and follow the comments for mentions of ELITEC.TXT.
The instructions included in elite-source.asm are those that match the binary files rather than ELITEC.TXT, to ensure that the build process produces binaries that match the released version of the game.
It also turns out there are two versions of the ELITEB BASIC source program on the cassette sources disc image, 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:
EQUB (POW + 128) AND Q%
while in $.ELITEB, this byte is generated by:
EQUB POW
The 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.
The 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.
Given 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 released game, whose executable can be found as ELTcode on the same disc. The version of ELITEB in the cassette sources as text files matches this version, O.ELITEB.
In 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.
The ELTB binary file in the extracted folder of this repository is the release version, so we can easily tell whether any changes we've made to the code deviate from the release version. However, the ELTB binary file on the sources disc matches the version produced by $.ELITEB, rather than the released version produced by O.ELITEB - in other words, ELTB on the source disc is not the release version.
The implication is that the ELTB binary file on the cassette sources disc image 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.
To support this discrepancy, there is an extra build target for building the ELTB binary as found on the sources disc, and as produced by $.ELITEB. You can build this version, which has the rear pulse laser, with:
make extract
The ELTcode executable produced by this build target is different to the released version, because the default commander has the extra rear pulse laser. You can use the verify target to confirm this. Doing make encrypt verify shows that all the generated files match the extracted ones, while make extract verify shows that the all the generated files match the extracted ones except for ELTB and ELTcode.
Right on, Commanders!
Mark Moxon