Implement M9.3 camera navigation and bounded input intentions
This commit is contained in:
+7
-1
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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