Crate crcbl_input 

Device-agnostic action system: gameplay and UI code consume actions, never raw devices. Keyboard, mouse, gamepad and on-screen controls are interchangeable binding sources behind one config layer.

Contexts

Every action belongs to one named context: ActionMap::declare puts it in GAMEPLAY_CONTEXT, which is always active, and ActionMap::declare_in names another. ActionMap::push_context and ActionMap::pop_context stack contexts over it — ActionMap::push_context_modal one that passes nothing it does not bind — GLOBAL_CONTEXT stays above them all, and the topmost active context that binds an input consumes it — context.rs has the rules, including what happens to a key held while the stack changes, and what ActionMap::suppress_held and ActionMap::suppress_held_action withhold on request. ui declares the engine’s reserved ui context, text the text context a text field pushes over it, and list the list context an open pop-up list pushes over it.

Patterns and devices

ActionMap::set_repeat attaches a Repeat to an action, and ActionMap::set_tap, ActionMap::set_hold and ActionMap::set_double_tap attach a Tap, a Hold and a DoubleTap, all evaluated on the clock ActionMap::begin_tick advances (repeat.rs, and patterns.rs for how the last three share a press and what ActionMap::cancel_patterns cancels). ActionMap::set_emits makes one of the last three press a named button action when it fires (emit.rs). ActionMap::last_device names the kind of Device that last spoke, ActionMap::last_device_changed says it just changed, and ActionMap::hint how an action’s binding is shown to the player on it (hint).

Why an input did what it did

ActionMap::set_tracing records, for each press, the context that consumed it and every binding that read it — or that a modal context stopped it, or that nothing binds it — in a bounded ring an input inspector reads (trace).

Gamepads

Every pad backend emits GamepadEvents, by the conventions gamepad.rs states — positional buttons, sticks with +Y up, triggers 0…1, raw axes. A game reads them directly, or feeds ActionMap::gamepad_event, where Binding::PadButton, Binding::PadDpad, Binding::PadStick and Binding::PadTrigger read them. The Windows backend is xinput, compiled on Windows only, the Linux one is evdev, compiled on Linux only, the macOS one is game_controller, compiled on macOS only, and the browser one is web_gamepad, compiled on wasm32 only: no other target has a backend yet, and none has a stand-in that would report “no pads” as though it had looked.

Re-exports

pub use binding_asset::AssetRefusal;

pub use binding_asset::AssetWriteError;

pub use binding_asset::BindingAssetError;

pub use binding_text::BindingParseError;

pub use hint::DefaultLabels;

pub use hint::Hint;

pub use hint::HintLabels;

pub use trace::Outcome;

pub use trace::RESOLUTION_TRACE_CAP;

pub use trace::TraceEntry;

pub use trace::TracedInput;

pub use trace::TracedRead;

Modules

binding_asset

A game’s default actions as a RON file: ActionMap::from_ron reads one, ActionMap::to_ron writes one.

binding_text

A Binding’s stable text form, both ways — what a player’s saved rebinds are written in.

evdev

The Linux gamepad backend: evdev, polled, onto the gamepad seam.

hint

How an action’s binding is shown to the player right now: ActionMap::hint answers with a Hint — Space while the player is on the keyboard, A once they pick up an Xbox pad, Cross on a PlayStation one.

list

The engine’s reserved list context: the keys an open pop-up list takes — a drop-down’s list or a context menu — so that they reach neither the UI’s navigation nor the game.

text

The engine’s reserved text context: the keys a text field takes while it is being typed into, so that they reach neither the UI’s navigation nor the game.

trace

Why an input did what it did: the resolution trace an input inspector shows, which is the answer to “input eaten mysteriously” by the context stack.

ui

The engine’s reserved ui context: the navigation actions every UI screen is driven by, as the reserved ui_* table in docs/notes/tooling.md (What the deleted 07-ui-debug plan left behind) defines them.

Structs

ActionDecl

A declared action: name + kind + bindings.

ActionMap

Resolves raw input events to action values.

ActionOverride

One action whose bindings differ from its declaration.

ActivePad

The pad whose sticks drive the game, its filtered sticks, and the let-go rule.

Axis1Action

1-D analog axis: −1.0 … 1.0 (triggers, scroll wheels, an absolute pointer coordinate).

Axis2Action

2-D analog axis (WASD composite, stick, mouse motion).

ButtonAction

Button action with edge-detection flags.

DoubleTap

A double tap: two presses, the first no longer than DoubleTap::tap_time, the second going down within DoubleTap::window of the first coming up.

GamepadId

One physical pad, for as long as it stays connected.

GamepadSnapshot

What one pad is doing now — a level, not a delta, like ActionMap::virtual_stick’s deflection. See the module docs for the conventions every field follows.

Hold

A hold: a press that lasts Hold::time.

InputTickState

The input state for one server tick.

PadButtons

A set of PadButtons: the ones a pad holds down.

Repeat

A repeat schedule: the first repeat after delay seconds held, then one every interval.

Tap

A tap: a press released within Tap::time.

Enums

ActionKind

What kind of value an action produces.

ActionMapError

What can go wrong when mutating an ActionMap.

ActionValue

A unified action value — one variant per action kind.

Binding

A binding source: what raw input triggers this action.

ButtonState

A digital action: pressed / released / held with duration.

Cardinal

One of four directions, with +Y up as Binding::Wasd has it.

Device

A kind of input device.

GamepadEvent

What a backend reports about a pad.

Modifier

The modifier a Binding::Chord or a Binding::ButtonChord waits for: either of its two keys.

OverrideRefusal

Why one entry of a saved list of rebinds was not applied — see ActionMap::apply_override_text.

PadAxis

One of a pad’s analog axes, and its index into GamepadSnapshot::axes.

PadButton

A pad button, by position — see the module docs.

PadKind

What family a pad is, for the labels a hint shows (ActionMap::hint). Bindings never read it: buttons are positional.

Pattern

One of the patterns ActionMap::set_emits can make emit an action.

PointerAxis

Which coordinate of the pointer a Binding::PointerPosition reads.

Stick

Which stick a Binding::PadStick reads.

StickUpdate

What ActivePad::submit did with a snapshot.

Trigger

Which trigger a Binding::PadTrigger reads.

Constants

DOUBLE_TAP_WINDOW

The longest gap between the first tap’s release and the second press that still makes a double tap, in seconds.

EIGHT_WAY_SECTOR

Where one of the eight directions ends and the next begins: sin(π/8), the component a unit vector has at 22.5° off an axis.

GAMEPLAY_CONTEXT

The base context: always active, and where ActionMap::declare puts an action.

GLOBAL_CONTEXT

The context above every other: always active, never pushed or popped, and routed ahead of the whole stack, a modal context included — where a toggle that must work over any screen goes (a debug camera, the map key, the key that opens and closes an inventory). Declare into it with ActionMap::declare_in. It is not on the stack, so ActionMap::active_contexts does not list it.

HOLD_TIME

How long a press lasts before a hold fires, in seconds.

PAD_ACTIVITY_THRESHOLD

How far a stick or trigger must travel before the pad counts as the device that last spoke — see ActionMap::last_device.

REPEAT_DELAY

How long an action is held before its first repeat, in seconds.

REPEAT_INTERVAL

The time between repeats once they start, in seconds.

TAP_TIME

The longest a press can last and still be a tap, in seconds.

Functions

eight_way

The four digital directions the deflection (x, y) (+Y up) asks for, as (up, down, left, right) — a diagonal sets two.

radial_deadzone

A stick’s (x, y) with a scaled radial dead zone applied: zero within deadzone of centre, then rescaled so the edge of the dead zone reads 0 and full throw reads 1, clamped to the unit disc, with the direction kept.