The Great Escape

================
Reverse engineering [Denton Designs'](http://en.wikipedia.org/wiki/Denton_Design
s) classic [ZX Spectrum](http://en.wikipedia.org/wiki/ZX_Spectrum) 48K game [The
Great Escape](http://www.worldofspectrum.org/infoseekid.cgi?id=0002125) using [
SkoolKit](http://skoolkit.ca/).
Goals
----**Goal one** is to build a fully documented disassembly of the game. SkoolKit en
ables us to generate both a detailed HTML format cross-referenced disassembly an
d an assembly listing suitable for rebuilding an image of the original game.
**Goal two** is to transform that C-style pseudocode into real C source code whi
ch behaves exactly like the original game. The work-in-progress reimplementation
project lives in [this repository](https://github.com/dpt/The-Great-Escape-in-C
).
SkoolKit
-------I'm reversing the game with the help of [SkoolKit](http://skoolkit.ca/), the rat
her nice toolkit for disassembling ZX Spectrum software written by Richard Dymon
d.
You can view the HTML disassembly [here](http://dpt.github.com/The-Great-Escape/
). Note that this often lags behind the current head of the source tree.
You can also disassemble and reassemble the game, resulting in a .TAP file which
you can load into an emulator. (e.g. you can fix bugs!)
SkoolKit disassemblies are normally written in a plain text comment style but I'
ve chosen to use a C-style pseudocode and Z80 fragments where C syntax cannot co
pe. Wise decision? Time will tell.
Also note that currently the disassembly is contained in a _control_ file rathe
r than a _skool_ file.
Building the Disassembly
-----------------------* First, make a local clone of this repository: `git clone https://github.com/dp
t/The-Great-Escape.git`
* `cd <the cloned repo>`.
* Drop a Z80 format snapshot of the game into the project directory. Call it `Th
eGreatEscape.z80`.
* `make install`. This will install TheGreatEscape.py into your `~/.skoolkit` di
rectory. You only have to do this once. (Note: If you wish to install into a dif
ferent location you may have to customise the path inside `Makefile`).
* `make disasm`. To build the HTML format disassembly.
If all's well you will see:
$ make disasm
mkdir -p build
sna2skool.py -H -R -c TheGreatEscape.ctl TheGreatEscape.z80 > build/TheGreat
Escape.skool

skool2html.py -H -o build/TheGreatEscape.skool
Using skool file: build/TheGreatEscape.skool
Using ref files: TheGreatEscape.ref, TheGreatEscapeBugs.ref, TheGreatEscapeF
acts.ref, TheGreatEscapeGlossary.ref, TheGreatEscapeGraphics.ref
Parsing build/TheGreatEscape.skool
Creating directory build/TheGreatEscape
Copying /Library/Python/2.7/site-packages/skoolkit/resources/skoolkit.css to
build/TheGreatEscape/skoolkit.css
Copying TheGreatEscape.css to build/TheGreatEscape/TheGreatEscape.css
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/Characters.html
Writing build/TheGreatEscape/Items.html
Writing build/TheGreatEscape/RoomObjects.html
Writing build/TheGreatEscape/Rooms.html
Writing build/TheGreatEscape/Map.html
Writing build/TheGreatEscape/graphics/glitches.html
Writing build/TheGreatEscape/reference/bugs.html
Writing build/TheGreatEscape/reference/facts.html
Writing build/TheGreatEscape/reference/glossary.html
Writing build/TheGreatEscape/index.html
* Open up `build/TheGreatEscape/index.html` in your browser and peruse
Building the Reassembly
----------------------* `make asm` to build
* `make bin` to build
://pasmo.speccy.org/)
* `make tap` to build
r.

just the assembly source.

assembly and binary. This step depends on the [Pasmo](http
assembler.
assembly, binary and .tap file for loading into an emulato

Currrent State
-------------I don't grok all the code yet, so I have to be vague when naming symbols. You wi
ll notice stuff like:
* 'sub_*' names a function I don't know
* 'byte_*' and 'word_*' in this context
sed as a byte (or word) but I can't yet
* Vague tokens like 'maybe', 'mystery',
not quite sure of something.

the purpose of.

mean 'something which I can see is acces
tell what it is.'
'unsure' or 'possibly' indicate that I'm

As work progresses on the reimplementation many of the mysteries of the original

will be revealed.