Input

app.input holds the state of the keyboard, the mouse and every connected gamepad as of this frame, so a system asks "is this key down?" instead of following key events. The engine updates it at the start of each frame's INPUT phase, before any system runs, and it stays the same for the rest of the frame.

Every device answers three questions per button:

Calltrue when
isDown(button)The button is held now.
isJustPressed(button)The button went down this frame, or since the last step in FIXED_UPDATE.
isJustReleased(button)The button went up this frame, or since the last step in FIXED_UPDATE.

"Just pressed" and "just released" last one frame, or one step in FIXED_UPDATE. A tap shorter than a frame reads as both in the same frame, so no press is lost. Key repeat does not count as a press. When the window loses focus every held key and button is released, and reads as just released that frame, so nothing stays stuck while the game is in the background.

Held state reads the same in every phase. Edges, the "just" calls, follow the phase that reads them. In INPUT, UPDATE and the other phases that run once a frame, "just" means this frame. FIXED_UPDATE runs zero, one or several steps a frame, so there it means since the previous step: the first step after a press sees it and no other step does. A press in a frame that runs no step waits for the next frame's first step, and a frame's second step does not see it again. A tap shorter than a step reads as both just pressed and just released in that step, with the key already up. Read a jump where the physics runs:

var velocityY = 0f
addSystem(Phase.FIXED_UPDATE) { app ->
    val transform = app.world.get(player, Transform)
    val ground = 500f
    // One step sees each press, however many steps this frame runs.
    val jump = app.input.keyboard.isJustPressed(Scancode.SPACE) || app.input.gamepads.isJustPressed(GamepadButton.SOUTH)
    if (jump && transform.y >= ground) velocityY = -600f
    velocityY += 1800f * app.time.deltaSeconds
    transform.y += velocityY * app.time.deltaSeconds
    if (transform.y >= ground) {
        transform.y = ground
        velocityY = 0f
    }
}

Each press reaches one step; a jump buffer or coyote time, which remember it for a few steps, is game logic, as in Rooftop Roller. A press that a menu reads in INPUT to start the game can also reach the first step of the scene it starts, when its frame ran no step. The snippets on this page are code for the setup block of runApp.

Keyboard

A key has two names. A Scancode is the key's position, named after the key in that place on a US keyboard. A KeyCode is the label the user's layout gives it. Use scancodes for controls that depend on where keys sit, such as movement on W, A, S and D, so they work on every layout. Use key codes when the letter matters, such as M for the map: on a French layout KeyCode.A is the key where Q sits on a US keyboard.

addSystem(Phase.INPUT) { app ->
    val keyboard = app.input.keyboard
    // By position: the key where W sits on a US keyboard, whatever the layout prints on it.
    if (keyboard.isDown(Scancode.W)) println("Forward")
    // By label: the key that types "m" on the user's layout.
    if (keyboard.isJustPressed(KeyCode.M)) println("Map")
    if (keyboard.isJustReleased(Scancode.SPACE)) println("Jump released")
}

The KeyCode calls look the key up through the current layout on every call, so a layout switch takes effect at once. A key code that no key on the layout produces is never down.

keyboard.axis(negative, positive) turns a pair of keys, two scancodes or two key codes, into a direction: -1 while only the negative key is down, 1 while only the positive one is, and 0 while both or neither are.

addSystem(Phase.FIXED_UPDATE) { app ->
    val keyboard = app.input.keyboard
    val dx = keyboard.axis(Scancode.A, Scancode.D) + keyboard.axis(Scancode.LEFT, Scancode.RIGHT)
    val transform = app.world.get(player, Transform)
    transform.x += dx.coerceIn(-1f, 1f) * 300f * app.time.deltaSeconds
    // By label: the keys that type "q" and "e" turn the ship, wherever the layout puts them.
    transform.rotation += keyboard.axis(KeyCode.Q, KeyCode.E) * 3f * app.time.deltaSeconds
}

For text entry or a key binding screen, read KeyPressed events from app.events instead: each carries the scancode, the key code and isRepeat, and they arrive in order.

Mouse

mouse.position is the cursor in window points, with (0, 0) at the window's top-left corner and y pointing down, the same unit as window.width and the canvas's screen space. It is (0, 0) until the mouse first moves over the window. mouse.delta is how far it moved this frame and mouse.wheel how far the wheel or touchpad scrolled: positive y scrolls up, one notch of a wheel is usually 1, and touchpads report fractions.

mouse.worldPosition is the world point under the cursor, seen through app.camera. Aim with it:

addSystem(Phase.UPDATE) { app ->
    val mouse = app.input.mouse
    val ship = app.world.get(player, Transform)
    // The world point under the cursor, through the camera as it stood at the start of INPUT.
    val target = mouse.worldPosition
    ship.rotation = Vec2(target.x - ship.x, target.y - ship.y).angle
    if (mouse.isJustPressed(MouseButton.LEFT)) println("Fire at $target")
    if (mouse.wheel.y != 0f) app.camera.zoom = (app.camera.zoom * (1f + 0.1f * mouse.wheel.y)).coerceIn(0.5f, 4f)
}

The engine computes worldPosition at the start of INPUT, through the camera as it stood then, its shake offset included. The offset keeps its value until the game changes it or a scene transition sets it to 0, so the cursor and the picture agree during a shake. A camera that follows the player in LATE_UPDATE moves after that, so the value is one frame behind the picture. When it matters, as for a cursor drawn in the world, convert the position yourself after the camera has moved:

addSystem(Phase.RENDER) { app ->
    // After a LATE_UPDATE camera move, worldPosition is a frame behind; this is not.
    val underCursor = app.camera.screenToWorld(app.input.mouse.position)
    app.canvas.drawRect(
        x = underCursor.x - 4f,
        y = underCursor.y - 4f,
        width = 8f,
        height = 8f,
        color = Color.WHITE,
        space = DrawSpace.WORLD,
    )
}

Buttons are MouseButton.LEFT, MIDDLE, RIGHT, X1 and X2. MouseButtonPressed events also carry the click count, for double clicks. To hide the system cursor or replace it with an image, see Shipping.

Gamepads

input.gamepads lists the connected pads in the order they were connected. It is a live view, so a reference to it stays current as pads come and go. Buttons and axes follow SDL's standard layout and are named by position, so GamepadButton.SOUTH is the bottom face button on every pad: A on an Xbox pad, cross on a PlayStation pad.

ReadRange
pad.leftStick, pad.rightStickx from -1 (left) to 1 (right), y from -1 (up) to 1 (down), dead zone applied.
pad.axis(GamepadAxis.LEFT_TRIGGER), RIGHT_TRIGGER0 released to 1 fully pressed.
pad.axis(GamepadAxis.LEFT_X) and the other stick axes-1 to 1, raw, no dead zone.
pad.isDown(GamepadButton.SOUTH) and the other buttonsAs for keys.
addSystem(Phase.FIXED_UPDATE) { app ->
    val pad = app.input.gamepads.firstOrNull() ?: return@addSystem
    val stick = pad.leftStick
    val transform = app.world.get(player, Transform)
    transform.x += stick.x * 300f * app.time.deltaSeconds
    transform.y += stick.y * 300f * app.time.deltaSeconds
    // Triggers read from 0, released, to 1, fully pressed.
    if (pad.axis(GamepadAxis.RIGHT_TRIGGER) > 0.5f) println("Boost")
    if (pad.rightStick.length > 0.5f) transform.rotation = pad.rightStick.angle
}

Sticks rarely rest at exactly zero, so leftStick and rightStick apply a radial dead zone, input.deadZone, 0.15 by default. Below it a stick reads zero; past it the distance is rescaled to grow from 0 at the edge of the dead zone to 1 at full tilt, so there is no jump.

A game that lets whichever pad is at hand play can ask the whole list. The List<Gamepad> extensions isDown, isJustPressed and isJustReleased are true when any connected pad matches, and false for an empty list:

addSystem(Phase.INPUT) { app ->
    val pads = app.input.gamepads
    // True when any connected pad matches, so whichever pad is at hand can play.
    if (pads.isJustPressed(GamepadButton.START)) println("Pause")
    if (pads.isDown(GamepadButton.SOUTH)) println("Jump held")
}

A Gamepad object lives for one connection. When the pad is unplugged it leaves the list, its isConnected turns false and it reads as released, but it stays safe to read. Plugged back in, the pad gets a new GamepadId and a new object. input.gamepadOrNull(id) finds a connected pad by id, and GamepadConnected and GamepadDisconnected events report the changes:

input.deadZone = 0.2f
addSystem(Phase.INPUT) { app ->
    app.events.forEach<GamepadConnected> { event -> println("Connected ${event.name} as ${event.id}") }
    app.events.forEach<GamepadDisconnected> { event ->
        println("Pad ${event.id} left; it is ${app.input.gamepadOrNull(event.id)}")
    }
}

Combining devices

The template adds the keyboard and the stick together and clamps the result to length 1, so two keys at once, or a key and the stick, are no faster than one. See the movement system in Getting started. The shooter in games/shooter goes further: it aims with the mouse until the right stick moves, and back once the mouse moves.

See also