Files
aevolution/docs/adr/0085-rebindable-engineering-controls.md
T
dingoandClaude Opus 5.5 5cf8709912 Add M9.8d rebindable engineering controls
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>
2026-10-02 11:30:17 -04:00

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.