# 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`.