goldeneye-pc-port/docs/BACKLOG.md

All of these items should be completed once the main original game is playable from start to finish on PC with no crashing or major issues.

---

Playtest defects — logged M-28 (2026-08-30), not yet worked

User-reported during free playtest. Suggested priority order below (cheap input fixes first, then the texture correctness bug, then the filtering feature).

• B1 — texture filtering / "interlaced" shimmer (feature). Whole game has an interlaced/shimmering look. Want N64 3-point-filter emulation + bilinear/trilinear handling like the Nightdive / Quake-remaster ports. MVP: one good default filtering mode in port/fast3d/ (3-point emu shader or clean bilinear). Long-term: full toggle set (see "PC graphics settings" → Quality + stretch goals below). Biggest of the four.
• B2 — glitchy textures / wrong colors (correctness bug). Some textures render with wrong colors / garbage — very noticeable on Depot (-level_30), present in many other spots too. Likely a texture-decode/format bug (CI/TLUT, RZ decode port/src/rzdecomp.c, or the import_texture_* path in gfx_pc.cpp). Distinct from B1. Needs investigation — could be a real fidelity blocker, not cosmetic-parked.
• B3 — RMB aim far too mouse-sensitive. Manual-aim (RMB/LShift) mouse sensitivity is way too high. Input.MouseAimSpeed (default 50) still overshoots badly. Quick fix: lower default + recheck the aim-band curve in port/src/input.c (the 61..80 stick push added M-24). Port-only.
• B4 — menu crosshair-cursor screens: PC input is wrong. Menu screens that use the crosshair cursor don't behave like a PC pointer. The original front-end was PC-style "select a file with the mouse" — menu input should be a separate mode from in-game input, not the same analog-stick emulation. Needs a dedicated menu-pointer path in port/src/input.c (absolute cursor → menu hit-test) rather than feeding synthetic stick deltas. Port-only.
• B5 — no game save on level completion. On the OG cartridge, finishing a level writes progress to EEPROM (unlocks next mission, records time/difficulty). On PC nothing is saved — progress is lost on quit. This is Phase 4 (file-backed EEPROM): osEepromWrite/Read are currently no-op stubs; build on PD's fs.c (file-backed save dir). The save logic already runs in the decomp — it just needs real backing storage. Blocks any multi-session campaign playthrough.

PC graphics settings

Optional video/rendering options, modelled on the PD port (baseline) with Quake 1 remaster / Nightdive-style extras as stretch goals. Every option defaults to the current behavior — zero visual delta at defaults.

Starting point (verified):

• port/src/config.c exists but is minimal (58 lines: Int + String only; PD's is 300 lines with Float/UInt, clamping, INI sections). Copy-and-adapt from pd_port/port/src/config.c.
• port/src/video.c is a trimmed port of PD's (250 vs 588 lines). Render path is architecturally identical to PD: native-res FBO (GE = 640×480 NTSC LAN1) → scaled blit to window, so all PD display options port over cleanly.
• No #ifdef PC blocks exist in src/ yet; only the documented ABI/layout exception edits (D3x) are present. Anything below that changes behavior (FOV, HUD placement, menu contents) is a policy decision — see route notes.

Baseline (PD parity) — each item cites its PD source:

1. Config system: full configRegister{Int,UInt,Float,String} + clamps (pd_port/port/src/config.c).
2. Window/display (video.c + SDL): fullscreen checkbox, fullscreen mode (borderless/exclusive), maximize, center window, resolution dropdown (display-mode list + "Custom"), HiDpi toggle.
3. Frame pacing: vsync (Adaptive/Off/On/N-frames via SDL_GL_SetSwapInterval), framerate cap slider (PD caps FPS when vsync is off — keep that guard).
4. Quality: MSAA Off/2x/4x/8x/16x (FBO samples — verify our FBO path accepts samples>0 first; PD reads it back via videoGetMSAA), texture filter Nearest/Bilinear, anisotropic 1–16 slider, mipmap filter, on-screen FPS display toggle.
5. FOV slider (baseline per owner decision). PD does this game-side (Game.PlayerN.FovY, g_PlayerExtCfg in their main.c + decomp edits). Two routes — decide in a spike:
   • (a) Port-layer: override the camera projection in our fast3d where the view matrix/projection is consumed. No src changes; must find the exact injection point (camera math flows through game GBI setup).
   • (b) PD-style port-only src/ edit reading a port-provided value. This would be the first behavioral src edit — exceeds the current ABI/layout exception in AGENTS.md #2; if chosen, expand the documented exception ("PC-port feature hooks, opt-in via config, default = original behavior") and record a Dxx finding.
6. Widescreen handling: non-4:3 window aspect → stretch vs pillarbox choice, plus HUD centering (None/4:3/Wide à la PD Game.CenterHUD). PD implements the HUD part with G_ASPECT_*_EXT extended GBI mods set game-side; for us that's either a fast3d viewport intercept of the HUD quads (route a) or a port-only src edit (route b). Same policy note as FOV.

In-game video options menu: v1 = config file (+ CLI flags if trivial). PD's in-game menu (pd_port/port/src/optionsmenu.c, 2042 lines) hooks into their decomp's menu tables with port-side handlers; GE's menu code differs, so it's an adaptation, not a copy. Feasible under route (b) policy; revisit after the config-file v1 works.

Stretch goals (Quake 1 remaster / Nightdive):

• Internal resolution scale: render at 2x/4x native then downscale (free supersampling AA, big fidelity win on modern displays).
• FXAA post-process toggle (cheap AA alternative to MSAA).
• SSAO + bloom / light-shaft post-processes — Quake Enhanced ships each enhancement as an individually-toggleable option; keep that pattern (one toggle each, all default off, shared post-FBO stage with FXAA/colorblind).
• Integer-scaling option.
• Texture upscaling filter (ESRGAN-style or pre-generated upscales) — the biggest item; do last. Note GE textures are RZ-compressed at load (port/src/rzdecomp.c) — an upscale pass would hook there or post-decode.

Acceptance: every option persists via config file; toggles apply live where PD's do; tools_pc/golden/ dumps byte-identical at all-defaults; no src/ changes unless route (b) is explicitly chosen and documented.

LAN deathmatch / multiplayer — the netplay foundation (do first)

The idea: play GE's existing competitive multiplayer (deathmatch / mission-based, 2–4P) across up to 4 instances of the PC port on a local network. This is the nettech proving ground: the game logic already exists in the decomp (original N64 feature — no new mode to invent), so this item isolates and de-risks the entire networking layer. Co-op (below) bolts onto whatever this produces.

Milestone 0 (prerequisite, real port work): verify GE's existing split-screen multiplayer works locally on PC — two cameras, split viewport, two independent input streams, full match lifecycle. Every code path netplay will drive must first work on one box.

Net model (research item — owner leans client-server):

• Leading candidate: host = server + player (Source-engine style): host runs the authoritative sim, clients send inputs and receive state. Friends connect by manual IP entry on a LAN. Self-healing desync, one machine owns truth.
• Cost to size up: a full per-tick state snapshot format (players, entities/props, AI, doors/props) must be defined from scratch — no existing save/replay infra covers frame state (EEPROM saves are mission-level only).
• Alternative for the research phase: lockstep/deterministic (exchange ~10 bytes of input per 60Hz tick, both machines run the full sim). Far less code if the sim is bit-deterministic across hosts — PRNG is ported verbatim (port/src/random.c, good), but host-scheduling nondeterminism is a known risk (see D24-implications note below). Desync = hard stop. A per-tick state-hash desync detector is cheap insurance either way.
• PD port has zero networking code — nothing to copy; the net layer is new (port/src/net.c-style, SDL_net or plain sockets).

Shape of the work under host-authoritative: generalize to host + N clients (N≤3), per-client input channels, state snapshots fanned out to all clients. The host already runs the full sim, so scaling past 2P is mostly protocol fan-out — which is why 2P is a natural intermediate milestone on the way to the 4-instance bar.

v1 bar: LAN only, manual IP entry (host listens / client connects), deathmatch playable; 2P first, then scale to 4 instances. No matchmaking, discovery, reconnect, or internet play. Stretch: ping display, graceful reconnect-on-drop, mission-based (non-deathmatch) multiplayer variants, remote-player model interpolation between snapshots (Quake Enhanced ships it; hides LAN jitter).

Co-op (new mode — built on the deathmatch net layer)

The idea: two players progress the single-player campaign levels together — locally on one PC, and over LAN with each player on their own PC. Sequenced after LAN deathmatch: reuse its connection handling, snapshot format, and input channels; this item adds the mode itself.

Key fact (defines the scope): GE has no co-op mode. Unlike PD, GoldenEye only ships split-screen competitive multiplayer. Co-op on solo levels exists in PD only — so this is a net-new game mode: mapping/level and GE game- code feature work, on top of the (already-existing) networking plumbing. Consequences:

• Non-negotiable #2 ("game logic unmodified") is about not altering existing behavior; adding a new mode is a separate, explicit owner decision. Record the policy call when work starts.
• pd_port/ is the reference implementation: PD's decomp shows how two-player co-op was wired into this same Indy engine (shared objective progression, both players' AI/enemy interaction, win/lose conditions, split-screen presentation). Expect an adaptation study, not a copy — GE's mission/ objective code differs file-by-file.
• Cheaper fallback worth considering during design: "freeplay" co-op (both players active on a solo level, but only P1's objective progress counts / or objectives are duplicated per player). Much less new logic; decide after the PD study.

v1 bar: LAN + local 2P co-op on solo levels over the deathmatch net layer. No matchmaking, discovery, reconnect, or internet play.

Fun features (remaster research: Quake 1 Remaster / Nightdive)

Feature mining from the Quake 1 Remaster (id, 2016), Nightdive's remaster line (Duke Nukem 3D: Forever, DOOM, System Shock), and — round 2, 2026-08-29 — Quake Enhanced, Quake II Enhanced, Turok Resurrection, Doom 64 Definitive Edition, SiN Reloaded. Pattern across all of them: classic fidelity as default + a shelf of opt-in QoL/accessibility/asset options. Tiered by effort; all stay in port/ unless noted.

Cheap wins (config toggles over existing infra):

• Screenshot hotkey. Productize the existing debug dump: gfx_opengl_dump_bound_fbo() (port/src/video.c:199) is already there — wire a keybind + configurable output dir, timestamped filenames. Every Nightdive title has this; ours is ~an afternoon.
• Screen-shake intensity slider (0–10x). All shake funnels through viShake() (src/game/bondview2.c:8300 et al.) which lands in our port shim — scale amplitude there, zero src changes. PD precedent: Game.ScreenShakeIntensity.
• No hit-flash / damage-indicator toggle. The red full-screen flash on taking damage is a top community-mod option; Nightdive ships it. Impl: find how the flash overlay is drawn (likely a full-screen HUD quad) and intercept in the port layer, or route-(b) one-liner.
• Auto-pause / input-hold on window focus loss. SDL focus events; trivial, prevents drive-by deaths when alt-tabbing.
• Controller polish (copy from PD input.c): per-player gamepad assignment (Input.ControllerIndex), per-stick deadzone/sensitivity sliders, rumble scale + rumble mapping to GE's feedback moments. Note osMotor* (Rumble Pak) is currently stubbed — accessory detection only (PCPortResearch §4) — so wiring it to SDL_GameControllerRumble is part of this item; Doom 64 DE shipped haptic feedback (a KEX first). We have basic pad support (D118); this is the remaster-grade layer on top.
• Tick-rate / framerate options. PD ships Game.TickRateDivisor + framerate cap. Flag: any tick-rate change must be reconciled with the future netplay determinism requirement before shipping as a user option (lock it to 60Hz default, document).
• Fog / draw-distance option. Turok's KEX port removed the N64's heavy distance fog; Quake II Enhanced added height-based fog with custom colors. fast3d already decodes fog generically (PCPortResearch §5) — a config slider scaling/overriding fog density, default = original values. Zero src changes.

Medium:

• High-res / user texture packs (the big goodwill item). Quake 1 Remaster's core feature is swappable asset sets (classic vs remastered toggle). GE textures are RZ-compressed and decoded at load (port/src/rzdecomp.c) — a per-texture override lookup against a user directory (fall back to ROM) hooks there. Enables the community to make packs; also our escape hatch for the blurry-asset complaints without touching fidelity defaults.
• Accessibility: colorblind post-process filters (protanopia/ deuteranopia/tritanopia full-screen shader pass) + the screen-shake slider above. Nightdive includes these; cheap once we have a post-process stage (shared infra with FXAA from the graphics item — sequence together). Quake II Enhanced also shipped high-contrast / readability UI options — add where the port layer can reach (bitmap HUD text limits scope; document what's not doable under route b).
• Crosshair customization (size/opacity at minimum; GE's crosshair is game-drawn — check whether it's a textured quad we can scale in the port layer before assuming route b).
• Widescreen FOV compensation — already baseline in the graphics item; listed here because it's the feature every remaster ships and users will expect.

Big / stretch:

• Demo / replay record + playback. Record the input stream (+ initial state), play back headlessly. Quake tradition; Nightdive titles have replay-ish tooling. Strong synergy with netplay work: a working replay system is a determinism test harness — if a recorded demo replays bit-identically, lockstep netplay's hardest assumption is proven. Consider building it as the netplay pre-flight tool even before it's user-facing.
• Photo mode. Pause + free orbit camera + capture (System Shock precedent). Free camera = port-layer camera override; pairs with the screenshot hotkey.
• In-game console. Type commands at runtime. Less "remaster feature" than dev tool, but for a WIP port it's arguably the highest-value item on this list: toggle debug flags, dump state, force conditions without restarting. PD has no equivalent; we'd own the design.
• Benchmark mode. Scripted auto-run sequence + FPS report (Quake tradition); trivial once tick-rate options exist.
• AI opponents in deathmatch. Quake Enhanced ships bots in DM. GE's N64 MP is human-only, so bots = net-new game logic — same policy class as co-op (record the owner decision when work starts). Stretch: lets a solo player exercise the netplay layer and makes MP approachable with 1–2 humans.
• Animation smoothing ("wiggle elimination"). Quake II Enhanced restored high-res skeletal animations specifically to kill low-fps "wiggle". GE's model keyframes are N64-rate; interpolating (slerp) between keyframes in the port-layer model-transform path would visibly smooth guard/Bond motion on modern displays. Stretch — sequence with the graphics backlog, do late.
• Dynamic shadows. Quake Enhanced's headline graphical feature. For fast3d this means a shadow-map pass + per-light casting — deep stretch; park next to texture upscaling (both "do last" items).
• Remastered audio option (Phase 3 note). System Shock's remake added new sounds/music. Keep N64 ADPCM fidelity as the default; optionally offer a lossless re-encoded soundtrack toggle — owner decision + content work, park until Phase 3 lands.
• Optional modern UI skin. SiN Reloaded shipped upgraded 2D screens / menu art; System Shock an overhauled interface. For GE this is route (b) game-side territory (menu tables in front.c / initmenus.c) — park as an explicit owner decision; lowest priority on this list.
• Stereo 3D — both reference families shipped it; explicitly deprioritized as anachronistic. Park unless someone asks.

Out of scope by the v1 bars above: online matchmaking, leaderboards, anti-cheat, cross-play (Quake 1 Remaster's biggest features; revisit only after LAN netplay is solid).

Also out of scope by policy (community port): online-platform integration — Steam/GOG/Epic achievements, cloud saves, storefront add-on downloads. No platform tie-in of any kind.

--Old is above here

---

Technical cleanup (backlogged; not gated on playability)

• Remove TEMP D63 debug scaffolding. ~16 references in port/src/ (libultra.c): the master-DL scanner and env-gated GE_D63 logging inside osSpTaskStartGo(). D63 is closed; this is dead weight in the hottest function in the port.
• Add a D24-implications bug class to docs/PORT-LEARNINGS.md. "Host-scheduling nondeterminism / fake priority semantics": the pthread kernel does not enforce N64's 0–31 priorities (osYieldThread = Sleep(0)), so interleavings impossible on console can occur, and frame timing has host jitter. Consequence for future sessions: when a flaky timing bug appears (especially Phase 3 audio underruns), reach first for host thread priorities (SetThreadPriority: scheduler thread time-critical, tick normal) and the deferred GE_DETERM mode (D117) — not for kernel changes.
• Watch item: osYieldThread = Sleep(0). The one place we fake cooperative behavior. If a level-sweep hot loop misbehaves under host load, this shim is the first thing to inspect. Keep as-is until then.

Architecture decision (recorded; no action)

• Keep the pthread + real src/sched.c model. Compared against the PD port's actual design (verified in pd_port/: zero threads — thread API is pure no-op, mainProc() runs as the host main thread, pdsched.c is a gutted frame-callback wrapper, audio driven inline via amgrFrame(), M_AUDTASK dropped). PD could do that only because their original N64 scheduler already used direct-call submission ("nothing writes to the cmdQ in PD") and they adapted game-side lib code (audiomgr.c). For GE — classic osSendMesg(cmdQ) protocol, real __scMain loop, amMain blocking on retrace/reply messages — that route means editing src/audi.c/submission points (non-negotiable #2 violation) and regressing Phase 3, which currently runs the full authentic audio scheduling protocol. No rewrite. Related: audio stays inline in the M_AUDTASK branch (docs/AUDIO-PLAN.md, Option A + sub-decision A3); no dedicated audio worker thread unless host thread priorities provably fail.