Files
aevolution/docs/adr/0085-rebindable-engineering-controls.md
T
2026-10-08 12:08:53 -04:00

4.3 KiB

[Reviewed]

ADR-0085: Rebindable engineering controls

Status

Accepted for M9.8d engineering client. Extends ADR-0079 (input intentions) and ADR-0084 (toolkit). Bindings are engineering controls, not final player UI.

Context

ADR-0079 fixed WASD/arrows/Tab in the platform adapter. M9.8 requires rebindable controls with conflict validation, reset to defaults and rejection of malformed configuration, without stuck actions or click-through while the binding UI is open.

Decision

include/evo/client/bindings.hpp (SDL-free, evo_client_controls) defines nine actions: four movement directions, four pan directions and toggle UI capture. Physical keys are USB HID keyboard usages (SDL scancodes share the numbering), named by US-layout position, so a key keeps its position across layouts. Only a fixed table of 92 keys is bindable: letters, digits, punctuation, F1-F12, navigation, arrows and keypad. Modifiers, locks, system/media keys are excluded; Escape is reserved to cancel a capture. Mouse click selection and wheel zoom are fixed.

Bindings is always valid: every action has a primary key, at most one secondary, and no key is used twice. BindingEditor stages changes; a conflicting assignment is refused with the other action named and leaves the draft unchanged; Apply validates the whole set. Releasing either key of an action releases the action (no counting of held keys, so nothing can stay stuck).

The adapter maps keys through the current bindings. set_bindings releases every held action and drains already queued input; fresh presses are then required. Binding capture (begin_key_capture) consumes keyboard and text events before the toolkit and world; the first non-repeat press is returned once, the rest of that batch is drained, focus loss cancels, and world input is captured while armed. The host keeps UI capture on while the Controls panel is open.

Configuration is a versioned text file (evo-controls 1, then action key [key] per action, comments allowed), at most 4096 bytes of printable ASCII. Any error rejects the whole file; the client then uses defaults, shows a notice and leaves the file unchanged. Apply writes a sibling temporary file and renames it over the target. The default location is SDL's per-user preference directory (Aeternalis Games/Evolution Engineering Client/controls-v1.txt); --controls FILE overrides it. The file contains key names only: no credentials, paths or grants.

Alternatives considered

  • ImGui key enums: toolkit types would enter the contract and the file.
  • SDL key names/keycodes: layout-dependent and SDL-specific text in a persisted file.
  • JSON/TOML: needs a parser dependency for nine lines.
  • Allowing modifiers or chords: interacts with toolkit shortcuts and focus; deferred.
  • Counting held keys per action: correct for two held keys but risks stuck actions when admission clears; rejected for engineering controls.

Benefits

Testable without SDL, bounded parsing, no partial configuration, no stuck actions.

Costs

US-position names may surprise non-US layouts (documented in the panel). Only one secondary key per action; no gamepad or mouse-button bindings.

Risks

Physical keyboard layouts, IME and OS shortcuts are not qualified by synthetic events. A file edited by hand can still choose awkward but valid keys.

Consequences

Application gains binding and capture APIs; host, panels, docs and tests change together. Future player controls need a separate product ADR.

M9.8d review corrections

Binding capture now also balances the toolkit: arming capture drops the toolkit's keyboard state and queued keyboard/text input (keys and modifiers whose releases capture will consume), and the chosen physical key stays owned until its release or focus loss, so its repeats, text and release reach neither toolkit nor world (text is suppressed while it is held). The adapter runs an idle toolkit frame when nothing is drawn and bounds the toolkit input queue at 512 events (dropped with every toolkit key/button released). The Controls host logic lives in apps/evo-client/controls_flow.hpp and is rehearsed with the real adapter.

Follow-up: ownership is a set (one bit per SDL scancode), not a single key. Each chosen key is released only by its own key-up or by focus loss; a later capture, or cancelling it, never transfers or drops earlier ownership; text stays suppressed while any owned key is held.