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:
+2
-1
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user