A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { defineResource } from '../ecs/resource';
import { defineSystem, Schedule } from '../ecs/system';
import type { App, Plugin } from '../app/app';
import { claimsKeyDefault, recordTabModifiers, clearTabModifiers } from './keyDefaultPolicy';
import { getPlatform, platformUnbindInputEvents } from '../platform';
import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';
import { inputRouter } from './inputRouter';
import { cancelPrimaryPointer, takePrimaryPointerCancellation } from './pointerCancellation';
import { recordTouchEnd } from './touchEdges';
import { recordActionEdge, discardActionEdges, clearActionEdges, beginFixedActionEdges, endFixedActionEdges, cancelActionEdges } from './actionEdges';
import type { Vec2 } from '../types';
import { RuntimeConfig } from '../defaults';
/**
* One active touch, in screen pixels with y growing downward.
*
* @beta
*/
export interface TouchPoint {
id: number;
x: number;
y: number;
}
/**
* Standard-mapping gamepad buttons (W3C "standard gamepad"). Positional names
* (SDL / Steam Input convention) avoid device assumptions; Xbox / PlayStation
* face labels are noted for reference.
*
* @public
*/
export enum GamepadButton {
South = 0, // A (Xbox) · Cross (PS)
East = 1, // B · Circle
West = 2, // X · Square
North = 3, // Y · Triangle
LeftBumper = 4, // LB · L1
RightBumper = 5, // RB · R1
LeftTrigger = 6, // LT · L2 (analog)
RightTrigger = 7, // RT · R2 (analog)
Back = 8, // View · Select / Share
Start = 9, // Menu · Options
LeftStick = 10, // L3 (stick click)
RightStick = 11, // R3
DpadUp = 12,
DpadDown = 13,
DpadLeft = 14,
DpadRight = 15,
Guide = 16, // Xbox · PS · Home
}
/** Standard-mapping gamepad axes (signed, [-1,1]).
* @public */
export enum GamepadAxis {
LeftX = 0,
LeftY = 1,
RightX = 2,
RightY = 3,
}
/** @internal Per-gamepad runtime state — current + previous frame, for edges. */
interface PadState {
connected: boolean;
buttons: number[];
prevButtons: number[];
axes: number[];
}
const ZERO_VIRTUAL: Vec2 = { x: 0, y: 0 };
/**
* This frame's raw input — the layer under {@link defineInputMap}'s named actions.
*
* `@beta`: per-frame touch state is reachable only as the raw `touches` /
* `touchesStarted` / `touchesEnded` maps, so freezing it freezes two gaps in that
* representation — no accessor for started/ended, and no write door at all.
*
* @beta
*/
export class InputState {
keysDown = new Set<string>();
keysPressed = new Set<string>();
keysReleased = new Set<string>();
mouseX = 0;
mouseY = 0;
/** How far the pointer moved this frame, summed over its events: what a locked pointer has instead of a position. Cleared at the end of the frame. */
mouseDeltaX = 0;
mouseDeltaY = 0;
mouseButtons = new Set<number>();
mouseButtonsPressed = new Set<number>();
mouseButtonsReleased = new Set<number>();
scrollDeltaX = 0;
scrollDeltaY = 0;
/** Whether the device can be touched — asked of the platform, not of history. */
touchAvailable = false;
touches = new Map<number, TouchPoint>();
touchesStarted = new Map<number, TouchPoint>();
/** Fingers lifted this frame, at the position they lifted AT — a release is
* hit-tested where it happened, and the live `touches` no longer hold it. */
touchesEnded = new Map<number, TouchPoint>();
// — Fixed-timestep edge mirrors —
// The render edges above are cleared once per rendered frame (Schedule.Last),
// but FixedUpdate runs a variable number of steps per frame (0 on a frame
// shorter than the timestep, 2+ when catching up). Reading a render edge from
// a fixed system therefore drops presses on sub-timestep frames and doubles
// them on catch-up frames. These mirrors are populated alongside the render
// edges but cleared per *step* (see endFixedStep), so a press/release reaches
// exactly one fixed step — the first one at or after it arrived. While a fixed
// step is running, the keyboard/mouse edge queries read these instead.
// (Godot's idle- vs physics-frame `just_pressed` split.)
keysPressedFixed = new Set<string>();
keysReleasedFixed = new Set<string>();
mouseButtonsPressedFixed = new Set<number>();
mouseButtonsReleasedFixed = new Set<number>();
private fixedContext_ = false;
isKeyDown(key: string): boolean {
return this.keysDown.has(key);
}
isKeyPressed(key: string): boolean {
return (this.fixedContext_ ? this.keysPressedFixed : this.keysPressed).has(key);
}
isKeyReleased(key: string): boolean {
return (this.fixedContext_ ? this.keysReleasedFixed : this.keysReleased).has(key);
}
getMousePosition(): { x: number; y: number } {
return { x: this.mouseX, y: this.mouseY };
}
/** How far the pointer moved this frame. Zero where the host does not say (a mini game has no pointer to lock). */
getMouseDelta(): { x: number; y: number } {
return { x: this.mouseDeltaX, y: this.mouseDeltaY };
}
isMouseButtonDown(button: number): boolean {
return this.mouseButtons.has(button);
}
isMouseButtonPressed(button: number): boolean {
return (this.fixedContext_ ? this.mouseButtonsPressedFixed : this.mouseButtonsPressed).has(button);
}
isMouseButtonReleased(button: number): boolean {
return (this.fixedContext_ ? this.mouseButtonsReleasedFixed : this.mouseButtonsReleased).has(button);
}
// — Edge intake (called by the platform binding for every raw event) —
// Centralised here so the render and fixed mirrors can never drift apart.
/** Record a key-down. The pressed edge only fires on the transition, so a
* browser's auto-repeat keydown for a held key doesn't re-trigger it. */
noteKeyDown(code: string): void {
recordTabModifiers(this, code);
if (!this.keysDown.has(code)) {
recordActionEdge(this, 'key', code, true);
this.keysPressed.add(code);
this.keysPressedFixed.add(code);
}
this.keysDown.add(code);
}
noteKeyUp(code: string): void {
if (this.keysDown.has(code)) recordActionEdge(this, 'key', code, false);
this.keysDown.delete(code);
this.keysReleased.add(code);
this.keysReleasedFixed.add(code);
}
noteMouseDown(button: number): void {
if (!this.mouseButtons.has(button)) recordActionEdge(this, 'mouse', button, true);
if (button === 0) takePrimaryPointerCancellation(this);
this.mouseButtons.add(button);
this.mouseButtonsPressed.add(button);
this.mouseButtonsPressedFixed.add(button);
}
noteMouseUp(button: number): void {
if (this.mouseButtons.has(button)) recordActionEdge(this, 'mouse', button, false);
this.mouseButtons.delete(button);
this.mouseButtonsReleased.add(button);
this.mouseButtonsReleasedFixed.add(button);
}
getScrollDelta(): { x: number; y: number } {
return { x: this.scrollDeltaX, y: this.scrollDeltaY };
}
getTouches(): TouchPoint[] {
return [...this.touches.values()];
}
getTouchCount(): number {
return this.touches.size;
}
getTouch(id: number): TouchPoint | null {
return this.touches.get(id) ?? null;
}
isTouchActive(id: number): boolean {
return this.touches.has(id);
}
/** Fingers that went down this frame. */
getTouchesStarted(): TouchPoint[] {
return [...this.touchesStarted.values()];
}
/** Fingers that came up this frame, at the position they came up at. */
getTouchesEnded(): TouchPoint[] {
return [...this.touchesEnded.values()];
}
/** Retire a touch after a normal release, retaining its position and press edge. */
endTouch(id: number): void {
const point = this.touches.get(id) ?? { id, x: 0, y: 0 };
recordTouchEnd(point, this.touchesStarted.has(id));
this.touches.delete(id);
this.touchesEnded.set(id, point);
}
// — Multi-touch —
/**
* Whether several fingers are handled at once. On (the default), every touch
* reaches the UI and the game. Off, one finger at a time does: the first to
* go down is the touch until it lifts, and a finger pressed meanwhile is
* ignored for its whole life, by the UI and the game alike, so a second
* finger cannot press a button or move a joystick under the first.
*/
/** What the game set with {@link setMultiTouch}, or null to follow the project (RuntimeConfig.multiTouch). */
private multiTouch_: boolean | null = null;
/** Single-touch mode: the finger being handled, or null when none is down. */
private soleTouch_: number | null = null;
/** Single-touch mode: fingers ignored until they lift. */
private ignoredTouches_ = new Set<number>();
/** On unless the project turned it off (Project Settings → Runtime) or the game did. */
isMultiTouchEnabled(): boolean {
return this.multiTouch_ ?? RuntimeConfig.multiTouch;
}
/**
* Handle several fingers at once, or one. Turning it off while several are
* down keeps the first that went down and cancels the rest, as the platform
* cancelling them would: their touches end with no release edge, and a UI
* control they were pressing lets go without a click.
*/
setMultiTouch(enabled: boolean): void {
const was = this.isMultiTouchEnabled();
this.multiTouch_ = enabled;
if (enabled === was) return;
this.ignoredTouches_.clear();
this.soleTouch_ = null;
if (enabled) return;
const down = [...this.touches.keys()];
this.soleTouch_ = down[0] ?? null;
for (const id of down.slice(1)) {
inputRouter.dispatchTouchCancel(id);
this.touches.delete(id);
this.touchesStarted.delete(id);
this.touchesEnded.delete(id);
this.ignoredTouches_.add(id);
}
}
/** @internal Whether a finger going down is handled; records it as the one in single-touch mode. */
admitTouch(id: number): boolean {
if (this.isMultiTouchEnabled()) return true;
if (this.soleTouch_ === null || this.soleTouch_ === id) {
this.soleTouch_ = id;
return true;
}
this.ignoredTouches_.add(id);
return false;
}
/** @internal Whether a finger's move, lift or cancel is ignored; a lift or cancel also retires it. */
touchIgnored(id: number, retiring = false): boolean {
if (this.ignoredTouches_.has(id)) {
if (retiring) this.ignoredTouches_.delete(id);
return true;
}
if (retiring && this.soleTouch_ === id) this.soleTouch_ = null;
return false;
}
/** @internal Every finger is gone (focus lost, the app hidden). */
forgetTouches(): void {
this.soleTouch_ = null;
this.ignoredTouches_.clear();
}
// — Virtual (an on-screen control, or anything else that decides to be input) —
/**
* Named 2D values a game writes itself — an on-screen control, the only
* input a touch device has. Named rather than a screen rectangle, so what
* is touched and what is read stay one object when the layout moves.
*/
private virtual_ = new Map<string, Vec2>();
private virtualSources_ = new Map<object, { id: string; x: number; y: number }>();
/** Set a named virtual input; held until overwritten, so stopping means
* writing zero. `y` defaults to 0 for button/1D use. */
setVirtual(id: string, x: number, y = 0): void {
const v = this.virtual_.get(id);
if (v) { v.x = x; v.y = y; } else this.virtual_.set(id, { x, y });
}
getVirtual(id: string): Vec2 {
const value = this.virtual_.get(id) ?? ZERO_VIRTUAL;
let x = value.x, y = value.y, contributed = false;
for (const source of this.virtualSources_.values()) {
if (source.id !== id) continue;
contributed = true; x += source.x; y += source.y;
}
return contributed ? { x: Math.max(-1, Math.min(1, x)), y: Math.max(-1, Math.min(1, y)) } : value;
}
/** A control owns only its contribution, even when several share a binding. */
setVirtualSource(owner: object, id: string, x: number, y = 0): void {
if (x === 0 && y === 0) { this.virtualSources_.delete(owner); return; }
const source = this.virtualSources_.get(owner);
if (source) { source.id = id; source.x = x; source.y = y; }
else this.virtualSources_.set(owner, { id, x, y });
}
removeVirtualSource(owner: object): void { this.virtualSources_.delete(owner); }
/** @internal Host cancellation releases managed controls, leaving manual values to their writer. */
cancelVirtualSources(): void { this.virtualSources_.clear(); }
/** Drop every virtual input — used when a control layer is torn down. */
clearVirtual(): void {
this.virtual_.clear();
this.virtualSources_.clear();
}
// — Gamepad (polled each frame; edges via current/prev diff, not events) —
/** Per-index pad state; an index persists across disconnect so a reconnect resumes. */
gamepads = new Map<number, PadState>();
/** Analog buttons (e.g. triggers) count as "down" at/above this value. */
gamepadButtonThreshold = 0.5;
/** Axis magnitudes below this read as 0 (rest-position stick jitter). */
gamepadDeadzone = 0.15;
/** Indices of currently-connected gamepads. */
getGamepads(): number[] {
const out: number[] = [];
for (const [i, p] of this.gamepads) if (p.connected) out.push(i);
return out;
}
isGamepadConnected(pad = 0): boolean {
return this.gamepads.get(pad)?.connected ?? false;
}
isGamepadButtonDown(button: number, pad = 0): boolean {
const p = this.connectedPad_(pad);
return !!p && (p.buttons[button] ?? 0) >= this.gamepadButtonThreshold;
}
isGamepadButtonPressed(button: number, pad = 0): boolean {
const p = this.connectedPad_(pad);
if (!p) return false;
const t = this.gamepadButtonThreshold;
return (p.buttons[button] ?? 0) >= t && (p.prevButtons[button] ?? 0) < t;
}
isGamepadButtonReleased(button: number, pad = 0): boolean {
const p = this.connectedPad_(pad);
if (!p) return false;
const t = this.gamepadButtonThreshold;
return (p.buttons[button] ?? 0) < t && (p.prevButtons[button] ?? 0) >= t;
}
/** Raw analog value of a button in [0,1] (triggers; 0/1 for digital buttons). */
getGamepadButtonValue(button: number, pad = 0): number {
return this.connectedPad_(pad)?.buttons[button] ?? 0;
}
/** Signed axis value in [-1,1], with the deadzone applied. */
getGamepadAxis(axis: number, pad = 0): number {
const p = this.connectedPad_(pad);
if (!p) return 0;
const v = p.axes[axis] ?? 0;
return Math.abs(v) < this.gamepadDeadzone ? 0 : v;
}
private connectedPad_(pad: number): PadState | undefined {
const p = this.gamepads.get(pad);
return p?.connected ? p : undefined;
}
/** True when the pointer is over an interactive UI element this frame (set each
* frame by the UI interaction system). Gameplay checks this to ignore input
* the UI handled — e.g. don't fire a weapon when clicking a HUD button.
* Unity's `EventSystem.IsPointerOverGameObject()` analog. */
pointerOverUI = false;
isPointerOverUI(): boolean {
return this.pointerOverUI;
}
/** Ingest this frame's snapshots: shift current→prev (edge detection) then
* store new values. Pads absent from `snapshots` are marked disconnected. */
/**
* Pads supplied by the HOST rather than by the hardware — a test harness, a
* driver, the editor's agent. They outrank the poll at the same index: the
* poll runs every frame, so anything merely written into {@link gamepads}
* is gone before a system reads it.
*
* @beta
*/
injectGamepad(snapshot: GamepadSnapshot): void {
this.injected_.set(snapshot.index, snapshot);
}
/** Give an index (or all of them) back to the hardware. @beta */
releaseGamepad(index?: number): void {
if (index === undefined) this.injected_.clear();
else this.injected_.delete(index);
}
private injected_ = new Map<number, GamepadSnapshot>();
updateGamepads(snapshots: GamepadSnapshot[]): void {
// An injected pad REPLACES the polled one at its index; a polled pad at
// an index nobody injected is untouched, so handing the game a
// controller does not blind it to one somebody plugged in.
const merged = this.injected_.size === 0 ? snapshots : [
...snapshots.filter((s) => !this.injected_.has(s.index)),
...this.injected_.values(),
];
for (const p of this.gamepads.values()) p.connected = false;
for (const snap of merged) {
let p = this.gamepads.get(snap.index);
if (!p) {
p = { connected: true, buttons: [], prevButtons: [], axes: [] };
this.gamepads.set(snap.index, p);
}
p.prevButtons = p.buttons;
p.buttons = snap.buttons;
p.axes = snap.axes;
p.connected = snap.connected;
}
}
clearFrameState(): void {
clearActionEdges(this);
this.keysPressed.clear();
clearTabModifiers(this);
this.keysReleased.clear();
this.mouseButtonsPressed.clear();
this.mouseButtonsReleased.clear();
this.scrollDeltaX = 0;
this.scrollDeltaY = 0;
this.mouseDeltaX = 0;
this.mouseDeltaY = 0;
this.touchesStarted.clear();
this.touchesEnded.clear();
}
/** Enter a fixed-timestep step: keyboard/mouse edge queries now read the fixed
* mirrors. Called by App before each FixedUpdate step. */
beginFixedStep(): void {
this.fixedContext_ = true;
beginFixedActionEdges(this);
}
/** Leave a fixed step: drop the consumed edges (so a later step this frame
* doesn't see them again) and restore the render context. Edges that arrived
* on a frame with no fixed step are never cleared here, so they survive to the
* next frame's first step instead of being lost. */
endFixedStep(): void {
endFixedActionEdges(this);
this.keysPressedFixed.clear();
this.keysReleasedFixed.clear();
this.mouseButtonsPressedFixed.clear();
this.mouseButtonsReleasedFixed.clear();
this.fixedContext_ = false;
}
}
/**
* This frame's raw input, as a resource. The input plugin writes it before any
* game system runs, and clears the per-frame edges after the last one.
*
* @beta
*/
export const Input = defineResource<InputState>(new InputState(), 'Input');
const executionOwners = new WeakMap<InputState, Set<object>>();
/** Internal, per-owner execution gate for the platform event funnel. */
export function setInputExecutionHeld(state: InputState, owner: object, held: boolean): void {
let owners = executionOwners.get(state);
if (held) {
if (!owners) { owners = new Set(); executionOwners.set(state, owners); }
const wasHeld = owners.size > 0;
owners.add(owner);
if (!wasHeld) inputEventCallbacks(state).onInputCancel?.();
} else {
owners?.delete(owner);
if (!owners?.size) executionOwners.delete(state);
}
}
/**
* The callbacks a platform's raw events arrive through — routed past the UI
* first, then recorded on `state`.
*
* Named and exported because the platform binding is not the only caller that
* should exist. A harness driving a running game has to be able to deliver a
* click, and the only faithful way to do that is through the same funnel the
* real event uses: a synthetic DOM event carries no usable `offsetX`, and
* poking `mouseX` and `mouseButtonsPressed` by hand skips the router, so UI
* that should have swallowed the click never sees it and gameplay behind a
* button reacts to presses the player never made.
*
* One implementation, so the injected event and the real one cannot diverge.
*/
export function inputEventCallbacks(state: InputState): InputEventCallbacks {
const finishTouch = (id: number, consumed: boolean): void => {
if (consumed) state.touches.delete(id);
else if (state.touches.has(id)) state.endTouch(id);
};
return {
onKeyDown(code) {
if (executionOwners.has(state)) return claimsKeyDefault(state, code);
if (inputRouter.dispatchKeyDown(code)) return true;
state.noteKeyDown(code);
return claimsKeyDefault(state, code);
},
onKeyUp(code) {
if (executionOwners.has(state)) return;
if (inputRouter.dispatchKeyUp(code)) {
state.keysDown.delete(code);
discardActionEdges(state, 'key', code);
}
else if (state.keysDown.has(code)) state.noteKeyUp(code);
},
onPointerMove(x, y, dx, dy) {
if (executionOwners.has(state)) return;
// Summed before anything can consume the move: a look that follows the pointer is not a click UI should swallow.
if (dx !== undefined && dy !== undefined && Number.isFinite(dx) && Number.isFinite(dy)) { state.mouseDeltaX += dx; state.mouseDeltaY += dy; }
// Pointer position tracks the cursor even when consumed so
// gameplay code that reads `getMousePosition()` (e.g. HUD
// cursor rendering) doesn't freeze while the editor is
// dragging a gizmo.
state.mouseX = x;
state.mouseY = y;
inputRouter.dispatchPointerMove(x, y);
},
onPointerDown(button, x, y) {
if (executionOwners.has(state)) return;
state.mouseX = x;
state.mouseY = y;
if (inputRouter.dispatchPointerDown(button, x, y)) return;
state.noteMouseDown(button);
},
onPointerUp(button) {
if (executionOwners.has(state)) return;
if (inputRouter.dispatchPointerUp(button)) {
state.mouseButtons.delete(button);
discardActionEdges(state, 'mouse', button);
if (button === 0) cancelPrimaryPointer(state);
}
else if (state.mouseButtons.has(button)) state.noteMouseUp(button);
},
onWheel(deltaX, deltaY) {
if (executionOwners.has(state)) return;
if (inputRouter.dispatchWheel(deltaX, deltaY)) return;
state.scrollDeltaX += deltaX;
state.scrollDeltaY += deltaY;
},
onTouchStart(id, x, y) {
if (executionOwners.has(state)) return;
// Before the UI: with multi-touch off, a second finger presses nothing.
if (!state.admitTouch(id)) return;
if (inputRouter.dispatchTouchStart(id, x, y)) return;
const point = { id, x, y };
state.touches.set(id, point);
state.touchesStarted.set(id, point);
},
onTouchMove(id, x, y) {
if (executionOwners.has(state)) return;
if (state.touchIgnored(id)) return;
if (inputRouter.dispatchTouchMove(id, x, y)) return;
const existing = state.touches.get(id);
if (existing) {
existing.x = x;
existing.y = y;
}
},
onTouchEnd(id) {
if (executionOwners.has(state)) return;
if (state.touchIgnored(id, true)) return;
finishTouch(id, inputRouter.dispatchTouchEnd(id));
},
onTouchCancel(id, primary) {
if (executionOwners.has(state)) return;
if (state.touchIgnored(id, true)) return;
inputRouter.dispatchTouchCancel(id);
state.touches.delete(id);
state.touchesStarted.delete(id);
state.touchesEnded.delete(id);
if (primary === true || (primary === undefined && state.touches.size === 0)) {
discardActionEdges(state, 'mouse', 0);
state.mouseButtons.delete(0);
state.mouseButtonsPressed.delete(0);
state.mouseButtonsReleased.delete(0);
state.mouseButtonsPressedFixed.delete(0);
state.mouseButtonsReleasedFixed.delete(0);
cancelPrimaryPointer(state);
}
},
onInputCancel() {
inputRouter.resetModifiers();
state.keysDown.clear();
state.mouseButtons.clear();
state.touches.clear();
state.forgetTouches();
state.cancelVirtualSources();
state.clearFrameState();
cancelActionEdges(state);
state.keysPressedFixed.clear();
state.keysReleasedFixed.clear();
state.mouseButtonsPressedFixed.clear();
state.mouseButtonsReleasedFixed.clear();
cancelPrimaryPointer(state);
},
};
}
export class InputPlugin implements Plugin {
name = 'input';
private target_: unknown;
private unbind_: (() => void) | null = null;
private readonly executionCleanup_ = new WeakMap<App, () => void>();
constructor(target?: unknown) {
this.target_ = target ?? null;
}
build(app: App): void {
const state = new InputState();
app.insertResource(Input, state);
const offExecution = app.onExecutionChange(held => setInputExecutionHeld(state, app, held));
this.executionCleanup_.set(app, () => { offExecution(); setInputExecutionHeld(state, app, false); });
state.touchAvailable = getPlatform().hasTouch?.() ?? false;
getPlatform().bindInputEvents(inputEventCallbacks(state), this.target_ ?? undefined);
// Gamepads are polled (no DOM events). Web supplies pollGamepads; platforms
// without it (WeChat, headless) skip gamepad input. Runs in First so the
// freshest pad state is up before any gameplay / action-map system reads it.
const platform = getPlatform();
if (platform.pollGamepads) {
const poll = platform.pollGamepads.bind(platform);
app.addSystemToSchedule(Schedule.First, defineSystem([], () => {
state.updateGamepads(poll());
}, { name: 'GamepadPollSystem' }));
}
app.addSystemToSchedule(Schedule.Last, defineSystem([], () => {
state.clearFrameState();
}, { name: 'InputClearSystem' }));
}
cleanup(app?: App): void {
if (app) { this.executionCleanup_.get(app)?.(); this.executionCleanup_.delete(app); }
platformUnbindInputEvents();
}
}
export const inputPlugin = new InputPlugin();