66 lines
3.5 KiB
Markdown
66 lines
3.5 KiB
Markdown
[Reviewed]
|
|
# 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.
|