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(engine): the funnel raw input arrives through has a name

yhh2c57a32e2c19
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 821227e97..2b180abe5 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1436 stable · 17 beta · 1 deprecated
+Symbols: 1437 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -9639,6 +9639,11 @@ FsmPlugin
(config: RuntimeInitConfig): Promise<void>
```
+## inputEventCallbacks — function
+```
+(state: InputState): InputEventCallbacks
+```
+
## inputPlugin — const
```
InputPlugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index efa544126..4e4e190ba 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1455 stable · 22 beta · 1 deprecated
+Symbols: 1456 stable · 22 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -9854,6 +9854,11 @@ FsmPlugin
(config: RuntimeInitConfig): Promise<void>
```
+## inputEventCallbacks — function
+```
+(state: InputState): InputEventCallbacks
+```
+
## inputPlugin — const
```
InputPlugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 1d39d3d4f..4c135a541 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1435 stable · 19 beta · 1 deprecated
+Symbols: 1436 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9634,6 +9634,11 @@ FsmPlugin
(config: RuntimeInitConfig): Promise<void>
```
+## inputEventCallbacks — function
+```
+(state: InputState): InputEventCallbacks
+```
+
## inputPlugin — const
```
InputPlugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 6915cd1ed..281b406cf 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1456 stable · 17 beta · 1 deprecated
+Symbols: 1457 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9889,6 +9889,11 @@ FsmPlugin
(config: RuntimeInitConfig): Promise<void>
```
+## inputEventCallbacks — function
+```
+(state: InputState): InputEventCallbacks
+```
+
## inputPlugin — const
```
InputPlugin
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 4c1fbe787..45708c421 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1446 stable · 17 beta · 1 deprecated
+Symbols: 1447 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -9666,6 +9666,11 @@ FsmPlugin
(config: WeChatRuntimeConfig): Promise<void>
```
+## inputEventCallbacks — function
+```
+(state: InputState): InputEventCallbacks
+```
+
## inputPlugin — const
```
InputPlugin
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index cdbd532a4..fdf98a865 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -206,6 +206,7 @@ export {
InputState,
InputPlugin,
inputPlugin,
+ inputEventCallbacks,
GamepadButton,
GamepadAxis,
type TouchPoint,
diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.ts
index eebb51aa8..16b718fd2 100644
--- a/sdk/src/input/input.ts
+++ b/sdk/src/input/input.ts
@@ -4,7 +4,7 @@ import { defineResource } from '../ecs/resource';
import { defineSystem, Schedule } from '../ecs/system';
import type { App, Plugin } from '../app/app';
import { getPlatform, platformUnbindInputEvents } from '../platform';
-import type { GamepadSnapshot } from '../platform/types';
+import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';
import { inputRouter } from './inputRouter';
export interface TouchPoint {
@@ -280,6 +280,83 @@ export class InputState {
export const Input = defineResource<InputState>(new InputState(), 'Input');
+/**
+ * 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 {
+ return {
+ onKeyDown(code) {
+ if (inputRouter.dispatchKeyDown(code)) return;
+ state.noteKeyDown(code);
+ },
+ onKeyUp(code) {
+ if (inputRouter.dispatchKeyUp(code)) return;
+ state.noteKeyUp(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.noteMouseDown(button);
+ },
+ onPointerUp(button) {
+ if (inputRouter.dispatchPointerUp(button)) return;
+ state.noteMouseUp(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;
+ existing.y = y;
+ } else {
+ state.touches.set(id, { id, x, y });
+ }
+ },
+ 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);
+ },
+ };
+}
+
export class InputPlugin implements Plugin {
name = 'input';
private target_: unknown;
@@ -293,66 +370,7 @@ export class InputPlugin implements Plugin {
const state = new InputState();
app.insertResource(Input, state);
- getPlatform().bindInputEvents({
- onKeyDown(code) {
- if (inputRouter.dispatchKeyDown(code)) return;
- state.noteKeyDown(code);
- },
- onKeyUp(code) {
- if (inputRouter.dispatchKeyUp(code)) return;
- state.noteKeyUp(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.noteMouseDown(button);
- },
- onPointerUp(button) {
- if (inputRouter.dispatchPointerUp(button)) return;
- state.noteMouseUp(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;
- existing.y = y;
- } else {
- state.touches.set(id, { id, x, y });
- }
- },
- 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);
- },
- }, this.target_ ?? undefined);
+ 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
diff --git a/sdk/tests/input-callbacks.test.ts b/sdk/tests/input-callbacks.test.ts
new file mode 100644
index 000000000..dfb11f237
--- /dev/null
+++ b/sdk/tests/input-callbacks.test.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file input-callbacks.test.ts
+ * @brief The funnel every raw event arrives through, as one exported thing.
+ *
+ * It is exported because the platform binding is not the only caller
+ * that should exist: a harness driving a running game has to deliver a
+ * click, and doing it any other way is not the same event. A synthetic
+ * DOM event carries no usable offsetX; writing `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.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InputState, inputEventCallbacks } from '../src/input/input';
+import { inputRouter } from '../src/input/inputRouter';
+
+describe('inputEventCallbacks', () => {
+ let state: InputState;
+ beforeEach(() => {
+ state = new InputState();
+ inputRouter.setUIHandler(null);
+ inputRouter.setEditorHandler(null);
+ });
+
+ it('records a pointer press the way a real event does', () => {
+ const cb = inputEventCallbacks(state);
+ cb.onPointerDown?.(0, 120, 45);
+ expect(state.mouseX).toBe(120);
+ expect(state.mouseY).toBe(45);
+ expect(state.isMouseButtonDown(0)).toBe(true);
+ expect(state.isMouseButtonPressed(0)).toBe(true);
+ cb.onPointerUp?.(0);
+ expect(state.isMouseButtonDown(0)).toBe(false);
+ expect(state.isMouseButtonReleased(0)).toBe(true);
+ });
+
+ it('tracks the cursor on a move without pressing anything', () => {
+ const cb = inputEventCallbacks(state);
+ cb.onPointerMove?.(7, 9);
+ expect(state.getMousePosition()).toEqual({ x: 7, y: 9 });
+ expect(state.isMouseButtonDown(0)).toBe(false);
+ });
+
+ it('records keys, wheel and touches through the same funnel', () => {
+ const cb = inputEventCallbacks(state);
+ cb.onKeyDown?.('ArrowRight');
+ expect(state.isKeyDown('ArrowRight')).toBe(true);
+ expect(state.isKeyPressed('ArrowRight')).toBe(true);
+ cb.onKeyUp?.('ArrowRight');
+ expect(state.isKeyDown('ArrowRight')).toBe(false);
+
+ cb.onWheel?.(3, -4);
+ expect(state.getScrollDelta()).toEqual({ x: 3, y: -4 });
+
+ cb.onTouchStart?.(1, 50, 60);
+ expect(state.getTouchCount()).toBe(1);
+ expect(state.getTouch(1)).toMatchObject({ x: 50, y: 60 });
+ cb.onTouchEnd?.(1);
+ expect(state.getTouchCount()).toBe(0);
+ });
+
+ it('lets the UI router refuse a press before gameplay records it', () => {
+ // The half a hand-written injector skips: a click on a button must not
+ // also reach the board behind it.
+ const handler = {
+ onPointerDown: () => true, // consumed
+ onPointerUp: () => true,
+ };
+ const off = inputRouter.setUIHandler(handler as never);
+ try {
+ const cb = inputEventCallbacks(state);
+ cb.onPointerDown?.(0, 10, 10);
+ // Position still tracks (a HUD cursor must not freeze) but the press
+ // never became a gameplay edge.
+ expect(state.mouseX).toBe(10);
+ expect(state.isMouseButtonDown(0)).toBe(false);
+ expect(state.isMouseButtonPressed(0)).toBe(false);
+ } finally {
+ off();
+ }
+ });
+});