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
+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.