Files
aevolution/docs/engineering/CAMERA_INPUT.md
T
dingoandClaude Opus 5.5 5cf8709912 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>
2026-10-02 11:30:17 -04:00

5.1 KiB

M9.3 camera and input contract

Decision: ADR-0079. 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. 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 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 capture indicator, an intention dot and (since M9.4) the environment fixture. 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. Input never sends network messages, modifies the world or acts for an organism; the M9.4 fixture authority's own water moves are independent of input. M9.6 must bind intention ticks and counters to secure sessions; the server independently validates all requests.