security-game/docs/adr/0007-locomotion-and-input-layers.md

ADR-0007: Locomotion and input layers

• Status: Accepted
• Date: TBD

Context

The prototype is first-person: WASD walks, mouse looks, Esc toggles capture. Action keys were then bound on the same letters. W is walk-forward in the input map and wand screening in GameManager._handle_key. A / D strafe and also allow or deny during inspection. Q is polite direction and is also bound as cancel.

A player who walks toward a guest on a wand venue therefore fires the wand. A player who strafes during an inspection can admit or refuse by accident. The mouse cannot click UI while it is captured, and Esc cannot mean both "release the mouse" and "I changed my mind."

Decision

Treat input as layers, only one of which owns a key at a time.

1. Locomotion (default): WASD walk relative to body yaw, mouse look on the captured cursor, pitch clamped. Short acceleration and deceleration. Gravity only when airborne; snap to the floor so the steps work. Walk speed stays around 3.2 m/s. No sprint or crouch in this pass.
2. Modal UI (radial, inspect, wand, radio, shift review): freeze walk and look. Recapture the mouse when the modal closes. A / D and arrows belong to the modal while it is open.
3. Equipment and global keys stay off the person-verb set: G flashlight, L door lock, Tab cycle nearby people, R emergency radio, F debug, V venue (debug). Wand leaves W; the optional shortcut is C.

Esc closes the top modal first and does nothing else. With no modal open it keeps the capture/release toggle.

Consequences

Positive

• Walking cannot fire wand, inspect, or admission.
• The mouse can click the action menu because capture is released while it is open.
• Cancel has one meaning when a menu is up.
• Locomotion stays first-person, which matches the body-camera framing.

Negative

• Freeze-while-modal means the player cannot sidestep during an inspect. That is accepted for this pass.
• Power users lose W as wand. The wheel and C replace it.
• The input map and _unhandled_input must agree, or the conflict returns.

Alternatives considered

• Keep letter-key verbs on WASD: Rejected because walk and wand already collide in the prototype.
• Third-person or click-to-move: Rejected; the body-camera overlay and the "you are the guard" framing depend on first person.
• Hold-right-mouse-to-look, free cursor otherwise: Rejected for this pass. Constant look is the default security-sim stance; the menu is the exception.
• Never freeze walk: Rejected because A / D cannot both strafe and step a menu highlight.