Assembly C Python Other
Clone or download
Permalink
Failed to load latest commit information.
dos The Great Escape DOS version disassembly. Dec 30, 2015
static-images Use “ITC Berkeley Oldstyle Std” font for HTML output, where available. Jan 3, 2018
tools makemaps: Update #includes for latest DPTLib. Oct 7, 2015
.gitignore screen: Define structure members. Nov 22, 2014
DecodeRooms.py Room decoding + interior object renaming pass. Oct 28, 2015
Makefile Move to using a .sft instead of a .skool. Apr 24, 2018
README.md Update README.md May 11, 2018
TODO.md Update TODO.md after recent changes. Apr 24, 2018
TheGreatEscape.css TheGreatEscape.css: Remove some rules which don't need overriding. May 26, 2018
TheGreatEscape.ctl.retired Retire the .ctl and move to a .skool file. Jun 23, 2015
TheGreatEscape.prof Add profile data captured from FUSE playing RZX recordings of the gam… Oct 18, 2014
TheGreatEscape.py Add route decoding for both HTML and assembly modes May 18, 2018
TheGreatEscape.ref More changelog updates. Apr 19, 2018
TheGreatEscape.sft $A7C9/get_supertiles: Rewrite as prose. Jun 26, 2018
TheGreatEscape.t2s Add tap2sna script. Oct 7, 2015
TheGreatEscapeBugs.ref 2018 Jan 3, 2018
TheGreatEscapeChangelog.ref Set SectionType to “ListItems” for the changelog. Jun 3, 2018
TheGreatEscapeFacts.ref Add “permanent slumber” fact. May 9, 2018
TheGreatEscapeGame.ref More changelog updates. Apr 19, 2018
TheGreatEscapeGlossary.ref 2018 Jan 3, 2018
TheGreatEscapeGraphics.ref Fix mask image generation - broken by the split in 22286cf. Apr 19, 2018

README.md

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 Game

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.

The Disassembly

Read the disassembly here.

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.

Chat

Join the chat at https://gitter.im/The-Great-Escape/Lobby

Goals

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 goals proceed in tandem.

SkoolKit

SkoolKit is the peerless Python toolkit for disassembling ZX Spectrum software written by Richard Dymond.

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!

Other SkoolKit disassemblies are normally written in a one comment per line style but I've chosen to attempt to reconstruct the logic of the original code as pseudo-C-style control structures. This makes it look weirder than I'd like but eases the conversion to C. My current work involves "normalising" the assembly: removing the pseudocode and replacing it with prose.

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
  • Then change to the repository and install the support file:
    • cd <cloned repo>
    • make install
      • This will install TheGreatEscape.py into your ~/.skoolkit directory. You only have to do this once. (Note: If you wish to install into a different location you may have to customise the path inside Makefile).
  • Finally, build the HTML format disassembly:
    • make disasm

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 --skool-hex --sft TheGreatEscape.sft build/TheGreatEscape.pristine.z80 > build/TheGreatEscape.skool
Using skool file template: TheGreatEscape.sft
skool2html.py --hex --asm-labels --rebuild-images build/TheGreatEscape.skool
Using skool file: build/TheGreatEscape.skool
Using ref files: TheGreatEscape.ref, TheGreatEscapeBugs.ref, TheGreatEscapeChangelog.ref, TheGreatEscapeFacts.ref, TheGreatEscapeGame.ref, TheGreatEscapeGlossary.ref, TheGreatEscapeGraphics.ref
Parsing build/TheGreatEscape.skool
Creating directory build/TheGreatEscape
Copying /usr/local/lib/python3.6/site-packages/skoolkit/resources/skoolkit.css to build/TheGreatEscape/skoolkit.css
Copying TheGreatEscape.css to build/TheGreatEscape/TheGreatEscape.css
Copying static-images/BarbedWire.png to build/TheGreatEscape/static-images/BarbedWire.png
Copying static-images/GameWindow.png to build/TheGreatEscape/static-images/GameWindow.png
Copying static-images/JoystickControls.png to build/TheGreatEscape/static-images/JoystickControls.png
  Writing disassembly files in build/TheGreatEscape/asm
  Writing build/TheGreatEscape/maps/all.html
  Writing build/TheGreatEscape/maps/routines.html
  Writing build/TheGreatEscape/maps/data.html
  Writing build/TheGreatEscape/maps/messages.html
  Writing build/TheGreatEscape/maps/unused.html
  Writing build/TheGreatEscape/buffers/gbuffer.html
  Writing build/TheGreatEscape/reference/bugs.html
  Writing build/TheGreatEscape/reference/changelog.html
  Writing build/TheGreatEscape/reference/facts.html
  Writing build/TheGreatEscape/reference/glossary.html
  Writing build/TheGreatEscape/graphics/glitches.html
  Writing build/TheGreatEscape/Intro.html
  Writing build/TheGreatEscape/Controls.html
  Writing build/TheGreatEscape/Completion.html
  Writing build/TheGreatEscape/Characters.html
  Writing build/TheGreatEscape/Items.html
  Writing build/TheGreatEscape/Masks.html
suggested width 17 > actual 16
  Writing build/TheGreatEscape/RoomObjects.html
  Writing build/TheGreatEscape/Rooms.html
  Writing build/TheGreatEscape/Map.html
  Writing build/TheGreatEscape/index.html
  • Open up build/TheGreatEscape/index.html in your browser and dive in.

Building Runnable Games

  • To build a .tap for loading into an emulator:
    • make tap will build build/TheGreatEscape.tap
  • Or use make z80 instead 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
  • Edit build/TheGreatEscape.skool
  • make tap
  • Reload build/TheGreatEscape.tap in 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

Work on reverse engineering progresses but slowly as this is a limited spare time (late night) project for me. (I've been chipping away at it since 2012...)

I switch between the reimplemented C version and the disassembly as while a disassembled function may make sense in of itself, transforming it into functioning C forces a great deal more detail to be thought about.

Presentation

Here's the slides from a presentation I delivered to my colleagues about the project in January 2016.