Skip to content

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
);
};
MemberMeaning
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.
pointerLast state of the primary pointer: clientX, clientY, per-frame dx/dy, buttons, inside, pointerType.
lockPointer(), unlockPointer(), pointerLockedPointer lock, below.
wheelWheel 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; 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:

WASD to move, click the floor
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
;
MemberMeaning
u, v, insidePosition of the primary pointer over the canvas, 0 to 1 from the top left, and whether it is over it.
target, hit, hitsEntity, nearest hit and every hit directly under the primary pointer (Hovered may sit on an ancestor), picked each frame in the input phase.
allThe 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.
draggedWhether the current gesture moved past the drag threshold.
capturedWhether 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
BindingMeans
"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 });