---
url: /pawn/docs/guide/input.md
description: >-
  The Input plugin: keyboard, pointer and wheel state per frame, and the Pointer
  module.
---

# Input

`Input` is a plugin that reads keyboard, pointer and wheel input per frame.

```ts
import { Input } from "@pawnjs/core";

const input = new Input();
engine.use(input);
```

DOM events are queued and applied at the start of the `input` phase, so every
system in a frame sees the same state, and listeners run in frame order rather
than DOM order.

## Polling

```ts
const drive: System = ({ delta }) => {
  if (input.isDown("KeyW")) speed += delta;
  if (input.wasPressed("Space")) jump();
  if (input.isButtonDown(0)) aim(input.pointer.dx, input.pointer.dy);
  zoom(input.wheel.y);
};
```

| Member | Meaning |
|---|---|
| `isDown(code)` | Whether a key is held. |
| `wasPressed(code)` | Whether a key went down this frame. |
| `wasReleased(code)` | Whether a key went up this frame. |
| `isButtonDown(button = 0)` | Whether a pointer button is held: 0 primary, 1 middle, 2 secondary. |
| `pointer` | Last state of the primary pointer: `clientX`, `clientY`, per-frame `dx`/`dy`, `buttons`, `inside`, `pointerType`. |
| `lockPointer()`, `unlockPointer()`, `pointerLocked` | Pointer lock, below. |
| `wheel` | Wheel movement summed over this frame, `{ x, y }` in pixels. |

Keys use `KeyboardEvent.code` (`"KeyW"`, `"Space"`, `"ArrowLeft"`), which does
not depend on the keyboard layout. Typing into form fields is ignored, and
losing window focus releases held keys.

## Listeners

```ts
const off = input.on("keydown", (event) => {
  if (event.code === "Escape") closeMenu();
});
off(); // removes the listener
```

Listeners run in the `input` phase. Event types: `pointerdown`, `pointermove`,
`pointerup`, `click`, `wheel`, `keydown`, `keyup`. Pointer and wheel events
carry `clientX` and `clientY`, pointer events also `pointerId`,
`pointerType`, `button`, `buttons` and `isPrimary`, wheel events `deltaX` and `deltaY`;
key events carry `code`, `key` and `repeat`.
Every event has the original DOM event as `native`.

`input.pointer` and these events are the raw pointer, in CSS pixels and
before any entity is involved. For the entity under the pointer, and for
clicks and double clicks that skip drags, use [`Pointer`](#pointer); for a
`click` on an entity itself, use the `Clickable` behavior.

Keys are polled in a system, and a `Pointer` click on the floor sets where
the box walks to:

```ts
import {
  Engine,
  Input,
  Pointer,
  Position,
  Scale,
  Shape,
  View,
} from "@pawnjs/core";
import { AmbientLight, DirectionalLight, PerspectiveCamera } from "three";

const SPEED = 3; // units a second

export default function input(canvas: HTMLCanvasElement): Engine {
  canvas.style.cssText = "display:block;width:100%;height:100%";
  const engine = new Engine({ canvas });
  const { world } = engine;
  const keys = engine.plugin(Input);
  const pointer = engine.plugin(Pointer);

  engine.scene.add(new AmbientLight(0xffffff, 0.7));
  const sun = new DirectionalLight(0xffffff, 2);
  sun.position.set(3, 8, 5);
  engine.scene.add(sun);

  world.spawn(
    Shape({ kind: "plane", color: "#27272a" }),
    Position({ y: -0.5 }),
    Scale({ x: 8, y: 1, z: 6 }),
  );
  const box = world.spawn(Shape({ kind: "box", color: "#6366f1" }), Position);
  let goal: { x: number; z: number } | null = null;

  // A click on the floor sets where the box walks to.
  pointer.on("click", ({ hit }) => {
    if (hit)
      goal = { x: hit.intersection.point.x, z: hit.intersection.point.z };
  });

  // Keys are polled every frame: WASD or the arrow keys steer the box.
  engine.addSystem(({ delta }) => {
    const p = box.get(Position);
    if (!p) return;
    const dx = +keys.isDown("KeyD") - +keys.isDown("KeyA");
    const dz = +keys.isDown("KeyS") - +keys.isDown("KeyW");
    if (dx || dz) goal = null;
    let x = dx;
    let z = dz;
    if (goal) {
      x = goal.x - p.x;
      z = goal.z - p.z;
      if (Math.hypot(x, z) < 0.05) goal = null;
    }
    const length = Math.hypot(x, z);
    if (length === 0) return;
    const step = Math.min(SPEED * delta, goal ? length : Infinity) / length;
    box.set(Position, {
      x: Math.max(-3.5, Math.min(3.5, p.x + x * step)),
      y: p.y,
      z: Math.max(-2.5, Math.min(2.5, p.z + z * step)),
    });
  });

  const camera = new PerspectiveCamera(45, 1, 0.1, 100);
  camera.position.set(0, 6, 6);
  camera.lookAt(0, -0.5, 0);
  engine.views.add(new View({ camera, background: 0x09090b }));

  engine.fitToElement(canvas);
  engine.start();
  return engine;
}

```

## Options

```ts
new Input({
  element: document.body,      // pointer events; defaults to the engine's canvas
  keyboardTarget: window,      // keyboard events; defaults to window
  orientationTarget: window,   // device orientation for tilt; defaults to window
  // Decide while the DOM event is dispatched whether to cancel its default
  // action. Listeners run a frame later, too late for preventDefault().
  preventDefault: (event) =>
    event.type === "keydown" && (event as KeyboardEvent).code === "Space",
});
```

## Pointer lock

`input.lockPointer()` locks the pointer to the element and hides it, for
looking around with the mouse in a first-person view. While locked,
`input.pointer.dx` and `dy` carry the mouse's own movement, as the position
stays put:

```ts
const input = engine.plugin(Input);
engine.plugin(Pointer).on("click", () => input.lockPointer());
engine.addSystem(() => {
  if (input.pointerLocked) look(input.pointer.dx, input.pointer.dy);
});
```

Browsers lock only soon after a click or key press, so call it from one.
`pointerLocked` turns true the frame after the browser grants it; Escape
or `input.unlockPointer()` gives the pointer back.

## Page layout

When the canvas covers the page with `pointer-events: none` (views in page
layout), listen on the page: `element: document.body`.

An `Input` can be installed on one engine.
`engine.plugin(Input)` returns the engine's `Input`, installing a default one
when there is none; plugins that read input (such as `CameraRig`) use it.

## Pointer

`Pointer` turns the pointers into what most scenes ask about: the entity
under the pointer and the entity clicked (not dragged across). It owns the
gesture: a press, any drag, the release, and the click or double click that
follows. It works in canvas fractions, follows `Input` in a page and can be
driven from code, so pointer logic runs and is tested without a browser.

```ts
import { Pointer } from "@pawnjs/core";

const pointer = engine.plugin(Pointer);
pointer.on("click", ({ entity }) => entity && select(entity));
pointer.on("doubleclick", ({ entity }) => entity && rig.focus(entity));
pointer.on("hover", ({ entity, previous }) => highlight(entity, previous));
// in a system:
const overLamp = pointer.target === lamp;
```

| Member | Meaning |
|---|---|
| `u`, `v`, `inside` | Position of the primary pointer over the canvas, 0 to 1 from the top left, and whether it is over it. |
| `target`, `hit`, `hits` | Entity, nearest hit and every hit directly under the primary pointer (`Hovered` may sit on an ancestor), picked each frame in the `input` phase. |
| `all` | The primary pointer, then every other pointer holding a button: `pointerId`, `primary`, `u`, `v`, `inside`, `buttons`, `dragged`. |
| `isDown(button = 0, pointerId?)` | Whether a button is held. |
| `dragged` | Whether the current gesture moved past the drag threshold. |
| `captured` | Whether a `press` listener took the current gesture over with `event.capture()`. |
| `on(type, listener)` | `press`, `click` and `doubleclick` carry `pointerId`, `primary`, `button`, `u`, `v`, `hits`, `hit` and `entity`; `hover` carries `entity` and `previous`; `release` carries `pointerId`, `primary`, `button`, `dragged` and `cancelled`, for every press, wherever it ends. |
| `moveTo(u, v, pointerId?)`, `leave(pointerId?)` | Move a pointer from code. |
| `press(button, pointerId?)`, `release(button, pointerId?)`, `cancel(pointerId?)` | Press and release from code. |

Every pointer presses and clicks, so two fingers tap two things at once;
events tell them apart by `pointerId`, and `primary` is true for the mouse
or the first finger down. Only the primary pointer hovers and moves `u`,
`v` and `target`. From code, a `pointerId` other than the primary one's
is another finger: `pointer.moveTo(0.2, 0.5, 7)` then `pointer.press(0, 7)`.

A gesture runs from the first button pressed until the last is released,
with every pointer down meanwhile, so both fingers of a pinch count. It is a
drag once any of them moves further than `dragThreshold` (4 CSS pixels by
default) from where it was pressed, and the release of a drag is no click,
so a click never also ends a camera drag. A click soon after another
(`doubleClickInterval`, 0.3 s of unscaled engine time by default), near it
and with the same button, is followed by `doubleclick`.

A `press` listener may call `event.capture()` to take the gesture over
until its last button is released (`pointer.captured`): `CameraRig` then
leaves it alone, which is how `Draggable` drags an entity without turning
the camera. Clicks still happen.

Events carry every hit, nearest first, for code that picks its own: the
nearest body that is still falling, or a node past a pulse in front of it.

```ts
pointer.on("click", ({ hits }) => {
  const body = hits.find((h) => h.entity?.has(Falling))?.entity;
  if (body) pop(body);
});
```

A lifted finger and a cancelled touch hover nothing. The pointer follows
`engine.plugin(Input)` when the engine has a canvas, so install a configured
`Input` before it, or pass one as `input`. With `input: null`, or on a
headless engine, it is driven only from code, e.g. by another source of
pointer positions. `enableHover: false` skips the per-frame pick when only
clicks matter.

```ts
new Pointer({
  enableHover: true,           // pick under the pointer every frame
  dragThreshold: 4,            // CSS pixels a tap may travel
  doubleClickInterval: 0.3,    // seconds between the clicks of a double click
});
```

```ts
// A test, headless:
const pointer = engine.plugin(Pointer);
pointer.moveTo(0.5, 0.5);
engine.step(1 / 60);
expect(pointer.target).toBe(box);
pointer.press();
pointer.release(); // emits click with the box
pointer.press();
pointer.moveTo(0.6, 0.5);
pointer.release(); // a drag: no click
```

Headless there are no CSS pixels, so distances are measured on a canvas of
`Pointer.HEADLESS_SIZE` (1000) pixels a side: `moveTo(0.5, 0.5)` then
`moveTo(0.51, 0.5)` moves 10 pixels.

Several fingers act at once: in Balloons every finger pops what it
presses, with one `press` listener.

## Actions

`Actions` names what the player does (`"jump"`, `"build"`, `"pause"`) and
binds each action to keys, pointer buttons and gamepads, so a game asks
for the action instead of a key, and a settings screen can rebind it:

```ts
import { Actions } from "@pawnjs/core";

const actions = new Actions({
  bindings: {
    left: ["KeyA", "ArrowLeft", "PadLeft", "LeftStickLeft"],
    right: ["KeyD", "ArrowRight", "PadRight", "LeftStickRight"],
    jump: ["Space", "PadA"],
    fire: ["Mouse0", "PadRT"],
    pause: ["Escape", "KeyP", "PadStart"],
  },
});
engine.use(actions);

engine.addSystem(({ delta }) => {
  player.x += actions.axis("left", "right") * speed * delta;
  if (actions.wasPressed("jump")) jump();
  if (actions.wasPressed("pause")) togglePause();
});

actions.bind("jump", ["KeyW", "PadA"]); // rebind
actions.bindingsOf("jump");             // ["KeyW", "PadA"], for a settings screen
```

| Binding | Means |
| --- | --- |
| `"KeyW"`, `"Space"`, `"ArrowLeft"` | A key, as `KeyboardEvent.code` |
| `"Mouse0"`, `"Mouse1"`, `"Mouse2"` | Primary, middle and secondary pointer button; a finger on the screen is `"Mouse0"` |
| `"SwipeUp"`, `"SwipeDown"`, `"SwipeLeft"`, `"SwipeRight"` | A held pointer moving `swipeDistance` one way, pressed for one frame |
| `"WheelUp"`, `"WheelDown"`, `"WheelLeft"`, `"WheelRight"` | The wheel turning, pressed for the frame it turns |
| `"PadA"`, `"PadB"`, `"PadX"`, `"PadY"`, `"PadLB"`, `"PadRB"`, `"PadLT"`, `"PadRT"`, `"PadSelect"`, `"PadStart"`, `"PadL3"`, `"PadR3"`, `"PadUp"`, `"PadDown"`, `"PadLeft"`, `"PadRight"` | A button of a standard gamepad, any one connected |
| `"LeftStickLeft"`, `"LeftStickUp"`, `"RightStickRight"`... | A stick pushed one way |
| `"TiltLeft"`, `"TiltRight"`, `"TiltForward"`, `"TiltBack"` | The phone or tablet tilted one way, once `Input.requestTilt()` turned tilt on |

* `isDown`, `wasPressed` and `wasReleased` work like `Input`'s, per frame;
  a key or a pointer button tapped between two frames still counts as one
  press.
* `value(action)` is how far an action is pressed, 0..1: 1 for a key, how
  far for a stick or trigger. `axis(negative, positive)` gives -1..1.
* A stick or trigger counts once past `deadZone` (default 0.5); its value
  is rescaled from there.
* `Actions` reads after `Input` in the `input` phase (order
  `Actions.ORDER`) and installs a default `Input` when there is none.
  `engine.plugin(Actions)` returns the installed one, or one without bindings.
* Gamepads come from `navigator.getGamepads()`. Pass `readGamepads` to feed
  them in tests, or `enableGamepad: false` to ignore them.
* A bound key does not also do what it does in the page: Space does not
  scroll or press a focused button, arrows do not scroll. This holds on
  the whole page while `Actions` is installed, as keys are read on
  `window`; give
  `Input` a `keyboardTarget` to keep a small embedded scene from taking
  them. Keys held with Ctrl, Alt or Cmd, Tab and Escape keep their action
  in the page as well. Keys pressed in a form field (an input, a slider, a
  text area) go to the field and do not press actions. Pass
  `enablePreventDefault: false` to leave every key to the page.

### Touch screens

On a phone, buttons on the page and tilting the device drive the same
actions. `addButton(element, action)` holds an action while a finger
presses the element; each finger counts on its own, and a quick tap still
presses once, as does pressing the element from the keyboard:

```ts
actions.bind("left", ["KeyA", "TiltLeft"]);
actions.bind("right", ["KeyD", "TiltRight"]);
actions.addButton(boostButton, "boost"); // returns a function to remove it

// Tilt needs a tap first: iOS asks the player for permission.
const input = engine.plugin(Input);
tiltButton.addEventListener("click", async () => {
  if (input.tilt.available) input.calibrateTilt(); // level is how it is held now
  else await input.requestTilt();
});
```

A finger anywhere on the engine's canvas (the `Input` element) presses
`"Mouse0"`, so one binding serves the mouse and a one-thumb game. One
finger counts at a time: a second one is ignored while the first is
down, and the next to land after the first lifts takes over, so thumbs
can take turns. Moving that finger `swipeDistance` CSS pixels (default
`Actions.DEFAULT_SWIPE_DISTANCE`, 30) from where it went down presses
the `Swipe*` binding of the way it moved, for one frame and once a
press. Swipes work with the mouse too, while its primary button is held,
which helps when trying a touch game on a desktop:

```ts
const actions = new Actions({
  bindings: {
    ollie: ["Space", "Mouse0"], // held while the finger is down
    flip: ["ArrowUp", "SwipeUp"],
    shuvit: ["ArrowRight", "SwipeRight"],
  },
  swipeDistance: 26,
});
engine.use(actions);
```

`input.tilt` is the tilt in degrees, measured on the screen as it is turned,
portrait or landscape: `x` is the right side down, `y` the top edge down,
both from where the device was held when tilt started or was last
calibrated. A `Tilt*` binding reads 0 within `tiltDeadZone` degrees
(default 2) and 1 at `tiltRange` degrees (default 20), counted as at
least a degree past the dead zone; both are properties of `Actions` too,
so a settings screen can change them live.

### Input buffer

`Actions` keeps the last presses of every action with their times
(`bufferSize`, default `Actions.DEFAULT_BUFFER_SIZE`, 16), for presses a
moment early and presses in order. Times are game time
(`FrameContext.elapsed`), so `timeScale` applies.

* `pressedWithin(action, seconds)` is true when the action went down at
  most that long ago, this frame included: a jump pressed just before
  landing still jumps. It stays true for those seconds, so forget a press
  once it is used with `clearBuffer(action)`.
* `sequence(actions, { within, among })` is true when the last presses
  are those actions in order, nothing between, the first at most
  `within` seconds ago (default `Actions.DEFAULT_SEQUENCE_WINDOW`, 0.5).
  With `among`, only presses of those actions count, so steering between
  the two presses of a skater's manual does not break it. A match is
  taken out of the buffer, so it counts once. The order of actions
  pressed in the same frame is not defined.
* `clearBuffer()` forgets every press, as when a run restarts or a menu
  opens.

```ts
if (grounded && actions.pressedWithin("jump", 0.15)) {
  jump();
  actions.clearBuffer("jump");
}
if (actions.sequence(["down", "right", "punch"], { within: 0.4 })) dashAttack();
```

`press(action, device)` presses an action once, in the next frame, as a
tap of an on-screen button does: for controls of your own, such as a
virtual stick that presses directions (`actions.press("up", "touch")`).
The device becomes `lastDevice`.

### Hints and rumble

`actions.lastDevice` is the device that last pressed an action:
`"keyboard"`, `"mouse"`, `"touch"` (a finger or a pen, on the screen or
on an on-screen button), `"gamepad"` or `"tilt"`, and `null` until one is
pressed. A HUD reads it to show the hints for what the player holds;
`actions.playedByTouch` is true for touch and tilt, when the player plays
with what is on the screen.

`actions.rumble({ strength, duration })` gives the player a jolt they feel,
as on a crash: it rumbles every gamepad that can, and vibrates a phone
played by touch or tilt. `strength` is 0..1 (default 1) and only gamepads
feel it; `duration` is in seconds (default `Actions.DEFAULT_RUMBLE_DURATION`,
0.15). Phones vibrate only once the page has been tapped, and Safari and
iOS do not vibrate at all. Pass `vibrate` to `Actions` to feed it in tests.

```ts
hint.textContent = actions.playedByTouch ? "Tap Start" : "W to start";
if (crashed) actions.rumble({ strength: 0.8, duration: 0.2 });
```
