Elite Universe Editor

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 (BBC Master) | Elite Compendium (BBC Micro) | Elite over Econet | Flicker-free Commodore 64 Elite | BBC Micro Aviator | BBC Micro Revs | Archimedes Lander

This repository collects together the source code for the Elite Universe Editor on the BBC Master, the BBC Micro with a 6502 Second Processor and the Commodore 64.

The Elite Universe Editor allows you to create your own universes in classic BBC Micro and Commodore 64 Elite. For more information, see the bbcelite.com website.

This repository builds the Universe Editor by pulling in the source code from various submodules:

• Elite Universe Editor Library
• BBC Master Elite Universe Editor
• 6502 Second Processor Elite Universe Editor
• Commodore 64 Elite Universe Editor

Contents

• Acknowledgements

  • A note on licences, copyright etc.

• Browsing the source in an IDE

• Folder structure

• Building the Elite Universe Editor from the source

  • Requirements
  • Windows
  • Mac and Linux

• The Commodore 64 patching process

Acknowledgements

6502 Second Processor Elite was written by Ian Bell and David Braben and is copyright © Acornsoft 1985.

The 6502 Second Processor code on this site is identical to the source discs released on Ian Bell's personal website (it's just been reformatted to be more readable).

BBC Master Elite was written by Ian Bell and David Braben and is copyright © Acornsoft 1986.

The BBC Master code on this site has been reconstructed from a disassembly of the version released on Ian Bell's personal website.

Commodore 64 Elite was written by Ian Bell and David Braben and published by Firebird, and is copyright © D. Braben and I. Bell 1985.

The code in the Commodore 64 flicker-free patch was reconstructed from a disassembly of the BBC Master version released on Ian Bell's personal website.

The Commodore 64 game disks in this repository are very similar to those released on Ian Bell's personal website, but to ensure accuracy to the released versions, I've used disk images from the Commodore 64 Preservation Project (it turns out that the disk images on Ian Bell's site differ slightly from the official versions). The Commodore Plus/4 version is based on the disk image from Ian Bell's site.

The commentary and Universe Editor code 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 project. You can find more information about this project in the accompanying website's project page.

Also, a big thumbs up to Kroc Camen for his epic Elite Harmless project, which is a really useful reference for anyone exploring the C64 binaries. Finally, thanks to the gurus in this Lemon64 forum thread for their sage advice.

The following archives from Ian Bell's personal website form the basis for this project:

• 6502 Second Processor sources as a disc image

• BBC Elite, Master version

A note on licences, copyright etc.

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 the Universe Editor 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.

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 this source, it will remain viable.

Browsing the source in an IDE

If you want to browse the source in an IDE, you might find the following useful.

• The Universe Editor code is in the main-sources folder in the library submodule. It is split up into multiple files to enable it to be squeezed into the different versions of Elite (which have different memory maps and different amounts of free space).

• 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 (in particular, you should understand the terminology I use for multi-byte numbers).

• The source code for the main Elite game (which the Universe Editor modifies) is in the 6502sp-elite-universe-editor and master-elite-universe-editor submodules. The annotated source files in these folders contain both the original Acornsoft code and all of the modifications made to hook the Universe Editor into the game, so you can look through the source to see exactly what's changed in order to add the Universe Editor. 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 Universe Editor binaries, while still containing details of all the modifications. You can find all the diffs by searching the sources for Mod:.

• The Commodore 64 version doesn't contain source for the original game, but instead patches the original game binaries to add the Universe Editor. This process is described in the Commodore 64 patching process below. The Universe Editor uses the same source files on all platforms, but there are some extra routines required by the Commodore 64 version, which can be found in the src folder in the c64 submodule folder.

• 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.

• If you know the name of a routine, you can find it by searching for Name: <name>, as in Name: SCAN (for the 3D scanner routine) or Name: LL9 (for the ship-drawing routine).

• 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 the Elite Universe Editor as much as I've enjoyed writing it.

Folder structure

There are three main folders and four submodules in this repository.

• 1-source-files contains the source files for creating the BBC disc images and README files.

• 2-assembled-output contains the output binaries from the build process for the Elite Universe Editor.

• 3-compiled-game-discs contains the disk images produced by the build process. These disks contain the Universe Editor.

• library-elite-universe-editor contains the shared source files for the Universe Editor. The same source is used for all versions.

• 6502sp-elite-universe-editor contains the source code for 6502 Second Processor Elite, modified to hook in the Universe Editor.

• master-elite-universe-editor contains the source code for BBC Master Elite, modified to hook in the Universe Editor.

• c64-elite-universe-editor contains the original disk images for Commodore 64 Elite, which we extract and modify to hook in the Universe Editor.

The 6502sp and master submodules are downstream of the repositories containing the fully documented source code for Elite on the 6502 Second Processor and BBC Master.

The c64 submodule uses a patching process that's described in the Commodore 64 patching process below.

Building the Elite Universe Editor from the source

Requirements

You will need the following to build the Elite Universe Editor 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 the beebasm.exe file.

• Python. Both versions 2.7 and 3.x should work.

• 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).

• For the Commodore 64 build, you will also need c1541 from the VICE emulator, which can be downloaded from the VICE site.

Builds are supported for both Windows and Mac/Linux systems, but please note that Windows only builds the BBC version. To build the Commodore 64 version as well, you will need to be on a Mac or Linux box. The process may work on the Windows Subsystem for Linux, but I haven't tested it.

In all cases the build process is defined in the Makefile provided. Let's look at how to build the Elite Universe Editor from the source.

Windows

For Windows users, there is a batch file called make.bat that runs the build. 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).

All being well, doing the following:

make.bat

will produce a file called elite-universe-editor-bbc.ssd in the 3-compiled-game-discs folder that contains the BBC version of the Universe Editor, which you can then load into an emulator, or into a real BBC Micro using a device like a Gotek.

Note that the Windows build will terminate with an error after the BBC disc image is created. This is because the Commodore 64 build only works on Mac and Linux.

Mac and Linux

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 the following:

make

will produce three files in the 3-compiled-game-discs folder called elite-universe-editor-bbc.ssd, elite-universe-editor-c64-ntsc.ssd and elite-universe-editor-c64-pal.ssd. These contain the BBC version of the Universe Editor, and the NTSC and PAL versions of the Commodore 64 Universe Editor. You can then load these into emulators or real machines.

The Commodore 64 patching process

The BBC version of the Elite Universe Editor is built from scratch using the annotated source code for Elite with the Universe Editor added into the source (see the 6502 Second Processor and BBC Master repositories for the original sources).

We don't have access to the source code for the Commodore 64 version of Elite, so in order to add the Universe Editor, we have to do the following:

• Extract the game binaries from the original Commodore 64 .g64 disk image (using c1541 from the VICE emulator)

• Assemble the additional code that's required for the Universe Editor (using BeebAsm as the source for the Universe Editor is shared between both platforms)

• Inject this new code into the game binaries and disable any copy protection code (using Python)

• Create a new disk image containing the modified game binaries (using c1541 once again)

To find out more about the above steps, take a look at the following files in the c64-elite-universe-editor submodule, which contain lots of comments about how the process works:

• The build.sh script controls the build. Read this for an overview of the patching process.

• The elite-universe-editor-c64.asm file is assembled by BeebAsm and produces a binary file called editor.bin that contains the bulk of the code that implements the Universe Editor. This binary file is then ready to be injected into the game binary to implement the Universe Editor patch.

• The elite-flicker-free.asm file is assembled by BeebAsm and produces a number of binary files. These contain the bulk of the code that implements the flicker-free algorithm, which is also included in the Universe Editor. These code blocks are saved as binary files that are ready to be injected into the game binary to implement the patch.

• The elite-modify.py script modifies the game binary and applies the Universe Editor and flicker-free patches. It does this by:

  • Loading the main binary into memory
  • Decrypting it
  • Patching it by injecting the output from BeebAsm and making a number of other modifications to the code
  • Encrypting the modified code
  • Saving out the encrypted and modified binary
  • Disabling any copy protection from the original disk

This approach is very similar to the patching process used to create the flicker-free version of Commodore 64 Elite. See the c64-elite-flicker-free repository for details.

---

Right on, Commanders!

Mark Moxon