goldeneye-pc-port/docs/HANDOFF.md

Handoff brief — GoldenEye 007 PC port (Phase 2: Session L — D88.1-3

VERIFIED (uncommitted), D88.4 is the new blocker)

Paste-ready brief. Authoritative context: AGENTS.md, docs/PCPortResearch.md §F (D69, D78-D88), docs/BRIEF-D69-stage-load.md.

READ THIS FIRST — verified but uncommitted work in the tree

The D88 Usetup*Z converter work is now format-verified and passes the -level_09 repro up to a new, further-along crash (D88.4) — but it is still uncommitted (carried through two interrupted sessions). This session (2026-08-28) built it, ran it, and confirmed the fix works; it did not commit (left to the resuming session so it can bundle D88.4).

git status shows:

• Modified: port/src/pccg.c, src/bondtypes.h, src/game/bondview2.c, src/game/bondview_r.c, src/game/prop.c, src/game/stan.c
• New/untracked: tools_pc/d88_emit.py

What is verified working (see PCPortResearch.md §F D88.1–D88.3):

• Tree compiles green: export PATH="/c/msys64/mingw64/bin:$PATH" && ./build-pc.sh ntsc-final.
• tools_pc/d88_emit.py (531 lines) is a complete converter; its output is already in data/pccg-ntsc-final/manifest.csv (21 Usetup*Z rows). port/src/pccg.c PCCG_MAX_FILES 128→256 lets the sidecar carry them.
• -level_09 + GE_D88=1 confirms proplvreset2 now walks the entire pads table correctly — real plink strings (p1988e, p12295e, …) and sane BUNKER1 world coords. The old prop.c:1306 crash is gone.
• SetupIntroCamera narrow-u32 #ifdef PORT fields: write-before-read claim verified against bondview_r.c:276-300 (all three fields written — prev link + both langGet() results — before any read).

THE NEW BLOCKER — D88.4: -level_09 now crashes in setupDoor (prop.c:971) → modelLoad (loadobjectmodel.c:335), garbage modelid into PitemZ_entries[]. Root cause: d88_emit.py deliberately leaves the propDefs polymorphic record stream as an un-byteswapped passthrough (its docstring defers the per-type bswap + PC/N64 sizeof audit of ~40 prop-def record types). door->obj is read big-endian → garbage. Same class as D87/D88.1. Full detail + fix plan in PCPortResearch.md §F D88.4. Also see D88.5 (stan tile lookups all miss during pad setup — watch, may be a related residual bug).

Next steps for the resuming session:

1. Read PCPortResearch.md §F D88.1–D88.5 (fully rewritten this session).
2. Fix D88.4: spec each propDefs record type, add per-type byteswap (+ intro polymorphic records) to d88_emit.py, audit struct sizes. Regenerate the sidecar (delete the Usetup rows from manifest.csv + their bytes first, or rebuild from d69_emit.py, then re-run python tools_pc/d88_emit.py ntsc-final).
3. Re-run -level_09; expect 1–2 more crashes down the prop-setup chain.
4. Once BUNKER1 loads without fault, commit the whole D88 bundle in sub-milestones (format spec → converter → port wiring → probes), §F D-labeling.
5. Then the render bugs (D75, below) and D85 become the path to a playable frame — see the expanded D75 note below and in §F.

Known rendering bugs (D75 — still open, orthogonal to the D88 crash)

Even once the crash chain is cleared, the front end has broken 3D model rendering (user-confirmed this session):

• Rareware logo: correct (fixed in D73/D74).
• Nintendo logo: renders but mispositioned.
• Gun-barrel intro: the James Bond character model is missing entirely.
• Intro credits / cast roll: the per-character 3D models do not appear at all (names draw, models don't). Pattern: textures/text draw; animated/skeletal character models never appear; static 3D (logos) appears but with a bad transform. Leading hypothesis is D75(b) — the animated-model path (animInit + raw offsets into struct player, cf. D56) is broken independently of the D73 matrix sin/cos fix. Full triage plan in PCPortResearch.md §F D75.

The rest of this document (below) is the last known-good, committed status as of commit 8c9c6a2c (D86+D87 resolved) — still accurate except D88 is now further along (D88.1–3 done/verified, D88.4 is the live crash).

Where things stand

D69 (the original "stage load faults" milestone blocker) remains RESOLVED. load_bg_file (bg.c) doesn't fault on BUNKER1. Since then, two more crashes further down the load chain were found and fixed this session (D86, D87), and a third — the current blocker — was root-caused but not fixed (D88).

D86 RESOLVED. modelInitRwData crash (model.c:6174) was a single truncating pointer cast in the player's embedded gait/arm model: src/game/initplayergaitobject.c:5 did player_gait_object_header.RootNode = (int)&player_gait_hdr; — a same-width no-op on N64 that truncates+zero-extends a real 64-bit pointer on PC. Fixed with a narrow #ifdef PORT branch assigning the pointer directly. Root-caused via a new node-walk trace (GE_D86=1, left in place, gated in model.c/objecthandler_2.c).

D87 RESOLVED. Once D86 stopped blocking progress, an idle (no-input) run eventually triggers the front-end's genuine attract-mode demo playback (select_ramrom_to_play() picks a random compiled-in demo — this is shipped retail behavior, not a debug feature) and crashed in ramrom_replay_handler (ramromreplay.c). Root cause: ramromfilestructure is a real ROM-compiled asset (big-endian, like everything else) loaded via romCopyAligned() — a raw byte copy by design (D66) — with no byteswap, so every multi-byte field read back scrambled (e.g. size_cmds 2 → 33554432) and drove wild pointer arithmetic. Fixed with a #ifdef PORT ramromFixupEndian() called once after the load (same pattern as the D54 cseq fixup). Not BUNKER1-specific — attract mode picks any of 7 demo locations at random, so don't rely on it for BUNKER1-specific testing (see -level_09 below).

D88 — SUPERSEDED, see "READ THIS FIRST" at top. D88.1–D88.3 (header + sub-table width/endian conversion) are now done and verified; D88.4 (propDefs byteswap) is the live blocker. The paragraph below is the original root-cause writeup, kept for context.

D88 (original writeup) — root-caused. Launch with -level_09 (NTSC LEVELID_BUNKER1 = 9; boss.c:199-339 decodes -level_XX into g_StageNum, bypassing the front end/attract-mode entirely — fast, deterministic BUNKER1 repro, crashes in well under a minute instead of waiting ~2 min for attract mode to maybe pick Bunker). Crash: proplvreset2 (prop.c:1306) segfaults reading g_CurrentSetup.pathwaypoints[i1].padID. Root cause: the per-level "Usetup<name>Z" file (prop.c:1267, struct stagesetup in bondtypes.h:4091) is loaded as raw ROM bytes and has zero PC porting work done on it — unlike bg/stan (D69/D80-82) and models (D43/D50). Two compounding problems, not just one:

1. The 10 top-level fields (pathwaypoints/waypointgroups/intro/ propDefs/patrolpaths/ailists/pads/boundpads/padnames/ boundpadnames) are declared as real pointers in the live C struct, so on PC they're 8 bytes each (an 80-byte header) instead of the file's real 4-byte-each (40-byte) N64 layout — same class as D79 (bg_room_data pointer growth). Field 0 reads fine; everything after it is reading the wrong bytes entirely.
2. The 4 meaningful bytes each field does store are big-endian (the code's own comment: "stores every internal reference as a byte offset from the start of the file") and nothing byte-swaps them — same class as D87. No PORT/byteswap handling exists anywhere in prop.c (confirmed by grep). Not fixed this session — this is D69-scale format-conversion work: a byte-accurate spec of the whole Usetup*Z format (top-level header + every nested sub-table: waypoint/waygroup/PropDefHeaderRecord/ PathRecord/AIListRecord/PadRecord/BoundPadRecord/pname, each likely with its own internal offsets not yet audited) plus either an offline converter sidecar (preferred pattern per AGENTS.md, same shape as tools_pc/d69_emit.py) or a careful runtime fixup pass that parses the raw 40-byte N64-packed header by explicit byte offset, byte-swaps each field, and writes results into the PC-widened struct.

Net effect vs. last session: the game now runs substantially further — all the way through room-streaming setup, past the intro's model pipeline, and into per-level "Usetup" data — before hitting D88. The "loads without fault" acceptance bar is still not met, but the remaining blocker is now narrowly scoped and has a fast, deterministic repro (-level_09, no attract-mode wait, no depending on which random demo attract-mode picks).

Recommended next steps, in order

1. D88. Get a byte-level spec of Usetup*Z (start from BUNKER1's file; strResource is built as "U" + "sev" + "Z"-style name in prop.c:1253-1265 — check setup_text_pointers[LEVELID_BUNKER1] for the exact literal). Decide offline-converter vs. runtime-fixup (D69's bg/stan work is the template for the former; D54's cseq fixup is the template for the latter — given the struct-width mismatch on top of the byteswap, a runtime fixup that manually walks the raw 40-byte N64 header by hand (not through the live stagesetup struct) into a freshly-populated g_CurrentSetup is probably simpler than a full sidecar here, but verify against a raw ROM hex dump either way).
2. Once BUNKER1 loads past proplvreset2, re-check for further crashes in the same vein (this session found 3 in a row — D86, D87, D88 — each only reachable after the previous one was fixed; expect more).
3. Once BUNKER1 reaches a rendered frame with no fault, revisit D85 (room primary/secondary GDL binaries decode to garbage via texLoadFromGdl) — use GE_PCDUMP="<range>:10" + tools_pc/pixcount.py to confirm non-black, non-degenerate content per the original D69 acceptance bar. (This session's GE_PCDUMP captures around frame 2100-2400 during attract-mode-driven "loading" were still on a HUD/menu screen, not real 3D geometry — don't read too much into pixel counts from before D88 is fixed.)
4. Do NOT touch D75/D76/D77 (parked, lower priority, unrelated).

Debug tooling added this session (kept, env-gated, zero cost when unset)

• GE_D86=1 — node-walk trace in modelInitRwData (model.c) + a load-identity probe in load_object_fill_header (objecthandler_2.c). Resolved the D86 crash; left in place since the same load_object_fill_header/modelInitRwData pipeline could surface new edge cases as more of the game becomes reachable.
• GE_D87=1 — block-setup trace in iterate_ramrom_entries_handle_camera_out and consumer trace in ramrom_replay_handler (ramromreplay.c). Resolved the D87 crash; left in place as it's a rarely-exercised path (attract mode) worth having visibility into if it acts up again.
• Pre-existing GE_D69STAN=1, GE_D69BB=1, GE_D69=1 — unchanged, still useful for the bg/stan/D85 load path (see prior session's HANDOFF entries, preserved in git history, for exactly what each logs).

New: fast, deterministic BUNKER1 repro (no attract-mode wait)

Launch with -level_09 as a program argument (./build-pc/ge007.x86_64.exe -level_09) to skip the front end/attract mode and load BUNKER1 directly — boss.c:199-339 decodes -level_XX (the two digit-chars are consumed as raw ASCII bytes: g_StageNum = tokenFindLevel[0]*10 + tokenFindLevel[1] - 0x210; NTSC LEVELID_BUNKER1 = 9 → "09" since '0'*10 + '9' - 0x210 = 9). This is now the preferred way to test BUNKER1-specific load/render work — it's faster (crashes/completes in well under a minute vs. ~2+ min waiting on attract mode) and deterministic (not dependent on which of 7 random demo locations attract mode happens to pick).

Environment / build

• export PATH="/c/msys64/mingw64/bin:$PATH" && ./build-pc.sh ntsc-final (~5 s). Build is GREEN with all D86/D87 work included.
• Run from the repo root, not build-pc/.
• Regenerate sidecars if missing: python tools_pc/d69_emit.py ntsc-final (bg/stan) and the D43/D50 model sidecar generator (pcmodels) — both gitignored, not checked in. (Both were already present in this dev environment this session.)
• GE_PCDUMP="<start>-<end>:<stride>" + tools_pc/pixcount.py for frame captures once D88 is fixed and a frame actually renders real BUNKER1 geometry.
• Crash log: ge007.crash.log (repo root); symbolicate with addr2line -e build-pc/ge007.x86_64.exe -f -C <pc> (image base 0x140000000).
• gdb launch mode is too slow for timing-dependent bugs (unchanged guidance). New this session: gdb attach mode (gdb -batch -x cmds.txt -p <winpid>, <winpid> = 4th column of ps -p <bashpid>) works well and is fast for "watch a global for a legitimate vs. corrupted write" questions on an already-running, not-yet-crashed process — see docs/PCPortResearch.md §F environment reminders for the exact recipe used to root-cause D87.

Non-negotiables (unchanged, see AGENTS.md)

1. N64 build files untouched.
2. Game logic unmodified except narrow, documented #ifdef PORT ABI/layout exceptions (D86/D87 this session, both logged in PCPortResearch.md §F). D88 is explicitly not patched with a quick inline hack — it needs the same disciplined spec-then-convert/fixup treatment as D69, logged as an open finding instead per AGENTS.md's "stop and write it up" guidance for anything beyond a narrow, obviously-correct exception.
3. Offline sidecar conversion preferred over runtime fixup for whole ROM-asset formats (D69/D80-82 pattern) — likely the right call for D88 too, though a careful runtime fixup is also plausible; decide after the byte-level spec work.