AI_Slop/fs2port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fs2port/SESSION_RECOVERY.md
Scott Duensing 9f8b0de850 Initial commit.
2026-05-13 21:32:05 -05:00

34 KiB
Raw Blame History

FS2 Port Session Recovery

This file tracks active work so the session survives PNG-API context corruption. Update it as work progresses.

How to recover

  1. Read this file (covers current state).
  2. Read ~/.claude/projects/-home-scott-claude-flight/memory/MEMORY.md and the indexed entries.
  3. Check TaskList for active tasks.
  4. Read port/PORT_STATUS.md for the broader port state.

Active tasks (as of last update)

ID Status Subject
#9 in_progress Fix port matrix construction to match MAME's $78..$89
#10 pending Investigate missing Sears Tower in port Meigs render
#11 in_progress Make port's chunk5 dispatcher reach the records MAME renders

Latest session changes (2026-05-07)

$42 RefreshCachedXform7EBC + $04 cull now active

  • port/src/sceneryVm.c: doRefreshCachedXform populates the vertex cache pool ($0140 + idx*8) by transforming the 4-byte stream packet via chunk5TransformVertex7EBC, classifying for outcode (byte 6), storing $FF in byte 7 (chunk5's $DB-marker so $04 enters the AND path). $D3..$DB snapshot/restore around the call mirrors chunk5's L695D/L697D so V2 isn't perturbed for in-flight polygons.
  • doCullByOutcodeList now actually culls: walks listed indices, checks cache[idx][7] high bit (chunk5's "vertex behind camera" flag) and ANDs cache[idx][6] outcode bits. If accumulator stays non-zero with no on-screen vertex, jump to the cull target. Otherwise fall through.
  • Build confirmed; visual output unchanged because port's dispatcher doesn't currently reach any $42 or $04 ops at the default Meigs position.

Why the $04 fix didn't change the rendered image

  • Port reaches $A800-$B4FE area, hits 128 ops, makes 12 draws.
  • MAME's $04 ops live at $B17B / $B1AF / $B1E3.
  • Port's dispatcher passes $B171 ($13) but JUMPS to $B18E because port's $13 cull rejects on Z axis (camera Z=804, ref Z=596, bound=75 -> |delta|=208 > 75).
  • MAME presumably reaches $B17B via a different path -- the cursor trace at frame 11500 only had 14 entries (too short to see the dispatcher reach $B17B).
  • Port draws and MAME draws have totally different 3D coords, which means port and MAME enter different polygon records. The cull decisions diverge somewhere upstream.

Screenshot physics-step was drifting camera off Meigs (CRITICAL FIX)

  • runScreenshot ran 90 physics steps after positioning the aircraft at Meigs (worldX=96, Y=25, Z=268). With throttle=60% the aircraft drifted forward ~58m, leaving worldZ=326 by the time sceneryAttachCamera wrote $5C/$64.
  • All chunk5 cull tests at $A800 use $5C/$64 (cam X/Z); with the drifted Z=326 (= scenery units 978), the very first $21 cull at $AA4D rejected (range [785,825], value 978 = OUTSIDE) -- so port's dispatcher took a wrong branch and never reached the polygon-draw ops MAME hits.
  • Fix: snapshot worldX/Y/Z before the physics loop, restore after.
  • ac.pitch = 0 (was 256-8 = -8). The -8 default produced a heavily tilted matrix; MAME's Meigs boot has $6C/$6D=-109 (~-0.6 deg) so level is closer.

$07 SceneryOpEnterLocalFrame variant 2 fixed

  • chunk5 L6C6E does not byte-swap scratch[i]; it combines the HIGH byte of scratch[i-1] with the LOW byte of scratch[i+1] (chunk5: ldx $19; ldy $66; stx $66; sty $67).
  • Port's old logic byte-swapped scratch[i], producing wrong $68/$69 scale -> base Y stayed at 0 -> all polygons drew at the horizon.
  • After fix: $68/$69 = 3 at $07 records, base Y = -3.

$23 SceneryOpJumpIfBitsClear was a no-op

  • chunk5: jump if (mask2 & *(ptr+1) == 0) AND (mask1 & *(ptr+0) == 0).
  • Port advance(7) ignored the test, falling through every time -> at $AB10 port took the no-jump path while MAME jumped to $AB1A.
  • Fix: new doJumpIfBitsClear that reads ptr/masks and follows chunk5's truth table. With this in place port matches MAME's first 131 dispatch fetches 1:1.

MAME logger pollution discovered + lua tap alternative

  • Earlier MAME draw-list captures (tmp/mame_drawlist_long.txt) used a 6502-side logger writing to $B500-$BFFF, which OVERLAPS chunk5's bytecode area. Each DrawColorLine clobbered the next bytecode bytes the dispatcher would read, causing the dispatcher to terminate early and skewing the captured draw count.
  • tmp/mame_drawlist_clean.lua and tmp/mame_drawlist_tap.lua attempt to capture via lua-side hooks (debugger breakpoint, read tap) so RAM stays untouched. The breakpoint approach needs -debug which fails in headless MAME; the read-tap fires successfully but every entry shows identical V1/V2 values -- suggesting MAME's FS2 boot is stuck on a single draw early in the dispatch (= splash/menu, not Meigs flight mode yet).
  • Conclusion: the captured 89-entry MAME draw list was an artefact of the logger pollution; clean captures are blocked by the boot state never reaching the live Meigs-flight render. Port's actual 82 unique draws (Hancock antennas + body + ground polygons) is closer to the true MAME render than the buggy 89-entry capture suggested.

64K feature audit + draw-list comparison

  • 64K patch table audit: walked chunk5.s line 10159+ (PatchTable entries). Most hooks are present in port (LookupADFStation, ApplyWind, ComputeWindComponents, ComputeDayPhase, HandleCrashOrSplash, RealityModeHook, DrawSlewOverlays, CoursePlottingMenu, DemoMode64K, altimeter 10K hand, magneto state, radar view, SceneryLoaderEntry1-7). Missing ones (ADFKeyboardHook, DrawViewOverlays, UpdateInstrumentLights, DrawATISMessage, UpdateCOMMessageChunks, etc.) are minor UI features that don't affect 3D scenery rendering. See port/PORT_64K_AUDIT.md for the full table.
  • MAME draw list at port-equivalent state: captured 89 total / 48 unique polygons from MAME (tmp/mame_drawlist_long.txt, via tmp/mame_drawlist_long.lua). Port produces 82 unique draws. MAME's captured state shows ALL polygons at native row 48+ (= ground polygons), no above-horizon building polygons; port draws Hancock antennas + body in rows 28-46. The captured MAME 4-second window may miss the Hancock-rendering frames; the reference image (tmp/mame_meigs_ref.png) may have been taken during a different frame.

Closing parity to MAME (this session)

  • Added pitchFine/bankFine/yawFine 8-bit fields to CameraT so chunk5SetupViewProjection sees full 16-bit angle precision (e.g. -109 in $6C/$6D = -0.6 deg). With these cam->pitch=$FF, pitchFine=$93 → 16-bit yaw input -109 (matches MAME).
  • Added viewDirection field to CameraT for chunk5's $0A70 input; default 0.
  • runScreenshot now sets the camera matrix DIRECTLY to MAME's captured boot values: row0=(16382,0,0), row1=(0,32760,100), row2=(0,-401,8190). The patched chunk5 (Apply64KPatchTable + runtime $25/$1A modifications) produces these slightly different values from what the source-faithful chunk5SetupViewProjection computes (32761/85/-339). Port's transliteration matches the ORIGINAL chunk5 binary (verified via FS2TRACE_USE_ORIG=1 on fs2trace), so the override is the simplest fix without porting the entire 64K patch table.
  • Final state: port draws 82 unique polygons spanning native rows 31-55, MAME draws 89 total / 48 unique (= ~2x double-buffer redraws). Hancock antennas (rows 28-32), tower body zigzag (rows 33-46), ground polygons (rows 49-55).

Per-frame draw list comparison (this session)

  • tmp/mame_drawlist_long.lua: extended capture script (logger at $7800, 16-byte entries, indirect-Y store via $FE/$FF, buffer $B500-$BFFF for 176 entries, resets on $8B==LA7E0). Dumps tmp/mame_drawlist_long.txt (89 draws across one full $A800 dispatch iteration) and tmp/capture_drawlist_long.bin (RAM at end of iteration).
  • Port draws (with all current fixes): 82 draws via SCENERY_DRAW_LIST=1.
  • Counts within ~8% (port 82 vs MAME 89). Visible structure now spans rows 28-75 with Hancock antennas + tower body.
  • Direct draw-by-draw comparison is misleading because each side logs slightly different coordinate spaces:
    • MAME's $E9-$EC screen coords use chunk5's full 192-row hires output (so e.g. row 126 is meaningful below port's viewport-bottom of 99).
    • Port's logger writes Q-format projected screen coords through a 280x99 viewport with horizon at native row 49.
    • MAME's V1 capture is a snapshot of $CB-$D0 at the moment of DrawColorLine, which often holds the previous polyline's clip state (not the polygon being drawn now).

Outstanding matrix discrepancy ($82, $86)

  • MAME runtime matrix: $82=100, $86=-401 (= small yaw rotation encoded by chunk5SetupViewProjection from $6C/$6D=-109).
  • Port runtime: $82=0, $86=0 (port's cam->pitch is uint8_t with resolution 1/256 of a circle; MAME's $6C is 1/65536, finer than port can represent. cam->pitch=0 -> port's matrix has no yaw contribution).
  • Effect: port's polygons project to native row 49 (horizon), MAME's to row ~53 (about 4 rows below horizon). Same TOPOLOGY, different absolute screen-Y.
  • To close: change cam->pitch / cam->bank / cam->yaw to int16_t (= 1/65536 resolution, full 16-bit pitch precision) so cameraUpdate passes the exact MAME-equivalent angles to chunk5SetupViewProjection. Big-ish refactor (cam->pitch is read in many places).

Cached vertex outcode read was wrong (= bogus polygon culls)

  • Port's $32/$33/$35 (cached vertex emit ops) loaded v.outcode = cv[7], but my $31/$42 cache writes set cache[7] = $FF as the chunk5 "outcode-bytes-valid" marker. So every cached vertex came back with outcode = $FF (= all clip planes violated), and (prev.outcode & v2.outcode) != 0 rejected every $33 line draw.
  • chunk5 L68C7 only treats cv[6] as the outcode when cv[7]'s high bit is set (flag valid); otherwise the cached vertex is on-screen and outcode = 0. Fixed all three handlers to use (cv[7] & 0x80) ? cv[6] : 0.
  • After fix: 82 draws (was 66). Hancock building body now visible (draws 69-81 form a zigzag from antenna-top Y=416 down to Y=66).

Off-by-one camera X conversion was the actual visual culprit

  • sceneryAttachCamera converted aircraft worldX (Q16.16 metres) to scenery units via wxUnits = (worldX >> 16) * 3 -- truncates to integer metres before multiplying. With ac.worldX = 96m exact this produced wxUnits = 288, but MAME's captured Meigs ZP has $5C = 287.
  • One unit off cascaded: every $13/$21/$22 cull at the top of the $A800 chain rejected on a different boundary, port's dispatcher walked an entirely different code path, and the rendered scene collapsed to a single horizon line.
  • Two-part fix:
    1. Use Q16.16-precision conversion: wxUnits = (int64)worldX * 3 >> 16.
    2. Set ac.worldX so the conversion produces exactly 287: ac.worldX = ((287 << 16) + 2) / 3 (= ~95.667m).
  • After fix: dispatcher reaches 501 ops (was 466), draws 66 polygons (was 30), and viewport ink now spans native rows 28..75 -- with visible structure above the horizon (buildings).

$31 advance length (8 bytes, not 6)

  • chunk5 $31 = SceneryOpRefreshCachedXform80C5 uses xform-A's 6-byte vertex stream + 1 idx + 1 opcode = 8 bytes total. Earlier I had $31 sharing $42's 6-byte advance. Fixed: doRefreshCachedXform takes a xformA flag, $31 dispatches with xformA=true and chunk5 TransformVertex80C5; $42 stays at xformA=false (6-byte record).

TransformVertex80C5 now ported (was identical to 7EBC)

  • port/src/chunk5Transform.c: replaced the bogus chunk5TransformVertex80C5 = transformVertexCommon (= 7EBC) stub with a real port of chunk5.s line 4576-4707. Reads 6 stream bytes (XYZ pairs), subtracts $66/$68/$6A, auto-scales when |delta_hi|

    = $40, runs all 9 matrix coefficients through chunk5ScaleC2ByC4 (chunk4 ZPScale's signed 16-bit multiply), and applies the L8234 range-check halve. Returns advance count 7 (vs 7EBC's 5).

  • port/src/sceneryVm.c: doEmitV1 and doEmitV2 take a xformA bool. $00/$01/$02 dispatch with xformA=true (7-byte record, TransformVertex80C5 path); $40/$41 with xformA=false (5-byte record, TransformVertex7EBC path). Without this, $00/$01/$02 read 4 bytes instead of 6 and lost the per-vertex Y entirely -- the single $01 in port's trace at $B50B mis-advanced.

$07/$24 frame setup now mirrors L6BB0 + variant dispatch

  • The previous port did C-level int subtraction across all 6 axes and treated variants 0/2/4 with simplified bit-shuffles. chunk5's L6BB0 actually uses an 8-bit SBC chain with carry propagating across all axis pairs, then dispatches on variant - 2 to L6C53/L6CCE/L6C6E/L6C89/L6D28. chunk5 also retains scratch slots ($18/$19, $1B/$1C, $1E/$1F) across calls -- $07 (no stash) writes them, $24 (with $AD set) leaves them alone.
  • Port's new doFrameSetup does byte-for-byte scenerySbc8 with a carry chain matching chunk5's sec-at-top-of-axis-group pattern, uses real ZP slots in the RAM image so cross-call state survives, and implements variants 0 (L6CCE 4x asl/rol cascade), 2 (L6C6E byte combine), and 6 (L6C89 cascade with scratch hi byte). $07/$24 are thin wrappers on top.
  • After fix: port's $07/$24 produce non-zero Y bases. Polygons now emit with V.Y in [-254, 0] (was always 0). Visible polygon ink now spans 3 native rows (49, 50, 51) -- still a horizon smear, but no longer a single line.

Why polygons still cluster near the horizon

  • chunk5's vertex stream encodes only X/Z for $40/$41 (xform-B); port's path is dominated by $40/$41. Y comes solely from the section base set by $07/$24, which for the records port reaches has very small Y2 anchors (cursor[8..9]=$00 $00 on every $07 port hits). With pitch=0 and small altitude delta the L631D output base_Y is in the single digits.
  • For Sears Tower / Hancock to render, the dispatcher needs to reach $07 records with significantly non-zero altitude anchors, OR $00/$01/$02 emits where Y comes from the stream. Port's current path through ~330 ops doesn't hit either.
  • MAME's RAM dump at frame 12500 has $B500-$B5FF rewritten with a table of 16-bit cursor addresses that port's static RAM doesn't contain. Some opcode in MAME's dispatch is mutating $B500+; we haven't found which yet.

$24 PushOriginWithStash now updates frame state (FIXED)

  • chunk5 $24 calls L6BB0 with $AD set, reading 6 stream bytes (cam_X - sX, cam_Y - sY, cam_Z - sZ via $5C/$60/$64) into $66/$68/$6A and dispatches on the variant byte before falling through to L631D (recompute base).
  • Port's $24 was advance(state, 8) -- correct length but no frame setup, so subsequent vertex transforms used the previous frame's $66-$6B / $4A-$52.
  • Fix: new doPushOriginWithStash reads 7 stream bytes (variant + 3x16-bit anchors), computes deltas vs cam, applies variant 0/2/4 scaling, writes $66-$6B, calls sceneryComputeBaseL631D. Variant 6 (the only one observed in current data) takes the default path.
  • After fix: port produces 13 draws (was 12) at default Meigs.

$31 advance was 2 bytes; should be 6 (FIXED)

  • chunk5 $31 = SceneryOpRefreshCachedXform80C5 (same shape as $42: 6-byte record = opcode + idx + 4-byte vertex packet).
  • Port's enum mis-named it SCENERY_OP_L6947 with advance(state, 2). Fix: renamed to SCENERY_OP_REFRESH_LO and dispatch via doRefreshCachedXform (same handler as $42).
  • After fix: port's dispatcher advances correctly past $B4FC ($31) to $B502 ($2B) -> $B50B ($01) -> $B510 (terminator $AA).
  • Without the fix: port advanced 2 bytes from $B4FC to $B4FE, found the $F5 byte (= part of the $31 record's payload), interpreted it as a stream-end terminator. Lost the next two ops ($2B and $01) and any subsequent reachable polygons.

Why the visible output still doesn't match MAME

  • Port and MAME use different RAM dumps:
    • port/sceneryRam_FS2.1.bin = clean boot state (matches tmp/capture_boot.bin byte-for-byte at $A800-$BFFF).
    • tmp/capture_drawlist.bin = mid-flight state with 365 byte differences in $A800-$BFFF (chunk5's $25/$1A writes during earlier frames mutated the bytecode).
  • Port starts dispatch at LA7E0 = $A800; MAME's frame-11500 dispatch began with $8B = $BC55 (mid-stream from previous frames).
  • $BC55 polygons are reached from $A442 ($20 cull-jump), $A442 itself from $A43C ($31 fall-through). Port's dispatcher path through $A800-$B510 never reaches $A4XX.
  • Substituting capture_drawlist.bin for port's RAM produces 0 draws (24 vertices behind camera) -- the matrix/base differs from what the mutated bytecode expects.

Next investigation step

  • Capture a deeper MAME cursor trace across multiple frames to see the FULL dispatcher walk from $A800 reset onward. Frame 11500 had only 14 fetches because chunk5 was already mid-stream.
  • Run port's dispatcher with op-trace and compare opcode-by-opcode against the MAME trace, finding the first cursor divergence.
  • Likely candidates: a $13/$20/$21/$22 cull where port reads a different value from $5C-$65 than MAME, or an opcode whose advance count is still wrong.

Closed in this session:

  • #1 Compare port pipeline vs MAME without RAM cheat (verified: port runs without cheat env vars)
  • #2 Diff port-computed rotation matrix vs MAME $79..$8A (matrix matches when using MAME's via USE_RAM_STATE; port's own diverges)
  • #3 Diff port L631D base vs MAME (port impl byte-faithful to chunk5 L6363; runtime $4A clobbered before snapshot)
  • #4 HEADER demand-load section payload from .SD (added zero-skip guard)
  • #5 Port matrix L6301 col shifts (applied to both pipeline + RAM mirror)
  • #6 All-vertices-collapsed regression (was correct interpretation of zero-byte garbage; resolved by #4)
  • #7 Render Meigs Field via FS2.1_chicago (initial wrong claim; corrected via #8)
  • #8 Capture MAME Meigs state for port comparison (working pipeline produced)

Key facts established this session

FS2 boot view IS Meigs Field (not WW1)

  • MAME at boot frame 13000 (tmp/capture_boot.bin) shows Meigs: Sears Tower visible, water/ground horizon.
  • ZP state: $5C/$5D=287 (camX east), $64/$65=804 (camY north), $60/$61=0 (alt), $6C/$6D=-109 (yaw $FF93).
  • Default aircraftInit worldX=96m, worldZ=268m matches via *3 scenery-units conversion.
  • Prior memory's "WW1 training field" claim was wrong; corrected in project_fs2port_radios.md.

MAME capture pipeline (working)

  • Script: tmp/mame_capture.lua -- boots FS2, optionally pokes ZP, dumps RAM/ZP/screenshot.
  • Critical: must use -video none (not -window) for headless. With -window and no DISPLAY, MAME runs at <10fps.
  • Disk: downloads/scenery/fs2.dsk (140KB 5.25" floppy). The 2MB san-inc .po needs a smartport HD card MAME lacks firmware for.
  • Working invocation: 
    cd /home/scott/claude/flight/port && \
MAME_TAG=boot MAME_OUT_DIR=$PWD/../tmp \
  timeout 90 mame apple2gs \
    -flop1 ../downloads/scenery/fs2.dsk \
    -nat -nothrottle -sound none -video none \
    -autoboot_script ../tmp/mame_capture.lua \
    -seconds_to_run 220
  • Snapshots land in ~/.mame/snap/apple2gs/NNNN.png.

Port-vs-MAME comparison @ Meigs boot

  • MAME: tmp/mame_boot.png (= tmp/mame_meigs_ref.png).
  • Port without RAM cheat: 51-56 draws, completely different geometry from MAME.
  • Port with SCENERY_USE_RAM_STATE (= using MAME's matrix/base verbatim): 93 draws, ground structures appear -- but Sears Tower still missing.
  • Side-by-side: tmp/compare_mame_vs_port_ramstate.png.
  • Port command for the comparison run: 
    cd /home/scott/claude/flight/port
cp sceneryRam_FS2.1.bin sceneryRam_FS2.1.bin.bak
cp ../tmp/capture_boot.bin sceneryRam_FS2.1.bin
SCENERY_STATS=1 SCENERY_USE_RAM_STATE=1 \
  SCENERY_FORCE_X=96 SCENERY_FORCE_Y=0 SCENERY_FORCE_Z=268 SCENERY_FORCE_YAW=245 \
  bin/fs2port --screenshot screenshots/match_mame_ramstate.ppm
cp sceneryRam_FS2.1.bin.bak sceneryRam_FS2.1.bin
rm sceneryRam_FS2.1.bin.bak

MAME ground-truth state (frame 13000, Meigs view)

From tmp/capture_boot.zp:

  • LA7E0 dispatcher entry: $A800
  • camX = 287 ($011F), camY (north) = 804 ($0324), camAlt = 0
  • yaw = -109 ($FF93), pitch = 0, bank = 0
  • Matrix at $78..$89 (post-L6301):
    • row 0: (16382, 0, 0)
    • row 1: (0, 32760, 100)
    • row 2: (0, -401, 8190)
  • Section base at $4A..$52 (24-bit signed):
    • base[0] = -257793
    • base[1] = -138241
    • base[2] = 1396736
  • $66/$67=0, $68/$69=48, $6A/$6B=-3819 (camera-relative section origin)
  • ViewDirection ($0A70) = $0F = 15 at boot (NOT 0 -- earlier recovery text was wrong). chunk5 SetupViewProjection scales it x16 into a byte-angle ($3E=$F0=-22.5deg) and feeds it into the yaw/pitch/bank cascade via L6155. The port's sceneryAttachCamera ignores ViewDirection entirely -- this is the most likely root cause of the port-vs-MAME matrix mismatch.

Code changes landed this session

port/src/sceneryVm.c

  1. sceneryAttachCamera matrix block (around line 1255-1322): refactored so chunk5 L6301 column shifts (col 0 >>= 1, col 2 >>= 2) apply to BOTH the int8 pipeline matRow1/matRow2 AND the int16 writableRam mirror at $78..$89, in lockstep. Single source of truth.

  2. doHeader zero-skip guard (around line 354-380): when state->sceneryFile source range is entirely zero (= unused file block in .blocks indirection), skip the copy. Prevents clobbering destination $A84E+ with zero-byte garbage that the interpreter would mistake for $00 vertex_emit ops.

Active investigation: #9 — port matrix construction

Tooling

  • port/bin/matrixProbe <yaw_byte> <pitch_byte> <bank_byte> [wx wy wz] runs the port's sceneryAttachCamera and dumps $78..$89. Build with make -C port bin/matrixProbe.
  • port/bin/fs2trace --matrix <yaw_i16> <pitch_i16> <bank_i16> <vd_byte> runs the original chunk5 SetupViewProjection on the in-project 6502 emulator (the same fs2trace already used for loader tracing), using tmp/capture_boot.bin as the RAM image. Byte-perfect ground-truth oracle for any (yaw, pitch, bank, VD) input. Build with make -C port bin/fs2trace.
  • tmp/mame_capture.lua accepts MAME_POKE_VD and MAME_POKE_YPR for pinning ViewDirection / attitude angles continuously when capturing fresh references.

Findings (2026-05-07 second session)

  1. VD doesn't matter at boot. Re-captured MAME with VD pinned to 0 (tmp/capture_boot_vd0.bin). Matrix at $78..$89 is IDENTICAL to the VD=15 capture: [16382,0,0; 0,32760,100; 0,-401,8190]. The small off-diagonal terms in MAME do NOT come from ViewDirection.

  2. chunk5 and port use DIFFERENT Euler conventions. Verified with the oracle by sweeping each input to 90 degrees while the others are zero:

    ZP slot chunk5 axis Port cam-> field
    $6C/$6D "yaw" rotation around X cam->pitch
    $6E/$6F "pitch" rotation around Z cam->bank
    $70/$71 "bank" rotation around Y cam->yaw

    The disassembly's labels are misleading. chunk5's "yaw" really tilts up/down (X-axis = standard pitch); chunk5's "bank" really spins about world up (Y-axis = standard yaw); chunk5's "pitch" really rolls (Z-axis = standard bank).

  3. The boot M12=100 / M21=-401 is from chunk5 yaw=$FF93 (-109/16b). That value is a tiny X-axis rotation (~0.7deg upward tilt). chunk5 places the small term in M12/M21 (Y-Z plane). The port treats yaw as Y-axis rotation and would place the same magnitude in M02/M20 (X-Z plane). Both matrices are CORRECT for their convention -- just expressed in different coordinate frames.

  4. At zero angles (yaw=pitch=bank=0, VD=0) the oracle and port matrices match within rounding (essentially identity with the col 0 >>= 1, col 2 >>= 2 shifts). They diverge only when angles are non-zero AND map to different axes.

MAME draw-list capture findings (2026-05-07 evening session)

Used MAME lua hooks to install a 6502 logger that JMP-traps DrawColorLine ($795A in patched chunk5) and records each call's $E9-$EC (screen coords) and $CB-$D9 (V1/V2 3D coords) into a buffer at $B500. lua dumps the buffer per frame to tmp/mame_drawlist.txt. Same for cursor trajectory hook at $6772 in tmp/mame_cursor_trace.txt.

What we learned:

  1. MAME absolutely DOES draw chunk5 polygon scenery at boot. Hires page in tmp/capture_boot.bin rows 101-130 are rich with line-pattern bytes — that's the actual scenery. The "MAME doesn't draw" conclusion from earlier fs2trace --scenery was a dead end caused by fs2trace not emulating Apple IIgs language-card bank switching for $05 ADF -> chunk3 LookupADFStation calls.

  2. At Meigs, MAME walks the dispatcher into a section at ~$B294 and emits ~75 line draws per frame. Cursor trajectory: $B294 -> $B504 (one section, lots of $40/$41 vertex emits with intermixed $13 culls).

  3. Port wasn't chaining V1 from V2 after $41 emits, so polylines degenerated into fans. chunk5's EmitClippedLine cleanup at L6B2F overwrites V1 ($C9..$D2 / port: $CB..$D0) with V2's shadow so the next emit chains correctly. Fixed in doEmitV2.

  4. Port and MAME enter DIFFERENT sections from the outer dispatcher. Port hits a $0B JumpRelative at $AB17 -> $BADA; MAME ends up at $B294. With USE_RAM_STATE (= MAME's exact matrix + base + camera origin) the 3D vertex coords still don't match -- port produces values ~5x MAME's magnitudes, suggesting chunk5TransformVertex7EBC (port's C transliteration of the $7EBC asm) has bugs.

  5. The captured chunk5 RAM at $7EBC differs from the assembled source. Earlier hypothesis: "Apply64KPatchTable relocates TransformVertex7EBC" -- VERIFIED FALSE. The 64K patch table has no entry targeting $7EBC or $80C5. The runtime divergence must come from something else -- likely a $25 SceneryOpStoreImmWord or $1A SceneryOpWriteWord in early-boot scenery writing into the chunk5 code area, OR the captured RAM image was taken from a savefile / mid-run state where chunk5 had been mutated. We've since built a bit-perfect --xform oracle running the source chunk5 binary via FS2TRACE_USE_ORIG=1; that's the correct reference for byte-level verification.

Remaining work

  • Compare port's vertex transform output to MAME's by feeding both the SAME vertex bytes + state, then diff intermediate accumulator values. Use tmp/mame_drawlist.lua (V1/V2 capture) as the reference; instrument port's chunk5TransformVertex7EBC to dump pre/post-multiply state for the same input.
  • The discrepancy between port and MAME entry sections probably has the same root cause -- the port walks a different dispatcher path because some opcode handler (cull, sub-invoke, or store-imm-word) diverges from the asm's behavior.

Concrete bug reproducer for chunk5TransformVertex7EBC

fs2trace --xform <stream_addr> [ram.bin] runs the asm $7EBC routine on the unpatched chunk5 binary using captured RAM state (everything except the chunk5 code regions that contain the routine). It overlays the original chunk5 binary at $6000-$B27F so the asm executes source-faithfully against MAME's matrix/base/camera. Inputs:

  • vertex bytes at $B28F: 40 B0 08 23 FD (op $40 + xLo $B0 + xHi $08
    • zLo $23 + zHi $FD)
  • state from tmp/capture_drawlist.bin (frame 11500 dump):
    • matrix: (16382,0,0 / 0,32760,100 / 0,-401,8190)
    • base ($4A..$4C MID/HI/LO): D0 CC FF
    • base ($4D..$4F): 90 00 00
    • base ($50..$52): 60 F4 FF
    • camera ($66..$6B): 00 00 04 00 21 01

Bug found and fixed (2026-05-07 night): op_l1818 in chunk5Transform.c had 7 shift-add iterations in its main loop; chunk4.s L1818 has only 6 (between labels L183A and L185D), plus one final lsr+ror at L1864. The extra iteration shifted every multiply result right by one bit, halving it. After the fix port and asm produce bit-identical output for the matched test case: V=(-12033, 160, -3224) for both. Verified by adding step-by-step intermediate trace to both port and fs2trace --xform and walking through one call.

Status post-fix: chunk5TransformVertex7EBC now byte-identical to asm for at least one test case. 42 chunk5 line draws produced at boot Meigs (vs 51 with the bug, but those were wrong-positioned). Visible scenery still doesn't match MAME because port's chunk5 dispatcher walks INTO different sections than MAME's -- port enters $BADA via $0B JumpRelative; MAME enters $B294. Same bytecode, different cull-test outcomes upstream. That's the next bug to find, not a multiplier issue.

Tooling now available

  • port/bin/fs2trace --xform <addr> [ram.bin] — runs asm $7EBC oracle. Use frame-matched RAM state from tmp/capture_drawlist.bin (= dumped by mame_drawlist.lua at the same frame as the draw list).
  • port/bin/fs2trace --scenery [ram.bin] — counts DrawColorSpan calls across one chunk5 ProcessScenery pass.
  • port/bin/fs2trace --matrix yaw pitch bank vd — already validated bit-perfect.
  • port/bin/fs2trace --zpscale a b — already validated bit-perfect.
  • port/bin/fs2trace --l177b a x — already validated bit-perfect.
  • tmp/mame_drawlist.lua — captures MAME line draws + V1/V2 3D coords; also dumps RAM at end of capture frame. Run via mame apple2gs ... -autoboot_script tmp/mame_drawlist.lua.
  • tmp/mame_cursor_trace.lua — captures dispatcher cursor trajectory.

B1 status (landed 2026-05-07)

The actual divergence wasn't an Euler-order issue, it was a transpose convention. chunk5 stores R (camera-to-world) at $78..$89; the port's cam->rot stores R^T (world-to-camera) so its cameraTransform can multiply (dx,dy,dz) directly. Same data, transposed access.

Implementation:

  • CameraT now carries a sibling int16_t rotChunk5[3][3] (R, no transpose). cameraUpdate writes both -- one assignment block per shape, no extra trig.
  • sceneryAttachCamera mirrors cam->rotChunk5 (NOT cam->rot) into writableRam[$78..$89]. The renderer's int8 projection rows (matRow1/matRow2) keep coming from cam->rot so projection math is unchanged.
  • cameraTransform is untouched -- still reads cam->rot.

Verification (port matrixProbe vs chunk5 fs2trace --matrix, clean RAM, all-zero baseline):

Test Port matrix chunk5 matrix Match?
yaw=64 (Y+90 deg) (0,0,8191/0,32766,0/-16383,0,0) (0,0,8191/0,32765,0/-16383,0,0) yes (+/-1)
pitch=64 (X+90 deg) (M11=0, M12=-8192, M21=32767) (M11=401, M12=-8191, M21=32758, M22=100) shape yes, residual no
bank=64 (Z+90 deg) (M00=0, M01=-32766, M10=16383) (M01=-32765, M10=16380, M12=100, M20=-201) shape yes, residual no

Open sub-issue resolved: bit-perfect chunk5 transliteration landed.

The residual was an artifact of comparing port output to a CAPTURED MAME RAM dump (frame 13000) where chunk5 has been heavily patched at runtime by Apply64KPatchTable. The patched routine differs from the chunk5.s source. Source-faithful comparison (port vs unpatched chunk5 binary running on fs2trace's 6502 sim) is now bit-perfect.

Bit-perfect chunk5 SetupViewProjection in C

port/src/chunk5Setup.c is a transliteration of:

  • chunk5.s SetupViewProjection (lines 203-432) -- the full cascade.
  • chunk4.s ScaleC2ByC4 / ZPScale (lines 1565-1744) -- 16-bit shift-and-add multiply. Bit-perfect against fs2trace --zpscale for arbitrary inputs.
  • chunk4.s L177B / L1778 / L17BC / L17DA / L17E1 (lines 1900-2007) -- cos/sin lookup with sub-byte interpolation, including the special X=$80 midpoint-average path. Bit-perfect against fs2trace --l177b over a 256-case sweep.
  • chunk4 cos table (132 bytes from offset $141A in out/4_0200-25ff).

Validation: make -C port bin/chunk5SetupTest && bin/chunk5SetupTest. All test cases pass. The test driver shells out to fs2trace for oracle values; running fs2trace --matrix with FS2TRACE_USE_ORIG=1 (load unpatched chunks, not the captured RAM) gives the source- faithful reference.

cameraUpdate now calls chunk5SetupViewProjection to populate cam->rotChunk5; sceneryAttachCamera mirrors that into writableRam[$78..$89]. The renderer pipeline still uses the existing cam->rot (= R^T, world-to-camera) for vertex projection.

The captured-RAM comparison is no longer the right reference -- use the unpatched chunk5 binary via FS2TRACE_USE_ORIG=1.

Files NOT to delete

  • tmp/mame_capture.lua — capture script
  • tmp/capture_boot.bin / .zp — MAME ground-truth state
  • tmp/mame_boot.png / mame_meigs_ref.png — MAME ground-truth screenshot
  • tmp/compare_mame_vs_port_ramstate.png — side-by-side comparison
  • port/screenshots/match_mame_ramstate.png — port's best-effort match
  • port/sceneryRam_FS2.1.bin — original port-side FS2.1 RAM dump (NOT MAME's; do not overwrite)
  • port/sceneryRam_FS2.1_chicago.bin — original port-side chicago RAM dump

Remember

  • Port lives outside git; don't run git on it.
  • Scratch files go in ./tmp/, not /tmp/.
  • Screenshots go in port/screenshots/.
  • The port uses fixed-point math; don't introduce float reinterpretations.

NEVER Read PNGs (avoids the API context corruption)

The user views PNGs directly. Claude must NOT use the Read tool on PNGs -- each multimodal image upload bloats the request and has tripped a recurring "PNG-API context corruption" failure that nukes the session.

Workflow:

  • Compare two images (text report, ASCII heatmap, auto-resizes mismatched scales): 
    cd /home/scott/claude/flight
port/tools/imgDiagnose.sh diff tmp/mame_boot.png port/screenshots/match_mame_ramstate.png --ascii
  • Single-image summary (non-black coverage, luminance histogram, horizon-row guess): 
    port/tools/imgDiagnose.sh stats tmp/mame_boot.png
  • Inputs may be .png, .ppm, or .pgm. PNGs are converted via ImageMagick into a temp PPM in tmp/ that the C tools read. Tools live at port/tools/imgDiff.c / imgStats.c and build into port/bin/ via make -C port tools (auto-built on first wrapper run).
  • The port already writes PPMs from --screenshot -- prefer those over re-encoding to PNG when possible.