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 verified tick for tick against VICE traces of the C64's four attract-demo rides (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/joeylib/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 hook level's 4000-tick simulation trace is identical to its golden (`tools/stsim/gate.sh`; the four C64 attract rides and thirteen synthesised ones), 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: prints the per-tick state a VICE trace records, so compare.py can diff the port against the C64.
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 KiB Raw Permalink Blame History