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
/**
* @file inputRouter.ts
* @brief Chain-of-responsibility input routing (editor → UI → game)
*
* The platform layer delivers raw events (key, pointer, wheel, touch) into
* the SDK. Before those events land in the `InputState` that gameplay code
* polls, they pass through the router's tier-1 (editor) and tier-2 (UI)
* handlers. Either tier can return `true` from a callback to consume the
* event; consumed events do not propagate to later tiers. Consumed releases
* silently clear previously held gameplay state without adding release edges.
*
* Tier-3 (game) is implicit — it is the InputState resource itself. Code
* that calls `state.isKeyDown(...)` / `state.isMouseButtonDown(...)` sees
* only events that no upstream handler claimed.
*
* Chain-of-responsibility (rather than a boolean editor-is-active flag)
* lets a tool consume only the events it actually cares about: a marquee
* drag claims mouse-move while pressed but lets wheel scroll through to
* the viewport camera; a modal dialog consumes Escape but ignores the
* arrow keys.
*/
// =============================================================================
// Types
// =============================================================================
export interface Modifiers {
readonly shift: boolean;
readonly ctrl: boolean;
readonly alt: boolean;
readonly meta: boolean;
}
const NO_MODS: Modifiers = Object.freeze({ shift: false, ctrl: false, alt: false, meta: false });
/**
* An input handler. All methods are optional; return `true` to consume an
* event (stops propagation to later tiers and to InputState), `false` /
* `void` to let it fall through.
*/
export interface InputHandler {
onKeyDown?(code: string, mods: Modifiers): boolean | void;
onKeyUp?(code: string, mods: Modifiers): boolean | void;
onPointerMove?(x: number, y: number, mods: Modifiers): boolean | void;
onPointerDown?(button: number, x: number, y: number, mods: Modifiers): boolean | void;
onPointerUp?(button: number, mods: Modifiers): boolean | void;
onWheel?(deltaX: number, deltaY: number, mods: Modifiers): boolean | void;
onTouchStart?(id: number, x: number, y: number): boolean | void;
onTouchMove?(id: number, x: number, y: number): boolean | void;
onTouchEnd?(id: number): boolean | void;
onTouchCancel?(id: number): boolean | void;
}
// =============================================================================
// Router
// =============================================================================
export class InputRouter {
private editorHandler_: InputHandler | null = null;
private uiHandler_: InputHandler | null = null;
private mods_: Modifiers = NO_MODS;
/** Registers the editor-tier handler and returns an unregister thunk. */
setEditorHandler(handler: InputHandler | null): () => void {
this.editorHandler_ = handler;
return () => {
if (this.editorHandler_ === handler) this.editorHandler_ = null;
};
}
/** Registers the UI-tier handler and returns an unregister thunk. */
setUIHandler(handler: InputHandler | null): () => void {
this.uiHandler_ = handler;
return () => {
if (this.uiHandler_ === handler) this.uiHandler_ = null;
};
}
get currentMods(): Modifiers {
return this.mods_;
}
/** Clear cancelled key chords without delivering input to handlers. */
resetModifiers(): void { this.mods_ = NO_MODS; }
// ── Dispatch (called by InputPlugin) ────────────────────────────────
dispatchKeyDown(code: string): boolean {
this.updateModsFromKey(code, true);
return (
invokeBool(asHandlerFn(this.editorHandler_?.onKeyDown), this.editorHandler_, code, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onKeyDown), this.uiHandler_, code, this.mods_)
);
}
dispatchKeyUp(code: string): boolean {
const consumed =
invokeBool(asHandlerFn(this.editorHandler_?.onKeyUp), this.editorHandler_, code, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onKeyUp), this.uiHandler_, code, this.mods_);
// Update mods AFTER dispatch so handlers see the modifier as still-held
// on the key-up edge that released it — matches DOM `event.shiftKey`
// semantics for keyup events.
this.updateModsFromKey(code, false);
return consumed;
}
dispatchPointerMove(x: number, y: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onPointerMove), this.editorHandler_, x, y, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onPointerMove), this.uiHandler_, x, y, this.mods_)
);
}
dispatchPointerDown(button: number, x: number, y: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onPointerDown), this.editorHandler_, button, x, y, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onPointerDown), this.uiHandler_, button, x, y, this.mods_)
);
}
dispatchPointerUp(button: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onPointerUp), this.editorHandler_, button, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onPointerUp), this.uiHandler_, button, this.mods_)
);
}
dispatchWheel(deltaX: number, deltaY: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onWheel), this.editorHandler_, deltaX, deltaY, this.mods_) ||
invokeBool(asHandlerFn(this.uiHandler_?.onWheel), this.uiHandler_, deltaX, deltaY, this.mods_)
);
}
dispatchTouchStart(id: number, x: number, y: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onTouchStart), this.editorHandler_, id, x, y) ||
invokeBool(asHandlerFn(this.uiHandler_?.onTouchStart), this.uiHandler_, id, x, y)
);
}
dispatchTouchMove(id: number, x: number, y: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onTouchMove), this.editorHandler_, id, x, y) ||
invokeBool(asHandlerFn(this.uiHandler_?.onTouchMove), this.uiHandler_, id, x, y)
);
}
dispatchTouchEnd(id: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onTouchEnd), this.editorHandler_, id) ||
invokeBool(asHandlerFn(this.uiHandler_?.onTouchEnd), this.uiHandler_, id)
);
}
dispatchTouchCancel(id: number): boolean {
return (
invokeBool(asHandlerFn(this.editorHandler_?.onTouchCancel), this.editorHandler_, id) ||
invokeBool(asHandlerFn(this.uiHandler_?.onTouchCancel), this.uiHandler_, id)
);
}
// ── Internal ────────────────────────────────────────────────────────
private updateModsFromKey(code: string, pressed: boolean): void {
let { shift, ctrl, alt, meta } = this.mods_;
if (code === 'ShiftLeft' || code === 'ShiftRight') shift = pressed;
else if (code === 'ControlLeft' || code === 'ControlRight') ctrl = pressed;
else if (code === 'AltLeft' || code === 'AltRight') alt = pressed;
else if (code === 'MetaLeft' || code === 'MetaRight' || code === 'OSLeft' || code === 'OSRight')
meta = pressed;
else return;
this.mods_ = { shift, ctrl, alt, meta };
}
}
// A module-level singleton parallels the existing `inputPlugin` singleton:
// editors attach their handler once at startup regardless of how many Apps
// may exist. Tests that need isolation can construct their own InputRouter.
export const inputRouter = new InputRouter();
// =============================================================================
// Helpers
// =============================================================================
// Invoke a handler callback with the supplied args. Returns true iff the
// handler explicitly returned `true` (the "I consumed it" signal). A
// handler that returns undefined / false / throws is treated as not
// consuming — broken handlers should not stop dispatch.
function invokeBool(
fn: ((...args: unknown[]) => boolean | void) | undefined,
thisArg: unknown,
...args: unknown[]
): boolean {
if (typeof fn !== 'function') return false;
try {
return fn.apply(thisArg, args) === true;
} catch {
return false;
}
}
// Cast helper — each InputHandler method has its own concrete signature,
// but from the dispatch loop we treat them uniformly. The type system
// can't infer this across heterogeneous methods, so we cast at the call
// site. The cast is safe because the method's own parameters line up
// with the args we pass.
type HandlerFn = ((...args: unknown[]) => boolean | void) | undefined;
function asHandlerFn(fn: unknown): HandlerFn {
return fn as HandlerFn;
}