Input

Static methods for reading mouse, keyboard, modifier keys, and gamepad state. All methods are static.

Mouse

Input.mouseX() / Input.mouseY()

Returns: Num — Current mouse X or Y position, in window coordinates, exactly as SDL reports them.

var x = Input.mouseX()
var y = Input.mouseY()
Gui.label("Mouse: %(x), %(y)")

These are window coordinates, never design coordinates

Setting a design size changes how the renderer maps content to the window; it does not change what mouseX/mouseY return. Under "letterbox" or "integer" scaling the mouse position and your design-space content are in different coordinate spaces, and hit-testing a sprite against a raw mouseX() will be wrong wherever the scale factor isn’t 1 (and offset by the letterbox bars).

Converting window coordinates to design space is currently the game’s job — the engine exposes no mapping helper to Wren. Window.getWidth()/getDesignWidth() and friends give you the numbers to do it yourself.

Input.mouseLeft() / Input.mouseRight() / Input.mouseMiddle()

Returns: Bool — true if the left, right, or middle button is currently held.

if (Input.mouseLeft()) {
  // drag or hold logic
}

Input.mouseJustPressedLeft() / Input.mouseJustPressedRight()

Returns: Bool — true if the button was just pressed this frame (edge-triggered, so only true for one frame per press).

if (Input.mouseJustPressedLeft()) {
  tryStartDrag()
}

Input.mouseWheelX() / Input.mouseWheelY()

Returns: Num — Scroll delta for this frame (horizontal and vertical wheel). Zero when not scrolling.

Mouse capture & cursor

For first-person and orbit cameras you usually want to capture the mouse: hide the cursor, lock it to the window center, and read motion as per-frame deltas — so looking around never lets the cursor drift off the window or stall at its edge. Provide your own key to release it (for menus, GUI, or quitting).

Input.setRelativeMouse(v) / Input.relativeMouse()

Enter (true) or leave (false) relative mode: the cursor is hidden and pinned to the window center, and mouse motion is delivered as deltas via Input.mouseDeltaX/Y. The built-in cameras (Cam.firstPerson, Cam.freeFly, orbit) automatically use those deltas, so they look correctly the instant relative mode is on. Input.relativeMouse() returns the current desired state.

The engine also auto-releases capture when the window loses focus (alt-tab / cmd-tab) and restores it on return, so the cursor is never trapped.

Input.setCursorVisible(v) / Input.cursorVisible()

Show (true) or hide (false) the OS cursor. Relative mode hides the cursor itself, so this only has a visible effect when relativeMouse() is false.

Input.mouseDeltaX() / Input.mouseDeltaY()

Returns: Num — Relative mouse motion this frame (pixels). Works in both normal and relative mode; use it to drive a custom camera’s look so it never stalls when the cursor reaches the window edge.

class Game {
  init() { Input.setRelativeMouse(true) }   // capture on start

  update(dt) {
    // free the cursor for a menu / to quit
    if (Input.keyJustPressed("escape")) {
      Input.setRelativeMouse(false)
      Input.setCursorVisible(true)
    }
  }
}

Keyboard

Input.key(name)

Returns: Bool — true if the key with the given name is currently held.

Parameters:

• name (String) — SDL scancode name, matched case-insensitively (e.g. "a", "space", "escape", "Left", "Right"). Keys are read by scancode, so they follow physical key position, not the user’s keyboard layout — "w" is the same physical key on QWERTY and AZERTY.

if (Input.key("a")) position = position - speed * dt
if (Input.key("d")) position = position + speed * dt

An unrecognized key name is silently false

A name SDL doesn’t recognize returns false every frame rather than raising an error — a typo like "spacebar" or "esc" reads as a key that is never pressed. If a binding seems dead, check the spelling against SDL’s scancode names first.

Input.keyJustPressed(name)

Returns: Bool — true if the key was just pressed this frame (edge-triggered).

Parameters:

• name (String) — SDL scancode name, as for Input.key.

if (Input.keyJustPressed("space")) {
  Audio.play(_jumpSound)
}

Input.modShift() / Input.modCtrl() / Input.modAlt()

Returns: Bool — true if the Shift, Ctrl, or Alt modifier is held.

if (Input.keyJustPressed("s") && Input.modCtrl()) saveGame()

Gamepad

Up to 4 gamepads are tracked. Buttons and axes are addressed by numeric index only — see the tables below.

Input.gamepadCount()

Returns: Num — One past the highest occupied gamepad slot — not the number of gamepads currently connected.

gamepadCount is a slot high-water mark, and the slots can have holes

Gamepads keep the slot they were assigned on connect. The count shrinks only when the topmost slots are vacated, so unplugging a controller below an occupied slot leaves a hole and does not lower the count. Two pads in slots 0 and 1 give a count of 2; unplug slot 0 and the count stays 2 while only one pad is connected.

So treat it strictly as an exclusive upper bound on player indices, never as a player count. Iterating 0...Input.gamepadCount() is the correct loop, but it can visit disconnected slots — and Wren has no gamepadConnected(player) binding, so a hole is indistinguishable from a pad sitting perfectly still (both read as all-buttons-false, all-axes-0). If you need real connect/disconnect tracking, watch for a slot’s inputs going permanently dead, or drive it from C++.

Input.gamepadButton(player, button)

Returns: Bool — Whether the given button is held. Returns false if player or button is out of range, or if no gamepad occupies that slot.

Parameters:

• player (Num) — Gamepad slot index, 0–3.
• button (Num) — Button index, 0-based. Numeric only — there is no name lookup.

Button indices are SDL3’s gamepad button order, which is positional (South is the bottom face button — A on Xbox, Cross on PlayStation, B on a Nintendo layout):

Index	Button	Index	Button
0	South (Xbox A)	8	Right stick click
1	East (Xbox B)	9	Left shoulder
2	West (Xbox X)	10	Right shoulder
3	North (Xbox Y)	11	D-pad up
4	Back	12	D-pad down
5	Guide	13	D-pad left
6	Start	14	D-pad right
7	Left stick click	15+	Misc / paddles / touchpad

// Slot 0, button 0 = bottom face button (Xbox A / PS Cross).
if (Input.gamepadButton(0, 0)) jump()

Input.gamepadAxis(player, axis)

Returns: Num — Axis value, normalized. Sticks read -1 to 1; triggers read 0 to 1. Returns 0 if player or axis is out of range, or if no gamepad occupies that slot.

Parameters:

• player (Num) — Gamepad slot index, 0–3.
• axis (Num) — Axis index, 0-based. Numeric only — there is no name lookup.

Index	Axis	Range
0	Left stick X	-1 → 1
1	Left stick Y	-1 → 1
2	Right stick X	-1 → 1
3	Right stick Y	-1 → 1
4	Left trigger	0 → 1
5	Right trigger	0 → 1

// Left stick on slot 0, with a hand-rolled dead zone.
var moveX = Input.gamepadAxis(0, 0)
var moveY = Input.gamepadAxis(0, 1)
if (moveX.abs < 0.25) moveX = 0
if (moveY.abs < 0.25) moveY = 0

Passing a String for button or axis fails silently

These parameters are read as numbers with no type check. Passing a string is Wren API misuse, and in a release build it does not raise an error — it reinterprets the value as a garbage index, which fails the range check and reads as a permanently unpressed button (false) or a dead axis (0). There is no name-based lookup to fall back on. Always pass an index from the tables above.

No dead zone is applied

Axis values are the raw hardware reading scaled to ±1 — the engine applies no dead zone. Sticks rest within roughly ±0.24 of centre on typical hardware, so a resting stick will drift your player unless you apply your own dead zone.

Values are scaled by 1/32768, so the positive end tops out at 0.99997, never exactly 1. Compare with >= against a threshold rather than testing == 1.

Touch

Touch is not scriptable yet

There is no touch API on Input — the methods above are the complete surface.

The engine’s C++ InputState does track touch (up to 8 simultaneous fingers, fed from SDL’s finger events), but none of it is bound to Wren, so a script cannot read finger positions or pressure today. Reaching it currently requires C++.

On a touch device, SDL may still synthesize mouse events from finger input — so Input.mouseLeft() and Input.mouseX()/mouseY() can be a workable single-finger stand-in. That is SDL’s behaviour rather than an engine guarantee, and it gives you one pointer, not multi-touch.