Gamepad

Gamepad state for one sampled input snapshot.

The host samples up to four gamepads once per host cycle. Queries are pure and do not cross the host boundary or allocate. Button state uses the same bits as keyboard and mouse input: held is 1, pressed is 2, released is 4. Unlike keyboard and mouse edges, which are recorded from the window system's events, gamepad edges come from comparing two consecutive samples: a button pressed and released between two cycles is not seen. Hold a button for at least one cycle to be sure it registers.

Resolve a View from the current input.devices during update!. Retaining a view also retains that snapshot's sampled lists.

from_index : U64 -> Try(Id, [InvalidGamepadIndex])

Validate and wrap a zero-based gamepad index.

lookup : Snapshot, Id -> [Connected(View), Disconnected]

Resolve a slot into a snapshot-scoped connected view. Callers handle disconnect once, after which button and axis queries stay allocation-free.

button_up : { ..state, buttons : List(U8) }, Id, Button -> Bool

Whether a button is currently up.

button_pressed : { ..state, buttons : List(U8) }, Id, Button -> Bool

Whether a button went from up to down between the previous sample and this one. Sampled, so a press and release inside one cycle is lost.

button_released : { ..state, buttons : List(U8) }, Id, Button -> Bool

Whether a button went from down to up between the previous sample and this one, with the same caveat as button_pressed.

axis : { ..state, axes : List(F32) }, Id, Axis -> F32

Read an axis from this input's latest sample. Stick axes are normally in [-1, 1]. raylib reports trigger axes in [-1, 1], where -1 is released.

Snapshot

:= {
    connected : List(U8),
    buttons : List(U8),
    axes : List(F32),
}

Fixed-size gamepad state sampled once per host-cycle input.

Id

:= [One, Two, Three, Four]

One of the four gamepad slots sampled by the platform.

is_eq : _

Compare two of these values.

Button

:= [
    Unknown,
    DpadUp,
    DpadRight,
    DpadDown,
    DpadLeft,
    FaceUp,
    FaceRight,
    FaceDown,
    FaceLeft,
    LeftBumper,
    LeftTrigger,
    RightBumper,
    RightTrigger,
    Select,
    Guide,
    Start,
    LeftStick,
    RightStick,
]

Standard gamepad buttons. Face directions are layout-neutral rather than assuming Xbox, PlayStation, or Nintendo labels.

Axis

:= [LeftX, LeftY, RightX, RightY, LeftTriggerAxis, RightTriggerAxis]

Analog stick and trigger axes.

View

Gamepad.View :: # (opaque)

A gamepad proven connected in this snapshot. This is a small value holding references to the existing flat lists; lookup does not allocate or resample. It is valid as a view of this snapshot only. Resolve the pad again from the next cycle's Devices.Snapshot instead of retaining it in the model.

id : View -> Id

Slot occupied by this connected pad.

button_up : View, Button -> Bool

Whether a button is currently up.

button_pressed : View, Button -> Bool

Whether a button went from up to down between the previous sample and this one. Sampled, so a press and release inside one cycle is lost.

button_released : View, Button -> Bool

Whether a button went from down to up between the previous sample and this one, with the same caveat as button_pressed.

axis : View, Axis -> F32

Read an axis from this input's latest sample. Stick axes are normally in [-1, 1].

left_stick : View -> { x : F32, y : F32 }

Left stick as a two-dimensional vector.

right_stick : View -> { x : F32, y : F32 }

Right stick as a two-dimensional vector.