Files
aevolution/docs/adr/0079-camera-and-input-intentions.md
T
2026-10-08 12:08:53 -04:00

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.