Implement M9.3 camera navigation and bounded input intentions
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user