@gameable/input

Interfaces

ActionMap

A resolved action map. Every method reads the bound state, or the state passed explicitly as the last argument, and takes either an action name or the handle ActionMap.handle returns.

Example

import { createActionMap, createInputState } from 'gameable/input';

const actions = createActionMap({ jump: ['Space'] }, createInputState());
const jump = actions.handle('jump');
console.log(actions.down('jump'), actions.down(jump)); // false false

Properties

names

readonly names: readonly string[];

Action names, in declaration order.

Methods

axis2()

axis2(
   action, 
   state?, 
   out?
): [number, number];

Read a two-axis action into a reusable tuple.

Parameters

Parameter	Type
action	ActionRef
state?	InputState
out?	[number, number]

Returns

[number, number]

bind()

bind(state): void;

Point the map at a different state, e.g. a replayed one.

Parameters

Parameter	Type
state	InputState

Returns

void

down()

down(action, state?): boolean;

Is any binding of this action held?

Parameters

Parameter	Type
action	ActionRef
state?	InputState

Returns

boolean

handle()

handle(name): number;

The stable handle for an action: its 1-based position in names.

Resolve it once, at startup, and pass it to the readers instead of the name. Unknown names throw here rather than sixty times a second.

Parameters

Parameter	Type	Description
name	string	The declared action name.

Returns

number

A small integer, 1..names.length.

pressed()

pressed(action, state?): boolean;

Did any binding of this action go down this frame?

Parameters

Parameter	Type
action	ActionRef
state?	InputState

Returns

boolean

released()

released(action, state?): boolean;

Did any binding of this action come up this frame?

Parameters

Parameter	Type
action	ActionRef
state?	InputState

Returns

boolean

---

Axis2Spec

A two-axis action: four buttons, and optionally a gamepad stick.

Example

import { type Axis2Spec } from 'gameable/input';

const move: Axis2Spec = { axis2: ['A', 'D', 'S', 'W'], gamepadAxes: [0, 1] };
console.log(move.axis2[3]); // 'W'

Properties

axis2

axis2: readonly [string, string, string, string];

Buttons driving [-X, +X, -Y, +Y], e.g. ['A', 'D', 'S', 'W'].

deadzone?

optional deadzone?: number;

Radial deadzone applied to the stick, 0..1. Default 0.15.

gamepadAxes?

optional gamepadAxes?: readonly [number, number];

Gamepad axis indexes for [x, y], e.g. [0, 1] for the left stick.

invertGamepadY?

optional invertGamepadY?: boolean;

Negate the gamepad Y axis so pushing the stick up matches W. Sticks report +1 when pushed down, so this defaults to true.

---

GamepadState

One gamepad slot. Slots are preallocated and reused; read connected before trusting buttons or axes.

Example

import { createInputState } from 'gameable/input';

const pad = createInputState().gamepads[0];
console.log(pad.index, pad.connected, pad.axes.length); // 0 false 6

Properties

axes

axes: Float32Array;

Standard mapping: lx, ly, rx, ry, left trigger, right trigger.

buttons

buttons: number;

Standard-mapping buttons held, one bit per button index.

connected

connected: boolean;

A pad is present in this slot.

index

index: number;

navigator.getGamepads() slot this state mirrors.

pressed

pressed: number;

Buttons that went down this frame.

released

released: number;

Buttons that came up this frame.

---

InputCapture

A live DOM capture. The engine loop drives beginFrame / endFrame once per rendered frame and consume once per fixed step; game code reads InputCapture.state.

Example

import { createInputCapture, isDown, keyIndex } from 'gameable/input';

const capture = createInputCapture(window);
capture.beginFrame();
capture.consume(); // one fixed step
console.log(isDown(capture.state, keyIndex('W'))); // false
capture.endFrame();
capture.dispose();

Properties

lockDenied

readonly lockDenied: boolean;

True when the last pointer-lock request was refused — no user gesture, a sandboxed frame, or the user pressing escape too recently. Cleared by the next InputCapture.requestPointerLock and by a successful lock.

state

readonly state: InputState;

The packed state, mutated in place every frame.

Methods

beginFrame()

beginFrame(): void;

Fold accumulated DOM events into the pending edges and publish the level state — keys held, modifiers, pointer position, gamepad axes. Pending edges and mouse deltas are not published here; they wait for InputCapture.consume.

Returns

void

consume()

consume(): void;

Take one fixed step's worth of input: publish the pending key, mouse and gamepad edges plus the accumulated mouse deltas into state, then clear them so the next step starts empty.

Call once per fixed simulation step, before the step reads state. The input module does this from its fixedUpdate.

Returns

void

dispose()

dispose(): void;

Remove every listener and return the state to neutral.

Returns

void

endFrame()

endFrame(): void;

Clear the published edges and deltas. Unconsumed input is untouched and is still waiting for the next InputCapture.consume.

Returns

void

exitPointerLock()

exitPointerLock(): void;

Release pointer lock if it is held.

Returns

void

requestPointerLock()

requestPointerLock(): void;

Ask the browser for pointer lock. Needs a user gesture to succeed.

Returns

void

---

InputCaptureOptions

Options for createInputCapture.

Example

import { createInputCapture, type InputCaptureOptions } from 'gameable/input';

const options: InputCaptureOptions = { pointerLock: true };
const capture = createInputCapture(window, options);
capture.dispose();

Extended by

• InputOptions

Properties

focused?

optional focused?: boolean;

Whether the target starts focused, before any focus/blur event.

Defaults to document.hasFocus() where that exists and to true where it does not. Pass it explicitly in a headless environment: jsdom reports hasFocus() === false for a document nobody clicked, which would leave preventDefault disabled for keys a test dispatches straight at the window.

gamepads?

optional gamepads?: boolean;

Poll navigator.getGamepads() each frame. Default true.

gamepadSlots?

optional gamepadSlots?: number;

How many gamepad slots to preallocate. Default 4.

onLockDenied?

optional onLockDenied?: () => void;

Called when the browser refuses pointer lock — a pointerlockerror, or a rejected requestPointerLock(). InputCapture.lockDenied carries the same answer for code that would rather poll than subscribe.

Returns

void

pointerLock?

optional pointerLock?: boolean;

Enable pointer lock. A mousedown on the target then requests the lock, and mouse deltas switch to movementX/movementY. Default false.

preventDefault?

optional preventDefault?: boolean;

Call preventDefault() on game keys while focused: the scroll keys always, and everything except escape and the F-keys while pointer-locked. Never fires for a browser shortcut (ctrl/meta/alt) or for a key typed into an editable element. Default true.

touch?

optional touch?: false | TouchOptions;

Fingers on the screen (touch.ts): on by default with no thumb sticks (every finger is the pointer, a tap is a click, two fingers pinch). Pass the sticks and the thresholds, or false for a page that handles touch itself. The last gamepad slot is the touch pad's while it is on.

---

InputModule

The input module, with the service exposed directly for hosts that do not go through the registry.

Example

import { input, type InputModule } from 'gameable/input';

const module: InputModule = input();
console.log(module.id, module.order); // 'input' -100

Extends

• EngineModule

Properties

id

readonly id: string;

Unique id. Also the service id when init returns a service.

Inherited from

EngineModule.id

order?

readonly optional order?: number;

Sort key. Lower runs first; equal keys keep registration order.

Rough convention: input -100, gameplay -50, physics 0, rendering helpers 200. Gameplay runs before physics so that the commands a guest tick emits are simulated by the step that follows rather than the next one.

Inherited from

EngineModule.order

service

readonly service: InputService | null;

The published service, or null before init and after dispose.

Methods

beginFrame()

beginFrame(): void;

Snapshot the frame. Safe before init and after dispose.

Returns

void

Overrides

EngineModule.beginFrame

dispose()

dispose(): void;

Release everything this module took.

Returns

void

Inherited from

EngineModule.dispose

endFrame()

endFrame(): void;

Clear this frame's published edges. Safe before init and after dispose.

Returns

void

Overrides

EngineModule.endFrame

fixedUpdate()

fixedUpdate(dt): void;

Hand this fixed step the edges and deltas that have accumulated since the previous one. Safe before init and after dispose.

Parameters

Parameter	Type	Description
dt	number	Always ctx.config.fixedDt; unused.

Returns

void

Overrides

EngineModule.fixedUpdate

init()

init(ctx): InputService;

Create the capture and return the service, which the engine publishes under input. Synchronous: input needs no asynchronous setup.

Parameters

Parameter	Type	Description
ctx	HostContext	The host context. It has no renderer by design, so the capture falls back to window when none is present.

Returns

InputService

The service, also available as InputModule.service.

Overrides

EngineModule.init

update()?

optional update(dt, alpha): void;

Run once per frame, after the fixed steps and before rendering.

Parameters

Parameter	Type	Description
dt	number	Clamped wall-clock seconds since the previous frame, scaled by time.timeScale.
alpha	number	Interpolation factor in [0, 1) for smoothing transforms.

Returns

void

Inherited from

EngineModule.update

---

InputOptions

Options for input.

Example

import { input, type InputOptions } from 'gameable/input';

const options: InputOptions = { pointerLock: true, actions: { fire: ['LMB'] } };
console.log(input(options).id); // 'input'

Extends

• InputCaptureOptions

Properties

actions?

optional actions?: Readonly<Record<string, ActionSpec>>;

Action bindings, compiled once during init.

focused?

optional focused?: boolean;

Whether the target starts focused, before any focus/blur event.

Defaults to document.hasFocus() where that exists and to true where it does not. Pass it explicitly in a headless environment: jsdom reports hasFocus() === false for a document nobody clicked, which would leave preventDefault disabled for keys a test dispatches straight at the window.

Inherited from

InputCaptureOptions.focused

gamepads?

optional gamepads?: boolean;

Poll navigator.getGamepads() each frame. Default true.

Inherited from

InputCaptureOptions.gamepads

gamepadSlots?

optional gamepadSlots?: number;

How many gamepad slots to preallocate. Default 4.

Inherited from

InputCaptureOptions.gamepadSlots

onLockDenied?

optional onLockDenied?: () => void;

Called when the browser refuses pointer lock — a pointerlockerror, or a rejected requestPointerLock(). InputCapture.lockDenied carries the same answer for code that would rather poll than subscribe.

Returns

void

Inherited from

InputCaptureOptions.onLockDenied

overlay?

optional overlay?: boolean | StickOverlayOptions;

Draw the thumb sticks on the page (stickOverlay.ts) while a thumb is on one: true for the defaults, or the overlay's options. Off by default; a page without sticks (touch.sticks unset) has nothing to draw.

pointerLock?

optional pointerLock?: boolean;

Enable pointer lock. A mousedown on the target then requests the lock, and mouse deltas switch to movementX/movementY. Default false.

Inherited from

InputCaptureOptions.pointerLock

preventDefault?

optional preventDefault?: boolean;

Call preventDefault() on game keys while focused: the scroll keys always, and everything except escape and the F-keys while pointer-locked. Never fires for a browser shortcut (ctrl/meta/alt) or for a key typed into an editable element. Default true.

Inherited from

InputCaptureOptions.preventDefault

target?

optional target?: HTMLElement | Window;

Element to capture from. Defaults to the renderer's canvas (ctx.renderer.domElement), then to the global window.

touch?

optional touch?: false | TouchOptions;

Fingers on the screen (touch.ts): on by default with no thumb sticks (every finger is the pointer, a tap is a click, two fingers pinch). Pass the sticks and the thresholds, or false for a page that handles touch itself. The last gamepad slot is the touch pad's while it is on.

Inherited from

InputCaptureOptions.touch

---

InputService

What the module publishes as the input service. init returns it, so the engine registers it under the module id and engine.get('input') resolves to exactly this object.

Example

import { input, type InputService } from 'gameable/input';

const module = input({ actions: { jump: ['Space'] } });
const service: InputService | null = module.service;
console.log(service); // null until the engine calls init()

Properties

actions

readonly actions: ActionMap;

The action map built from options.actions.

lockDenied

readonly lockDenied: boolean;

True when the browser refused the last pointer-lock request. Show a "click to play" prompt rather than assuming the mouse is captured.

state

readonly state: InputState;

The packed state for the current frame.

Methods

consume()

consume(): void;

Publish one fixed step's worth of edges and mouse deltas into state.

The module already does this from its own fixedUpdate, which runs at order -100 and therefore before any gameplay module. It is exposed for a host that drives the loop itself and does not register the module.

Returns

void

exitPointerLock()

exitPointerLock(): void;

Release pointer lock if it is held.

Returns

void

requestPointerLock()

requestPointerLock(): void;

Ask the browser for pointer lock; needs a user gesture.

Returns

void

---

InputState

The whole input block for one frame: the packed form of WIT input-state.

Example

import { createInputState, isDown, keyIndex } from 'gameable/input';

const state = createInputState();
console.log(state.keysDown.length, isDown(state, keyIndex('W'))); // 8 false

Properties

focused

focused: boolean;

The capture target has focus; treat input as neutral when false.

gamepads

gamepads: GamepadState[];

Gamepad slots, preallocated and stable. The last one is the touch pad's while a finger is down.

keysDown

keysDown: Uint32Array;

Keys held this frame, 256 bits in 8 words.

keysPressed

keysPressed: Uint32Array;

Keys that went down this frame.

keysReleased

keysReleased: Uint32Array;

Keys that came up this frame.

mods

mods: number;

Modifier flags, as Mods bits.

mouse

mouse: MouseState;

Pointer state.

touch

touch: TouchState;

Fingers on the screen, beside what they mirror into the keys, the pointer block and the touch pad (touch.ts). Host-side only: the guest reads the mirrors.

---

MouseState

Pointer state for one frame. dx/dy are the frame's accumulated movement: movementX/movementY while pointer lock is held, the client-space difference otherwise.

Example

import { createInputState } from 'gameable/input';

const { mouse } = createInputState();
console.log(mouse.x, mouse.dx, mouse.locked); // 0 0 false

Properties

buttons

buttons: number;

Buttons held, as MouseButtons bits.

dx

dx: number;

Accumulated X movement for the frame.

dy

dy: number;

Accumulated Y movement for the frame.

locked

locked: boolean;

Pointer lock is currently held by the capture target.

pressed

pressed: number;

Buttons that went down this frame.

released

released: number;

Buttons that came up this frame.

wheel

wheel: number;

Accumulated wheel delta for the frame, in lines; positive is down.

x

x: number;

Client-space X in CSS pixels.

y

y: number;

Client-space Y in CSS pixels.

---

StickOverlay

A stick overlay.

Properties

element

readonly element: HTMLElement;

The two rings' root.

Methods

dispose()

dispose(): void;

Take the rings off the page.

Returns

void

update()

update(touch): void;

Move the rings to where the sticks are; hide the ones at rest. Once a frame.

Parameters

Parameter	Type
touch	TouchState

Returns

void

---

StickOverlayOptions

Options for createStickOverlay.

Properties

knob?

optional knob?: number;

The knob's diameter, CSS pixels. Default 44.

parent?

optional parent?: HTMLElement;

The element the rings go in. Defaults to the document's body.

reach?

optional reach?: number;

The ring's radius, CSS pixels; the same as the touch layer's reach. Default 56.

zIndex?

optional zIndex?: number;

Stacking order. Default 20.

---

TouchArea

The target's box in client space, as getBoundingClientRect gives it.

Properties

height

height: number;

left

left: number;

top

top: number;

width

width: number;

---

TouchLayer

The touch layer, driven by the capture.

Properties

pad

readonly pad: GamepadState;

The pad slot the layer drives (its index is TOUCH_PAD_INDEX while connected).

state

readonly state: TouchState;

The state the capture publishes as state.touch.

Methods

consume()

consume(): void;

Publish this step's deltas (the pointer's, the pinch's, the turn's) and clear them.

Returns

void

down()

down(
   event, 
   area, 
   now
): boolean;

A finger landed. Returns false for a pointer the layer ignores (a mouse).

Parameters

Parameter	Type	Description
event	TouchPointerEvent	The pointer event.
area	TouchArea	The target's box in client space (its halves place the sticks, its top strip the band).
now	number	Milliseconds, the same clock as tick.

Returns

boolean

endFrame()

endFrame(): void;

Clear the published deltas at the end of a frame.

Returns

void

mouseDown()

mouseDown(
   x, 
   y, 
   now
): void;

The mouse's left button went down: a click, a hold and a drag are the same gestures a finger makes, so a game binds Tap once. The pointer block is the mouse handlers' own; this only names the gesture.

Parameters

Parameter	Type	Description
x	number	Client-space x.
y	number	Client-space y.
now	number	Milliseconds.

Returns

void

mouseMove()

mouseMove(x, y): void;

The mouse moved with the left button down.

Parameters

Parameter	Type
x	number
y	number

Returns

void

mouseUp()

mouseUp(
   x, 
   y, 
   now
): void;

The mouse's left button came up.

Parameters

Parameter	Type
x	number
y	number
now	number

Returns

void

move()

move(event): boolean;

A finger moved.

Parameters

Parameter	Type
event	TouchPointerEvent

Returns

boolean

releaseAll()

releaseAll(): void;

Every finger let go: focus lost, the page hidden, the capture disposed.

Returns

void

tick()

tick(now): boolean;

Time passes: holds mature. Returns true when something changed.

Parameters

Parameter	Type
now	number

Returns

boolean

up()

up(
   event, 
   now, 
   cancelled
): boolean;

A finger lifted (cancelled: the browser took it, so never a tap).

Parameters

Parameter	Type
event	TouchPointerEvent
now	number
cancelled	boolean

Returns

boolean

---

TouchOptions

Options for the touch layer, given as touch to createInputCapture or input().

Example

import { input, type TouchOptions } from 'gameable/input';

const touch: TouchOptions = { sticks: 'both', reach: 56 };
console.log(input({ touch }).id); // 'input'

Properties

deadzone?

optional deadzone?: number;

Radial deadzone of a stick, as a share of the reach. Default 0.15.

doubleTapMs?

optional doubleTapMs?: number;

A second tap within this many milliseconds and doubleTapSlop pixels of the first is a double tap. Default 300.

doubleTapSlop?

optional doubleTapSlop?: number;

See doubleTapMs. Default 40.

holdMs?

optional holdMs?: number;

A finger held still this long (milliseconds) is a hold. Default 500.

reach?

optional reach?: number;

The stick's reach from its centre to the rim, in CSS pixels. Default 56.

sticks?

optional sticks?: "none" | "left" | "both";

Which thumb sticks the screen has: 'none' (every finger is the pointer; the default), 'left' (a finger landing on the left half moves a stick, the right half is the pointer) or 'both' (a left stick for movement and a right one for the camera, the right thumb also being the pointer).

tapMs?

optional tapMs?: number;

A touch shorter than this (milliseconds) that never moved is a tap. Default 350.

tapSlop?

optional tapSlop?: number;

How far a finger may wander and still be a tap, in CSS pixels. Default 12.

topBand?

optional topBand?: number;

A strip at the top of the target, as a share of its height, where a finger landing is nobody's (a page's own bar sits there). Default 0.

---

TouchPointerEvent

A pointer event as the layer reads it: the four fields, so a test can hand over a plain object.

Properties

clientX

clientX: number;

clientY

clientY: number;

pointerId

pointerId: number;

pointerType

pointerType: string;

---

TouchSink

How the touch layer writes into the capture. The capture binds these to its own live mirrors; a test binds them to fakes.

Methods

pointerDown()

pointerDown(x, y): void;

The pointer finger went down (the left button, at this position).

Parameters

Parameter	Type
x	number
y	number

Returns

void

pointerMove()

pointerMove(x, y): void;

The pointer finger moved; the capture accumulates the delta itself.

Parameters

Parameter	Type
x	number
y	number

Returns

void

pointerUp()

pointerUp(): void;

The pointer finger came up, or stopped being the pointer.

Returns

void

pulseKey()

pulseKey(index): void;

A one-step pulse of a pseudo-key: pressed and released in the same step.

Parameters

Parameter	Type
index	number

Returns

void

setKey()

setKey(index, down): void;

Set or clear a level pseudo-key.

Parameters

Parameter	Type
index	number
down	boolean

Returns

void

wheel()

wheel(lines): void;

Wheel lines from a pinch; negative zooms in.

Parameters

Parameter	Type
lines	number

Returns

void

---

TouchState

Everything the touch layer knows this step, beside what it mirrors into the keys, the pointer block and the touch pad.

Example

import { createInputState } from 'gameable/input';

const { touch } = createInputState();
console.log(touch.fingers, touch.pinch, touch.left.active); // 0 1 false

Properties

centreX

centreX: number;

centreY

centreY: number;

dx

dx: number;

The pointer finger's movement this step.

dy

dy: number;

fingers

fingers: number;

Fingers on the target right now, the sticks' included.

left

left: TouchStick;

The thumb sticks.

pinch

pinch: number;

Two fingers: the scale this step (1 = no change), the turn this step in radians (counter-clockwise on screen positive), and their centre.

right

right: TouchStick;

tapX

tapX: number;

Where the last tap (or double tap) landed.

tapY

tapY: number;

turn

turn: number;

x

x: number;

The pointer finger's position, client-space CSS pixels (the last known when none).

y

y: number;

---

TouchStick

One thumb stick, as the game and a stick overlay read it.

Example

import { createInputState } from 'gameable/input';

const { left } = createInputState().touch;
console.log(left.active, left.x, left.y); // false 0 0

Properties

active

active: boolean;

A thumb is on this stick.

originX

originX: number;

Where the stick's centre is, client-space CSS pixels.

originY

originY: number;

touchX

touchX: number;

Where the thumb is, client-space CSS pixels.

touchY

touchY: number;

x

x: number;

The stick's push, -1..1, right positive.

y

y: number;

The stick's push, -1..1, DOWN positive (a real stick's convention).

Type Aliases

ActionBindings

type ActionBindings = Readonly<Record<string, ActionSpec>>;

The whole action map, as game code declares it.

Example

import { type ActionBindings } from 'gameable/input';

const bindings: ActionBindings = {
  fire: ['LMB', 'GamepadRT'],
  move: { axis2: ['A', 'D', 'S', 'W'], gamepadAxes: [0, 1] },
};
console.log(Object.keys(bindings).length); // 2

---

ActionRef

type ActionRef = string | number;

How a reader names the action to read: the declared name, or the small integer ActionMap.handle minted for it.

Resolving a name costs a Map lookup and a branch; resolving a handle is an array index. Hoist the handle out of the frame body and the read becomes a handful of bit tests with no string work at all.

Example

import { createActionMap, createInputState, type ActionRef } from 'gameable/input';

const actions = createActionMap({ jump: ['Space'] }, createInputState());
const jump: ActionRef = actions.handle('jump');
console.log(actions.down(jump)); // false

---

ActionSpec

type ActionSpec = readonly string[] | Axis2Spec;

One action's bindings: a button list, or a two-axis spec.

Variables

DEFAULT_GAMEPAD_SLOTS

const DEFAULT_GAMEPAD_SLOTS: 4 = 4;

Default number of preallocated gamepad slots.

---

GAMEPAD_AXES

const GAMEPAD_AXES: 6 = 6;

Number of axes a GamepadState carries: lx, ly, rx, ry, lt, rt.

---

GAMEPAD_BUTTON_INDEX

const GAMEPAD_BUTTON_INDEX: Readonly<Record<string, number>>;

Standard-mapping gamepad button indexes, by friendly name. The names follow the Xbox layout because that is what the W3C standard mapping describes; GamepadCross and friends alias the PlayStation spelling.

Example

import { GAMEPAD_BUTTON_INDEX } from 'gameable/input';

console.log(GAMEPAD_BUTTON_INDEX.GamepadA); // 0
console.log(GAMEPAD_BUTTON_INDEX.GamepadRT); // 7

---

KEY_COUNT

const KEY_COUNT: 256 = 256;

Number of bits — and therefore key slots — in a packed key bitset.

---

KEY_INDEX

const KEY_INDEX: Readonly<Record<string, number>>;

Index of every known key, by KeyboardEvent.code.

Lookup is exact and case-sensitive; use keyIndex to accept friendly aliases such as 'W' or 'LMB'.

Example

import { KEY_INDEX } from 'gameable/input';

console.log(KEY_INDEX.KeyA); // 0
console.log(KEY_INDEX.Space); // 64

---

KEY_NAMES

const KEY_NAMES: readonly string[];

The inverse of KEY_INDEX: 256 slots, '' where nothing is assigned.

Example

import { KEY_NAMES } from 'gameable/input';

console.log(KEY_NAMES[0]); // 'KeyA'
console.log(KEY_NAMES.length); // 256

---

KEY_WORDS

const KEY_WORDS: number;

Number of u32 words a packed key bitset occupies.

---

Mods

const Mods: Readonly<{
  Alt: number;
  CapsLock: number;
  Ctrl: number;
  Meta: number;
  NumLock: number;
  Shift: number;
}>;

Keyboard modifier bits, in input-mods flag order.

Example

import { createInputState, Mods } from 'gameable/input';

const state = createInputState();
state.mods = Mods.Shift | Mods.Ctrl;
console.log((state.mods & Mods.Shift) !== 0); // true

---

MouseButtons

const MouseButtons: Readonly<{
  Back: number;
  Forward: number;
  Left: number;
  Middle: number;
  Right: number;
}>;

Mouse button bits, matching mouse-state.buttons in the WIT contract and the DOM MouseEvent.button numbering.

Example

import { createInputState, MouseButtons } from 'gameable/input';

const state = createInputState();
state.mouse.buttons = MouseButtons.Left;
console.log((state.mouse.buttons & MouseButtons.Left) !== 0); // true

---

PACKAGE

const PACKAGE: "@gameable/input";

Package identity marker for gameable/input.

Example

import { PACKAGE } from 'gameable/input';

console.log(PACKAGE); // 'gameable/input'

---

POINTER_BASE

const POINTER_BASE: 248 = 248;

First index of the reserved pointer block. Indexes below this are real KeyboardEvent.code values; POINTER_BASE + n is mouse button n.

---

POINTER_BUTTON_MAX

const POINTER_BUTTON_MAX: 4 = 4;

Highest mouse button the pointer block can represent (0..4).

---

TOUCH_KEYS

const TOUCH_KEYS: Readonly<{
  doubleTap: "DoubleTap";
  drag: "Drag";
  hold: "Hold";
  pinch: "Pinch";
  stickLeft: "StickLeft";
  stickRight: "StickRight";
  tap: "Tap";
}>;

The gesture pseudo-keys, by gesture.

Example

import { keyIndex, TOUCH_KEYS } from 'gameable/input';

console.log(TOUCH_KEYS.tap, keyIndex(TOUCH_KEYS.tap)); // 'Tap' 128

---

TOUCH_PAD_AXIS_PINCH

const TOUCH_PAD_AXIS_PINCH: 4 = 4;

This step's pinch as log2 of the scale, and turn in radians.

---

TOUCH_PAD_AXIS_TURN

const TOUCH_PAD_AXIS_TURN: 5 = 5;

---

TOUCH_PAD_INDEX

const TOUCH_PAD_INDEX: 255 = 255;

The index of the touch pad in input-state.gamepads: the virtual gamepad the host's touch layer connects while a finger is on the screen. Its axes are the two thumb sticks (lx, ly, rx, ry, the standard mapping's order, +y pushed down), then this step's pinch (log2 of the scale) and turn (radians). A real gamepad never reports this index.

Functions

axis2()

function axis2(
   state, 
   negX, 
   posX, 
   negY, 
   posY, 
   out?
): [number, number];

Read four keys as one clamped 2D axis: x = posX - negX, y = posY - negY.

The result is written into a reusable tuple. Consume it before the next call, or pass your own out — this keeps the per-frame allocation count at zero, which hard rule 2 requires of anything on the update path.

Parameters

Parameter	Type	Default value	Description
state	InputState	undefined	The state to read.
negX	number	undefined	Key index driving -X, e.g. keyIndex('A').
posX	number	undefined	Key index driving +X, e.g. keyIndex('D').
negY	number	undefined	Key index driving -Y, e.g. keyIndex('S').
posY	number	undefined	Key index driving +Y, e.g. keyIndex('W').
out	[number, number]	AXIS2_SCRATCH	Tuple to write into; defaults to a shared scratch tuple.

Returns

[number, number]

out, holding the axis values, each in -1..1.

Example

import { axis2, createInputState, keyIndex, setBit } from 'gameable/input';

const state = createInputState();
setBit(state.keysDown, keyIndex('W'), true);
const [x, y] = axis2(state, keyIndex('A'), keyIndex('D'), keyIndex('S'), keyIndex('W'));
console.log(x, y); // 0 1

---

clearEdges()

function clearEdges(state): void;

Clear every single-frame edge: key press/release bitsets, mouse edges and deltas, gamepad edges. The loop calls this from endFrame.

Parameters

Parameter	Type	Description
state	InputState	The state to clear, in place.

Returns

void

Example

import { clearEdges, createInputState } from 'gameable/input';

const state = createInputState();
state.mouse.dx = 12;
clearEdges(state);
console.log(state.mouse.dx); // 0

---

createActionMap()

function createActionMap(bindings, state?): ActionMap;

Compile a binding declaration into an ActionMap.

Unknown binding spellings throw here, at startup, rather than silently doing nothing sixty times a second.

Parameters

Parameter	Type	Description
bindings	ActionBindings	The action declaration.
state?	InputState	State the map reads by default; may be supplied later with ActionMap.bind or per call.

Returns

ActionMap

The compiled map.

Example

import { createActionMap, createInputState, keyIndex, setBit } from 'gameable/input';

const state = createInputState();
const actions = createActionMap(
  {
    fire: ['LMB', 'GamepadRT'],
    jump: ['Space', 'GamepadA'],
    move: { axis2: ['A', 'D', 'S', 'W'], gamepadAxes: [0, 1] },
  },
  state,
);
const move = actions.handle('move');

setBit(state.keysDown, keyIndex('D'), true);
console.log(actions.axis2(move)); // [1, 0]

---

createInputCapture()

function createInputCapture(target, options?): InputCapture;

Attach DOM listeners to target and collect input into a packed state.

Keyboard, focus and gamepad-connection events are attached to the owning window (a canvas only receives key events when it is focusable); mouse, wheel and context-menu events are attached to target itself; pointerlockchange is attached to the owning document.

Parameters

Parameter	Type	Description
target	HTMLElement | Window	The element that owns the pointer — usually the canvas — or a window.
options	InputCaptureOptions	See InputCaptureOptions.

Returns

InputCapture

A live capture; call dispose() when the engine shuts down.

Example

import { createInputCapture, keyIndex, wasPressed } from 'gameable/input';

const capture = createInputCapture(window, { pointerLock: true });
// Resolve the index once, never inside the frame body.
const SPACE = keyIndex('Space');

function frame(): void {
  capture.beginFrame();
  capture.consume(); // one fixed step's worth of edges
  if (wasPressed(capture.state, SPACE)) console.log('jump');
  capture.endFrame();
}

frame();
capture.dispose();

---

createInputState()

function createInputState(gamepadSlots?): InputState;

Allocate a zeroed InputState. This is the only allocation the input pipeline performs; everything afterwards mutates it in place.

Parameters

Parameter	Type	Default value	Description
gamepadSlots	number	DEFAULT_GAMEPAD_SLOTS	How many gamepad slots to preallocate.

Returns

InputState

A fresh, neutral input state.

Example

import { createInputState } from 'gameable/input';

const state = createInputState();
console.log(state.gamepads.length, state.focused); // 4 false

---

createStickOverlay()

function createStickOverlay(options?): StickOverlay;

Draw the thumb sticks on the page.

Parameters

Parameter	Type	Description
options	StickOverlayOptions	See StickOverlayOptions.

Returns

StickOverlay

The overlay; call update(state.touch) once a frame.

Example

import { createInputState, createStickOverlay } from 'gameable/input';

const overlay = createStickOverlay({ reach: 56 });
overlay.update(createInputState().touch);
overlay.dispose();

---

createTouchLayer()

function createTouchLayer(
   sink, 
   pad, 
   touch, 
   options?
): TouchLayer;

Create the touch layer.

Parameters

Parameter	Type	Description
sink	TouchSink	Where the layer writes keys, the pointer block and the wheel.
pad	GamepadState	The gamepad slot the layer drives (the capture's last one).
touch	TouchState	The state to fill (the capture's state.touch).
options	TouchOptions	See TouchOptions.

Returns

TouchLayer

The layer.

Example

import { createInputState, createTouchLayer, type TouchSink } from 'gameable/input';

const state = createInputState();
const sink: TouchSink = {
  setKey: () => undefined,
  pulseKey: () => undefined,
  pointerDown: () => undefined,
  pointerMove: () => undefined,
  pointerUp: () => undefined,
  wheel: () => undefined,
};
const layer = createTouchLayer(sink, state.gamepads[3], state.touch, { sticks: 'both' });
const area = { left: 0, top: 0, width: 800, height: 600 };
layer.down({ pointerId: 1, pointerType: 'touch', clientX: 100, clientY: 400 }, area, 0);
console.log(state.touch.left.active); // true

---

createTouchState()

function createTouchState(): TouchState;

A neutral touch state. createInputState calls this, so every state has one.

Returns

TouchState

The state, all fingers up.

Example

import { createTouchState } from 'gameable/input';

console.log(createTouchState().fingers); // 0

---

gamepadButtonIndex()

function gamepadButtonIndex(name): number;

Resolve a gamepad binding name to a standard-mapping button index.

Parameters

Parameter	Type	Description
name	string	A Gamepad* name from GAMEPAD_BUTTON_INDEX.

Returns

number

The button index, or -1 when the name is not a gamepad button.

Example

import { gamepadButtonIndex } from 'gameable/input';

gamepadButtonIndex('GamepadA'); // 0
gamepadButtonIndex('KeyW'); // -1

---

input()

function input(options?): InputModule;

Create the input EngineModule.

beginFrame folds the frame's DOM events into the capture's pending edges and publishes the level state; fixedUpdate hands one simulation step the edges and mouse deltas that have accumulated since the previous step; endFrame clears the published edges. All three delegate to the capture and allocate nothing.

Parameters

Parameter	Type	Description
options	InputOptions	See InputOptions.

Returns

InputModule

The module; register it with the engine.

Example

import { input } from 'gameable/input';

const module = input({
  pointerLock: true,
  actions: { fire: ['LMB', 'GamepadRT'], move: { axis2: ['A', 'D', 'S', 'W'] } },
});

console.log(module.id); // 'input'

---

isDown()

function isDown(state, index): boolean;

Is the key at index held this frame?

A negative index (what keyIndex returns for an unknown name) is always false, so an unresolvable binding is dead rather than fatal.

Parameters

Parameter	Type	Description
state	InputState	The state to read.
index	number	A frozen key index.

Returns

boolean

True when the key is down.

Example

import { createInputState, isDown, keyIndex } from 'gameable/input';

const state = createInputState();
state.keysDown[keyIndex('W') >> 5] |= 1 << (keyIndex('W') & 31);
console.log(isDown(state, keyIndex('W'))); // true

---

isFingerPointer()

function isFingerPointer(pointerType): boolean;

Is this pointer a finger or a pen? A mouse keeps its own events.

Parameters

Parameter	Type	Description
pointerType	string	The event's pointerType.

Returns

boolean

True for a touch or a pen.

---

keyIndex()

function keyIndex(nameOrCode): number;

Resolve a KeyboardEvent.code, a friendly alias or a mouse-button name to its frozen bit index.

Accepted spellings, in order: the exact code ('KeyW', 'Space'), a single letter or digit ('W', '7'), a short name ('Esc', 'Ctrl', 'Up'), a mouse button ('LMB', 'RMB', 'Mouse3'). Gamepad bindings are not keys — see createActionMap for those.

Parameters

Parameter	Type	Description
nameOrCode	string	The code or alias to resolve.

Returns

number

The bit index, or -1 when nothing matches.

Example

import { keyIndex } from 'gameable/input';

keyIndex('KeyW'); // 22
keyIndex('W'); // 22, the same key
keyIndex('LMB'); // 248, the left mouse button
keyIndex('nonsense'); // -1

---

keyIndex2()

function keyIndex2(nameOrCode): number;

The second index of an alias that names a left/right pair, so a binding of 'Shift' covers both shift keys.

Parameters

Parameter	Type	Description
nameOrCode	string	The code or alias to resolve.

Returns

number

The second bit index, or -1 when the name maps to one key only.

Example

import { keyIndex, keyIndex2, KEY_NAMES } from 'gameable/input';

console.log(KEY_NAMES[keyIndex('Shift')]); // 'ShiftLeft'
console.log(KEY_NAMES[keyIndex2('Shift')]); // 'ShiftRight'
console.log(keyIndex2('KeyW')); // -1

---

pointerKeyIndex()

function pointerKeyIndex(button): number;

The key index that mirrors a DOM MouseEvent.button number.

Parameters

Parameter	Type	Description
button	number	MouseEvent.button: 0 left, 1 middle, 2 right, 3 back, 4 forward.

Returns

number

The mirrored key index, or -1 for a button outside the block.

Example

import { pointerKeyIndex } from 'gameable/input';

pointerKeyIndex(0); // 248
pointerKeyIndex(9); // -1

---

resetInputState()

function resetInputState(state): void;

Return the state to neutral: nothing held, no edges, no deltas. Capture calls this on blur so a key held when the window loses focus does not stick down forever.

Parameters

Parameter	Type	Description
state	InputState	The state to reset, in place.

Returns

void

Example

import { createInputState, isDown, keyIndex, resetInputState, setBit } from 'gameable/input';

const state = createInputState();
setBit(state.keysDown, keyIndex('W'), true);
resetInputState(state);
console.log(isDown(state, keyIndex('W'))); // false

---

resetTouchState()

function resetTouchState(touch): void;

Put a touch state back to neutral, in place.

Parameters

Parameter	Type	Description
touch	TouchState	The state to reset.

Returns

void

Example

import { createTouchState, resetTouchState } from 'gameable/input';

const touch = createTouchState();
touch.fingers = 2;
resetTouchState(touch);
console.log(touch.fingers); // 0

---

setBit()

function setBit(
   words, 
   index, 
   value
): void;

Set or clear one bit in a packed key bitset. Exported for capture and for tests that hand-build a state; game code reads, it does not write.

Parameters

Parameter	Type	Description
words	Uint32Array	The eight-word bitset.
index	number	Bit index; out-of-range indexes are ignored.
value	boolean	True to set the bit, false to clear it.

Returns

void

Example

import { createInputState, isDown, keyIndex, setBit } from 'gameable/input';

const state = createInputState();
setBit(state.keysDown, keyIndex('KeyA'), true);
console.log(isDown(state, keyIndex('KeyA'))); // true

---

wasPressed()

function wasPressed(state, index): boolean;

Did the key at index go down this frame?

Parameters

Parameter	Type	Description
state	InputState	The state to read.
index	number	A frozen key index.

Returns

boolean

True on the single frame the key went down.

Example

import { createInputState, keyIndex, wasPressed } from 'gameable/input';

const state = createInputState();
console.log(wasPressed(state, keyIndex('Space'))); // false

---

wasReleased()

function wasReleased(state, index): boolean;

Did the key at index come up this frame?

Parameters

Parameter	Type	Description
state	InputState	The state to read.
index	number	A frozen key index.

Returns

boolean

True on the single frame the key came up.

Example

import { createInputState, keyIndex, wasReleased } from 'gameable/input';

const state = createInputState();
console.log(wasReleased(state, keyIndex('Space'))); // false