# Space Taxi

A port of Space Taxi (John Kutcher, Muse Software, 1984), the Commodore 64
game, to every machine [JoeyLib](../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
```

```console
$ 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:

```console
$ 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

```console
$ 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:

```console
$ ../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

```console
$ 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.