Appearance
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 listenerListeners 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; 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 clickHeadless 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,wasPressedandwasReleasedwork likeInput'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. Actionsreads afterInputin theinputphase (orderActions.ORDER) and installs a defaultInputwhen there is none.engine.plugin(Actions)returns the installed one, or one without bindings.- Gamepads come from
navigator.getGamepads(). PassreadGamepadsto feed them in tests, orenableGamepad: falseto 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
Actionsis installed, as keys are read onwindow; giveInputakeyboardTargetto 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. PassenablePreventDefault: falseto 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 withclearBuffer(action).sequence(actions, { within, among })is true when the last presses are those actions in order, nothing between, the first at mostwithinseconds ago (defaultActions.DEFAULT_SEQUENCE_WINDOW, 0.5). Withamong, 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 });