Gamepad

:= []

Gamepad module - allocation-free helpers for the per-frame Host snapshot.

The host samples up to four gamepads once per frame. Availability, packed button state, and axes are stored in three flat persistent lists so queries do not cross the host boundary or allocate. Button state uses the same bits as keyboard and mouse input: held = 1, pressed = 2, released = 4. Resolve a pad from the current Host each frame; retaining either a snapshot or ConnectedPad keeps old lists alive and makes the host copy on update.

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

Validate and wrap a zero-based gamepad index.

lookup : Snapshot, GamepadId -> [Connected(ConnectedPad), Disconnected]

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

available : { ..state, connected : List(U8) }, GamepadId -> Bool

Compatibility query for code that only needs connectivity. Prefer snapshot.lookup(id) before reading buttons or axes.

button_down : { ..state, buttons : List(U8) }, GamepadId, Button -> Bool

Whether a button is currently held.

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

Whether a button is currently up.

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

Whether a button was first pressed this frame.

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

Whether a button was released this frame.

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

Read an axis sampled for this frame. Stick axes are normally in [-1, 1]. raylib reports trigger axes in [-1, 1], where -1 is released.

left_stick : { ..state, axes : List(F32) }, GamepadId -> { x : F32, y : F32 }

Left stick as a two-dimensional vector.

right_stick : { ..state, axes : List(F32) }, GamepadId -> { x : F32, y : F32 }

Right stick as a two-dimensional vector.

Snapshot

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

Fixed-size input snapshot stored on Host and sampled once per frame.

GamepadId

:= [One, Two, Three, Four]

One of the four gamepad slots sampled by the platform.

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.

ConnectedPad

Gamepad.ConnectedPad :: # (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. Do not retain it in app models; call host.gamepad(id) again when the next frame arrives.

id : ConnectedPad -> GamepadId

Slot occupied by this connected pad.

button_down : ConnectedPad, Button -> Bool