Files
aevolution/docs/adr/0079-camera-and-input-intentions.md
T

3.5 KiB

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.