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

Controller & input options wave (port plan)

Status: Wave A IMPLEMENTED (code complete, clean Windows/MSYS2 build; pending user by-ear/by-eye feel-check + Deck tuning of item 5) — the "low-hanging fruit" from the Nightdive Turok PC-port options menu that is cheap, well- scoped, and port-layer only (zero src/ / src/game edits → rule 2 and the ABI exception do not apply). Sequenced after v0.4.0 ships. This is the input wave; the sibling video/audio/graphics Tier-A items (borderless window, primary display, brightness, master volume, button glyphs, uncapped-FPS) are a separate follow-on wave — see §Out of scope.

Reference: docs/dev/RUMBLE-PLAN.md (D401) is the closest precedent — a controller option that lives entirely in port/src/input.c + port/src/optionsoverlay.c + a configRegister* key + a kResetDefaults entry, with the game side (src/joy.c, src/ stick consumers) untouched. docs/dev/GEPD-INPUT-PLAN.md documents the pad poll path this wave extends.

---

Ground truth (current state, verified 2026-09-27)

Pad poll = inputComputePad() (port/src/input.c:1375), runs on the game thread (osContStartReadData). It reads the SDL axes/buttons for pad idx, writes out a 16-bit button mask plus *stick_x / *stick_y (the N64 signed char stick, clamped to STICK_MAX). All the knobs in this wave are applied inside inputComputePad, before the two *stick_x/*stick_y writes at :2063-2064 — i.e. the port re-shapes the input the game already consumes, never the game's stick→turn math.

Two pitch modes drive the look stick (selected by Input.NaturalPitch, the default-on "SOLITARE" mode, D194/D238):

• Continuous (natural-pitch, the default): the right stick is the continuous look axis — input.c:1927-1933: rxs = scaleAxis(rx); … rys = -scaleAxis(ry); if (padLookInvertY) rys = -rys; sx = rxs; sy = rys;. The left stick becomes digital-step movement. This is the path the X/Y look-sensitivity + look-smoothing + right-stick deadzone knobs target.
• Digital (native, natural-pitch off): the left stick is analog movement/turn and the right stick is digitized into the C-button look (:1935-1947, thresholds at RSTICK_THRESHOLD). Look here is the faithful N64 digital C-button turn — not sens-scalable (there is no analog look to scale), so the new look-sens/smoothing knobs are inert in this mode, exactly as Input.AimMode/Input.AimRange already are per mode.

Existing pad knobs (all configRegister* in input.c, rows in optionsoverlay.c INPUT section): Input.PadDeadzone (single, padDeadzone = STICK_DEADZONE, :524), Input.PadTriggerPct (:525), Input.PadLookInvertY (:526), Input.RumbleScale (D401). scaleAxis() applies the shared deadzone + STICK_MAX scale to a raw int16 axis.

Already covered elsewhere (do not re-plan): mouse sens/invert/smoothing (Input.MouseSensitivity/MouseInvertY/MouseSmoothing), uncapped FPS (docs/dev/UNLOCKED-FPS-PLAN.md — parked; has a real perf prerequisite, D250), controller rebinding (PR #109 / D383 — the hard, open gap, out of scope).

---

Items (all port-layer)

1. Input.PadLookSensX — right-stick look horizontal sensitivity (S)

New int key, default 100 (= 1×, current behaviour), range ~25–200 %. Applied in the continuous-look branch only: after rxs = scaleAxis(rx), rxs = clamp(rxs * padLookSensX / 100, ±STICK_MAX) before sx = rxs (input.c:1928/1932). Pure gain on the emitted look X. In digital mode: inert.

• Row: INPUT, "Look sensitivity (left/right)", slider, after "Rumble strength".
• Risk: none (monotonic gain; 100% = byte-identical to today). Deck-testable.

2. Input.PadLookSensY — right-stick look vertical (pitch) sensitivity (S)

Same shape, applied to rys (input.c:1930/1933): rys = clamp(rys * padLookSensY / 100, ±STICK_MAX). Default 100, range ~25–200 %. Kept separate from X (Turok splits them; pitch and yaw feel different on a stick). Independent of the existing Input.HipfirePitchSpeed (that one is the hipfire/mouse pitch rate, a different path). In digital mode: inert.

• Row: INPUT, "Look sensitivity (up/down)", slider.
• Risk: none (same as item 1).

3. Input.PadSouthpaw — swap L/R triggers (S)

New toggle, default off. Today (input.c:1954-1958): TRIGGERRIGHT > trigPt → GE_CONT_G; TRIGGERLEFT > trigPt → GE_CONT_R. Under southpaw, swap the two GE_CONT_G/GE_CONT_R assignments (left trigger becomes the right-shoulder action and vice-versa). Two lines. Lets left-handed / southpaw players put their index finger on the primary fire trigger.

• Row: INPUT, "Southpaw", toggle.
• Risk: none at default off; trivial to verify by re-aiming.

4. Input.PadDeadzoneL / Input.PadDeadzoneR — per-stick deadzone (S–M)

Split the single Input.PadDeadzone into a left (movement) and a right (look) deadzone. Thread the deadzone through scaleAxis() (it is currently the global padDeadzone) as a per-call argument: left-stick calls use padDeadzoneL, right-stick calls use padDeadzoneR.

• Back-compat/migration: on load, if Input.PadDeadzoneL/R are absent but legacy Input.PadDeadzone is set, seed both from it (one-time, like the AimStyle→AimMode migration at input.c:449-454). Keep Input.PadDeadzone registered so old inis keep loading; it becomes hidden/superseded (D337/D333 precedent for a superseded key).
• Rows: INPUT, "Deadzone (left stick)" + "Deadzone (right stick)", sliders.
• Risk: low — a deadzone is a per-axis floor; splitting it cannot change behaviour when both equal the current single value. Watch the menu-navigation path (:1918-1922, left stick in menus) to use the left deadzone there.

5. Input.PadLookSmoothing — right-stick look low-pass (M)

New key, default 0 (off), range 0–10 (0 = off = today). When >0, low-pass filter the emitted right-stick look deflection so the look axis eases rather than tracking the stick 1:1 — the pad analogue of Input.MouseSmoothing (which smooths the relative mouse delta). Because the continuous stick is absolute (not a delta), implement as a per-pad exponential moving average on the emitted rxs/rys (state kept per idx, reset on pad hot-unplug and on aim-mode exit so releasing the stick recentres cleanly). The higher the value, the heavier the easing.

• Row: INPUT, "Look smoothing", slider (0 = off).
• Risk: medium — an EMA on an absolute stick can feel laggy or fail to recentre if the filter isn't driven back to 0 when the stick is centred; needs hands-on tuning on the Deck (the natural test device). Keep default off so it ships inert until tuned.

6. Mouse vertical sensitivity row (trivial — folds in)

Input.MouseYScale already exists as a registered key; it just has no F10 row. Add one slider row (INPUT) so the asymmetric X/Y mouse sensitivity is user-adjustable without editing the ini. No input.c change — row only.

---

Shared plumbing (do once, not per item)

• configRegisterInt/Float for each new key in input.c next to the existing pad-key registrations (~:2536-2538).
• Static state next to padDeadzone/padLookInvertY (:524-526): padLookSensX/Y, padSouthpaw, padDeadzoneL/R, padLookSmoothing + the per-pad EMA state for item 5.
• F10 rows in optionsoverlay.c rows[] INPUT section (after "Rumble strength", with the other controller rows) + matching front options rows via the shared optionsRow* accessors (both UIs read rows[] — D401 precedent, so one definition covers F10 and the front options screen).
• kResetDefaults entries for each new key (neutral: sens 100, smoothing 0, southpaw 0, deadzones = STICK_DEADZONE) so INPUT "Reset to defaults" covers them (D401 item-3 precedent).

Ground rules

1. Port-layer only — every edit is in port/src/input.c, port/src/optionsoverlay.c, port/src/frontoptions.c, and CMakeLists.txt (nothing new to compile — no new files). Zero src/ / src/game edits → rule 2 and the pointer-width ABI exception are not engaged.
2. Off-by-default = today's behaviour. Every new key defaults to a neutral value that leaves the emitted stick/buttons byte-identical to the current build, so the golden gate (D117/golden_gate.sh) is unaffected at defaults and the v0.4.0 playtest baseline is preserved.
3. Per-mode honesty. The continuous-look knobs (1, 2, 5) apply only in natural-pitch mode; in digital mode they are inert — document this on the rows (mirrors how Input.AimRange is hidden in Centred mode, D338), rather than pretending they affect the digital C-button look.
4. Deck is the reference device for the pad wave (native Steam Controller, the real-world target); Windows + a plugged gamepad as the second check.

Verification

1. ./build-pc.sh ntsc-final clean (no new symbols/dupes — the configRegister*
   • kResetDefaults additions are the only new references).
2. /linkcheck + the golden gate (tools_pc/golden_gate.sh) — must pass unchanged at defaults (proves the neutral-default invariant).
3. Hands-on, on a pad / the Steam Deck: each knob at a non-neutral value changes feel as expected and at default leaves it identical; southpaw re-maps the triggers; per-stick deadzones floor the correct stick; look smoothing eases and recentres on stick release (item 5's known risk).
4. New finding (D4xx, next free label) recording the wave + per-item Deck-test result, cross-ref'd to D401 (precedent), D337/D338 (per-mode gating pattern), D333 (AimStyle migration pattern), PR #109 (out-of-scope rebind).

Out of scope for this wave (see the assessment above)

• Sibling Tier-A, other sections (separate follow-on wave): borderless windowed, primary-display selection, brightness slider, master audio volume, button-prompt glyphs.
• Tier B (medium, contained): radial fog toggle, HUD opacity, flash- intensity slider (promote Game.NoHitFlash), show-HUD master toggle, audio output device, low-pass filter, SMAA/FXAA.
• Uncapped FPS — docs/dev/UNLOCKED-FPS-PLAN.md (parked; D250 perf prerequisite means it is not quick).
• Tier C (rule-2 / big-feature / out-of-scope): head-bobbing sliders, death-cinematic / switch-on-pickup / walk toggles (all src/game flow), bloom / light-scattering / water refraction-reflection / simple shadows, violence / blood colour, multiple graphics APIs, and full controller rebinding (PR #109 — the genuinely hard input item).

Suggested sequencing (v0.5.0)

1. Wave A (this doc): items 1–4 + 6 (sens X/Y, southpaw, per-stick deadzone, mouse-Y row) — all low-risk, shippable behind neutral defaults.
2. Item 5 (look smoothing) lands in the same wave but may ship default-off pending Deck feel-tuning.
3. Wave B: the sibling video/audio/graphics Tier-A items.
4. Revisit Tier C only with explicit sign-off (rule-2 items need the docs/dev-process.md procedure).

---

Implementation status (2026-09-28)

Wave A code is complete and compiles clean (Windows/MSYS2 ninja incremental, exit 0, no new warnings — only the pre-existing ramrom.c / gfx_pc.cpp ones). Every edit is in port/src/input.c + port/src/optionsoverlay.c; frontoptions.c needed no change (both UIs read the shared rows[] via the optionsRow* API). Zero src/ edits, no new files/symbols — only file-local statics + configRegisterInt calls — so the link is unchanged.

Implemented (all off/neutral-by-default → byte-identical at defaults):

• 1/2. Input.PadLookSensX / Input.PadLookSensY (25–200 %, dflt 100): right-stick look, applied in the natural-pitch branch of inputComputePad() after scaleAxis(), re-clamped to STICK_MAX. Inert in digital mode (the right stick is digitized there, no analog look to scale).
• 3. Input.PadSouthpaw (toggle, dflt 0): swaps the fire (GE_CONT_G) and grenade (GE_CONT_R) trigger actions after the raw edges are captured, so edge-detection stays consistent.
• 4. Input.PadDeadzoneL / Input.PadDeadzoneR (0–30000, dflt 7000): scaleAxis() now takes a per-stick deadzone param; left-stick (movement) calls pass L, right-stick (look) calls pass R. The legacy Input.PadDeadzone key stays registered (no row) so old inis load; a one-time migration in inputInit() seeds any unset L/R (C-init sentinel PAD_DZ_UNSET = -1) from the legacy value, before any configSave. The single "Stick deadzone" row is replaced by "Deadzone (left stick)" / "(right stick)".
• 5. Input.PadLookSmooth (0–10, dflt 0 = off, shown "N/10"): per-pad EMA low-pass on the natural-pitch look output (padSmSX/padSmSY[MAX_PADS]), reset on hot-unplug (inputRescanPads) so a snapped-back stick can't lag from a stale value; otherwise the EMA decays to 0 as the stick recentres. Turok has this as on/off; GE ships a graduated 0-10 knob instead. Ships default-off pending Deck feel-tuning.
• 6. Input.MouseYScale row (dflt 100): the pre-existing registered key finally gets an INPUT slider row ("Mouse vertical sensitivity") — row only, no input.c change.

Verbiage + display baseline (Turok PC, 2026-09-28): row labels now match the Turok options menu verbatim where GE has an analogue — Mouse horizontal / vertical sensitivity, X axis / Y axis look sensitivity, Look smoothing, Southpaw, Vibration (was "Rumble strength"), Deadzone (left/right stick). The display is baselined to Turok's scales: sensitivity + deadzone knobs read 0-100 with 50 = the default (the existing calibratedDefault "N/100" path), and look smoothing reads 0-10 ("N/10"). (Turok's Mouse/Controller subsection split is not mirrored — GE keeps one flat INPUT section per D356, so the two invert rows retain their "(mouse)"/"(controller)" suffixes to stay unambiguous.)

kResetDefaults covers all six so INPUT "Reset to defaults" is complete; calibratedDefault() gives the sensitivity + deadzone rows their 50/100 default midpoint, and dispMax renders the smoothing knob as "N/10".

Still owed (verification, not code): user by-ear/by-eye feel-check of the new knobs on a real pad (esp. item 5 smoothing strength + item 1/2 sens range), the Deck cross-check, and confirming the per-stick deadzone migration on an old-ini user (L/R seed from Input.PadDeadzone).