From 00cb87907cdff002b7f284954bdc4da551cc38ff Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Fri, 24 Jul 2026 20:24:43 -0500
Subject: [PATCH] Controls map: docs/CONTROLS.md, shipped with the dist

Written from the default bindings.txt so it matches what the game
actually writes. Covers the Xbox pad (ASCII diagram plus a table of
every button and its RIO address), the keyboard - numpad flight
cluster diagram, the Shift/Ctrl/Alt throttle and reverse modifiers,
Alt+Q abort - and the panel button banks, showing how the number and
letter rows map onto the five MFD clusters exactly as printed on the
pod board, with the G/B gap keys and the F-key Secondary/Screen
columns. Also notes the keypads being deliberately unbound, the RGB
lamp mirror, and how to rebind with worked examples.

pack-dist copies it to the dist as CONTROLS.txt, flattened to ASCII so
it reads correctly in Notepad while the markdown source keeps its
typography. README links it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md        |   4 +-
 docs/CONTROLS.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++
 pack-dist.ps1    |  15 ++++-
 3 files changed, 188 insertions(+), 2 deletions(-)
 create mode 100644 docs/CONTROLS.md

diff --git a/README.md b/README.md
index cdf9a46..f85de18 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,8 @@ button, and axis; written with the full default layout on first run).
 Default controls: numpad flies (8/2/4/6 stick, 7/9 pedals, 0 trigger),
 Shift/Ctrl throttle, Alt reverse, arrows look, Space fires, letter rows
 are the MFD button banks as printed on the panel. **Alt+Q** aborts a
-mission.
+mission. Full map with pad and keyboard diagrams:
+[docs/CONTROLS.md](docs/CONTROLS.md).
 
 ## Building
 
@@ -59,6 +60,7 @@ mission.
 
 | Doc | Contents |
 |-----|----------|
+| [docs/CONTROLS.md](docs/CONTROLS.md) | Controls map — pad and keyboard diagrams, the panel button banks, rebinding |
 | [docs/RP412-ROADMAP.md](docs/RP412-ROADMAP.md) | The original plan and workstreams |
 | [docs/RP412-FRONTEND-DESIGN.md](docs/RP412-FRONTEND-DESIGN.md) | TeslaConsole analysis, the egg format, the console protocol, and the Steam mapping — with status notes as each layer landed |
 | [docs/STEAM-3-MACHINE-TEST.md](docs/STEAM-3-MACHINE-TEST.md) | Multiplayer test procedure, Steam Input notes, the abort key |
diff --git a/docs/CONTROLS.md b/docs/CONTROLS.md
new file mode 100644
index 0000000..7bc7c54
--- /dev/null
+++ b/docs/CONTROLS.md
@@ -0,0 +1,171 @@
+# Red Planet 4.12 — controls map
+
+Generated from the default `bindings.txt` (the file the game writes
+beside the exe on first run). Everything here is rebindable: edit that
+file and restart, or delete it to get these defaults back.
+
+Grammar reminder, from the file's own header:
+
+```
+key <name>      button <addr> [toggle]
+key <name>      axis <axis> deflect <n>      # held, springs back
+key <name>      axis <axis> rate <n>         # walks per second, sticks
+pad <button>    button <addr> [toggle]
+padaxis <src>   axis <axis> [invert] [deadzone <d>] [rate <n>]
+```
+
+---
+
+## Xbox controller
+
+```
+              ( LB )  Panic                Throttle / reverse  ( RB )
+             ( LT )  Left pedal              Right pedal  ( RT )
+        ______________________________________________________
+       /                                                      \
+      /    [Back]                                  [Start]     \
+     |     config 2                                config 1      |
+     |                                                           |
+     |        ,--.                                    (Y)        |
+     |       ( L  )  stick X / Y                   Upper         |
+     |        `--'                            (X)       (B)      |
+     |                    +---+              Pinky     Middle    |
+     |     D-pad  -->     |hat|                  (A)             |
+     |                    +---+                 Main             |
+     |                                                           |
+     |                              ,--.                         |
+     |                             ( R  )  throttle (Y axis)     |
+      \                             `--'                        /
+       \____________________________________________________ _/
+```
+
+| Control | Does | RIO address |
+|---|---|---|
+| Left stick | Joystick X / Y (inverted, deadzone 0.24 — pod convention) | axes |
+| Right stick Y | Throttle, as a **rate**: hold to wind it up or down, position sticks | axis |
+| Left / right trigger | Left / right pedal (deadzone 0.12) | axes |
+| **A** | Main trigger | `0x40` |
+| **B** | Middle | `0x46` |
+| **X** | Pinky | `0x45` |
+| **Y** | Upper | `0x47` |
+| **LB** | Panic | `0x3D` |
+| **RB** | Throttle button — reverse thrust | `0x3F` |
+| D-pad | Hat: up / back / left / right (look) | `0x42` `0x41` `0x44` `0x43` |
+| **Start** | Config 1 | `0x37` |
+| **Back** | Config 2 | `0x36` |
+
+Start and Back are not extra buttons: `0x37`/`0x36` are the first two
+buttons of the Upper Right MFD's top row, which is where the config
+buttons live on the real board — so the `9` and `0` keys do the same
+thing.
+
+---
+
+## Keyboard
+
+### Flight cluster — the number pad
+
+```
+                    +-----+-----+-----+
+                    |  7  |  8  |  9  |     7 / 9  left / right pedal
+                    | Lped| fwd |Rped |     8 / 2  stick forward / back
+                    +-----+-----+-----+     4 / 6  stick left / right
+                    |  4  |  5  |  6  |     0      main trigger
+                    | left|     |right|
+                    +-----+-----+-----+
+                    |  1  |  2  |  3  |
+                    |     | back|     |
+                    +-----+-----+-----+
+                    |     0     |  .  |
+                    |  trigger  |     |
+                    +-----------+-----+
+
+   Shift  throttle up      Ctrl  throttle down      Alt  reverse thrust
+   (both throttle keys walk the axis and it holds where you leave it)
+```
+
+| Key | Does |
+|---|---|
+| NumPad 8 / 2 | Stick forward / back |
+| NumPad 4 / 6 | Stick left / right |
+| NumPad 7 / 9 | Left / right pedal |
+| NumPad 0, Space | Main trigger (`0x40`) |
+| Shift / Ctrl | Throttle up / down (position holds) |
+| Alt | Reverse thrust (`0x3F`) |
+| Arrow keys | Hat — look up / back / left / right |
+| **Alt + Q** | Abort the mission (score banked, back to menu or lobby) |
+
+### Panel buttons — the letter and number rows
+
+The rest of the keyboard is the pod's button board, laid out as it is
+printed on the panel. Each MFD has 8 buttons (a 4-wide top row and a
+4-wide bottom row); the keyboard rows run left to right across the
+three upper MFDs, then the two lower ones.
+
+```
+  UPPER MFDs      Left MFD          Middle MFD         Right MFD
+   top row     1   2   3   4  |  5   6   7   8  |  9   0   -   =
+   bottom row  Q   W   E   R  |  T   Y   U   I  |  O   P   [   ]
+                 0x2F..0x2C       0x27..0x24        0x37..0x34
+                 0x2B..0x28       0x23..0x20        0x33..0x30
+
+  LOWER MFDs      Left MFD                            Right MFD
+   top row     A   S   D   F        (G unbound)     H   J   K   L
+   bottom row  Z   X   C   V        (B unbound)     N   M   ,   .
+                 0x0F..0x0C                            0x07..0x04
+                 0x0B..0x08                            0x03..0x00
+
+  COLUMNS beside the map
+   Secondary   F1  F2  F3  F4  F5  F6        0x10..0x15
+   Screen      F7  F8  F9  F10 F11 F12       0x18..0x1D
+```
+
+G and B are deliberately unbound: they are the physical gap between the
+Lower Left and Lower Right MFD clusters on the real board.
+
+Every one of these buttons is also **clickable on screen** — the red
+strips around each MFD and the amber strips beside the map are the same
+addresses, and they light up when the game commands their lamps.
+
+### Not bound by default
+
+The pilot keypad (`0x50`–`0x5F`) and external operator keypad
+(`0x60`–`0x6F`) have no keys assigned — the game never reads them. They
+remain bindable if you want them (they arrive as arcade RIO key events).
+
+---
+
+## RGB keyboard lighting
+
+If the machine has a Dynamic Lighting keyboard, bound panel keys mirror
+the pod's lamps: red for the MFD banks, amber/yellow for the Secondary
+and Screen columns, blinking in step with the on-screen buttons.
+Unbound keys go dark. Set `RP412KEYLIGHT=0` in `environ.ini` to switch
+it off.
+
+---
+
+## Rebinding
+
+`bindings.txt` sits beside the exe, written with the full default layout
+and its own documentation on first run. Change a line, restart the game.
+Delete the file to restore these defaults — worth doing after an update,
+since an existing file is never overwritten.
+
+Examples:
+
+```
+key J       button 0x40        # main trigger on J as well
+pad X       button 0x40        # move the trigger to the X button
+key NumPadAdd    axis Throttle rate 0.75    # throttle on numpad +/-
+key NumPadSubtract axis Throttle rate -0.75
+padaxis LeftStickX axis JoystickX deadzone 0.15   # drop 'invert' to flip X
+```
+
+Addresses: `0x00`–`0x47` are the lamp buttons above, `0x50`–`0x6F` the
+keypads. Axis names: `Throttle`, `LeftPedal`, `RightPedal`, `JoystickX`,
+`JoystickY`. Key names follow the .NET `Keys` naming (`A`–`Z`, `D0`–`D9`
+for the digit row, `F1`–`F12`, `NumPad0`–`NumPad9`, `Up`, `Down`,
+`Left`, `Right`, `Space`, `Return`, `Shift`, `Ctrl`, `Alt`,
+`OemMinus`, `Oemplus`, `Oemcomma`, `OemPeriod`, `OemOpenBrackets`,
+`OemCloseBrackets`, …).
diff --git a/pack-dist.ps1 b/pack-dist.ps1
index 702e49e..596f5e7 100644
--- a/pack-dist.ps1
+++ b/pack-dist.ps1
@@ -64,6 +64,18 @@ foreach ($file in 'RPDPL.INI', 'JOYSTICK.INI', 'RPL4.RES', 'TEST.EGG',
     Copy-Item (Join-Path $assets $file) $dist
 }
 
+# The controls map travels with the game (players get the diagrams
+# without needing the repo). Flattened to ASCII so it reads correctly
+# in Notepad - the markdown source keeps its typography.
+$controls = Get-Content (Join-Path $root 'docs\CONTROLS.md') -Raw -Encoding UTF8
+foreach ($pair in @(
+        @([char]0x2014, '-'), @([char]0x2013, '-'), @([char]0x2018, "'"),
+        @([char]0x2019, "'"), @([char]0x201C, '"'), @([char]0x201D, '"'),
+        @([char]0x00D7, 'x'), @([char]0x2192, '->'), @([char]0x2026, '...'))) {
+    $controls = $controls.Replace([string]$pair[0], [string]$pair[1])
+}
+Set-Content -Path "$dist\CONTROLS.txt" -Encoding ascii -Value $controls
+
 # --- OpenAL runtime --------------------------------------------------------
 # The exe links OpenAL32.dll (32-bit). Prefer shipping the already-installed
 # runtime beside the exe; oalinst.exe covers machines where that misses.
@@ -259,7 +271,8 @@ pod's real button banks: click them with the mouse, and they light up
 as the game commands their lamps.
 environ.ini is self-documenting: every option ships in the file with
 a comment (Steam networking, keyboard lighting, stick inversion, LAN
-hosting, developer keys, and more).
+hosting, developer keys, and more). CONTROLS.txt has the full controls
+map with pad and keyboard diagrams.
 
 Known prototype notes: pods race untextured (the player1-8 skins come
 from the presets system, not shipped data), and text drawn on the plasma