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
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.mdindex 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```InputPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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```InputPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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```InputPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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```InputPlugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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```InputPlugindiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 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.tsindex 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 thediff --git a/sdk/tests/input-callbacks.test.ts b/sdk/tests/input-callbacks.test.tsnew file mode 100644index 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();+ }+ });+});