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>
This commit is contained in:
dingo
2026-10-02 11:30:17 -04:00
co-authored by Claude Opus 5.5
parent bb8c2fc359
commit 5cf8709912
23 changed files with 1292 additions and 45 deletions
+2 -1
View File
@@ -457,7 +457,8 @@ terrain meshing or procedural creature animation is required.
**M9.8a (2026-10-02):** isolated Dear ImGui 1.92.9b probe qualified on Windows/Linux;
M9.8b adds bounded UI state, protected external input capture and bounded session
event delivery. M9.8c integrates the launcher, legend, labelled inspector, click
selection and session panel. ADR-0084 records each scope.
selection and session panel. M9.8d adds rebindable controls (ADR-0085). ADR-0084
records the toolkit scopes.
**M9.8 planning (2026-10-02):** user-confirmed Windows ZIP, temporary Gitea Actions
artifacts, labelled engineering UI/launcher and control rebinding. See the
+3 -2
View File
@@ -7,10 +7,11 @@ SDL3 probe (ADR-0084). M9.8b adds bounded notification/dialog state, protected
external input capture and bounded session events with disconnect/drain/reconnect
backpressure. M9.8c adds the launcher (labelled local fixture vs dev region,
bounded errors, Retry/Cancel), legend, labelled inspector, click selection, session
panel with the intention outcome record, and visible notifications/dialog. Tests,
panel with the intention outcome record, and visible notifications/dialog. M9.8d
adds rebindable controls (ADR-0085) with conflict checks and a validated file. Tests,
visual review and limits are recorded in engineering/VALIDATION.md.
Next: M9.8d rebindable controls, then packaging and qualification (9.8e-g).
Next: M9.8e reproducible Windows ZIP, then route design and qualification (9.8f-g).
Windows packages will be built locally until a Windows runner exists. Testing is internal; 172.10.1.160 is the
RKE2 control-plane address. VM qualification and the cluster restart drill remain
outstanding, as agreed. See engineering/M9_8_DELIVERY_PLAN.md.
@@ -0,0 +1,64 @@
# 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.
+2 -1
View File
@@ -96,4 +96,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0082: Dev session transport](0082-dev-session-transport.md) - TLS 1.3-only Mbed TLS 4.1.1 LTS (pinned, compiled-down), dev-only HMAC grants, versioned bounded protocol v1 and session admission for M9.
- [ADR-0083: Dev region sessions](0083-dev-region-sessions.md) - session server in evo-server, durable no-effect intentions on synthetic carriers, empty organism presentation, reconnect with fresh baselines, loopback-only drill-time dev deployment.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - accepted for the isolated M9.8a Dear ImGui 1.92.9b compatibility probe; application UI follows.
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
- [ADR-0085: Rebindable engineering controls](0085-rebindable-engineering-controls.md) - SDL-free action/HID-key bindings, conflict validation, versioned all-or-nothing controls file, binding capture before toolkit/world.
+4
View File
@@ -92,3 +92,7 @@ models in `src/client/ui`. Dear ImGui is confined to the platform adapter (overl
callback, event routing first, capture flags) and `apps/evo-client/panels.cpp`;
library headers expose no toolkit type. Panels read presentation copies only and
return requested actions; the app owns sessions, fixture and selection.
M9.8d (ADR-0085) adds SDL-free bindings (actions vs HID key usages, validation,
versioned controls file) to `evo_client_controls`; the adapter maps keys through
them and offers binding capture ahead of toolkit and world input.
+8 -3
View File
@@ -55,9 +55,14 @@ Use `poll_events()` -> read current window/navigation -> update camera ->
`step(frame)` retains the combined poll/present convenience for lifecycle tests.
Focus loss, hidden/minimized/closed/failed/zero-area state, or UI capture clears
held state. A fresh non-repeat keydown is needed to re-arm; releases always
clear keys. UI code calls `set_ui_capture` before world polling. Tab toggles an
engineering capture mode in the adapter; repeats do not retoggle it. Window
close remains available while captured.
clear keys. UI code calls `set_ui_capture` before world polling. The
toggle-capture action (default Tab) toggles an engineering capture mode in the
adapter; repeats do not retoggle it. Window close remains available while captured.
M9.8d (ADR-0085): keys reach `InputState` only through the current `Bindings`
(defaults: WASD move, arrows pan, Tab toggles capture). `set_bindings` releases
held actions and drains queued input; binding capture consumes the chosen key
before the toolkit and world. Releasing either key of an action releases it.
A 256-event saturated batch clears admission. Remaining queued keydowns are
ignored until a later poll drains the backlog; the drained state remains neutral
+8 -3
View File
@@ -1,4 +1,4 @@
# Native engineering client (M9.2–M9.8c)
# Native engineering client (M9.2–M9.8d)
This opens a resizable native window showing camera-controlled environment habitats
and organisms either from a local in-memory fixture authority or from one dev
@@ -47,13 +47,18 @@ one explicit backend, without fallback. `--frames N` exits after N bounded steps
window and pauses drawing. These options permit unattended smoke checks.
`--layer NAME` selects the displayed field or `moisture`; `--refresh-every N`
(1..1000 fixture authority ticks) delays view refresh so the stale state is visible.
Controls are saved to `controls-v1.txt` in the per-user settings directory
(Windows: `%APPDATA%\Aeternalis Games\Evolution Engineering Client`); `--controls
FILE` uses another file and `--show-controls` opens the Controls panel at start.
An invalid file is reported, left unchanged, and defaults apply.
`--pick X,Y` performs one scripted world click at window coordinates and
`--screenshot FILE.bmp` (requires `--frames`) saves the last frame; both exist for
unattended visual review.
Usage errors exit 2, lifecycle/fixture failures exit 1, orderly exit returns 0.
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
updates the small intention indicator (sent as intentions in remote mode). A left
Engineering controls (defaults; rebindable, ADR-0085): arrow keys pan, mouse wheel
zooms around the pointer, WASD updates the small intention indicator (sent as
intentions in remote mode). A left
click without dragging selects the topmost organism, else the habitat cell, for the
Inspector; a click that lands on a panel or dismisses a notification never selects
through it. Toolkit events are processed first: while a text field is focused or
+13
View File
@@ -70,3 +70,16 @@ Notices (app panels): newest at the bottom right, at most 320 logical pixels wid
stack stops at 60 % of the viewport height and shows how many notices are not drawn
and how many were discarded. `client-panels` renders the production panels through
the adapter and checks notice geometry and close-button dismissal.
## M9.8d controls panel
Opened from the launcher ("Controls...") or the mode banner. While open the host
keeps UI capture on, so neither keys nor clicks reach the world. Each slot button
arms adapter key capture for that slot (other buttons disabled); Escape or "Cancel
capture" ends it without a change, focus loss cancels it. A conflicting or
unbindable key is refused with fixed text naming the other action; the draft is
unchanged. Apply validates the whole set, installs it (held actions released) and
saves; Reset defaults and Cancel only change the draft/close. A save failure leaves
the bindings active for the session with a warning notice. The Legend hint lists
the keys in force. `client-panels` checks the panel geometry and that a slot click
requests capture without a world click.
+3 -3
View File
@@ -1,8 +1,8 @@
# M9.8 delivery plan
Status: M9.8a probe, M9.8b owned state/capture/event bounds and M9.8c launcher,
legend, labelled inspector and click selection complete, 2026-10-02; remaining
segments planned.
Status: M9.8a probe, M9.8b owned state/capture/event bounds, M9.8c launcher,
legend, labelled inspector and click selection, and M9.8d rebindable controls
complete, 2026-10-02; remaining segments planned.
No application UI or deployment completion is claimed. See ADR-0084 for the toolkit boundary.
## Confirmed scope
+41
View File
@@ -3756,3 +3756,44 @@ live WSL dev region showing the wrapped connection notice with its close button.
Limits unchanged: no physical mouse/keyboard session, DPI or accessibility review;
the live screenshot sent no intentions. No Docker/Gitea, packaging or deployment.
## 2026-10-02 — M9.8d rebindable controls (ADR-0085)
Implemented SDL-free bindings (nine actions, 92 named HID key positions, Escape
reserved, modifiers/locks/system keys excluded), a staging editor with conflict
refusal, and a versioned all-or-nothing controls file (4096 bytes, printable ASCII,
temp-file replace). The adapter maps keys through the bindings, releases and drains
on `set_bindings`, and offers binding capture ahead of the toolkit and world. The
app adds a Controls panel (launcher and banner), Legend key hints, startup loading
with a fixed-text notice on rejection, and `--controls FILE` / `--show-controls`.
Tests: `client-bindings` (names, defaults, conflicts incl. own secondary, missing
primary, reserved/modifier keys, editor refusal leaves draft unchanged, reset,
serialize/parse round trip, comments/CRLF/tabs/order, unknown/duplicate/missing
actions, bad names, extra tokens, non-ASCII/NUL, size bound, unsupported version,
file load/save/replace, unreadable/too large/invalid/missing directory). Lifecycle
`rebinding`: rebinding while held releases and drains (new key queued before the
change does not act), unbound old key ignored, two keys per action never stick,
rebound toggle, capture consumes the key (repeat ignored, toolkit never sees it,
rest of batch drained), Escape returned, focus loss and cancel give no key.
`client-panels` controls panel: fits viewport, a slot click requests capture for
Move left without a world click, chosen key consumed before the toolkit.
Executed: Windows MSVC client 9/9 and client-network 10/10 (final). Linux: clang-19
client-probe with clang-tidy enabled (keep-going; one test finding fixed) CTest
13/13; Xvfb/X11 lifecycle and panels; Clang ASan/UBSan CTest 13/13 plus Xvfb
lifecycle/panels; GCC 14 client-network CTest 10/10; clang-tidy app main/panels
(client-network); repository format check.
Visual review (dummy driver, software renderer): Controls panel with a custom file
(J/L/I/K, F1 + Keypad0) and matching Legend hint; invalid file (missing actions)
showing "Saved controls rejected: Move left needs a primary key..." with defaults in
use and the file byte-identical afterwards. Review found the startup notice expired
immediately (UI clock not yet advanced); fixed. A CRLF parsing defect was found by
the new test and fixed. CTest smoke runs create the empty per-user settings
directory (SDL creates it on lookup); no controls file is written by tests.
Not run: interactive rebinding with a physical keyboard, non-US layouts, IME, the
Apply/save path end-to-end through the GUI (covered by file and editor tests), DPI,
accessibility, Docker/Gitea, packaging or deployment.