Binding capture tracked one owned key, so a second capture could overwrite an unreleased earlier choice and leak its repeats. Ownership is now a bitset over scancodes, released per key or on focus loss, with successive-capture, release order, cancel and focus-loss regressions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# 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.
|