Keyboard & Mouse Input

Scripts that define a loop run once per animation frame, and from inside that loop they can read the mouse and keyboard. The examples below all draw to a canvas with set_canvas and respond to input in real time.

Press the play button to start each example. Keyboard examples only receive keys while the canvas has focus, so click the canvas first.

Following the Mouse

mouse_pos() returns the cursor’s [x, y] position in canvas pixels, and mouse_pressed(button) reports whether a button is currently held. The button constants are MOUSE_LEFT, MOUSE_MIDDLE, MOUSE_RIGHT, MOUSE_X1, and MOUSE_X2.

let W = 320
let H = 240
set_canvas(W, H, scale=1)

fn loop() {
    draw_rect(0, 0, W, H, color=(17, 24, 39))

    // `mouse_pos()` returns the cursor's [x, y] in canvas pixels.
    let m = mouse_pos()
    let x = m[0]
    let y = m[1]

    // A crosshair that tracks the cursor.
    draw_rect(0, y, W, 1, color=(55, 65, 81))
    draw_rect(x, 0, 1, H, color=(55, 65, 81))

    // The dot turns green while the left button is held.
    let color = if mouse_pressed(MOUSE_LEFT) { (74, 222, 128) } else { (96, 165, 250) }
    draw_rect(x - 6, y - 6, 12, 12, color=color)
}

Press the play button to execute

Moving with the Keyboard

The key object names every key: key.Left, key.A, key.Space, and so on. Each key exposes .pressed, which is true on every frame the key is held down. That makes it a good fit for continuous movement.

Click the canvas to give it focus, then steer the box with the arrow keys or WASD. The box is yellow while the canvas has keyboard focus and grey when it doesn’t.

let W = 320
let H = 240
let size = 24
let speed = 3
set_canvas(W, H, scale=1)

let x = (W - size) / 2.0
let y = (H - size) / 2.0

fn loop() {
    // `.pressed` is true every frame the key is held down.
    if key.Left.pressed or key.A.pressed { x = x - speed }
    if key.Right.pressed or key.D.pressed { x = x + speed }
    if key.Up.pressed or key.W.pressed { y = y - speed }
    if key.Down.pressed or key.S.pressed { y = y + speed }

    // Keep the box on screen.
    x = x.clamp(0, W - size)
    y = y.clamp(0, H - size)

    draw_rect(0, 0, W, H, color=(17, 24, 39))
    // Yellow while the canvas has keyboard focus, grey otherwise.
    let color = if input_focus() { (250, 204, 21) } else { (107, 114, 128) }
    draw_rect(x, y, size, size, color=color)
}

Press the play button to execute

Reacting to a Single Press

For actions that should happen once per key press—like toggling something—use .just_pressed instead of .pressed. It’s true only on the frame the key goes down, so holding the key doesn’t repeat the action.

Click the canvas, then tap Space to flip the light on and off.

let W = 320
let H = 240
set_canvas(W, H, scale=1)

let on = false
let presses = 0

fn loop() {
    // `.just_pressed` fires once per press, not every frame Space is held.
    if key.Space.just_pressed {
        on = !on
        presses = presses + 1
    }

    let bg = if on { (250, 204, 21) } else { (30, 41, 59) }
    draw_rect(0, 0, W, H, color=bg)

    let label = if on { "on" } else { "off" }
    print("Space pressed \(presses) times. Light is \(label).")
}

Press the play button to execute

Input Reference

These functions and objects are available to any script with a loop:

Name	Description
`mouse_pos()`	The cursor’s `[x, y]` position in canvas pixels.
`mouse_pressed(button)`	`true` while `button` is held down this frame.
`mouse_just_pressed(button)`	`true` on the frame `button` is pressed.
`mouse_just_released(button)`	`true` on the frame `button` is released.
`mouse_focus()`	`true` while the cursor is over the canvas.
`input_focus()`	`true` while the canvas has keyboard focus.
`MOUSE_LEFT`, `MOUSE_MIDDLE`, `MOUSE_RIGHT`, `MOUSE_X1`, `MOUSE_X2`	Button numbers passed to the `mouse_*` functions.
`key.<Name>`	A key, e.g. `key.Space`, `key.A`, `key.Left`, `key.Enter`.

Each key.<Name> reports its state relative to the previous frame:

Attribute	Description
`.pressed`	`true` every frame the key is held down.
`.released`	`true` every frame the key is up.
`.just_pressed`	`true` only on the frame the key goes down.
`.just_released`	`true` only on the frame the key comes up.
`.just_pressed_with_repeat`	Like `.just_pressed`, but also fires on a repeat cadence while the key is held—handy for menus and text cursors.

Key names cover the letters (A–Z), the number row (Key0–Key9), the function keys (F1–F12), the arrows (Left, Right, Up, Down), Space, Enter, Escape, Tab, Backspace, the modifiers (LeftShift, LeftCtrl, LeftAlt, and their Right counterparts), and the keypad (Kp0–Kp9, KpEnter, and friends).