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