goldeneye-pc-port/docs/dev/UNLOCKED-FPS-PLAN.md

Unlocked FPS Plan

Status: proposal, parked — documented while audio work (project Phase 3) is active. Do not start Phase 0 until audio is done; first action when resumed is the Phase 0 measurement pass.

M-119 note: this plan's premise below ("default preset = ~30fps") is now stale — D248 (M-118) found and fixed a real port bug (a pointer-width scheduler ABI bug) that had been silently halving the game to 30fps since the port's inception; the corrected default is a genuine 60fps. Re-measure Phase 0 against the corrected baseline before resuming this plan. Also see D250 (M-119, open): the exposed real 60fps cost now drops to 20-40fps intermittently on some levels — a performance pass may be a prerequisite for this plan, not just a baseline re-measurement. Related: docs/dev/findings.md §D117 (GE_DETERM), §D155 (catch-up clamp), port/src/libultra.c (pacemaker), src/game/frametiming.c, src/sched.c.

Decisions (agreed)

1. Default preset = the original pace — whatever the game currently does (measured ~30 fps; Phase 0 pins the exact rate). All testing, level sweeps, determinism runs (GE_DETERM), and playtest baselines stay on the default preset. Its code path must remain byte-for-byte what it is today.
2. Unlocked FPS (60 / 120 / uncapped) is EXPERIMENTAL. It ships behind a clearly-labelled option and may be less polished than the default.
3. Hard requirement: raising the presentation rate must never change game speed. Sim rate is invariant across presets. This is "the main speed-up issue" and it gates everything else.
4. Follow the PD PC port where feasible (pd_port checkout): wall-clock accumulator pacing with remainder carry, vsync + framerate-limit options, safety cap when vsync is off.

Non-goals (for now)

• Motion interpolation between sim ticks (the only thing that would make 120 fps look like 120 fps). Requires per-entity prev/cur state in the DL-building game code — rule #2 territory, parked as a separate proposal.
• Changing the sim rate itself (running logic at 120 Hz with halved constants is explicitly out — game logic).

Background: why raising FPS today speeds up the game

One clock drives everything:

• portTickThread (port/src/libultra.c) posts a VI-retrace message on a free-running grid (60 Hz NTSC / 50 Hz PAL, g_tickIntervalUs).
• src/sched.c __scMain blocks on that retrace; __scHandleRetrace notifies clients → exactly one sim tick + one render per retrace.
• osGetCount() is wall-clock scaled to 46.5 MHz. waitForNextFrame() (src/game/frametiming.c) converts elapsed time to deltaFrames, which becomes g_ClockTimer (src/game/lv.c:1008) driving the per-tick sim loops.

The quantization is the trap: nextFrameTime = (elapsed + Q/2) / Q (Q = one frame quantum). The +Q/2 bias rounds every interval up to at least 1 tick, and waitForNextFrame spins until ≥1 tick is due. Consequence: sim speed tracks the retrace rate almost 1:1 — 30 Hz retrace → 30 ticks/s, 120 Hz retrace → ~120 ticks/s (each 8.3 ms interval rounds up to a full tick). That is exactly the observed "anything faster speeds up the game".

Two useful existing properties:

• GE's game code already handles g_ClockTimer == 0 and multi-tick deltas everywhere (for (i = 0; i < g_ClockTimer; i++), explicit == 0 guards in bondhead/bondview2/propobj/explosion). The N64 used this for dropped frames.
• D155 already clamps catch-up to 6 ticks after a real-time hitch.

What the PD port does (reference)

• src/game/timing.c frametimeCalculate(): wall-clock accumulator with remainder carry (lostframetime60t) → diffframe60 / diffframe240 ticks due per rendered frame; render loop runs at display rate.
• Vsync + framerate limit options (VIDEO_MAX_FPS 200/240); vsync-off with no cap forces the safety cap.
• Feasibility mapping to GE:
  • Pacing math (accumulator + carry) → adoptable port-only. ✓
  • Render frames carrying zero sim ticks → blocked in GE by waitForNextFrame's ≥1-tick enforcement (frameDelay, only settable under LEFTOVERDEBUG). A crafted osGetCount() cannot defeat it (the spin + +Q/2 bias always yield ≥1). Needs a game-code change → parked (see "Parked" below), and note it buys little without interpolation.

Phases

Phase 0 — Baseline & ground truth (port-only)

Goal: know exactly what the default preset does before touching anything.

• Measure actual sim rate and present rate of the current default build (speedgraph + a video.c counter; add a periodic log line sim=..Hz render=..Hz). Confirm NTSC vs PAL build.
• Find why the default is ~30 rather than the console's 60 Hz. Candidates: - tick-thread 4 ms chunked-sleep drift under host load; - __scTaskReady double-buffer check (sched.c) stalling a task every other retrace; - __scHandleRetrace's client flag read *((s32*)client + 2) is out-of-bounds of OSScClient (struct is only next+msgQ; the decomp even says "im wrong size"). For gfxClient[0] it happens to read gfxClient[1].next (zero) — but this is layout luck, worth a documented finding either way.
• Record a Dxxx finding with the measured rates and root cause.
• Decision gate: if 30 fps turns out to be a port artifact rather than original behavior, document it and decide with data whether the default preset keeps the current pace (test continuity) or is fixed. Default assumption: keep current behavior as the "original" preset either way; a fix becomes its own item.

Phase 1 — PD-style pacing hardening (port-only)

Makes the default preset stable and drift-free; no game-code changes.

• Replace the free-running tick grid in portTickThread with a wall-clock accumulator + remainder carry (PD frametimeCalculate math): post ticks when real time says they're due, carry the remainder, bounded catch-up after hitches (D155 philosophy). No drift under load, no burst of back-to-back ticks.
• video.c: proper frame limiter for fractional caps (spin+sleep hybrid), triple-buffered swap chain, and the PD safety rule (vsync off + no cap → force a max cap so "unlocked" can't spin).
• Config: keep Video.VSync / Video.FpsCap; add whatever Phase 2 needs.

Phase 2 — Experimental presentation rates (port-only)

The user-visible "60 / 120 / unlocked" feature. Game speed is invariant by construction: sim + render stay on the original tick clock; only present runs faster by showing each rendered frame more than once.

• Frame duplication at the present stage (video.c / fast3d SDL swap path, near gfx_pre_swap_hook): after a fresh frame is presented, re-present the last finished frame on extra vsyncs until the next sim tick's frame is ready. Target rates: 60, 120, uncapped (safety-capped à la PD VIDEO_MAX_FPS).
• Input at present rate: sample SDL input continuously in port/src/input.c; each sim tick consumes the latest state (compare against PD joy.c). This is the real tangible win of the feature: up to ~half a frame of latency removed even without interpolation.
• Options menu entries, clearly labelled experimental (port/src/optionsoverlay.c), default preset untouched.
• Audio check: src/audi.c uses real-time osGetTime() and its own thread; libaudio buffer sends ride the sim/retrace clock. Verify nothing divides by an assumed frame rate; expect no changes.

Phase 3 — Verification & sign-off

• GE_DETERM regression: default preset simulation path byte-identical to pre-change (existing determinism diffs keep passing).
• Preset-invariance playtest: a timed in-game event (e.g. a fixed-length animation or timer) takes the same real time on default / 60 / 120 / unlocked. This is the acceptance test for decision #3.
• Hitch recovery: force a multi-second stall (debugger pause / asset load), confirm D155 clamp holds and no speed spiral on any preset.
• ./build-pc.sh + /linkcheck ritual; new findings in §F/§H with index labels.

Timing-consumer audit (each gets a line in the finding)

Consumer	Clock class	Action
src/game/frametiming.c (waitForNextFrame, updateFrameCounters)	sim-time	unchanged; stays tick-locked
src/boss.c:403,517 (main-loop gate, MAIN_LOOP_TICK_INTERVAL)	sim-time	unchanged; re-verify vs new pacemaker
src/usb.c:387,405 (LibDragon flash timeouts)	real-time	fine as-is; document
src/speed_graph.c	measurement	fine; source of the rate log line
libultrare/audio/env.c, reverb.c lastCnt	perf counters only	fine; document
src/audi.c g_DeltaTime etc. (osGetTime)	real-time	fine; verify in Phase 2

Parked (needs explicit sign-off, separate proposals)

1. True decoupled sim/render (PD's zero-tick render frames). Minimal change class: relax waitForNextFrame's ≥1-tick enforcement so rendered frames can carry deltaFrames = 0 (GE already guards g_ClockTimer == 0 everywhere). This is a behavior-affecting game-code edit gated off by default — outside the ABI-only D3x exception, needs its own rules decision. Perceptual benefit over Phase 2 duplication is small without interpolation, so do this only as a prerequisite for #2.
2. Motion interpolation (prev/cur entity state, lerp at render time). The actual "120 fps looks like 120 fps" feature. Large, invasive, in DL-building game code. Separate proposal; not implied by this plan.

Open questions

• Phase 0 outcome: is the ~30 fps default a port artifact? (fix vs keep — see decision gate)
• PAL builds: default stays 50 Hz pace; experimental present rates identical option set. Confirm no PAL-specific pacing assumptions in Phase 1 math.
• Naming/caps for "unlocked": adopt PD's safety-cap value (200/240) or expose the cap as a slider?

M-87 PD-legacy-survey note (candidate 8): if this plan stalls and GE stays fixed-tick, PD's Game.TickRateDivisor (0–10, slow-motion/perf lever) + Game.ExtraSleep (port/src/main.c:39,167-168, applied src/game/timing.c:49) is a cheap borrowable fallback lever — not otherwise relevant since this plan's whole direction is decoupling sim from frame rate, the opposite of PD's fixed-tick-with-a-divisor approach.