# Input

## Keyboard — `Res<ButtonInput<KeyCode>>`

| Method | Purpose |
|--------|---------|
| `pressed(k)` | held this frame |
| `just_pressed(k)` / `just_released(k)` | edge detection |
| `any_pressed(iter)` / `any_just_pressed(iter)` / `all_pressed(iter)` | multi-key checks |
| `get_pressed()` / `get_just_pressed()` | iterate held / newly pressed |
| `clear_just_pressed(k)` | consume the press |

`ButtonInput<Key>` exists for logical/locale-aware keys (text-ish input); `KeyCode` is physical layout.

## Mouse

Buttons: `Res<ButtonInput<MouseButton>>` — same API. Variants: `Left`, `Right`, `Middle`, `Back`, `Forward`, `Other(u16)`.

Motion and scroll:

| Type | Kind | Purpose |
|------|------|---------|
| `MouseMotion` | Message | raw per-event `delta: Vec2` — read with `MessageReader<MouseMotion>` |
| `AccumulatedMouseMotion` | Resource | frame total, reset each frame — usually what you want |
| `MouseWheel` | Message | scroll with `MouseScrollUnit` (Line/Pixel) |
| `AccumulatedMouseScroll` | Resource | frame total scroll |

Cursor position — from the `Window` component, logical pixels, origin top-left:

```rust
fn cursor(windows: Query<&Window>) -> Result {
    if let Some(pos) = windows.single()?.cursor_position() { /* ... */ }
    Ok(())
}
```

**UI click-through trap**: `ButtonInput<MouseButton>` is raw winit input — it fires even when the click landed on a UI panel. World-click handlers must verify the click wasn't consumed by UI (e.g. a full-screen background `Interaction` node that only receives clicks passing through all UI).

## Gamepad

- Buttons: `Res<ButtonInput<GamepadButton>>` — same pressed/just_pressed API; analog buttons also map to `[0.0, 1.0]`.
- Axes: `Res<Axis<GamepadAxis>>` → `get(axis) -> Option<f32>` in `[-1.0, 1.0]`.
- Messages: `GamepadButtonStateChangedEvent`, `GamepadButtonChangedEvent`, `GamepadAxisChangedEvent`, `GamepadConnectionEvent`.
- Deadzones/thresholds: `GamepadSettings` component.

## Touch

- `TouchInput` message with `TouchPhase` (Began/Moved/Ended).
- `Touches` resource — active-touch queries, analogous to `ButtonInput`.
- `ForceTouch` for pressure-capable devices.
- Requires the `touch` feature flag.

## Feature gating (0.18+)

Input sources (`mouse`, `keyboard`, `gamepad`, `touch`, `gestures`) are feature-gated. They're on by default via `bevy_window`/`bevy_gilrs`, but with `default-features = false` they must be listed explicitly — missing input with no errors usually means a missing feature.

## Action mapping

Bevy has no built-in action-mapping layer. The community standard is `leafwing-input-manager`; check the project's `Cargo.toml` before hand-rolling bindings.

## Pattern

```rust
fn movement(keys: Res<ButtonInput<KeyCode>>) {
    let mut dir = Vec3::ZERO;
    if keys.pressed(KeyCode::KeyW) { dir.z -= 1.0; }   // forward is -Z
    if keys.pressed(KeyCode::KeyS) { dir.z += 1.0; }
    if keys.pressed(KeyCode::KeyA) { dir.x -= 1.0; }
    if keys.pressed(KeyCode::KeyD) { dir.x += 1.0; }
}
```