Input
The application owns four input devices and lends them to your states: app->keyboard(),
app->gamepads(), app->mouse() and app->touch(). All four are read once at the start of
every step, before any state updates (The tick),
and you ask them questions from update(). If a build fails after you change your input code,
Read a build error shows how to read the error.
Change a control in your game
Section titled “Change a control in your game”The starter project’s controls are in two files, one for each of its screens. The game itself,
HelloState in game\states\hello_state.cpp, reads the keys that move the greeting and the
key that asks to quit. The quit question, ConfirmState in game\states\confirm_state.cpp,
reads its own keys for yes and no. Each screen reads only its own keys, so changing a key on one
screen does not change it on the other. This section moves the greeting with I, J, K
and L in place of W, A, S and D, and makes Q do what Escape did on
both screens: ask to quit, and answer no. It takes about ten minutes.
Do Make a first change first, and keep a copy of the game with the copy line from its step 1 before you start. The commands run in the x64 Native Tools Command Prompt, in your project’s folder:
cd /d C:\dev\mygame-
Change the movement keys. Open the game’s state:
Terminal window notepad game\states\hello_state.cppPress Ctrl+F and search for
keyboard_direction(const Keyboard& keyboard). Below it are fouriflines, each reading an arrow key and a letter:samples/minimal/states/hello_state.cpp {direction.x -= 1.0f;}if (keyboard.held(Key::right) || keyboard.held(Key::d)){direction.x += 1.0f;}if (keyboard.held(Key::up) || keyboard.held(Key::w)){direction.y -= 1.0f;}if (keyboard.held(Key::down) || keyboard.held(Key::s))samples/minimal/states/hello_state.cpp, lines 47–59 at
0f4f503Change the four letters after
Key::, and nothing else on the lines, so that they read:// ...if (keyboard.held(Key::right) || keyboard.held(Key::l))// ...if (keyboard.held(Key::up) || keyboard.held(Key::i))// ...if (keyboard.held(Key::down) || keyboard.held(Key::k))Key names are lower case:
Key::j, notKey::J. The letters name where a key is, not what is printed on it, so on a French keyboardKey::ais the key marked Q. Every name is on the Keyboard reference page, underKey: the other letters,digit_0todigit_9for the number row,space,enter,escape,tab,shift,control,f1tof12, the arrowsleft,right,upanddown, and the rest.If you have done Copy the components into your game, I, J, K and L already work its rows, and the same key would then do both. Choose four letters no other line of
update()reads; search the file forKey::to see which those are. -
Change the quit key. In the same file, search for
Key::escape. It is on this line, inHelloState::update:samples/minimal/states/hello_state.cpp Change
escapetoq:pressedis true on the one step a key goes down;held, in step 1, is true for as long as it stays down. Usepressedfor something that happens once per press, such as asking to quit, andheldfor something that goes on, such as moving. -
Change the line that tells the player. The words along the bottom of the window are a string in the same file. Search for
WASD move it, and change that string to say what the keys are now:L"Left stick, arrows or IJKL move it. B or Q asks to quit. Touch shows a marker.", font_name,Keep the
Lbefore the opening quotation mark and the, font_name,after the closing one. Save and close Notepad. -
Change the question’s keys. Q now opens the quit question, but the question still answers no to Escape, and says so. Open it:
Terminal window notepad game\states\confirm_state.cppSearch for
Key::escape, and change it toKey::qon that line:Then search for
B or Escape = noand change those words in the question’s line:this->question_ + L" A or Enter = yes, B or Q = no", font_name,The question’s line is placed by hand:
310.0fis about half its width, as the comment above it says, and the new words are five characters shorter, so the line now sits a little left of the middle. That is harmless. To centre it again, change310.0fon the next line to286.0f, half the new line’s width: its 44 characters are 13 pixels each in the starter’s font and window.Save and close Notepad. The Q that opens the question does not also answer it: a state put on screen by a key press does not see that same press, as Held, pressed and released below explains, so the player has to press Q again to say no.
-
Build, test and run. Quit the game first if it is open, then:
Terminal window cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exeTwo files are compiled again, which took 9 seconds on a fast desktop with the tests:
Output [1/5] Running utility command for game_content[2/5] Checking that no engine file includes a game header[3/5] Building CXX object game\CMakeFiles\MyGame.dir\states\confirm_state.cpp.obj[4/5] Building CXX object game\CMakeFiles\MyGame.dir\states\hello_state.cpp.obj[5/5] Linking CXX executable game\MyGame.exeTest project C:/dev/mygame/out/build/x64-debugStart 1: MyGameTests1/2 Test #1: MyGameTests ...................... Passed 0.01 secStart 2: MyGameSmokeTests2/2 Test #2: MyGameSmokeTests ................. Passed 7.41 sec100% tests passed, 0 tests failed out of 2Total Test time (real) = 7.44 secThe game opens with
Left stick, arrows or IJKL move it. B or Q asks to quit.along the bottom. Holding L moves the greeting right; W, A, S and D no longer move it, and Escape does nothing. Q showsReally quit? A or Enter = yes, B or Q = no; Q again closes the question, and Q then Enter quits.
The gamepad’s buttons are changed the same way: GamepadButton::b is a few lines below the
quit key in hello_state.cpp, inside the for loop over the pads, and GamepadButton::a and GamepadButton::b are beside the
keys in confirm_state.cpp. The button names, from a, b, x and y to start, back
and the four dpad_ directions, are on the Gamepad reference page,
under GamepadButton.
To have two keys do the same thing, keep both and join them with ||, which means “or”, the way
each movement line joins an arrow and a letter. For example, to ask to quit with Escape or Q:
In the browser build, the line under the game is set in game\web\shell.html. Open it,
search for Escape asks to quit, and change the words between the quotation marks on that line,
for example to:
"Arrows, IJKL or the left stick move the text, and a finger on it shows its id. Q asks to quit; Enter says yes and Q says no.";The page check in Build for the browser presses Escape
and then Enter to quit, so give it the new key, --quit-keys KeyQ,Enter. With the old
Escape,Enter it now stops with run_page: MyGame.html did not finish within 60 s, the
--timeout 60 that page’s command gives, and 1, because Escape no longer asks to quit.
If something fails
Section titled “If something fails”Any other build error is in Read a build error. To undo the whole section, put the two files back from your copy as Getting a file back shows.
Held, pressed and released
Section titled “Held, pressed and released”Every device answers the same three questions about a key or button:
| Question | Meaning |
|---|---|
held(...) |
Down now. |
pressed(...) |
Down now, and not down at the previous step. True for one step per press. |
released(...) |
Up now, and down at the previous step. |
Use held for anything continuous (moving, charging, scrolling) and pressed for anything that
happens once per press (jumping, confirming, opening a menu). Because each step compares against
the one before it, a state pushed by a press does not see that same press: the button was already
down at the previous step.
Keyboard
Section titled “Keyboard”Keys are named by position, not by the character printed on them. Key::w, Key::a,
Key::s and Key::d are the block under the left hand on any layout, which is what a movement
binding wants. The minimal sample reads arrows and WASD together:
{
{ direction.x -= 1.0f; } if (keyboard.held(Key::right) || keyboard.held(Key::d)) { direction.x += 1.0f; } if (keyboard.held(Key::up) || keyboard.held(Key::w)) { direction.y -= 1.0f; } if (keyboard.held(Key::down) || keyboard.held(Key::s)) { direction.y += 1.0f; }
return direction;}samples/minimal/states/hello_state.cpp, lines 43–65 at 0f4f503
Typed text is separate. keyboard.typed() returns what the player typed during the step, as
UTF-8, with the keyboard layout, dead keys and input methods already applied by the system. It is
valid until the next step, so copy it to keep it. Use it for a name-entry box, never for
movement.
Before displaying typed text, follow the wide conversion and font check.
Do them when the text changes, outside draw(); the game’s editing and
name-entry rules remain its own.
When the window loses focus, every held key is treated as released, so a character does not walk on by itself after an alt-tab.
Gamepads
Section titled “Gamepads”Gamepads has four slots, numbered 0 to 3, and answers held, pressed and released with a
slot and a GamepadButton. The full state of a slot, sticks and triggers included, is
state(slot).
On Windows the pads are read through XInput, so only XInput-compatible controllers appear; being a USB or Bluetooth controller alone does not make one compatible. A Windows slot is XInput’s system user index. A pad keeps that slot while connected, but unplugging and plugging it back in can give it another slot. A slot is not a persistent controller identity.
In a browser the pads come from the Gamepad API. The engine assigns each new standard-mapping pad the lowest free engine slot, and keeps it there until it disconnects; the browser’s own gamepad index is not the engine slot. That path has been driven only by fake pads a page script supplies in headless Chrome: no physical pad has played through it yet.
Do not check whether a pad is connected before reading it. An empty slot reads as a neutral
pad with nothing pressed, and pressed is false unless the slot was occupied at both steps.
The connected(slot), just_connected(slot) and just_disconnected(slot) queries are for
decisions such as showing “Player 2, press Start” or rebinding a player after a disconnect.
A single-player game accepts every slot
Section titled “A single-player game accepts every slot”Reading only slot 0 can ignore the player’s only controller: Windows can leave it in a higher slot after another pad is unplugged. The minimal sample reads all four slots’ B edges and left sticks, alongside Escape, with no connected guard:
{ stick_deadzone);}samples/minimal/states/hello_state.cpp, lines 122–129 at 0f4f503
Any pad can move the greeting or ask to quit, and any pad can answer the confirmation. Several pads’ directions add, so opposite pushes cancel; the motion rules clamp the combined direction to one unit. That is the sample’s policy. A game assigning pads to separate players instead keeps a slot for each player and handles its disconnects; see Local multiplayer.
Sticks are raw, from −1 to 1 on each axis, with +y pointing down like every other
coordinate in the engine. Choosing a deadzone is the game’s decision, made once with
apply_deadzone(stick, deadzone). It is circular, and rescales what is left so a small push
outside the deadzone moves slowly rather than jumping to the threshold:
this->motion_ = step_motion(this->motion_, stick_direction, keyboard_direction(keyboard), dt);samples/minimal/states/hello_state.cpp, lines 155–157 at 0f4f503
The minimal sample’s rules add the keyboard’s direction to the stick’s and clamp the sum, so both work at once and neither is the “real” device:
{ Vector2F direction = stick + keys; if (direction.length_squared() > 1.0f) { direction.normalize(); } return direction;}samples/minimal/rules/motion.cpp, lines 7–15 at 0f4f503
They take both answers as plain directions and never see a device, which is what lets a test run them with none (Test your game).
Triggers are read as numbers from 0 to 1, or as buttons with trigger_held, trigger_pressed
and trigger_released, each taking the threshold that counts as pulled.
Vibration
Section titled “Vibration”vibrate(slot, Vibration{ low_frequency, high_frequency, seconds }) sends one request to a pad’s
two rumble motors. low_frequency is the heavy motor and high_frequency the light one, each a
strength from 0 to 1. A request lasts seconds, at most max_vibration_seconds (five), because
a browser plays rumble as an effect with a duration and cannot hold a level until told otherwise;
the engine stops the motors itself when the time passes, on Windows too. A new request on a slot
replaces the one running there, so a longer effect is asked for again before the last one ends.
stop_vibration(slot) stops it early.
A strength outside 0 to 1, a duration outside its range or a slot outside 0 to 3 throws, rather
than being clamped into something you did not ask for. An empty slot, a pad with no rumble the
platform can reach, or a game in the background is not an error: vibrate answers
VibrationResult::unavailable, and nothing waits to be sent later. submitted means the pad API
took the request, not that the player felt it.
The engine stops a slot’s request when its pad leaves the slot, so a different pad arriving there never inherits it, and stops every request when the game goes into the background. Coming back replays nothing. When to stop for your own reasons, such as opening the pause menu, is your game’s call, as are the strengths, the timing and whether the player wants vibration at all.
On Windows the request goes to XInput’s two motors; XInput reaches no trigger motors. In a browser
it is the Gamepad API’s dual-rumble effect, which Chrome offers and which Firefox does not, so
there vibrate answers unavailable. No controller has been felt vibrating through either
path yet; the headless tests check what reaches each backend’s call, not the motors.
To try it in the starter project, open game\states\hello_state.cpp, search for
if (quit_requested) in HelloState::update, and paste this just above that line:
// A short buzz on every pad whose A was pressed this step.{ { }}It needs no new #include. It takes the pads a second time, as rumble, because the pads
above it is const, which lets it read the pads but not send them anything. Build, test and run
as in Make a first change, then press A on an
XInput pad: both motors run at half strength for a quarter of a second. With no pad, or a pad
with no motors, nothing happens and nothing goes wrong, because vibrate answers unavailable
and the code above ignores the answer. To show it, keep the answer,
const VibrationResult result = rumble.vibrate(...), and compare it with
VibrationResult::submitted.
Binding tables
Section titled “Binding tables”A table is optional. The starter’s two keys per direction, read one if at a time, is the
right size for a game with a handful of keys, and every guide on this site keeps it. Come back to
this section when the keys are too many to keep in your head.
Labrador has no action-mapping layer: what each key does is your game’s, written in your game. Nor is there input capture. Reading a key never consumes it, so every reader in a frame sees the same presses and the same text, and a developer console that wants the keyboard to itself gates its own readers. Routing input through one place, as the table below does, is what makes that gate one line. For more than a handful of bindings, a table keeps it in one place. LineSweeper has nine for the keyboard, nine for the pad and seven for the buttons it draws for a touchscreen:
constexpr Binding bindings[] = { { Key::right, button_right }, { Key::down, button_soft_drop }, { Key::space, button_hard_drop }, { Key::up, button_hard_drop }, { Key::x, button_rotate_clockwise }, { Key::z, button_rotate_anticlockwise }, { Key::c, button_hold }, { Key::shift, button_hold },};samples/linesweeper/states/play_state.cpp, lines 50–60 at 0f4f503
and reads them into one byte per step, which is the whole of what its rules see:
for (const Binding& binding : bindings){ if (keyboard.held(binding.key)) { input |= binding.button; }}
// OR sources into one byte: the rules do not distinguish devices.// This one-player sample reads slot zero; an empty slot contributes// neutral input without a separate connected() test.for (const PadBinding& binding : pad_bindings){ if (pads.held(0, binding.pad)) { input |= binding.button; }}
// Every finger, against the rectangles the controls were drawn at// this tick. Held, like the other two, so a thumb resting on LEFT is// the same delay and the same repeat as a held arrow key.const ControlSet touched = controls_held(this->arrangement_, this->app_->touch()->points());
for (const ControlBinding& binding : control_bindings){ if ((touched & control_bit(binding.control)) != 0) { input |= binding.button; }}
return input;samples/linesweeper/states/play_state.cpp, lines 212–245 at 0f4f503
LineSweeper reads held rather than pressed for these, and works out the presses inside its
rules by comparing each step’s byte with the last. That keeps a recorded match replayable: the
recording carries its own presses. The
sample’s design notes
explain the choice.
Directions for menus
Section titled “Directions for menus”Menus want “up, down, left, right” rather than a stick vector, with a repeat when a direction is
held. pad_direction(state) turns a pad’s d-pad and left stick into a Direction, and
DirectionRepeat turns a held direction into presses: one at once, another after a delay, then
one every interval. LineSweeper’s pause menu combines the keyboard and the pad, then repeats:
{
// Arrow priority is up, down, left, right, then the pad. Read held // levels here; DirectionRepeat owns the navigation event timing. { return Direction::up; }
if (keyboard.held(Key::down)) { return Direction::down; }
if (keyboard.held(Key::left)) { return Direction::left; }
if (keyboard.held(Key::right)) { return Direction::right; }
// Slot 0, spelt here rather than tracked, because this is a one-player // game - the same decision read_input() makes in play_state.cpp and // for the same reason.}samples/linesweeper/states/pause_state.cpp, lines 271–301 at 0f4f503
All four directions are read, and the menu decides what each means: up and down move the cursor, and left and right change the piece palette on its Colours row.
this->repeat_.update(this->held_direction(), dt);samples/linesweeper/states/pause_state.cpp, lines 352–353 at 0f4f503
When a menu opens while a direction is already held, call repeat.start_held(direction) in
init(): the held direction then has to be let go before it counts, so the cursor does not jump
before the menu is on screen. The Menus guide continues from here.
Mouse answers held, pressed and released for MouseButton::left, right, middle, x1
and x2, and also reports position() in window pixels, motion() since the last step, and
wheel() and wheel_horizontal() in notches. While a button is held the mouse keeps reporting
movement outside the window, so a drag is one gesture.
A game played with a pad usually hides the pointer: app->set_cursor_visible(false), or
cursor_visible = false in ApplicationOptions to hide it from the first frame. The mouse is
still read while the pointer is hidden. set_cursor_confined(true) keeps the pointer inside the
window on Windows while the window is active, and lets it go while the player moves or resizes the
window. A browser can lock a pointer but not confine one, so there it does nothing.
Touch holds every finger on the glass, up to ten, as points with an id and a position in
window pixels. A point’s id is handed out when it goes down and is never given to another, so
held(id), pressed(id), released(id) and motion(id) ask about one finger, and a map from
finger to whatever it is dragging can be keyed on it. points() is this step’s points, in the
order they went down. A point that has been lifted is no longer in it, so finding releases walks
the step before:
{ if (touch.released(point.id)) { // a finger came up at point.position }}A tap shorter than a step is still pressed on one step and released on the next. A point the system takes away, or every point when the window loses the foreground, disappears without a release. A touch is never also a mouse click, on Windows or in a browser, and a pen is the mouse. Both paths have been driven only by simulated touch, Chrome’s touch emulation in a browser and touch injected into a window on Windows; no real touchscreen has driven either yet. The minimal sample draws a marker with the id at every point:
for (size_t i = 0; i < this->touch_markers_.size(); ++i){ if (i < points.size()) { marker->set_text(L"+" + std::to_wstring(points[i].id)); static_cast<float>(points[i].position.x), static_cast<float>(points[i].position.y)) + touch_marker_offset); } else { marker->set_text(L""); }}samples/minimal/states/hello_state.cpp, lines 163–179 at 0f4f503
On-screen controls are the game’s, too. LineSweeper draws eight buttons once a finger has touched the screen, asks each step which button every point is on, and feeds those into the same byte its keys do, so a thumb resting on a button is a held key. Its design notes say how, and how it lays itself out for a phone held upright. That layout has run only under Chrome’s device emulation and in a tall window on Windows, never on a real phone, and the hosted demo gives a phone a poster and a recording of the game to tap and watch, not the game itself, until real iPhone checks and the host page’s phone layout pass. Android remains unverified.
From a pointer to the world
Section titled “From a pointer to the world”A mouse position and a touch point are pixels, and what they land on is drawn in world
coordinates through a camera. camera.world_position(point, viewport) is the way back: the world
point under that pixel, seen through that view. LineSweeper’s buttons ask it which board point a
finger is on:
arrangement.viewport);samples/linesweeper/presentation/touch_controls.cpp, lines 109–110 at 0f4f503
With several views, which pane a pointer is in is the game’s question: the call answers for any pixel, inside the viewport or not, so a split-screen game picks the view first.
What was checked
Section titled “What was checked”On 31 October 2026, in a starter project made from a starter ZIP of this tree, with Visual Studio
2026’s compiler 19.51 and Emscripten 6.0.12, the edits in
Change a control in your game were made as worded, by an agent
editing the files with tools rather than Notepad, and the build and tests printed what step 5
shows, with the project’s folder shown as C:\dev\mygame. The game was started and driven with
key presses, and screenshots showed the new line along the bottom, the greeting moved right by
L, nothing on Escape, the question with B or Q = no after Q, the question gone
after a second Q, and the game exiting with code 0 on Q then Enter. Key::Q and
Key::esc were each built with both presets to get the messages above, and the page was built
with wasm-debug and checked in Edge by the page runner with --quit-keys KeyQ,Enter, which
passed, and with Escape,Enter, which timed out as described. The vibration example was built
with both presets; no pad was connected, so no motor was felt and the unavailable path was read
from the code.
A second agent then followed the section as worded in another fresh starter. Step 5’s build
printed the five lines shown and both tests passed; driven with keys, the game did what step 5
says; the Key::Q and Key::esc messages, clang’s included, the shell.html line and the
vibration example matched, and the page check passed with --quit-keys KeyQ,Enter. It found
what the page now says: the check with the old keys, run as Build for the browser gives it,
reports within 60 s, not 20; GamepadButton::b is inside the for loop a few lines below the
quit key, not on the next line; which step 1 the copy comes from; and the shorter question
sitting left of the middle. 286.0f was then built in the first starter and the question
screenshotted with 310.0f and with 286.0f: the line’s middle was 21 pixels left of the
window’s and then 3 pixels right of it.
A review in a third fresh starter made the edits again, by script rather than Notepad: the build
printed the five lines step 5 shows and both tests passed, Key::Q gave the C2838 and C2065
pair at line 122, and screenshots showed the new line, the greeting moved by L, nothing on
Escape, the question after Q and gone after a second, and the game exiting with code 0
on Q then Enter. The browser build was not repeated.
Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.