goldeneye-pc-port/docs/M-24-QOL-REVIEW.md

M-24 — input rework + playtest QoL (review sheet)

Follow-up work: docs/M-25-QOL-REVIEW.md ([Video] ini knobs, …).

Session M-24, 2026-08-30. Three commits on master:

Commit	Title
f3ec5170	mouse-look rework (D118b/c) + real ge007.ini parser
65ed0315	F12 screenshot + mouse frees on focus loss
33506aee	gamepad hotplug, wheel weapon-cycle, title FPS

Scope guarantee: every change is in port/ (shim layer). No src/ file was touched — no game-logic / ABI / asset-format change. Nothing here is #ifdef PORT in game code. The N64 build is untouched.

Files changed: port/src/input.c, port/src/video.c, port/src/config.c, port/include/input.h, plus docs (HANDOFF.md, LEVEL-PLAYTEST.md, PORT-LEARNINGS.md, PCPortResearch.md §F D118).

---

1. Mouse-look rework (port/src/input.c) — fixes D118b, D118c

The bug

The old bridge always converted mouse-Y to digital C-up/C-down presses. That was wrong two ways, because GE's aim model is mode-dependent (read from src/game/bondview2.c bondviewProcessInput / MoveData):

Mode	Yaw source	Pitch source	What C-up/C-down do
Hipfire (!insightaimmode)	analog stick-X ("natural turn")	digital C-up/C-down only (stick-Y is move fwd/back, no pitch)	look up / down
Aim mode (R / RMB held)	analog stick past ±60 → (stick-60)/10	analog stick past ±60	crouch / lean / zoom (bondview2.c:5340,5351) — not aim

• D118c (aim + mouse-down → crouch): emitting C-down for "look down" while aiming triggered moveData.crouchDown.
• D118b (inverted Y): GE's native pitch is inverted — U_CBUTTONS → speedVertaDown (bondview2.c:5272-5279), i.e. C-up looks down. Mapping mouse-down → C-down gave mouse-down = look up.

The fix

inputComputePad() now branches on whether the aim button is held (our own RMB/LShift state — the exact signal for the default hold-to-aim scheme):

• Aim mode: push stick_x / stick_y into the 61..80 band, proportional to the per-poll mouse delta (× MouseAimSpeed/100 × 4, clamped). Emit no C-buttons. → crouch bug gone; yaw and pitch now behave identically (both analog).
• Hipfire: yaw on stick_x += dx × MouseTurnSpeed/100 × 6; pitch = digital C-up/C-down on |dy| ≥ 1.5 px/poll.
• "Mouse-down looks down" is the default (accounts for GE's inversion); MouseInvertY flips it.
• Per-poll deltas, no accumulator (mouse = displacement device, GE aim = rate device; consume the whole delta each poll, stop moving → stick releases immediately).

Known residual — D118a (lower priority, not a regression)

In hipfire only, yaw (analog) and pitch (digital C-button) still feel different. Aim mode — where GE's precise vertical aiming actually happens — is now fully analog and consistent. A fully-analog hipfire pitch would need an #ifdef PORT hook in bondview.c (would also be needed for toggle-aim control schemes, where "RMB held" ≠ insightaimmode). Deferred.

Review risk

Low. Pure output-shaping of the N64 pad struct. Worst case is bad feel, tunable at runtime (below). Cannot crash or desync — same OSContPad contract as before.

---

2. ge007.ini parser (port/src/config.c) — was a stub

configLoad() / configSave() only logged TODO before. The registered options (configRegisterInt) therefore could not be changed without a recompile.

Now: parses $S/ge007.ini — [Section] blocks, Key = value, # / ; comments; clamps ints to their registered min/max; writes a defaults file on first run; rewrites on clean exit (main.c already calls configLoad() at startup and configSave() on the unreachable-in-practice shutdown path). Dotted keys (Input.MouseAimSpeed) group into [Input] on disk.

Live-tunable [Input] knobs (edit with the game closed):

Key	Default	Meaning
MouseEnabled	1	mouse-look on/off
MouseAimSpeed	50	aim-mode (RMB) sensitivity, percent
MouseTurnSpeed	100	hipfire yaw sensitivity, percent (new; split from AimSpeed)
MouseInvertY	0	1 = mouse-down looks up

Other sections already register options ([Audio] BufferSize, QueueLimit) and now round-trip too.

Implementation notes for review: no <ctype.h> / atoi — the project's src/str.c defines isspace, which collided with libmsvcrt at link time once config.c referenced the libc one, so config.c carries tiny local isws / lc / parseInt helpers. Options registered after configLoad() (none today — all are PD_CONSTRUCTOR) would miss the first-run save.

Review risk

Low-medium. New file I/O in port/. Failure modes are contained: missing file → write defaults; unparseable line → skipped; unknown key → logged and ignored. No effect on any code path that does not read a registered option.

---

3. Playtest QoL (port/src/video.c + port/src/input.c)

All wired through the existing host-thread SDL event pump (videoPumpEvents).

Feature	How	Notes
F12 screenshot	keydown sets a flag; consumed in videoEndFrame (render thread, GL context current) via the existing gfx_opengl_dump_bound_fbo	→ ppm/shot_NNN.ppm; view with tools_pc/ppm2bmp.py. Same mechanism as GE_PCDUMP.
Alt-tab frees the mouse	SDL_WINDOWEVENT_FOCUS_LOST/GAINED → inputSetMouseGrab(0/1)	New inputSetMouseGrab() in input.c: toggles SDL relative-mouse mode (respecting MouseEnabled), zeroes the aim delta, and gates inputUpdate() mouse reads on a mouseGrabbed flag so a released cursor can't drift the aim.
Mouse wheel = weapon cycle	SDL_MOUSEWHEEL → inputPostWheel() queues a 2-poll GE_CONT_A press	GE's default scheme cycles weapon forward on a bare A edge (invButtons = A_BUTTON, bondview2.c:5162 → weaponForwardOffset, :5326). Both wheel directions cycle forward — no clean backward input without the A+fire combo. Same overload the keyboard already has (Space/Z/E = A).
Gamepad hotplug	SDL_CONTROLLERDEVICEADDED/REMOVED → inputRescanPads() (close all + re-open)	Caveat: the game latches inputConnectedMask() at osContInit (boot). A pad added after boot still works for play (it merges into controller 0 — inputComputePad(0) always checks pads[0]) but won't appear as a separate controller channel. Plug it before launch for genuine multi-pad.
Window title shows FPS	videoPumpEvents calls wmAPI->set_window_title("GoldenEye 007 - N fps") ~1 Hz from vidAvgFPS	Cosmetic.

Alt-Enter fullscreen toggle was already present (gfx_sdl2.cpp:299) — not added here, just documented.

Review risk

Low. Screenshot reuses a proven path. Focus/grab and hotplug are SDL window ops on the thread that created the window. Wheel→A is opt-in physical input identical in effect to tapping the existing keyboard A key.

---

Verification done

• Build green (./build-pc.sh ntsc-final), no new warnings in touched files.
• -level_09 (BUNKER1): crash-free to frame 900 (30–35 s window), 91.6% pixel coverage — unregressed vs the committed baseline, checked after each of the 3 commits (3/3, 2/2, 2/2 runs; the one early NO-FRAME was the known D117/D134 machine-load flakiness, cleared on retry).
• -level_20 (Silo): crash-free.
• ge007.ini: written on first run, re-read with no unknown-key warnings, values round-trip.
• Input is a headless-agent blind spot — live feel of the mouse rework, the wheel cycle, and a real gamepad are UNVERIFIED; that's the WS6 playtest's job. See docs/LEVEL-PLAYTEST.md.

What a reviewer should check by playing

1. Mouse aim in aim mode (hold RMB) feels smooth and 1:1-ish; no crouch when you pull the mouse down to look down (D118c).
2. Mouse-Y not inverted at MouseInvertY = 0 (D118b); flipping the ini value inverts it.
3. Editing MouseAimSpeed / MouseTurnSpeed in data/ge007.ini (game closed) actually changes sensitivity next launch.
4. Mouse wheel swaps weapons; F12 drops a ppm/shot_*.ppm; alt-tab frees the cursor and returns cleanly; a gamepad plugged in before launch works.

Still TODO (not started)

Key rebinding, in-render on-screen FPS overlay, in-game options menu, backward weapon cycle, the bondview.c analog-aim hook (D118a + toggle-aim).