Syplheed-Reborn/docs/re/flight-controls-runtime.md

# In-flight control mapping — measured, not assumed

**Status:** ✅ for the weapon bindings (ammo counters move), 🟡 for the rest (HUD
observation only). Probes: `tools/re-capture/fire_probe.sh` (hold each input, photograph
the ammo counters) and `lock_probe.sh` (tap each, watch the reticle). Stage 02, in flight.
Evidence: [`captures/fire-probe-ammo-counters.png`](captures/fire-probe-ammo-counters.png).

| input | effect | confidence |
|---|---|---|
| **`RB`** | **Nose gun.** `NOSE BM` 06000 → 05956 in a 4 s hold ≈ **11 rounds/s**; `HEAT` bar rises | ✅ |
| **`Y`** | **Main mount** (missiles). `MAIN MPM` 00300 → 00299 per tap | ✅ |
| **`RT` / `LT`** | Throttle up / brake, a *persistent* setting (488 → 1510 → 174 u/s) | ✅ (earlier session) |
| **d-pad** | **Tactical map** overlay (grid with contact blips) — not target cycling | 🟡 |
| `LB`, `X`, `B`, `A`, `LS`, `RS` | No change to either ammo counter | ✅ (as "not a weapon") |

## Targeting appears to be automatic, and that is the lethality problem

No input was found that cycles a target. The green `TARGET` marker is already present in
idle frames with nothing pressed, so the game selects for us — most likely whatever sits
nearest the reticle — and a guided missile's lock is then a **time-on-target** mechanic
rather than a button.

That fits the measurements end to end:

- the guns fire fine (11 rounds/s) but the kill counters read `0000` after five gun-only
  runs → **we shoot and miss**;
- guided missiles (`Missile_P`, Power 200, `GuidanceType` 5) got the first kills,
  `WARPLANES 0002`, but only **2 per 98 launches**;
- the pilot's own log shows aim error wandering between ~10° and ~40° for most of a
  pass.

So the remaining bottleneck is **not** the target choice (escort weighting), **not** the
ballistics (now taken from the confirmed `Shell` records), and **not** the input mapping
(measured above). It is that the steering loop never holds the nose on one contact long
enough to complete a lock. The next thing worth doing is making aim *dwell* — and the
cheapest oracle for whether a lock ever completes is the reticle itself, or finding the
lock timer in the player object with the same anchoring trick used for hull.

## The game's own action list (from the OPTIONS key-config screen)

Decoded from `dat/GP_OPTIONS.pak` (`po_keys_btn*` sprites) — this is the authoritative
set of bindable in-flight actions, straight off the disc, no probing required:

| # | Action | Our mapping |
|---|---|---|
| 1 | Aircraft Control | LX/LY ✅ |
| 2 | View Point Control | RX/RY (unused by the pilot) |
| 3 / 4 | Left / Right Yaw Control | — (separate from pitch/roll!) |
| 5 / 6 | Accelerate / Decelerate | `RT` / `LT` ✅ |
| 7 | **Use Main Weapon** | `Y` ✅ |
| 8 | **Use Nose Weapon** | `RB` ✅ |
| 9 | Special Move | ❔ |
| 10 | Maneuver | ❔ |
| 11 | Resupply | ❔ |
| 12 | **Change Target** | ❔ — **this is the target-select the loop needs** |
| 13 | Change Main Weapon | ❔ (would reach `ASMissile`, Power 5000) |
| 14 | **Padlock Mode Toggle** | ❔ — **the aim-dwell mechanism** |
| 15 | Radar Map Toggle | d-pad 🟡 (matches the observed map overlay) |

Two entries change the plan outright:

- **`Change Target` exists**, so target selection *is* an input after all. The earlier
  probe swept `LB/X/B/A/LS/RS` and found no ammo change — consistent with those being
  exactly these non-weapon actions. The probe simply watched the wrong indicator.
- **`Padlock Mode Toggle`** is a view/aim lock onto the selected target. That is the
  aim-dwell problem solved *by a game mechanic* rather than by tuning a PD controller —
  and it is why a human player can hold a contact long enough to lock a missile.

Also note `CONTROL SETTINGS` carries a **`Control Type`** preset plus **Yaw / Pitch /
Roll Sensitivity** and a separate **`Throttle`** option: the mapping is not fixed, and
the craft's response to a given stick deflection is configurable. Any calibration done
against one profile (e.g. the `ctrl_probe.py` throttle numbers) is only valid for the
save's current settings.

## What the tutorials state outright

`tutorial_capture.sh <index> <secs> <tag>` plays one lesson and photographs it. Captions
use a typewriter effect, so crop `900x125+160+40` from many frames to read a full
sentence. Lessons that require the player to *do* something stall (BASIC CONTROLS sits
on "Go to the box on your screen" forever with nobody flying); the expository ones run
on their own.

- **HEADS-UP DISPLAY (index 1):** *"Enemies are displayed with **red markers** and allies
  with **blue markers**." · "Targeting an enemy displays an Armor Gauge…" ·* **"Press Ⓐ
  twice to target the enemy closest to the center of the screen."**
- **ADVANCED CONTROLS (index 5):** `B`+`LS` = Side Roll / 180 Degree Turn / Level Off ·
  `B`+`A` together = face the target · `LT`+`RT` together = *"sets your fighter's speed
  to that of the target… works well when you are trying to get behind an enemy. Once
  behind an enemy, this also helps you attack them."*

**`Change Target` is Ⓐ pressed TWICE** — a double tap. That is why every button sweep in
this document found nothing and why I wrongly concluded targeting was automatic: each
sweep tapped once. It also explains the missiles — `GuidanceType 5` needs the *game's*
selection, and the loop had never made one, so 98 launches guided to nothing.

## Notes for the reimplementation

- Two independent weapons with separate ammo pools and separate HUD counters:
  `NOSE BM` (gun, 6000) and `MAIN MPM` (missiles, 300).
- The gun has a **HEAT** bar that fills while firing — a sustained-fire limit the
  reimplementation needs; its cap and cool-down rate are not measured yet.
- The tactical map is a full-screen overlay bound to the d-pad and does not pause flight
  (the craft kept taking fire with it open).