Space Taxi

A port of Space Taxi (John Kutcher, Muse Software, 1984), the Commodore 64 game, to every machine JoeyLib targets: the Apple IIgs, Commodore Amiga, Atari ST, MS-DOS, Sharp X68000, and DVX. One C codebase builds for all six.

The game is a routine-for-routine re-expression of the C64 original in C, written from its disassembly (MECHANICS.md): the flight physics, the fare machine, the 24 levels' hook programs, the title and level intros, the high-score table and name entry, the music (captured from the game's own SID player), and the speech. The simulation (stSim.c) is checked tick for tick against the original game running in VICE: a ride on each of the 25 screens, A..X and the MYSTERY SCREEN, traces byte for byte as on the C64 (tools/stsim; VERIFIED.md), and the gates below hold it there.

Setting up

Space Taxi builds with JoeyLib, which owns the cross compilers, the library, the asset tools, and every machine's build rules. Check JoeyLib out beside this repository and install its toolchains (its README covers the installer):

games/
    joeylib/      a JoeyLib checkout, set up with ./install.sh
    spacetaxi/    this repository

$ cd ../joeylib
$ ./install.sh install toolchains        # the cross compilers
$ ./install.sh install emulators         # to run it and for the gates

JOEYLIB=PATH on the make command line (or in the environment, for the scripts) points at a checkout somewhere else.

The game data

The levels and the title screen are extracted at build time from a memory image of the original C64 game. It is a copy of a commercial game, so it is not in the repository; supply your own:

$ scripts/importData.sh PATH...

PATH is the image itself, a folder holding it, or a .zip or .tar.gz with it inside. It is recognised by its checksum and installed as stuff/raw.bin, which git ignores. Without it the game still builds; only the levels (and the per-level sprite banks baked from them) are left out, and make says so.

Building

$ make                  # every machine whose toolchain is installed
$ make dos              # one: iigs amiga atarist dos x68000 dvx
$ make clean

Everything lands in build/<machine>/bin/:

Machine	Program
Apple IIgs	`STAXI`, and `STAXI.2mg`: a bootable 2 MB volume (stripped GS/OS that launches the game from its own folder)
Amiga	`Taxi/Taxi` with its `DATA/`
Atari ST	`STAXI/STAXI.PRG` with its `DATA/`
MS-DOS	`STAXI/STAXI.EXE` with its `DATA/`
Sharp X68000	`STAXI/STAXI.X` with its `DATA/`
DVX	`apps/kpunch/staxi/`: `staxi.app`, its help file, and `DATA/`

The bakes (levels, the pre-compiled sprite cels, the speech) are made per machine in build/generated/<machine>/. JoeyLib's library is built on demand in the JoeyLib checkout's own build/.

Running

JoeyLib's joey-run starts a build in the right emulator:

$ ../joeylib/joey-run --project . --port dos staxi
$ ../joeylib/joey-run --project . --port amiga taxi
$ ../joeylib/joey-run build/iigs/bin/STAXI.2mg
$ ../joeylib/joey-run --headless --seconds 90 --snapshot taxi.png --project . --port atarist staxi

The IIgs volume is larger than an 800 KB floppy, so MAME boots it off a CFFA2 card (mame apple2gs -sl7 cffa2 -hard1 build/iigs/bin/STAXI.2mg).

The gates

$ make check                 # build, then every gate
$ scripts/verify.sh disk     # or name the ones to run

Gate	What it proves
`stsim`	Every screen's ride (all 25: the four C64 attract recordings and twenty-one synthesised streams, up to 4000 ticks, crashes costing a cab as in a real game) traces exactly as the real C64 traced it -- `gateHashes.txt` holds the md5s of the C64's traces (`tools/stsim/gate.sh`) -- and every cel a ride shows is pre-compiled (`celGate.sh`)
`harness`	The screens above the simulation -- the high-score table, name entry, its save -- on JoeyLib's host BLANK port (`tools/staxiharness`)
`disk`, `disk01`	`STAXI.2mg` boots, launches the game, and draws on a ROM 3 and a ROM 01 IIgs
`iigsaudio`	The IIgs sound interrupt is NTP's, the DOC is audible, and its sound slots carry waveforms
`x68kaudio`	Every X68000 noise write is a code from the port's table, and the ADPCM runs at 7812 Hz to both speakers while the game speaks

scripts/verify.sh exits 0 when every gate passed, 1 when one failed, and 3 when none failed but one was skipped (an emulator or a machine's build missing, or the game data not imported).

Tools

tools/stsim -- the simulation on the host, and its C64 counterpart: stsim prints one line of state per tick, c64trace.py rides the same input on the original disk in VICE and prints the same line from the C64's memory, and gate.sh c64 compares the two for every screen (compare.py shows where they part). That needs VICE's x64sc and the original SPACETAX.D64 in stuff/; gate.sh c64hashes is how gateHashes.txt is made. recorder searches for the synthesised rides.
tools/staxiharness -- the front-end screen checks.
tools/staxibake -- writes the cel bank the build pre-compiles per machine.
assets/ -- the generators behind the committed C64 tables (genC64Data.py, genDemoStreams.py, genSongData.py, extractSpeech.py) and the level extractor the build runs (romToLevel.py).
scripts/bench-staxi-title.sh, scripts/diag-staxi-screen.sh -- IIgs measurement and diagnosis under headless MAME.

MECHANICS.md and VERIFIED.md are the disassembly notes; TODO.md lists what is still open.

5.5 KiB Raw Blame History