The Great Escape
This project reverse engineers Denton Designs' classic ZX Spectrum 48K game The Great Escape from a tape image of the original game into a cross-referenced and annotated HTML disassembly and full assembly source code, using SkoolKit.
The Great Escape is a 1986 isometric 3D prison break game for the 48K ZX Spectrum where you play a POW trying to escape from a nazi prison camp. It's one of the best-regarded Spectrum games and I want to know how the authors managed to pack all that magic into the 48K ZX Spectrum.
Read the current version of the disassembly here. It's not only an assembly listing: it has decoded game graphics, characters, items, animations and various other details about the game's workings.
Note that the disassembly may lag behind the head of the source tree: it might not feature the very latest changes until I push an updated build.
My first goal is to build a fully documented disassembly of the game. SkoolKit lets us build both an annotated assembly listing suitable for rebuilding an exact image of the original game and a detailed cross-referenced disassembly in HTML format.
The second is to transform the annotated assembly into C source code which behaves exactly like the original game. The work-in-progress reimplementation project lives in this repository and the two projects proceed in tandem.
In addition to producing the cross-referenced HTML disassembly SkoolKit can also produce an annotated assembly listing. We can use this to reassemble the game to a .TAP file which you can load into an emulator. You can use it to alter the game and fix 30-year-old bugs!
Building the Cross-Referenced Disassembly
- First, install SkoolKit
- Then make a local clone of this repository:
git clone https://github.com/dpt/The-Great-Escape.git
- Finally change to the repository and build the HTML format disassembly:
cd <cloned repo>
If all's well you will see output like:
$ make disasm tap2sna.py --output-dir build @TheGreatEscape.t2s && mv build/TheGreatEscape.z80 build/TheGreatEscape.pristine.z80 Downloading http://www.worldofspectrum.org/pub/sinclair/games/g/GreatEscapeThe.tzx.zip Extracting The Great Escape.tzx Writing build/TheGreatEscape.z80 mkdir -p build sna2skool.py --hex --sft TheGreatEscape.sft build/TheGreatEscape.pristine.z80 > TheGreatEscape.skool Using skool file template: TheGreatEscape.sft skool2html.py --hex --asm-labels --rebuild-images TheGreatEscape.skool Using ref files: TheGreatEscape.ref, TheGreatEscapeBugs.ref, TheGreatEscapeChangelog.ref, TheGreatEscapeFacts.ref, TheGreatEscapeGame.ref, TheGreatEscapeGlossary.ref, TheGreatEscapeGraphics.ref Parsing TheGreatEscape.skool Output directory: build/TheGreatEscape Copying /usr/local/lib/python3.7/site-packages/skoolkit/resources/skoolkit.css to skoolkit.css Copying TheGreatEscape.css to TheGreatEscape.css Copying static-images/BarbedWire.png to static-images/BarbedWire.png Copying static-images/GameWindow.png to static-images/GameWindow.png Copying static-images/JoystickControls.png to static-images/JoystickControls.png Writing disassembly files in asm Writing maps/all.html Writing maps/routines.html Writing maps/data.html Writing maps/messages.html Writing maps/unused.html Writing buffers/gbuffer.html Writing reference/bugs.html Writing reference/changelog.html Writing reference/facts.html Writing reference/glossary.html Writing graphics/glitches.html Writing Intro.html Writing Controls.html Writing Completion.html Writing Characters.html Writing Items.html Writing Masks.html suggested width 17 > actual 16 Writing RoomObjects.html Writing Rooms.html Writing Map.html Writing index.html
- Open up
build/TheGreatEscape/index.htmlin your browser and dive in.
Building Runnable Games
- To build a .tap for loading into an emulator:
make tapwill build
- Or use
make z80instead to build a .z80 image if you prefer.
Any of the above steps will invoke its prior step automatically.
To Edit, Rebuild and Run the Game
make skool-- to build the .skool file
build/TheGreatEscape.tapin your emulator
Building the Assembly Source
If skool files are not to your taste and you prefer a regular assembly listing:
make asm will build
build/TheGreatEscape.asm. This can then be passed into Pasmo, for instance, to build a binary.
Current State of the Project
The reverse engineering of the game is now complete, but work will continue to improve the accuracy and readability of the disassembly.
Presentations & Write-ups
Here's the slides from a presentation I delivered to my colleagues about the project in January 2016.
There's a more recently updated version too which were written for a 2020 presentation about the project to the ABug user group: http://abug.org.uk/index.php/2020/07/04/the-great-escape-risc-os-conversion-david-thomas/
In 2019 I did a big write-up about the project on my website: http://www.davespace.co.uk/the.great.escape/