goldeneye-pc-port/docs/dev/GEPD-INPUT-PLAN.md

GEPD-inspired input overhaul — FINAL PLAN (issues #89, #90)

Status: plan only — no code changes yet. Companion to port/src/input.c (current state: D118/D165/D166/D194/D214/D223/D238 lineage).

1. The reference (no longer vendored in the public repo)

The GEPD Edition Mouse Injector source was vendored at reference/mouse-injector/ and removed from the public repo on 2026-09-19 (GPLv2 code + a prebuilt binary inside an MIT project; never compiled here). See reference/mouse-injector/README.md for provenance and how to re-vendor it locally if you need the original. The file that mattered was games/goldeneye.c (~380 lines, the whole GE aim model), plus device.c (raw mouse polling) and maindll.h (tickrate — the units every per-tick constant assumes). The model is quoted inline below and in the D194 findings; the ported result lives in port/src/input.c.

What the Mouse Injector does (GE)

What the Mouse Injector actually does (GE)

Aspect	GEPD implementation (games/goldeneye.c)
Mouse source	Raw driver deltas via ManyMouse (device.c), cursor locked by periodic SetCursorPos. No OS pointer accel, no deadzone.
Hipfire look	Direct camera write: camx += XPOS/10 * (SENS/40) * (fov/basefov) degrees per tick; camy likewise, clamped ±90 (−20 in tank). Linear in px — this is why GEPD "just feels right".
Aim mode (R)	Crosshair position accumulator crosshairpos += XPOS/10 * SENS/292, clamped to ±CROSSHAIRLIMIT (5.159° = screen edge). Gun/arm pose derived per-weapon from a 33-entry offset table. View scrolls only past 72% of the way to the edge: aimx = (ratio−0.72) * 475 * timestep, scaled by fov/basefov.
FOV coupling	Every term carries (fov/basefov) — scopes automatically get finer control. basefov = min(60, override).
Tank	Separate direct write to the tank x-rotation global (0x80036484), different scale (360/TANKXROT * 2.5); crosshair X locked to 0 when driving with tank equipped.
Menus	Mouse moves the menu cursor directly (menux/y += px/10*SENS*6, clamped to screen rect); aim button acts as B (back) in menus; wheel = weapon cycle macro.
Safety gates	Injection only when `camera==4
Extras	Crouch toggle mode, dedicated reload key (ROM hack — not portable to us), FOV override + viewmodel repositioning (ROM hacks — we have the clean equivalents in port/), intro skip on FIRE+AIM.

Already inherited (do not redo)

• D194 GEPD-mirror aim (aimGepdCompute()): crosshair-position model, ±5.159° clamp, 72% edge scroll at 475/s, fov scaling, per-tick overwrite of crosshair_x/y_pos + gun_azimuth_angle/turning. This is GEPD's aim mode.
• D223 mouse-wheel weapon cycling (A / A+Z synthesis) — mirrors GE_Controller()'s weapon macro; D214 ini key binds; click-to-lock capture; F10 options overlay with aim/turn sensitivity sliders; D194(b) dt-decoupled look; menu pointer via direct cursor_h/v_pos writes (mirrors GEPD's menux/y writes).

Remaining inheritances (this plan)

GEPD's hipfire is a direct linear camera write — we still route hipfire through the N64 stick curve (#89). Also un-inherited: raw-input-by-default, crouch toggle, GEPD-style safety gates on our always-live look paths, and its sensitivity/FOV coupling discipline. That's WIs 1–3 + 6 below.

Reference split (GEPD vs PD port)

Two references, two jobs (decided during #89/#90 triage):

• GEPD Mouse Injector (was reference/mouse-injector/, removed from the public repo 2026-09-19 — see its README stub) = what the mouse does to the camera. The only reference with GE-specific knowledge (camera fields, crosshair limits, tank case, safety gates). Primary for WI-1.
• PD PC port checkout (standing reference, see AGENTS.md) = how a PC game presents and captures input: cursor-lock behavior, raw input handling, sensitivity units/scaling, and the shipped in-game options/keybind UI. Primary for WI-2 conventions and WI-5's menu design. PD knows nothing about GE — never use it for camera math.

2. Issue #89 — "mouse movement is not uniform; slow motion barely registers"

Diagnosis (high confidence)

The complaint is the hipfire path. Today hipfire converts mouse px into an analog stick value (sx += (int)(hipEdx * hipSens * MOUSE_TURN_GAIN)), and the game then runs that stick through its own N64-era natural-turn response — a quadratic-ish curve with a soft floor (D238: "saturates the game's quadratic natural-turn curve at ~13 px/poll"). Consequences, exactly as the reporter describes:

1. Slow mouse motion → small stick values → squared-off tiny turn rates → "almost unrecognised".
2. Fast motion saturates the curve at full 315°/s — so the usable band is narrow and the feel is non-uniform (bang-bang-ish).
3. (int) truncation of the stick adds a quantized dead zone on top.

GEPD/PD-PC never hit this because they write the camera angles directly — the stick curve is bypassed entirely, and sensitivity is linear in px with FOV scaling. We already do exactly that in aim mode (D194); hipfire is the one leftover N64-stick-shaped path.

Secondary contributors worth folding in:

• Input.MouseRawInput defaults to 0 — on X11/Wayland (the #90 reporter is on Linux) OS pointer acceleration still shapes relative deltas; GEPD reads the raw driver. Windows is largely unaffected.
• Sensitivity is spread over 4 knobs (MouseSensitivity, MouseTurnSpeed, AimModeSens, legacy MouseAimSpeed) — the reporter "tried adjusting ge007.ini" and couldn't find the one that mattered for hipfire.

Work items

WI-1 (core fix): direct camera writes for hipfire look. Mirror GEPD's hipfire branch in input.c.

Pre-flight: skim the PD port's port/src/input.c mouse path first and match its conventions (sensitivity units, dt handling, focus-loss behavior) so the result feels like PD PC rather than a reinvention. GEPD supplies the GE camera math; PD supplies the UX shape.

Implementation:

• New path hipDirectCompute() next to aimGepdCompute(): convert this poll's dt-scaled px to degrees using the current viewport (deg/px = fovy/viewH, or hfov/viewW — reuse whatever D194 absolute aim used), scale by MouseTurnSpeed * MouseSensitivity, and add straight to g_CurrentPlayer->vv_theta / vv_verta (clamp ±90). Same confinement as today: only when idx==0, cursor captured, in a running stage.
• GEPD's safety gates must be ported over (aim mode got away without them because it requires RMB held; hipfire is always live): check the decomp equivalents of GEPD's camera==4||0 && menupage==11 && !dead && !watch && !pause before writing. menupage → current_menu (already have); the rest are player/game globals — read-only, no logic change.
• Tank: GEPD writes a separate tank-rotation global with its own scale and locks crosshair X to 0 when driving with the tank equipped. Find the decomp symbol for 0x80036484 (tank.c) and mirror it; if too fiddly, phase 2 — tanks are rare in single-player.
• Keyboard turn (arrows → stick) keeps the existing stick path; only mouse px goes direct. Escape hatch: Input.MouseDirectLook=1 default, 0 reverts to the current stick path (kept as-is).
• This makes hipfire and aim mode share one linear mental model: px → screen angle, FOV-scaled, dt-normalized. Expect to then simplify or delete the D166/D238 curve-tuning knobs that become inert (MouseAimCurve, AimBand, legacy MouseAimSpeed) — after playtest, and keep the config keys as no-op aliases so existing inis don't break.

WI-2: raw input by default. Flip Input.MouseRawInput default to 1 (SDL hints already handled in inputInit). Verify Windows relative-mode deltas are unaffected; this mainly fixes Linux feel. Keep the escape hatch.

WI-3: one honest sensitivity number. With WI-1, hipfire and aim both scale off px→degrees, so MouseSensitivity becomes genuinely master. Add it to the F10 overlay (see WI-5), document the knob hierarchy in the generated ini header comment, and re-calibrate defaults against GEPD's SENS≈40 ≈ 1:1 screen-angle mapping (our current 38/50/100 trio should land close; measure, don't guess).

Verification: GE_INPUTLOG linearity check — log px-in vs deg-out at slow and fast speeds (ratio must be constant); headless script harness for the stick-fallback path; manual playtest checklist (hipfire slow/fast, aim mode, scope zoom, tank, menu, death/cutscene safety gates). New finding Dxxx in docs/dev/findings.md, index row added.

3. Issue #90 — in-game key bindings + "ini binds don't work" + sensitivity menu

Diagnosis candidates for "binds don't work properly" (repro before fixing)

1. Not a bug, GE design: in-game, a fresh A edge without Z held is the weapon-cycle-forward signal (D223 documents weaponForwardOffset). The default Action bind includes E — so "pressing E changes weapon" is the game's own behavior, and "Escape reloads/activates switches" is the default Cancel=Escape → B button. The user's mental model (PC: E = interact) collides with GE's A/B semantics. Address via documentation + possibly a PC-idiomatic default set (product decision; GEPD itself uses Q=A, E=B).
2. Ini syntax footgun: keys must be written as Input.Bind.Action=E (or Bind.Action=E under [Input]). A bare Action=E under [Input] resolves to Input.Action, which is unregistered and silently ignored. configLoad also ignores unknown keys with no warning — add a log line for unrecognized keys so users get feedback.
3. Key-name format: binds use SDL scancode names ("Left Ctrl", "Up", "Space"); nothing documents this in the ini. Add per-key comments in configSave output and/or a # valid names: ... header.
4. There may still be a real parse bug lurking (strtok on the seeded buffer, constructor ordering vs configLoad) — repro first: write an ini with Input.Bind.Action=E, launch, confirm via GE_INPUTLOG that E alone produces A. Fix whatever actually breaks; don't fix hypotheticals.

Work items

WI-4: keybind audit + ini ergonomics. Repro (above), fix real bugs, add unknown-key warnings, document scancode names in the saved ini. Cheap, do first — it unblocks #90's half regardless of the UI work.

WI-5: F10 overlay — bindings section + master sensitivity. Model the UX on the PD port's shipped in-game options menu (standing reference checkout) where anything is player-facing. optionsoverlay.c already has row/hit-test/scroll infrastructure and owns all input while open; what's missing:

• A new row kind ROW_BIND: label = action, value = first bound key name; click → "press a key…" state that captures the next scancode (keyboard or mouse button), writes it into g_bindStr[a] (replacing or appending — decide: GEPD/PD use one primary + optional secondary; simplest v1 = replace single key, keep multi-key only for ini power users), then inputRebuildBinds()
  • persist via the existing config save path.
• Expose Input.MouseSensitivity (master), and after WI-1 trim the panel to master + per-mode fine-trim + invert Y (drop inert legacy rows).
• Bind capture must swallow all input while armed (overlay already does this) and handle ESC = cancel, Backspace/Delete = clear.

WI-6 (nice-to-have, from GEPD): crouch toggle. GEPD's CROUCHTOGGLE state machine (GE_Crouch) is ~20 lines and pure port-side (stance flag write). Low priority; include only if WI-1..5 land cleanly.

4. Suggested order

1. WI-4 (keybind repro/fix + ini docs) — small, unblocks #90 partially.
2. WI-1 (direct hipfire) + WI-2 (raw input default) — the #89 fix; playtest-heavy, needs the safety gates done right.
3. WI-5 (overlay binds + master sens) — completes #90.
4. WI-3 (sensitivity consolidation/cleanup) — after WI-1 defaults settle.
5. WI-6 (crouch toggle) — optional garnish.

5. Constraints reminders

• All work is port/-only: direct struct writes are the established D194 pattern (read/write live game state from the input poll, no logic change). Any temptation to "fix" the natural-turn curve in src/game = rule-2 sign-off territory — don't.
• Keep every removed/renamed ini key registered as an alias so shipped inis keep loading; log deprecations at startup.
• Findings: new Dxxx entries for WI-1 (hipfire direct look), the #90 bind repro outcome, and the overlay bind UI; update findings-index.csv.