Skip to content

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.

feat(sdk): InputRouter — chain-of-responsibility event routing

esenginecbf42f2391a2
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 3a20ebe63..a4aad43ab 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -159,6 +159,13 @@ export {
type TouchPoint,
} from './input';
+export {
+ InputRouter,
+ inputRouter,
+ type InputHandler,
+ type Modifiers,
+} from './inputRouter';
+
export { GestureDetector, type SwipeDirection } from './gesture';
// =============================================================================
diff --git a/sdk/src/input.ts b/sdk/src/input.ts
index 30f6e2650..435e879c3 100644
--- a/sdk/src/input.ts
+++ b/sdk/src/input.ts
@@ -2,6 +2,7 @@ import { defineResource } from './resource';
import { defineSystem, Schedule } from './system';
import type { App, Plugin } from './app';
import { getPlatform } from './platform';
+import { inputRouter } from './inputRouter';
export interface TouchPoint {
id: number;
@@ -102,39 +103,51 @@ export class InputPlugin implements Plugin {
getPlatform().bindInputEvents({
onKeyDown(code) {
+ if (inputRouter.dispatchKeyDown(code)) return;
if (!state.keysDown.has(code)) {
state.keysPressed.add(code);
}
state.keysDown.add(code);
},
onKeyUp(code) {
+ if (inputRouter.dispatchKeyUp(code)) return;
state.keysDown.delete(code);
state.keysReleased.add(code);
},
onPointerMove(x, y) {
+ // 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) {
state.mouseX = x;
state.mouseY = y;
+ if (inputRouter.dispatchPointerDown(button, x, y)) return;
state.mouseButtons.add(button);
state.mouseButtonsPressed.add(button);
},
onPointerUp(button) {
+ if (inputRouter.dispatchPointerUp(button)) return;
state.mouseButtons.delete(button);
state.mouseButtonsReleased.add(button);
},
onWheel(deltaX, deltaY) {
+ if (inputRouter.dispatchWheel(deltaX, deltaY)) return;
state.scrollDeltaX += deltaX;
state.scrollDeltaY += deltaY;
},
onTouchStart(id, x, y) {
+ 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 (inputRouter.dispatchTouchMove(id, x, y)) return;
const existing = state.touches.get(id);
if (existing) {
existing.x = x;
@@ -144,10 +157,12 @@ export class InputPlugin implements Plugin {
}
},
onTouchEnd(id) {
+ if (inputRouter.dispatchTouchEnd(id)) return;
state.touches.delete(id);
state.touchesEnded.add(id);
},
onTouchCancel(id) {
+ if (inputRouter.dispatchTouchCancel(id)) return;
state.touches.delete(id);
state.touchesEnded.add(id);
},
diff --git a/sdk/src/inputRouter.ts b/sdk/src/inputRouter.ts
new file mode 100644
index 000000000..e66e406e9
--- /dev/null
+++ b/sdk/src/inputRouter.ts
@@ -0,0 +1,208 @@
+/**
+ * @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 update InputState and do not propagate to
+ * later tiers.
+ *
+ * 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_;
+ }
+
+ // ── 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;
+}