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

81 lines
4.3 KiB
Markdown

[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.