goldeneye-pc-port/docs/PLAN-linear-level-sweep.md

PLAN — Linear pass: boot → menu → every solo level loads & renders

Paste-ready brief for a fresh session. Pivot from depth-first (BUNKER1 + graphics rabbit-holes) to breadth-first: make the normal player path work end-to-end (intro → credits → main menu → mission/level select), then confirm all 21 solo levels load and render without crashing. Turns the remaining work into a scoped list.

Preflight (unchanged)

CLAUDE.md + AGENTS.md non-negotiables → docs/HANDOFF.md → docs/PORT-LEARNINGS.md → docs/AGENT-WORKFLOW.md before any subagent.

Scope decisions (locked with the user)

• Intro / credits / menus: bar is functional, not crashing. Menus navigable start to finish; the intro is skippable with any button. Cosmetic defects are out of scope here — log them in docs/GRAPHICS-BACKLOG.md: gun-barrel Bond model missing (D75), Nintendo-logo transform (D75), mirrored glyphs (D114/D116), no audio (D77), partial disclaimer screen (D76).
• Text X-mirror (D114/D116): stays parked. Menus are navigable with mirrored text.
• Level sweep depth: load + render + no immediate crash only. A "soak" is pointless with no input (level triggers never fire). Play-to- completion validation is a separate human step (complex input), driven by a per-level checklist this plan produces (WS6).
• N64 reference captures: deferred. Use PC golden frames + tools_pc/framediff.py; eyeball against memory/video for "matches original". tools_pc/mupen64/ is available if a level looks wrong.

Facts established (exploration, this session)

Front end is a stage — LEVELID_TITLE (0x5A). Logic in src/game/front.c (~8700 lines) + src/game/title.c (gun-barrel/logo 3D) + src/game/ramromreplay.c (attract demos). State machine = MENU_* enum (src/bondconstants.h:1831), driven per frame by menu_init() (front.c:8536) through three switch tables (update_/init_/interface_ menuXX_* at front.c:8598/8637/8666); rendered by menu_jump_constructor_handler() (front.c:8718). Transitions: frontChangeMenu(menu, reload) (front.c:8513). Boot entry: initgamedata.c:9 sets menu_update = MENU_LEGAL_SCREEN.

Intro states (each: init_ loads assets, interface_ advances on timer OR any button, constructor_ renders): MENU_LEGAL_SCREEN → NINTENDO_LOGO → RAREWARE_LOGO → EYE_INTRO (gun-barrel walk, "007", blood) → GOLDENEYE_LOGO → DISPLAY_CAST (credit roll) → idle → select_ramrom_to_play() (attract demo). Any button during intro sets prev_keypresses → logos short-circuit to MENU_FILE_SELECT, cast roll skipped. Gun-barrel sub-state machine is gunbarrel_mode (u8) in title.c (insert_bond_eye_intro title.c:297, renderGunbarrelEyeIntroSequence title.c:608).

Menu → level launch: mission select → selected_stage = mission_folder_setup_entries[…].stage_id (front.c:3301) → MENU_DIFFICULTY → MENU_BRIEFING / MENU_007_OPTIONS → init_menu0B_runstage() (front.c:6900) → bossSetLoadedStage(selected_stage) → g_MainStageNum → bossMainloop inner loop exits → g_StageNum = g_MainStageNum (boss.c:647) → lvlStageLoad. Level → level always routes back through the front end (MENU_MISSION_COMPLETE, interface_menu0D_missioncomplete front.c:7119; auto-advance scans mission_folder_setup_entries for the next stage_id >= 0). No direct in-stage jump.

21 solo levels; LEVELID value == -level_XX number (boss.c:337 decode d0*10 + d1 - 0x210). Mission order + numbers: Dam 33, Facility 34, Runway 35, Surface1 36, Bunker1 09, Silo 20, Frigate 26, Surface2 43, Bunker2 27, Statue 22, Archives 24, Streets 29, Depot 30, Train 25, Jungle 37, Control 23, Caverns 39, Cradle 41, Aztec 28, Egypt 32, Cuba 54. Enum: src/bondconstants.h:1633-1685; mission table mission_folder_setup_entries[] front.c:434-466.

Per-level memory args already have a table — memallocstringtable[] (boss.c:101-142), one row/LEVELID (-ml -me -mgfx -mvtx -mt -ma). The auto-inject loop boss.c:369-414 already selects the right row per stage load — but it is gated on g_DebugAndUpdateStageFlag, which the port only sets when -level_ is absent (boss.c:199-202; rmonGetToken() → 0 on PC, port/src/n64stubs.c:134). So bare -level_09 today uses default pools; hence the manual -ml0 -me0 -mgfx100 -mvtx50 -mt700 -ma150 in the HANDOFF repro line. Documented TODO: PCPortResearch.md §H (D95 area) and docs/HANDOFF.md "Next task".

D88.4 is a cross-level blocker. Every level's Usetup*Z feeds the propDefs polymorphic record stream, which tools_pc/d88_emit.py deliberately leaves un-byteswapped. BUNKER1 crashes in setupDoor (prop.c:971) on a garbage BE door->obj. Any level hits the same class when its prop set is walked. Groundwork: tools_pc/d88_propdefs.py, tools_pc/d88_layoutprobe.c (machine SZ/PTR lines), tools_pc/d88_propdef_scan.py (per-level type histogram). Placeholder sizes still to resolve in d88_propdefs.py: VEHICLE/AIRCRAFT/TANK/AMMO/DEPOSIT_IN_ROOM.

Tooling: GE_PCDUMP="a-b:step" → ./ppm/ (port/src/video.c:181); tools_pc/pixcount.py (non-black pixel count / content check), tools_pc/framediff.py (structural regression vs tools_pc/golden/ — the port is NOT frame-deterministic, D117), tools_pc/ppm2bmp.py. Crash log ge007.crash.log; symbolicate addr2line -e build-pc/ge007.x86_64.exe -f -C <pc> (image base 0x140000000). Objectives: propDefs PROPDEF_OBJECTIVE_* (bondconstants.h:4332), status src/game/objective_status.c (get_status_of_objective() :161) — needed only for WS6.

Workstreams

WS1 is a prerequisite for all. WS2 (front.c/title.c/lv.c/ ramromreplay.c/initmenus.c/port/) and WS3 (tools_pc/d88* + narrow prop.c) are disjoint → parallelisable. WS4 depends on WS3. WS5 iterative. WS6 is the user's.

WS1 — Frictionless per-level boot (small, first)

Goal: ./build-pc/ge007.x86_64.exe -level_XX with no other args boots any level with its correct pools.

Change: in src/boss.c under #ifdef PORT, also set g_DebugAndUpdateStageFlag = 1 when -level_ is present (mirror of boss.c:199-202). The existing loop boss.c:369-414 then supplies the right memallocstringtable row per stage; the generic preload at boss.c:207-210 is harmless (per-loop tokenSetString at :413 overrides). Debug-harness / ABI-class #ifdef PORT edit (same character as the -level_ ASCII parse already in the file). Document as a new Dxx in PCPortResearch.md §F. Alt if boss.c is judged out of bounds: synthesize the string in the port token layer (port/src/system.c sysGetTokenString). Boss.c is simpler and preferred.

Also update docs/HANDOFF.md repro line; drop the manual -m* list once verified.

Verify: -level_09 alone == today's full-arg behaviour (same frame, framediff.py green vs tools_pc/golden/).

WS2 — Front-end walkthrough & crash repair (human playtest loop)

Goal: a human can go boot → (watch or skip intro) → file/folder select → mode select → mission select → difficulty → briefing → level launches, and after a level, mission-complete → next briefing, with no crash / hang / dead-end. Cosmetic wrongness acceptable and logged.

Method: same loop as the M-10 input playtest — overseer builds, human drives, defects come back as a list, overseer root-causes each (expect the pointer-width / BE-rodata / N64-Gfx-sizing classes in PORT-LEARNINGS.md), narrow #ifdef PORT fix, re-test.

Files in scope: src/game/front.c, src/game/lv.c (interface_menu05_fileselect is here), src/game/title.c, src/game/initmenus.c, src/game/ramromreplay.c, port/src/*. NOT prop.c / tools_pc/d88* (WS3).

Human checklist:

1. Boot → legal → Nintendo → Rareware → gun-barrel → GE logo → cast roll → (idle) attract demo. Note any crash/hang; cosmetic noted separately.
2. Press a key during intro → confirm short-circuit to file select.
3. File/folder select: create a folder, enter it; folder-delete sub-UI; 30 s idle → back to legal screen.
4. Mode select → Mission select: page through all 20 mission entries, each briefing text/photo loads without fault.
5. Pick mission + Agent difficulty + briefing → Start → level loads.
6. In-level: die / abort → mission-failed → menu. Complete a short level (or cheat) → mission-complete → auto-advance to next briefing.
7. MP chain (lower priority): MP options → scenario/stage/char/handicap/ teams → MP match loads.

Do NOT fix here (log/confirm in GRAPHICS-BACKLOG.md): D75, D76, D77, D114/D116.

Deliverable: front-end crash list + root causes + fixes; GRAPHICS-BACKLOG.md updated with confirmed cosmetic state.

WS3 — D88.4 propDefs converter (cross-level blocker)

Goal: Usetup*Z propDefs converts correctly offline for all 21 levels so setupDoor / prop instantiation stops reading BE garbage.

Method: subagent brief, same shape as D69 / D88.1-3 (offline sidecar converter). Byte-spec every PROPDEF_* record type (~40, enum bondconstants.h), per-type field byteswap + pointer-width audit, extend tools_pc/d88_emit.py. Use d88_propdefs.py / d88_layoutprobe.c / d88_propdef_scan.py. Resolve the placeholder sizes (VEHICLE/AIRCRAFT/TANK/AMMO/DEPOSIT_IN_ROOM) via d88_layoutprobe.c.

Files: tools_pc/d88_emit.py, tools_pc/d88_propdefs.py, tools_pc/d88_layoutprobe.c, + narrow #ifdef PORT in src/game/prop.c if a struct-width mismatch surfaces (D79/D88 class).

Budget: structural — generous. On expiry: write up spec progress in §F/D88 with confidence rating.

Verify: -level_09 walks past setupDoor to a rendered BUNKER1 frame with props; spot-check 2-3 other levels' prop walk.

WS4 — Per-level load + render sweep

Goal: status matrix for all 21 solo levels — (a) lvlStageLoad completes without fault, (b) ≥1 non-degenerate frame renders, (c) survives ~300 frames / ~15 s with no input (immediate-crash check only).

Prereq: WS1 + WS3 landed.

Method: agent-driven, one level at a time (-level_XX). Each: launch GE_PCDUMP="1-300:30", capture ge007.crash.log, run pixcount.py. Record PASS / CRASH@ / RENDERS-EMPTY / HANG. Symbolicate every crash (addr2line). Group failures by root-cause class.

Deliverable: docs/LEVEL-STATUS.md — table (level, number, load, render, crash site, notes), refreshed as WS5 closes items.

WS5 — Per-level crash triage (iterative)

Goal: drive the WS4 matrix to "all 21 load + render".

Method: one focused investigation per distinct failure class (subagent brief per AGENT-WORKFLOW.md template; read PORT-LEARNINGS.md first). Expected classes: pointer-width struct growth in per-level assets, BE-rodata not converted, N64-Gfx/Vtx sizing, per-level pool exhaustion (memallocstringtable PC bumps, cf. D95). Fix = narrow #ifdef PORT or converter extension; document each in §F.

Verify per fix: target level's WS4 check → PASS and -level_09 framediff stays green.

WS6 — Human completion-validation pass (user-run, after WS4 green)

Goal: confirm each level is playable start to finish and matches the original — the part needing real input.

Deliverable produced for the user: docs/LEVEL-PLAYTEST.md — per-level checklist template: spawn point; each difficulty-gated objective (objective_status.c) reachable and registering COMPLETE; guards / props / doors behave; level exit / mission-complete fires clean; timing + layout match retail. User fills it per level; findings feed a WS5-style triage round.

Verification (overall)

• Per merged patch: export PATH="/c/msys64/mingw64/bin:$PATH" && ./build-pc.sh ntsc-final green, /linkcheck clean, single-frame GE_PCDUMP diff vs tools_pc/golden/ via framediff.py.
• WS1: -level_09 alone == old manual-arg behaviour.
• WS3: BUNKER1 renders props past setupDoor.
• WS4/WS5: docs/LEVEL-STATUS.md all 21 rows = load+render PASS.
• Regenerate sidecars after any converter change: python tools_pc/d43_emit.py ntsc-final && python tools_pc/d69_emit.py ntsc-final && python tools_pc/d88_emit.py ntsc-final --regen.

Out of scope (tracked elsewhere — do not start here)

• D75 / D76 / D114 / D116 / D77 and all docs/GRAPHICS-BACKLOG.md items.
• D118a/b input polish, rebinding, gamepad hotplug, ge007.ini.
• Weapon-model-doesn't-draw (AUDIT-M6 #5), rest of the struct player offset audit.
• Audio (Phase 3), saves/EEPROM (Phase 4), docs/BACKLOG.md (PC graphics options, co-op, netplay).