AI_Slop/fs2port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
fs2port/SESSION_RECOVERY.md
Scott Duensing b4ddd15710 Docs updated.
2026-05-14 10:13:07 -05:00

4.4 KiB
Raw Blame History

FS2 Port Session Recovery

This file is the entry point for resuming work after a session break. Updated 2026-05-14.

How to recover

  1. Read this file (current state + ground rules).
  2. Read ~/.claude/projects/-home-scott-claude-flight/memory/MEMORY.md and follow the indexed entries that are relevant to the current task.
  3. Read port/PORT_STATUS.md for the per-feature port-vs-original table.
  4. Read port/PORT_64K_AUDIT.md if working on 64K-mode patch hooks or the scenery VM's $03 / $0E opcodes.

Current state (2026-05-14)

The port is feature-complete against FS2 for most subsystems. See port/PORT_STATUS.md for the detailed comparison. Highlights:

  • Rendering: 36/36 pixel-exact line matches vs MAME at boot Meigs via a 5-plane frustum line clipper with chunk5ScaleC2ByC4 plane-snap (see memory project_fs2port_frustum_clip.md). Palette-buffer rendering by default; SCENERY_NTSC=1 reverts to true HIRES decode.
  • Scenery demand-load: default-on; port/src/sceneryVm.c::doHeader pulls section bytes from the .SD file on every HEADER opcode. All FS2.1 region variants share the FS2.1 .SD source via sdSourceFile in RegionMetaT. Set SCENERY_DEMAND_TRACE=1 to log fires.
  • Instruments: all FS2 gauges drawn except oil temp/pressure. VOR2/ADF gauge mode-gating on ac->adfMode matches FS2 behaviour.
  • WW1 ace mode: bullets, bombs, AI fire, damage, drop-with-velocity.
  • Modes: full edit mode (F7) via editor.c; title/config screen via title.c; crash recovery snapshot (Space when crashed).
  • Recent cleanup pass: dead code removed (ww1aceDropBomb, Coord16T/VertexT, DEG2RAD, rendererSwapFillColors); shared helpers consolidated into camera.h / font.h / fs2math.h; 19-branch SCENERY_REGION strcmp chain replaced with table-driven sceneryDataRegionFromName.

Files NOT to delete

  • tmp/mame_capture.lua - MAME 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

Ground rules

  • Port lives outside git - don't run git on port/. The disassembly side (src/, out/) IS tracked; make validate enforces byte-identity there.
  • Scratch files go in ./tmp/ inside the project, NOT /tmp/.
  • Screenshots go in port/screenshots/, never port/ or /tmp/.
  • Port uses fixed-point math - don't introduce float reinterpretations of 6502 fixed-point values; translate the math directly. See memory feedback_port_fixed_point.md.
  • Byte-identical validation discipline applies to the disassembly side: every change to src/chunk*.s must keep make validate green. See memory feedback_byte_identical.md.

NEVER Read PNGs (avoids 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 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.

Historical archive

Pre-2026-05-13 session journals documenting the scenery-rendering breakthroughs (matrix construction, $07 EnterLocalFrame variants, $23 SceneryOpJumpIfBitsClear, $42 RefreshCachedXform, $04 CullByOutcodeList, frustum clip, etc.) are now indexed in the memory system rather than journaled here. Each significant finding has a dedicated memory note under ~/.claude/projects/-home-scott-claude-flight/memory/project_fs2port_*.md.