RP412/docs/CONTROL-PRESETS.md

# Red Planet — the six control presets on the map screen

The six amber buttons down the right flank of the map display, labelled
PRESET 1 … PRESET 6 on the glass itself. They are not a display option and
they do not touch the map: **each one is a complete factory layout for the
four mappable joystick buttons**, authored per vehicle and shipped in
`RPL4.RES`. Pressing one swaps the whole stick over, live, mid-race.

```
 map glass, right flank (vRIO 0x18..0x1D, amber)
  ┌──────────────┐
  │ PRESET 1  ●  │  Secondary7   press
  │ PRESET 2  ○  │  Secondary8     │
  │ PRESET 3  ○  │  Secondary9     ▼
  │ PRESET 4  ○  │  Secondary10  VTVRIOMapper::SelectPresetMessageHandler
  │ PRESET 5  ○  │  Secondary11    │            (keyboard 1-6 joins here)
  │ PRESET 6  ○  │  Secondary12    ▼
  └──────────────┘               L4VTVControlsMapper::PresetEnable(n)
                                   ├─ remove old ModePresetN from the
                                   │  mode manager, add the new one
                                   │     │
                                   │     ▼
                                   │  every control mapping whose modeMask
                                   │  carries that bit goes live; the other
                                   │  five presets' mappings go dead
                                   │
                                   └─ NotifyOfPresetChange(old, new)
                                         ▼
                                      lamp old→dim, new→on
```

## 1. What the player sees

The map is the pod's portrait-mounted secondary monitor. Its gauge group
paints the button legends itself — `tags` in
`assets/RP411/GAUGE/L4GAUGE.CFG:1611`, six 16×102 strips at x=464:

| legend | file | cell |
|---|---|---|
| PRESET 1 … PRESET 6 | `butpres1.pcc` … `butpres6.pcc` | one per legend cell down the right edge |
| ZOOM + / ZOOM − / reticle / HORN | `butzmin`, `butzmout`, `butcross`, `buthorn` | left edge, top four cells |

The legend grid is not `height/6`: the first cell starts 13 rows down and
the six cells are 102 tall on a 105 pitch (13 + 6×102 + 5×3 = 640). vRIO's
`MFDSplitView::LayoutButtons` scales exactly that grid so each on-screen
button lands against its own painted label
(`MUNGA_L4/L4MFDVIEW.cpp:683`, constants at `:103`).

Addresses run **down** each column from the anchor — the map view is
created with `SideColumns, 0x10, 0x18` (`MUNGA_L4/L4VB16.cpp:4450`), so the
left column is Secondary1…6 top-to-bottom and the right column is
Secondary7…12, i.e. **PRESET 1 is the top button, PRESET 6 the bottom**.
That ordering is confirmed by the left column, where the code binds
Secondary1→zoom in, 2→zoom out, 3→reticle, 4→horn
(`RP_L4/RPL4MPPR.cpp:1857`) and the artwork paints ZOOM+/ZOOM−/cross/HORN
in exactly that order, leaving the bottom two cells blank — the pod wires
only 6 of each column's 8 addresses; 0x16/0x17 and 0x1E/0x1F are Tesla
relays (`MUNGA_L4/L4CTRL.cpp:1901`).

Preset 1 is lit at construction, the other five dim
(`RP_L4/RPL4MPPR.cpp:1962`). These six lamps are driven explicitly by
`NotifyOfPresetChange`; unlike most panel lamps they are not linked to
their button's mapping state (`SetAutomaticOperation(False)` in
`CreateControlledLamp`, `RP_L4/RPL4MPPR.cpp:47`).

## 2. The mechanism — a preset is a mode-mask bit

The engine gates every control mapping behind a `ModeMask`. RP adds six
bits purely for this (`RP_L4/RPL4MODE.h:30`, `nextModeBit` = 0 so the
values are literal):

| mode | bit | value |
|---|---|---|
| ModeNonConfig / ConfigReady / ConfigOn | 0–2 | 0x001 / 0x002 / 0x004 |
| **ModePreset1 … ModePreset6** | **3–8** | **0x008 … 0x100** |
| ModeBasic / ModeStandard / ModeIntercom | 9–11 | 0x200 / 0x400 / 0x800 |

`PresetEnable` (`RP_L4/RPL4MPPR.cpp:685`) does one thing: removes the
outgoing preset's bit from the application mode manager and adds the
incoming one. `ControlsUpdateManager::Update` then only dispatches
instances whose `modeMask` intersects the live mask
(`MUNGA/CONTROLS.h:599` shows the same test in `GetMapState`), so five
sixths of the authored stick mappings are simply invisible at any moment.

Consequences that fall out of that design:

- Presets cost nothing to switch — no rebuild, no allocation, one mask word.
- They are exactly six because there are six switches: `presetCount = 6 //
  limited to number of switches!` (`RP_L4/RPL4MPPR.h:119`).
- Nothing *but* control mappings is preset-scoped. No gauge, bitmap or
  strip in `L4GAUGE.CFG` references `ModePreset*` — the mode names exist
  in the lookup table (`RP_L4/RPL4MODE.cpp:23`) only so the resource
  compiler can resolve them in the control-mapping source.
- Entering configuration state drops all six (`ModeAllNonConfig`) and
  restores the previously selected one on exit
  (`RP_L4/RPL4MPPR.cpp:483`).

Keyboard `1`–`6` calls `PresetEnable` directly
(`RP_L4/RPL4MPPR.cpp:1048`), the same entry point the flank switches use.
Both paths therefore move the lamps, because `PresetEnable` announces the
change itself through the virtual `NotifyOfPresetChange` (`:733`) rather
than leaving it to the switch handler — see §7.

## 3. What is actually in a preset

Only the four mappable stick buttons are ever preset-scoped —
`FirstMappableButton`…`LastMappableButton` minus the hat
(`MUNGA_L4/L4CTRL.h:497`):

| element | button |
|---|---|
| 0x40 | trigger |
| 0x45 | pinky |
| 0x46 | thumb low |
| 0x47 | thumb high (by the hat) |

Everything else — throttle, pedals, stick axes, hat, the whole aux panel —
is bound `ModeAlwaysActive` or `ModeNonConfig` and is identical in all six
presets. The functions that can land on a stick button are the ones that
also have a panel button and a "configure" partner: booster fire, chute,
weapon trigger, LIFT CUT, SIDESLIP, HORN, and intercom PTT
(`RP/VTVMPPR.cpp:144`, `RP/BOOSTER.cpp:50`, `RP/CHUTE.cpp:48`,
`RP/WEAPSYS.cpp:103`).

## 4. The shipped tables

The mappings are streamed from the vehicle resource at mission start —
`LBE4ControlsManager::CreateStreamedMappings`
(`MUNGA_L4/L4CTRL.cpp:2153`), fed from the entity's ControlMappings list
resource by name: `"L4"` for the pod RIO, `"Thrustmaster"` for the stick
(`RP_L4/RPL4APP.cpp:761`). Each record is a `ControlsMapping`
(`MUNGA/CONTROLS.h:783`) carrying its own mode mask, so a single button can
appear six times with six different targets.

**All 26 VTVs in `assets/RP411/RPL4.RES` ship a full six-preset table, for
both the RIO and the Thrustmaster.** Decoded, the *lepton* (two boosters,
one chute, unarmed) reads:

| | trigger | pinky | thumb low | thumb high |
|---|---|---|---|---|
| PRESET 1 | booster 1 | **PTT** | chute | booster 2 |
| PRESET 2 | booster 1 | **LIFT CUT** | chute | booster 2 |
| PRESET 3 | booster 1 | PTT | **LIFT CUT** | booster 2 |
| PRESET 4 | booster 1 | chute | LIFT CUT | booster 2 |
| PRESET 5 | booster 1 | LIFT CUT | **HORN** | booster 2 |
| PRESET 6 | **LIFT CUT** | chute | booster 2 | booster 1 |

An armed vehicle substitutes the weapon trigger for the primary booster.
The *puck* (one booster, laser):

| | trigger | pinky | thumb low | thumb high |
|---|---|---|---|---|
| PRESET 1 | laser | — | HORN | booster |
| PRESET 2 | laser | LIFT CUT | HORN | booster |
| PRESET 3 | laser | — | LIFT CUT | booster |
| PRESET 4 | laser | HORN | LIFT CUT | booster |
| PRESET 5 | laser | LIFT CUT | HORN | booster |
| PRESET 6 | **LIFT CUT** | laser | — | booster |

The authored intent is consistent across every vehicle in the file:

1. **Presets 1–5 keep the primary weapon (or lead booster) on the
   trigger** and shuffle the *secondary* duties — where LIFT CUT lives,
   whether the stick carries PTT or HORN, and whether the chute/third
   system stays on the stick at all.
2. **Preset 2 always puts LIFT CUT on the pinky** and **preset 6 always
   puts LIFT CUT on the trigger** — verified true for all 26 tables.
   Preset 6 is the outlier layout: everything shifts up a finger and the
   trigger becomes a handling control rather than a fire control.
3. Vehicles carrying fewer systems leave cells empty, and some presets then
   collapse into duplicates — on the puck, presets 2 and 5 are identical.
4. Heavily armed vehicles spend the freed cells on second and third
   weapons instead of HORN (bttlbrg, gator, roadblk).

## 5. Editing the active preset in flight

The presets are also the storage for in-mission rebinding. With the CFG
button on the upper-right MFD (`AuxUpperRight1/2`, registered under
`ModeStandard` — `RP_L4/RPL4MPPR.cpp:1826`), the pod enters configuration
state: the aux strips swap their legends from tool art to SET art
(`strptol1/2.pcc` → `strpset1/2.pcc`, `L4GAUGE.CFG:715`), and every
mappable button gets a temporary mapping to the chosen system's "choose"
message (`RP_L4/RPL4MPPR.cpp:604`). Pressing a panel button arms a
function; pressing a stick button toggles it via `AddOrErase`, which
writes against **`previousPresetModeMask`** — the currently selected
preset, and only that one (`RP_L4/RPL4MPPR.cpp:1538`).

The `configMap` gauge on that display (`RPL4GAUG.cpp:3199`, placed at
`L4GAUGE.CFG:749`) shows the state of all four stick buttons against the
armed function, one icon each, using the same preset mask:
`cfgNone` / `cfgOther` / `cfgMe` / `cfgBoth` for
`unmapped` / `mappedByOthers` / `mappedByMe` / both
(`MUNGA/CONTROLS.h:315`).

Configuration is unavailable in Basic control mode — the CFG button and the
`configMap` gauge are both `ModeStandard`, which is set by Standard,
Veteran and Master but cleared by Basic (`RP_L4/RPL4MPPR.cpp:374`).

**Nothing is persisted.** Edits live in the `ControlsMappingGroup` chains
for the mission only; no code writes mappings back to disk, and the next
mission re-streams the authored table from `RPL4.RES`. (Porting a real
bindings file is still open — see the roadmap's Workstream A.)

## 6. The preset number goes out on the wire

`PresetEnable` sets `mustMatch = preset_number` unconditionally, before the
early-out, tagged `HACK - for backward watcher compatibility`
(`RP_L4/RPL4MPPR.cpp:700`). `mustMatch` is a replicated attribute of the
mapper (`RP/VTVMPPR.cpp:384`), so a watcher/spectator station sees which
preset a pilot is on. It is the only preset state that leaves the machine.

## 7. Defects found while reading

**Fixed (2026-08-06):** both lamp defects below.

1. **The preset loop wrote past `modeLamp`.** `modeLampCount` is 4, but the
   preset pass stored six lamps into `modeLamp[i]`, i = 0…5. The members
   are declared `configLamp[2], modeLamp[4], presetLamp[6]` in that order
   (`RP_L4/RPL4MPPR.h:312`), so indices 4 and 5 landed in
   `presetLamp[0..1]` and the whole thing was self-consistent by memory
   layout — the preset press handler read the same out-of-range slots.
   Two real consequences: an out-of-bounds write, and it **destroyed the
   four control-mode lamps** created immediately above (`:1921`), so
   `NotifyOfControlModeChange` drove PRESET 1–4's lamps on the map flank
   and the Basic/Standard/Veteran/Master lamps on the upper-right MFD were
   never lit at all. `presetLamp[]` was meanwhile never populated or read.
   The preset pass now fills `presetLamp[]` (`:1960`), which is what the
   array was always for.
2. **Keyboard preset switching desynchronized the lamps.** The lamp work
   lived in `SelectPresetMessageHandler`, so only the flank switches moved
   the lamps and keyboard `1`–`6` left the wrong one lit. It now lives in
   the virtual `NotifyOfPresetChange`, announced by `PresetEnable` itself
   (`:733`) — one place, every path. `VTVRIOMapper` overrides it to move
   the six flank lamps (`:1651`); the base mapper and the Thrustmaster
   mapper have no preset lamps and inherit the no-op (`:746`).

   Verified by reading the commanded RIO lamp states out of the running
   game (`PadRIO::lampState`, PadRIO + `TEST.EGG`, at rest in Basic mode).
   Before and after are byte-identical except for lamp 0x33:

   | lamps | before | after |
   |---|---|---|
   | 0x18 PRESET 1 / 0x19–0x1D PRESET 2–6 | 3c / 14 | 3c / 14 |
   | 0x30–0x32 MASTER/VETERAN/STANDARD | 14 | 14 |
   | **0x33 BASIC** | **14 (dim — never lit)** | **3c (lit)** |

Still open, by design rather than by accident: `PresetEnable` early-outs on
`preset_number == previousPresetNumber`, so re-pressing the lit switch is a
no-op. Correct for switching, but it also means a preset can never be used
as a "reset to authored bindings" after the player has edited it in
configuration mode.