Gamepads
Generated from engine/input/gamepads.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/input/gamepads.h" · namespace labrador
class Gamepads
Section titled “class Gamepads”Every pad, this frame and last, and the edges between them.
A game reads the borrowed instance from Application::gamepads(). The shell constructs it and calls poll(); game code does not advance the snapshots itself.
WHY THE ENGINE POLLS THIS AND A GAME DOES NOT. An edge is "down now, up last frame", so it is only right if "last frame" is the frame before this one. An edge detector a game keeps for itself advances its "previous" only on the frames its owner happens to be running, so it needs priming by hand at every transition, and a second one - menus beside gameplay - drifts from the first. Application polls this once per fixed update, before that update's states run, so every reader measures across the same two polls and nothing is primed.
A slot is a slot. The backend assigns it (GamepadReader::read) and a pad keeps it while it stays connected, but it is not stable across a replug - a controller that comes back in a different slot is a different slot. Binding a player to one for the length of a match is a decision a game makes; the engine reports connected(), just_connected() and just_disconnected() so that it can make it, and makes none itself.
max_count
Section titled “max_count”static constexpr int max_count = 4;Gamepads
Section titled “Gamepads”For the shell or a device fixture. A game uses Application::gamepads(). reader is borrowed and must outlive this.
void poll();Called by the shell before state updates. Samples the reader once and reads every slot. What was current becomes previous, so every edge below is measured across exactly one frame.
state · previous_state
Section titled “state · previous_state”const GamepadState& previous_state(int slot) const;Throw std::out_of_range naming the slot if it is not in [0, max_count). A slot outside that is a bug in the caller rather than an absent pad, and the two deserve different answers (T6).
held · pressed · released
Section titled “held · pressed · released”bool pressed(int slot, GamepadButton button) const;bool released(int slot, GamepadButton button) const;trigger_held · trigger_pressed · trigger_released
Section titled “trigger_held · trigger_pressed · trigger_released” float threshold) const;bool trigger_pressed(int slot, GamepadTrigger trigger, float threshold) const;bool trigger_released(int slot, GamepadTrigger trigger, float threshold) const;A trigger is analogue, so an edge on one needs the threshold that makes it a button. The caller supplies it because no single value is right for every use of the same trigger.
connected · just_connected · just_disconnected
Section titled “connected · just_connected · just_disconnected”bool connected(int slot) const;bool just_disconnected(int slot) const;vibrate
Section titled “vibrate”Sends one bounded request to the pad in slot, replacing any request still running there; gamepad.h's Vibration says what the fields mean and what is the game's to decide. The slot is checked as state() checks it, then the request as check_vibration checks it, and both throw rather than send something else.
unavailable when the slot had no pad at the last poll or the reader could not pass the request on; nothing is then waiting to be sent. submitted when the pad API took it, which is not evidence that a motor turned. A request is stopped when its seconds pass, its pad leaves the slot, the reader is suspended or the reader is destroyed, and resuming does not replay it. Which of a game's own transitions should also stop one - a pause menu, a scene change - is the game's call, with stop_vibration.
stop_vibration
Section titled “stop_vibration”void stop_vibration(int slot);Stops slot's motors and forgets its request. Safe on an empty slot and on one with nothing running. Throws std::out_of_range for a slot state() would refuse.
Related types
Section titled “Related types”Named in the public declarations above: GamepadButton, GamepadReader, GamepadState, GamepadTrigger, Vibration, VibrationResult.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/collision/collision_state.cppsamples/components/gallery_binding.cpp,gallery_state.cpp,gallery_text.cppsamples/linesweeper/states/pause_state.cpp,play_state.cppsamples/local_multiplayer/controls.h,join_state.cpptests/input/scripted_gamepad_source_tests.cpp,vibration_tests.cpptests/input/web/scripted_no_api_tests.cpp
Explained in
Section titled “Explained in”Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.