joeylib2/examples/spacetaxi/PLAN.md

Space Taxi port plan

Roadmap for bringing the JoeyLib port to functional parity with the C64 original. Sequenced so each phase delivers something testable on its own and unblocks the next. Each phase ends with a user-test checkpoint -- regressions must be caught before moving on.

Workflow per subsystem

Same loop every time, so it stays cheap to iterate:

1. Find -- grep the live RAM dump for relevant register writes ($DC00, $D015, $D400-$D418, $07F8-$07FF, etc.) or use callGraph.py to find routines touching specific addresses.
2. Read -- pull the routine into a window via disLive.py <dump> <out> <start> <end>, study the annotated listing.
3. Document -- append behavior summary to MECHANICS.md in plain English. Add new labels/vars to stuff/spacetaxi/labels.txt.
4. Reannotate -- python3 disLive.py mem0000-level1.bin live-level1.lst to regenerate the (annotated) listing from the dump + labels.txt in one step. The .lst file is the only readable form -- labels are baked in directly.
5. Port -- update the matching JoeyLib C file (stEngine.c, stPassenger.c, stRender.c, stAudio.c, stLevel.c, spacetaxi.c).
6. Build + ship -- make -f make/dos.mk EXAMPLE=spacetaxi first, then once stable also amiga / atarist / iigs.
7. User test -- run scripts/run-dos.sh staxi, report behavior. Do not start the next phase before this.

Phase 0 -- foundation (DONE)

• Disassembly toolchain in stuff/spacetaxi/
• Full live-RAM listing + annotated variant
• MECHANICS.md baseline
• Asset pipeline (tools/assetbake/assetbake.py, extractor realigned)
• Bugfixes: sprite size in tile units, palette clobber, tile-bank load clamp, fire-not-thrust, palette/sheet collision
• Template-velocity physics in stEngine.c

Phase 1 -- physics + collision (NEXT)

Make the cab fly correctly. Highest impact: nothing else works until the player can hover, land, and crash.

Task	Investigate	Update
1.1	Trace $7D95/96 gravity word writers -- when is gravity on?	stEngine.c: gate gravity on the same conditions
1.2	Find writers of $721D (player state byte). High bit = "dying". What sets it?	stEngine.c: crash trigger logic
1.3	Trace phase-2 handler at $6B24 -- this is what runs after $6A72 advances. Likely the crash / fall-to-ground sequence	New stEngine.c crash-anim path
1.4	Find pad-vs-wall predicate. Hardware $D01F says "we hit bg"; some code looks at char codes near taxi feet to decide PAD vs WALL	stLevel.c: pad detection by tile code
1.5	Confirm screen-edge wrap at $6AED -- when X-velocity carries the taxi off the right edge, does it wrap or stop?	stEngine.c: edge behavior

Checkpoint: cab flies smoothly, can land on a pad, crashes hard.

Phase 2 -- visuals + animation

Make the screen match the original's look frame-by-frame.

Task	Investigate	Update
2.1	Confirm taxi has one cel only. The 2 writes to $07F8 (taxi sprite ptr) -- are they per-level (color swap) or per-frame? Read those sites	stRender.c: reduce ST_TAXI_CEL_COUNT to 1, kill thrustFrame
2.2	What renders the engine flame under the taxi during thrust? Either a second sprite or a tile overwrite	stRender.c: flame overlay
2.3	Passenger walk: trace updates to passenger sprite Y/X in the sprite state table (NOT $D004-$D00D; the table memory)	stPassenger.c: walk frame timing
2.4	Title-screen layout: the C64 title positions logo / credits / instructions at specific char rows. The extractor pulls the screen layout; check the .txt against the disassembly's title-init routine to confirm we render the same layout	assets/levels/title.txt, stRender.c title overlay

Checkpoint: the title screen, gameplay, and game-over screens each look like the C64.

Phase 3 -- audio

Authentic feel needs the SID engine. JoeyLib audio is per-platform, so the abstraction is "SFX event id" -- the SID details only land in the DOS / Amiga / ST tone-generator backend.

Task	Investigate	Update
3.1	Music engine: voice 1+2 melodic table. Find where tunes are stored, how the row pointer advances, how note-to-freq lookup works	stAudio.c: music playback state machine
3.2	Thrust SFX: confirmed voice 1 freq sweep from $721B. Find writer of $721B (start of thrust) and what triggers it to stop	stAudioSfxThrust envelope
3.3	Crash SFX: voice 3 noise burst. LDA #$81 STA $D412 ... LDA #$80. Find duration / pitch envelope	stAudioSfxCrash
3.4	Land SFX: a successful landing must trigger some audible cue. Trace from collision dispatch when sprite-bg collision is at low vy	stAudioSfxLand
3.5	Door / passenger SFX: passenger enters/exits the cab on a pad. Probably also voice 3 noise or a brief tone	new SFX

Checkpoint: thrust, land, crash, and at least one music loop all play audibly on DOS. Approximate timbres OK; pitch + envelope should roughly match.

Phase 4 -- game logic

Make the game progress. State machine, scoring, lives.

Task	Investigate	Update
4.1	Passenger spawn: when does fare N+1 appear after fare N is delivered? Look for writes to the passenger-active flags in the state table	stPassenger.c
4.2	Patience timer: a passenger has a countdown. Find the per-frame decrement and what happens at zero (passenger leaves? lose pad?)	stPassenger.c
4.3	Scoring: base fare from $7D..., tip math for time-on-board. BCD arithmetic on a 4-byte score	stHud.c, score storage
4.4	Level transitions: $7215 == $19 is the "level complete" sentinel. What writes that, and how does the game pick the next level?	spacetaxi.c main switch
4.5	Lives: where is the lives counter? How does the game decide game-over?	stEngine.c crash branch, spacetaxi.c

Checkpoint: can complete a level, advance, lose all lives, see game-over, restart from title.

Phase 5 -- level data

Match the original's 25 levels (or however many ship in the disk image; verify from SPACETAX.D64).

Task	Investigate	Update
5.1	Level table layout in RAM: where are per-level pad coords stored? Per-level music ID? Per-level taxi spawn? Per-level fare list?	stLevel.c STL1 format
5.2	Extract every level from the D64 image (we already have level1 / level2 / title dumps; need a way to dump every level state). Either replay through the game in VICE and snapshot each level, or read the level table once and reconstruct	extractor: bulk-export
5.3	Verify the title screen extraction matches the original byte-for-byte (chars + colors)	title.dat regenerate

Checkpoint: all original levels playable, named correctly, ordered correctly.

Phase 6 -- cross-platform parity

DOS lands first. Then bring the other three up.

Target	Specific work
Amiga	Verify build still runs; PT replayer for music; joystick
Atari ST	Same; YM2149 for SFX, MOD for music
IIgs	Resolve ROOT-segment limit so the binary fits; wire asset
	pipeline into the disk packager (3 options in earlier note);
	Ensoniq sound match

Checkpoint: each of the four targets boots, shows title, plays at least one level end-to-end.

Working notes

• All chat-side analysis must stay in plain English -- disassembly excerpts go in local files (MECHANICS.md, labels.txt), not pasted back into the session.
• One subsystem per session is the right cadence. Trying to "do them all at once" without user-test feedback compounds errors.
• Keep this plan up to date: as each task lands, mark it DONE with the commit SHA or date, and add new tasks discovered during the work.