Module input 

Keyboard and controller input as a game’s actions (game ADR-0006, game ADR-0034), generic over its ActionSet (tickets 1106 and 1107): a data-driven Keymap from chords and controller buttons to actions (keymap), and InputState (state), which turns presses and releases plus frame time into the actions screens see, including repeat for held repeatable keys and buttons. FrameInput (frame) is one frame’s input as a screen sees it.

The player’s own bindings (3 slots per action, per layout, and the controller buttons) are in bindings; pad turns the controllers’ raw state into button presses, and crank a crank’s turns; help_keys names keys and buttons in help text.

Fixed keys (fixed, game ADR-0031): plain Escape backs out of capturing a key and plain Delete empties a slot on a rebinding screen, so neither can be bound (Chord::is_reserved). Which action a fixed key also triggers in play is the game’s (ActionSet::fixed_keys). Shift+Escape and Shift+Delete are ordinary chords.

A screen declares the actions it reacts to (Screen::actions); ui_actions gives them for an engine screen or widget, which reacts to UiActions. fit checks that the required ones fit a target’s buttons (ADR-0008 §3).

Key, Chord, Button and Layout are the keymap file’s (shuyi_assets::keymap) and re-exported here.

Re-exports

pub use bindings::BindError;

pub use bindings::ButtonSlots;

pub use bindings::LayoutBindings;

pub use bindings::PadBindings;

pub use bindings::PlayerKeys;

pub use bindings::Slots;

pub use crank::Crank;

pub use fixed::TextKey;

pub use fixed::capture_abort_key_name;

pub use fixed::clear_slot_key_name;

pub use fixed::is_capture_abort;

pub use fixed::is_clear_slot;

pub use fixed::text_key;

pub use fixed::text_key_names;

pub use frame::FrameInput;

pub use frame::frame_seconds;

pub use help_keys::ARROWS;

pub use help_keys::HelpKeys;

pub use keymap::ChordWait;

pub use keymap::Keymap;

pub use pad::ButtonSet;

pub use pad::PadId;

pub use pad::PadKind;

pub use pad::PadState;

pub use pad::Pads;

pub use state::Device;

pub use state::Input;

pub use state::InputState;

pub use state::MAX_REPEATS_PER_UPDATE;

Modules

bindings

The player’s key and button bindings (tickets 0217 and 0816, game ADR-0031, game ADR-0053): every rebindable action has SLOTS key slots and SLOTS controller-button slots. Each layout keeps its own keys (LayoutBindings); the buttons are one setup shared by both layouts (PadBindings); the lot is saved as PlayerKeys. Rules from docs/design/controls.md, Rebinding keys and Rebinding buttons. Pure: the game reads and writes the saved text. Generic over the game’s ActionSet (ticket 1106).

crank

A crank (the Playdate’s, ticket 1035) as two controller buttons: each notch wound backwards is a press and release of Button::CrankBack, each notch forwards one of Button::CrankForward, so the crank reaches a game through the player’s bindings like any button (game ADR-0034). How far a notch is comes from the keymap file’s crank (CrankDef).

fit

Whether a game’s controls fit a target (ADR-0008 §3): on each screen, the required actions it declares (Screen::actions) must bind to distinct inputs the target’s profile offers.

fixed

The keys no player can rebind (docs/design/controls.md, Rebinding keys; game ADR-0031): plain Escape backs out of the Key bindings screen’s “Press a key…” and plain Delete empties a slot there, so neither can be bound (Chord::is_reserved); and a text box’s own Enter, Backspace and Escape. Which action a fixed key also triggers in play is the game’s data (ActionSet::fixed_keys).

frame

FrameInput: one frame’s input as a screen sees it. Generic over the game’s ActionSet (ticket 1106), and frame_seconds, which makes a frame time a platform reports safe to add up.

help_keys

Help text that names keys and controller buttons. Names always come from the active Keymap, never string literals, because each layout binds actions to different keys (game ADR-0015) and the player can rebind them (game ADR-0031); and they follow the Device the player pressed last (docs/design/controls.md, Controller): keys on the keyboard, the pad’s own button names on a controller.

keymap

Keymap: the lookup from key chords and controller buttons to a game’s actions, plus the key-repeat timings (game ADR-0015, game ADR-0031, game ADR-0034). Generic over the game’s ActionSet (ticket 1106).

pad

Controllers (ticket 0219, game ADR-0034): from each connected pad’s raw state to the Button presses and releases InputState is fed. Pure: app fills a PadState per pad every frame (gilrs on native, the browser’s Gamepad API on web) and Pads::update does the rest, so both platforms share these rules (docs/design/controls.md, Controller):

state

InputState: turns key and controller-button presses and releases plus frame time into a game’s actions, with repeat for held repeatable keys and buttons (game ADR-0015, game ADR-0034), and button chords (ticket 1034). Generic over the game’s ActionSet (ticket 1106).

Structs

ButtonChord

What a controller binding is: one Button, or two pressed together (a button chord, ticket 1034), written "South+East" in keymap files and saved bindings. The two are kept in Button::ALL order, so "East+South" is the same chord as "South+East" (and is shown as the latter). How a chord fires is the input’s business (shuyi_ui::input::state).

Chord

A key plus modifier state, e.g. h or Shift+h. Shift+h and h are different chords.

ChordDef

How ButtonChords fire (shuyi_ui::input::state): a chord button whose own action waits for its partner waits at most window_ms (unless it waits for its release).

CrankDef

How a crank turns into Button::CrankBack and Button::CrankForward presses (shuyi_ui::input::crank): one per notch_degrees wound.

KeymapDef

The validated keymap: every Layout’s default keys, the layout picker’s bindings, the default controller buttons, plus the key-repeat timings and stick thresholds they share.

Layout

A complete set of key bindings the player can pick: one entry of layouts in the keymap file, named by its id. The file decides which layouts there are; this is only the name, kept inline so a layout is Copy. Names are ASCII letters, digits and _, at most LAYOUT_NAME_MAX bytes (RightHanded).

RepeatDef

Key-repeat timings for held repeatable actions.

StickDef

How far a stick must be pushed to count as a held direction (Button::LeftStickUp and the rest), in percent of its full travel. release_percent is below press_percent, so a stick resting near the edge of the dead zone doesn’t flicker.

Enums

Button

A controller button, named by its position on an Xbox-shaped pad, whatever is printed on it (game ADR-0034). Each stick’s four directions count as buttons too, and so does a crank wound one notch either way (the Playdate’s, ticket 1035: pressed and let go once per notch), and so does an item of the game’s own in the system’s menu (pressed and let go when the player picks it, ADR-0008 §3). app translates what the platform reports to these; anything else on a pad is ignored, and so are the system’s own buttons (the Playdate’s Menu and Lock, the Deck’s Steam and Quick Access), which no keymap can name.

Key

A hardware-agnostic keyboard key. app translates platform key codes to these; anything without a variant is ignored.

UiAction

What the generic widgets (a menu), the Key bindings screen and the debug hook react to. A game maps some of its actions onto these with ActionSet::ui; the rest are its own business.

Constants

LAYOUT_NAME_MAX

Most bytes in a Layout’s name.

NAVIGATION

What the engine’s menu-like screens react to: the four directions, Confirm and Cancel.

SLOTS

Key slots per action: a layout lists at most this many chords for an action, and the player can give each action up to this many keys (docs/design/controls.md, Rebinding keys).

Traits

ActionSet

Everything a player can ask for in one game: the game’s action enum. The keymap file, the keymap, held keys and repeat, the player’s saved bindings and help text are all built on it, never on one game’s actions.

Functions

ui_actions

The game’s actions that ActionSet::ui takes for one of uis, in ActionSet::ALL order: what an engine screen or widget that reacts to uis declares (Screen::actions).

Type Aliases

Bindings

Validated bindings as a lookup: each chord maps to exactly one action (of one group). Unbound chords are absent.

LayoutKeys

One layout’s default keys: every action with its chords in the order the keymap file lists them (at most SLOTS, none reserved), no chord on two actions of one group. The order matters: the first chord is the one help text names, and the chords fill the player’s key slots in this order.

PadKeys

The default controller buttons: every action with its buttons and button chords in the order the keymap file lists them (at most SLOTS), none on two actions of one group. One table for every layout.