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