SDL-free action/HID-key bindings with conflict validation, a staging editor and a versioned all-or-nothing controls file (ADR-0085). The adapter maps keys through the bindings, releases and drains on rebinding, and captures the chosen key ahead of the toolkit and world. The client adds a Controls panel, key hints, startup loading with a bounded rejection notice, and --controls/--show-controls. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.4 KiB
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.