Implement M9.3 camera navigation and bounded input intentions

This commit is contained in:
dingo
2026-10-01 17:26:35 -04:00
parent 04c7715646
commit bb0412cd0f
19 changed files with 899 additions and 27 deletions
+7 -1
View File
@@ -398,7 +398,13 @@ The added Gitea client job awaits remote verification.
surface/resource lifecycle implemented under ADR-0078; Windows/Linux tests,
analysis, ASan/UBSan and headless replay evidence in engineering/VALIDATION.md.
Physical DPI/input and real GPU loss remain hardware qualification, not claims
from injected events. Next gate: M9.3.
from injected events.
**M9.3 status (2026-10-01):** local-mm camera, logical/drawable conversion,
cursor-anchored zoom, bounded sequence/tick intentions and focus/UI/backlog
suppression implemented under ADR-0079. Camera round trips and native event
regressions are recorded in engineering/VALIDATION.md. The app uses local
fixture ticks, not server time. Next gate: M9.4.
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
+8 -8
View File
@@ -2,17 +2,17 @@
## Current gate — 2026-10-01
M9.2 adds an opt-in native `evo-client`, immutable presentation frame contract and
RAII platform/renderer lifecycle ([ADR-0078](adr/0078-native-client-lifecycle.md)).
Resize/pixel scale, focus, minimized/hidden windows, reset/loss and orderly close
are covered by Windows/Linux tests. Direct X11 linking resolves the observed
M9.1 unload allocation issue in repeated sanitizer checks. See
M9.3 adds local-mm pan/zoom camera mapping and bounded sequence/tick input
intentions ([ADR-0079](adr/0079-camera-and-input-intentions.md)). Focus loss,
UI capture/release and saturated event batches cancel held input. WASD controls
an intention indicator; arrows/wheel navigate the presentation fixture. See
[CLIENT.md](engineering/CLIENT.md) and [VALIDATION.md](engineering/VALIDATION.md).
Updated remote Gitea client execution remains unverified locally.
Next: **M9.3**, camera and bounded input intentions. The window displays a static
presentation fixture, not organisms or a connected world. No deployment,
simulation rules, persistent formats or world state changed in M9.2.
Next: **M9.4**, rendering microscopic environment views. The client displays a
camera-controlled fixture, not organisms or a connected world. Its tick is a
local input fixture counter. No deployment, simulation rules, persistent formats
or world state changed in M9.3.
The sections below retain earlier milestone delivery history.
@@ -0,0 +1,64 @@
# ADR-0079: Local camera and bounded input intentions
## Status
Accepted for M9.3 engineering client. No movement physics, network format or tick
frequency is selected. Controls are engineering bindings, not final player UI.
## Context
M9.2 has logical/drawable sizes but no navigation or input state. M6 views use a
caller-selected local XY habitat, measured in millimetres; pixels cannot become
authoritative positions. Focus changes can otherwise leave held movement active.
## Decision
Use SDL-free camera and input value contracts. Camera doubles are presentation
only, in the local XY plane (+X right, +Y up), with named millimetre coordinates.
Screen coordinates are logical window units (+Y down); drawable conversion uses
independent X/Y ratios. Content scale is not applied twice. Camera resize retains
centre/zoom; cursor-anchored zoom preserves the selected world point. Reject
non-finite values, zero viewports and out-of-range operations without mutation.
Input has fixed held-key state and bounded wheel accumulation, not an event or
command queue. WASD produces a signed quantized movement vector of norm <=1000;
arrows pan the camera and wheel zooms. UI capture (Tab in the engineering app)
and window focus/visibility gate both. Losing admission clears all held keys and
wheel state. Regaining admission requires a fresh non-repeat keydown; ignored
presses never resume by themselves. A release always clears its key.
External UI capture release drains pending events before re-admission, and a
saturated 256-event batch similarly quarantines its remaining input until drained.
Sampling produces one intention with a monotonically increasing sequence and
strictly increasing caller-supplied tick; suppressed input emits a neutral vector.
Invalid ticks or counter exhaustion fail without consuming sequence. No time is
read by input code. The standalone app labels its frame counter as a local input
fixture tick; M9.6 must bind this contract to validated session/tick context and
server-side admission. Never transmit native struct memory or trust client ticks.
Split platform polling from presentation so input and camera projection use the
current viewport before drawing; retain `step(frame)` as the combined convenience.
No new dependencies. No authoritative simulation or world format changes.
## Alternatives considered
- SDL keyboard state polling: can resurrect physically held keys after focus/UI
capture; explicit event-held state gives clear re-arm semantics.
- Mouse pixels as world coordinates: changes intent with DPI; rejected.
- Unbounded input event queue: unnecessary until session/prediction contracts exist.
- Variable simulation delta: camera pacing is presentation only, not simulation time.
## Benefits
Testable without SDL, bounded memory, no stuck input, explicit units and sequence
semantics; camera changes cannot change biological state.
## Costs
Local projection has finite numeric bounds and approximate floating-point round
trips. Bindings and single-window capture are deliberately narrow.
## Risks
Synthetic events do not qualify physical keyboard layouts, IME or multi-monitor
DPI. M9.6/M10 still need authentication, tick windows, replay protection and rate
limits. This contract is neither a secure session nor a networking implementation.
## Consequences
Public camera/input headers, host caller and tests change together. M9.4 will
project environmental data through this camera. UI capture is an explicit host
API; a future UI must set it before polling its world-input batch.
+1
View File
@@ -90,3 +90,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0077: Scoped native client dependencies](0077-scoped-native-client-dependencies.md) - SDL 3.4.16 window/events and 2D renderer for the opt-in M9.1 probe; no simulation dependency.
- [ADR-0078: Native client lifecycle](0078-native-client-lifecycle.md) - main-thread RAII application, immutable presentation frames and explicit surface/device failure handling.
- [ADR-0079: Camera and input intentions](0079-camera-and-input-intentions.md) - local-mm projection, bounded sequence/tick intentions, focus/UI capture and explicit host event ordering.
+9 -3
View File
@@ -1,4 +1,4 @@
# Native client boundary (M9.2)
# Native client boundary (M9.2–M9.3)
Implemented scope: desktop lifecycle and primitive presentation, not gameplay.
ADR-0077 selects SDL; ADR-0078 defines its ownership and view boundary.
@@ -23,7 +23,7 @@ main or be used/destroyed on another thread.
valid until frame destruction/assignment. `Application::step(const Frame&)`
borrows it for the call only; there is no queue, stored pointer or simulation
mutation. Coordinates are logical window units, top-left origin, +Y down. They
are presentation units, never world millimetres. M9.3 owns world-screen mapping;
are presentation units, never world millimetres. M9.3 implements world-screen mapping;
M9.4 projects environment samples. In particular, do not retain M6 validation
tokens/store pointers in a renderer or serialize them as a client protocol.
@@ -32,7 +32,7 @@ separately. Resizes/display changes query SDL rather than trust event payloads.
Drawing scales independently by pixel/logical width and height; content scale is
for future UI sizing, not a second pixel multiplier. Hidden/minimized/zero-area
windows skip rendering. Focus loss disables the future input admission flag;
there are no held gameplay inputs in M9.2. Close is terminal.
M9.3 clears all held intentions on admission loss. Close is terminal.
Each step consumes at most 256 events, filters window-specific events and renders
one frame. Target reset needs only redraw (no cached textures). Device reset
@@ -41,6 +41,12 @@ failure latch an error until destruction; no silent backend substitution or busy
recovery loop. Typed errors reach the process boundary. The host paces frames
outside the renderer and catches allocation/standard-library exceptions.
M9.3 also exposes separate `poll_events()` and `present(frame)` calls so camera
mapping uses current resize/input state. SDL-free camera and input contracts are
specified in [CAMERA_INPUT.md](../engineering/CAMERA_INPUT.md) and ADR-0079.
UI capture and event-backlog handling suppress held world input; sequence/tick
intentions do not confer server authority. M9.6 owns session binding.
Failure tests inject actual SDL events, including foreign window IDs, with no
test-only production hooks. Real device failures and physical DPI/input require
manual hardware qualification at M9.8. The native client is opt-in and never
+78
View File
@@ -0,0 +1,78 @@
# M9.3 camera and input contract
Decision: [ADR-0079](../adr/0079-camera-and-input-intentions.md).
Headers: `include/evo/client/camera.hpp`, `input.hpp`, `application.hpp`.
No SDL types enter the camera/input contracts. Neither library mutates or links
the simulation. The world coordinate header supplies numeric bounds only.
## Coordinates and camera
`WorldPoint` stores presentation doubles in millimetres in a caller-selected
region-local XY plane, +Y up. Its half-open range matches M5/M6 voxel bounds
times the 1000 mm pitch: [-1048576000, 1048576000) on both axes. Do not mix
frames/worlds or silently map the old periodic particle fixture into this plane.
M6 micrometre habitat offsets require explicit conversion to mm at M9.4 projection.
`ScreenPoint` is logical window space, top-left origin and +Y down. `PixelPoint`
is drawable space. Viewport dimensions must be 1..32768; zero/minimized surfaces
are not a camera viewport. Application skips viewport updates while zero-area.
`units_per_mm` is logical units per mm, bounded [0.0001, 10000]. Screen/pixel
conversions validate finite values within +/-1e15; world projection may be
offscreen. Clip to the viewport before converting to renderer float primitives.
The projection is `screen_x = (world_x - centre_x) * scale + width/2` and
`screen_y = (centre_y - world_y) * scale + height/2`. Pixel conversions apply
pixel_width/width and pixel_height/height independently. Display content scale
is not a further multiplier. Round trips are approximate; tests use 1e-6 mm
tolerance for their bounded fixtures, not a global deterministic-state promise.
Resize retains centre/zoom. Pan moves the camera in screen-axis directions by
at most 32768 logical units per component per call. Positive X moves the camera
right; positive Y moves it down. Zoom requires a positive finite factor and an
anchor inside the logical viewport. It preserves the world point under that
anchor; requests beyond zoom/world bounds reject without mutation. These are
engineering numeric limits, not biological movement or world-size rules.
## Input and host ordering
`InputState` has eight held-key slots, one cursor and bounded accumulated wheel
steps ([-8,8], individual inputs must be finite and within [-128,128]). Navigation
consumes wheel steps once; held pan directions persist until release/admission
loss. Pointer events require finite coordinates within +/-32768 logical units.
Invalid values reject rather than entering camera math.
`Intention` carries sequence, tick and a signed movement vector. Cardinal
components are +/-1000, diagonals +/-707 (norm <=1000); opposite keys cancel.
This is direction/demand, never velocity, distance, energy or accepted position.
Sequences start at 1 by default; the host can seed a local stream counter but
that is not an authenticated resume grant. Successful samples require strictly
increasing ticks. Exhaustion/stale tick rejection consumes neither tick nor
sequence. Inactive input still samples a neutral intention, allowing later
session adapters to express stopped input. No pending command queue exists.
Use `poll_events()` -> read current window/navigation -> update camera ->
`sample_intention(tick)` -> build immutable frame -> `present(frame)`.
`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.
A 256-event saturated batch clears admission. Remaining queued keydowns are
ignored until a later poll drains the backlog; the drained state remains neutral
until a fresh keydown. This prevents delayed releases from sustaining movement.
All window-specific input filters the owned SDL window ID.
Releasing capture through the external UI API also drains the pending SDL batch
before re-admission, preventing keys queued while captured from becoming world
presses. Poll once after release, then fresh presses are admitted. The engineering
Tab toggle is processed in event order, so subsequent presses after that toggle
belong to its new capture state.
The standalone host uses an increasing **local fixture tick**, not server time.
It draws a world-anchored rectangle, a capture indicator and an intention dot.
Camera panning uses 400 logical units/second with elapsed time clamped to 0.1 s;
wheel zoom uses 2^(steps/4). These are presentation controls. No network messages,
world modifications or organism actions occur. M9.6 must bind intention ticks
and counters to secure sessions; the server independently validates all requests.
+10 -2
View File
@@ -1,8 +1,9 @@
# Native engineering client (M9.2)
# Native engineering client (M9.2–M9.3)
This opens a resizable native window containing a static presentation fixture.
This opens a resizable native window containing a camera-controlled presentation fixture.
It does not simulate a world, connect to a server or implement cellular gameplay.
Contract: [client architecture](../architecture/CLIENT_ARCHITECTURE.md), ADR-0078.
Camera/input: [contracts and limits](CAMERA_INPUT.md), ADR-0079.
## Build and run
@@ -26,6 +27,13 @@ one explicit backend, without fallback. `--frames N` exits after N bounded steps
window and pauses drawing. These options permit unattended smoke checks.
Usage errors exit 2, lifecycle failures exit 1, orderly exit returns 0.
Engineering controls: arrow keys pan, mouse wheel zooms around the pointer, WASD
updates the small intention indicator without moving the world fixture. Tab
toggles UI capture: the top-left bar turns orange and navigation/movement input
is suppressed. Leaving capture/focus loss requires fresh presses. This is a
focus exercise, not the final player UI. The host's input tick is a local fixture
counter and is never interpreted as authoritative server time.
For native X11 regression on a CI host:
```sh
+44
View File
@@ -3240,3 +3240,47 @@ boundary requires single-main-thread use. Tests do not establish physical
multi-monitor DPI, real keyboard/focus behavior, Wayland, hardware GPU loss or
human visual acceptance. Those remain M9.3/M9.8 qualification work. No cluster
operation was performed.
## M9.3 camera and input intentions — 2026-10-01
Implemented ADR-0079 and CAMERA_INPUT.md: SDL-free local-mm camera and held input
state, explicit logical/pixel conversion, cursor-anchored zoom, bounded
sequence/tick intentions and polling-before-projection. The app demonstrates
arrows/wheel navigation, a WASD intention indicator and Tab UI capture. Its tick
is a local fixture counter; no server/session/authoritative movement is present.
Executed:
- Windows MSVC 19.44 Release via `tools/windows-check.ps1 -Preset client -Action
check`: 3/3 labeled tests passed. Native Windows lifecycle/input executable
and the final `evo-client --frames 3` smoke passed.
- Linux GCC 14 Release, existing combined probe/client build: 5/5 labeled tests
passed; native Xvfb/X11 lifecycle and input events passed. The final app-only
startup/error-reporting adjustment was additionally built/tested with MSVC and
Clang ASan below (the GCC suite preceded that adjustment).
- Clang 19 Debug ASan/UBSan: all owned camera/input/platform/app/test code built;
3/3 labeled tests and native Xvfb/X11 tests passed with leak detection enabled,
without preload or suppressions. Final hidden/software three-frame app smoke
also passed. SDL/system libraries remain outside comprehensive instrumentation.
- Pure camera tests cover 220 world/logical/pixel round trips over four viewport/
DPI/aspect combinations and five zoom scales (1e-6 mm tolerance for fixtures),
anchor preservation, pan direction, resize stability, NaN/infinity, numeric
limits and unchanged state after rejected operations.
- Input tests cover key release/opposites/diagonals, focus re-arm, ignored repeats,
UI capture, bounded/consumed wheel accumulation, invalid input, monotonically
increasing sequence/tick and stale/overflow rejection. Native SDL tests cover
WASD/arrows, Tab repeat, focus loss/regain, wheel direction/pointer, minimize,
saturated event batches and queued keys crossing external capture release.
- clang-tidy 19 with warnings-as-errors passed on all six changed/new translation
units; corrected a duplicated wheel-error branch. Final app-only adjustment
also passed analysis. Repository format-check passed.
- Headless Release configured with both client options OFF, rebuilt `evo-sim`,
replayed seed 123456 / eight entities / 1000 ticks: unchanged
`d61ad5bf0c928c76`, `replay_verified=true`.
The existing client CI target now picks up the controls library and expanded
lifecycle suite automatically. Docker/Gitea execution was not observed locally.
No full headless suite or TSan rerun; owned client state remains main-thread-only.
No physical keyboard/IME, human visual, real multi-monitor DPI, Wayland or real
GPU-failure qualification is claimed from injected events and Xvfb. No network
traffic, database, world mutation or deployment operation was introduced.