BBC Micro cassette Elite | BBC Micro disc Elite | 6502 Second Processor Elite | BBC Master Elite | Acorn Electron Elite | NES Elite | Elite-A | Teletext Elite | Elite Universe Editor | Elite Compendium | Elite over Econet | Flicker-free Commodore 64 Elite | BBC Micro Aviator | BBC Micro Revs | Archimedes Lander
This repository contains source code for Lander on the Acorn Archimedes, with every single line documented and (for the most part) explained.
It is a companion to the lander.bbcelite.com website.
See the introduction for more information.
This repository contains source code for Lander on the Acorn Archimedes, with every single line documented and (for the most part) explained.
You can build the fully functioning game from this source. Two variants are currently supported: the Arthur variant, and the RISC OS 2 variant.
It is a companion to the lander.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 Lander 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 Lander from the source on a modern computer, to produce a working game disc that can be loaded into a Acorn Archimedes or an emulator, then you want the section on Building Lander from the source. You can also build the source on an Archimedes, as described in the the Archimedes section.
My hope is that this repository will be useful for those who want to learn more about Lander and what makes it tick. It is provided on an educational and non-profit basis, with the aim of helping people appreciate the magic of David Braben's 32-bit masterpiece, and the first ever game for the ARM platform.
Lander was written by David Braben and is copyright © D.J.Braben 1987.
The code on this site has been reconstructed from a disassembly of the version released on the application discs for Arthur and RISC OS.
The commentary is copyright © Mark Moxon. Any misunderstandings or mistakes in the documentation are entirely my fault.
This repository is not provided with a licence, and there is intentionally no LICENSE file provided.
According to GitHub's licensing documentation, 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".
The reason for this is that my commentary is intertwined with the original Lander game code, and the original game is copyright. The whole site is therefore covered by default copyright law, to ensure that this copyright is respected.
Under 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.
My 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 Acornsoft's games for the BBC Micro and Archimedes, it will remain viable.
If you want to browse the source in an IDE, you might find the following useful.
-
The most interesting files are in the main-sources folder:
-
The main game's source code is in the Lander.arm file - this is the motherlode and probably contains all the stuff you're interested in. It produces a file called
GameCodethat contains the entire game. -
The RISC OS application bundles up the game into a
!RunImage, whose source is in the RunImage.arm file. In the version on the RISC OS application disc the!RunImagebinary is encrypted, but in this version the game binary is simply wrapped in a relocation routine (though encryption may be added later).
-
-
It's probably worth skimming through the notes on terminology and notations 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.
-
The entry point for the main game code is routine
Entry, which you can find by searching forName: Entry. -
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 Lander as much as I have.
There are five main folders in this repository, which reflect the order of the build process.
-
1-source-files contains all the different source files, such as the main assembler source files, BASIC loaders, RISC OS application files and so on.
-
2-build-files contains build-related scripts, such as the crc32 verification scripts and vasm converter script.
-
3-assembled-output contains the output from the assembly process, when the source files are assembled and the results processed by the build files.
-
4-reference-binaries contains the correct binaries for each release, so we can verify that our assembled output matches the reference.
-
5-compiled-game-discs contains the final output of the build process: folders that contains the compiled game for each variant and which can be run on real hardware or in an emulator, plus zips of those folders for easier deployment. It also contains version of the source code that can be built on an Archimedes; see the Archimedes section for information on the latter. The Arthur variant contains the GameCode binary in two formats: as a pair of files (GameCode and GameCode.inf) that is suitable for programs that support inf files, or as a single file (GameCode,8000-A614) that will work with HostFS. Both options contain the load and execution address of the file, and you should choose the one that works for you when copying the game to your emulator or Archimedes.
This repository also includes a version of Lander with a much bigger landscape: 64 by 64 tiles, to be precise (as compared to the original 12 by 10 tiles). This version also runs on all versions of RISC OS (the original only works on Arthur and RISC OS 2). The big-landscape code is in a separate branch called big-landscape, and apart from the code differences for the landscape size and later versions of RISC OS, this branch is identical to the main branch and the same build process applies.
The landscape size is configurable. The default is 64 by 64 tiles (which equates to TILES_X = 65 and TILES_Z = 65), but you can set your own values by passing x and z parameters to the build. For example, building BigLander like this on Mac or Linux:
make x=122 z=122
or this on Windows:
make.bat x=122 z=122
would build BigLander with a landscape size of 121 x 121 tiles (i.e. TILES_X = 122 and TILES_Z = 122). The number of tiles is given in the !Help file of the generated application, along with the build date.
The annotated source files in the big-landscape branch contain both the original Lander code and all of the modifications for the bigger landscape, 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 big-landscape binaries, while still containing details of all the modifications. You can find all the diffs by searching the sources for Mod:.
BigLander should work on all versions of RISC OS, but to get it working on a Raspberry Pi, you may need to create a text file in the !Boot.Loader folder called CMDLINE/TXT, containing the word disable_mode_changes (reboot after you create this). Make sure you have !ADFFS loaded, and then BigLander should run. You can see a video guide to this process on YouTube.
If BigLander on your Pi is blurry, you can change the GPU upscaler method. Edit the CONFIG/TXT in !Boot.Loader and add scaling_kernel=8 on a new line before rebooting. This will probably make your desktop a bit messy, but BigLander should now look pretty great (and you can remove the line to go back to blurry BigLander and a crisp desktop).
For more information on BigLander, see the accompanying website.
Builds are supported for Windows and Mac/Linux systems. In all cases the build process is defined in the Makefile provided.
The build process also creates a version of the source that can be built on [Archimedes][#archimedes] machines.
You will need the following to build Lander from the source:
-
vasm, which can be downloaded from the vasm homepage.
-
Python. The build process has only been tested on 3.x, but 2.7 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).
Let's look at how to build Lander from the source.
For Windows users, there is a batch file called make.bat that builds the project. Before this will work, you should edit the batch file and change the values of the VASM and PYTHON variables to point to the locations of your vasmarm_std.exe and python.exe executables (you need the vasmarm_std executable). You also need to change directory to the repository folder (i.e. the same folder as make.bat).
All being well, entering the following into a command window:
make.bat
will produce folders called arthur and riscos in the 5-compiled-game-discs folder, which contain the Arthur and RISC OS variants of the game, which you can then load into an emulator, or into a real Acorn Archimedes using a device like a Gotek. It also produces a zip file for each variant, which can be found in the zip folder (note that these zips do not contain RISC OS filetype metadata; filetypes are included as filename suffixes, so they will work with HostFS).
The build process uses a standard GNU Makefile, so you just need to install make if your system doesn't already have it. If vasm or Python are not on your path, then you can either fix this, or you can edit the Makefile and change the VASM and PYTHON variables in the first two lines to point to their locations (you need the vasmarm_std executable). You also need to change directory to the repository folder (i.e. the same folder as Makefile).
All being well, entering the following into a terminal window:
make
will produce folders called arthur and riscos in the 5-compiled-game-discs folder, which contain the Arthur and RISC OS variants of the game, which you can then load into an emulator, or into a real Acorn Archimedes using a device like a Gotek. It also produces a zip file for each variant, which can be found in the zip folder (note that these zips do not contain RISC OS filetype metadata; filetypes are included as filename suffixes, so they will work with HostFS).
The build process outlined above produces a file called LanderSrc,fff in the 5-compiled-game-discs folder, or BLanderSrc,fff if you are building BigLander. These files contain versions of the game source that can be built on an Archimedes.
To build the source on an Archimedes, you first need to convert the BBC BASIC text file into tokenised BBC BASIC. If you have RISC OS 3, then you can use Edit to do this, as follows:
-
Download the source as a BBC BASIC text file for Lander or BigLander.
-
Copy the file to an Archimedes machine (if you aren't already downloading it in RISC OS).
-
If you are using HostFS then the filetype should be set automatically, but if you need to set it manually, it should be a Text file.
-
Load the text file into Edit. You should see the fully documented source code appear.
-
Click Menu on Edit's icon bar icon, choose "BASIC options > Line number increment" and set the value to 1.
-
Click Menu over Edit's window, choose "Misc > Set type" and set the value to BASIC.
-
Save the file, which is now a BASIC program.
You now have the Lander source in BBC BASIC, which is how David Braben originally wrote it (though without quite so many comments).
To build the game from this source, simply run the file by double-clicking it. It will assemble the game and save the GameCode file into the current directory, so you may want to set the current directory before doing this. You may need to allocate more memory to the Next slot for the assembly to work: you need at least 832K to build Lander, and at least 904K to build BigLander.
You can play the game by simply double-clicking on the GameCode file. You can run Lander on Arthur, RISC OS 2 or up to RISC OS 3.11, and you can run BigLander on any version of RISC OS. You may need to allocate more memory to the Next slot for the game to run: you need at least 168K to run Lander, and at least 400K to run BigLander.
Note that the main source code in this repository is very close to being in BBC BASIC format, but it isn't exactly the same (which is why the BBC BASIC version is created by the build process rather than actually being the main source). This is because BBC BASIC has some limitations that make it a tricky companion for large commentaries like this. For example, the colon character separates multiple statements in BBC BASIC, but this also applies within comments, so any comments that contain colons will cause runtime errors when used in BASIC. The same applies with unmatched brackets and double-quotes, though these only generate warnings (though they do break the Text to BASIC conversion process). BBC BASIC also doesn't support comma-separated EQU arguments, which makes laying out tables like the object blueprints rather difficult.
As a result the main source code in this repository is an homage to BBC BASIC's assembly language format, but it is not 100% accurate. That's why the build includes a conversion script to convert the Lander.arm source file into a working BBC BASIC source. See the convert-to-basic.py script for details.
The build process prints out checksums of all the generated files, along with the checksums of the files from the original sources.
The 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.
The binaries in the 4-reference-binaries folder are those extracted from the released version of the game, 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:
[--originals--] [---output----]
Checksum Size Checksum Size Match Filename
-----------------------------------------------------------
9985364c 39488 9985364c 39488 Yes !RunImage.bin
aa7f1052 39440 aa7f1052 39440 Yes GameCode.bin
All the compiled binaries match the originals, so we know we are producing the same final game for both the Arthur and RISC OS variants.
The !RunImage file in the RISC OS variant of Lander is encrypted. The 2-build-files/decrypt folder contains a script that decrypts the binary.
It turns out that the decrypted !RunImage is identical to the Arthur variant's GameCode binary, so the RISC OS variant is the exact same game, just encrypted. To prove this, I've written a Python script called lander-decrypt.py that decrypts the original !RunImage binary. This Python script is based on the original decryption routine, whose source is in lander-decrypt.arm.
The !RunImage produced by the build process doesn't include this encryption, and in its place there's a small routine that simply copies the game code to address &8000, without making any changes (you can see this in the main RunImage.arm source).
During 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).
Mark Moxon