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(native): the input seam answers the same contract the web does
esengine082b35376672
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex b10a4f85f..9dad66702 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -263,6 +263,7 @@ if(ESTELLA_QUICKJS_DIR)host/bindings/RenderBindings.cpphost/bindings/AssetBindings.cpphost/bindings/AudioBindings.cpp+ host/bindings/InputBindings.cpphost/bindings/NetBindings.cpphost/bindings/TextEditorBindings.cpphost/media/native_audio.cppdiff --git a/native/host/Bindings.hpp b/native/host/Bindings.hppindex 86b35b246..6b299d73e 100644--- a/native/host/Bindings.hpp+++ b/native/host/Bindings.hpp@@ -48,6 +48,10 @@ void registerAssetBindings(HostState& h, JSValue global);* the SDK's hasAudioBindings() gates the native backend on real availability. */void registerAudioBindings(HostState& h, JSValue global);+/** es_pollGamepads — the one half of input the engine pulls rather than is+ * pushed; see InputBindings.cpp. */+void registerInputBindings(HostState& h, JSValue global);+/** es_fetch over the platform's native networking. */void registerNetBindings(HostState& h, JSValue global);diff --git a/native/host/Host.cpp b/native/host/Host.cppindex 2fa8c4c4c..43115df97 100644--- a/native/host/Host.cpp+++ b/native/host/Host.cpp@@ -355,6 +355,33 @@ void touch(int type, int id, float x, float y) {for (JSValue& v : args) JS_FreeValue(h.js, v);}+void pointer(int type, int button, float x, float y) {+ if (!booted()) return;+ HostState& h = host();+ JSValue args[4] = {+ JS_NewInt32(h.js, type), JS_NewInt32(h.js, button),+ JS_NewFloat64(h.js, x), JS_NewFloat64(h.js, y),+ };+ callJs(h, "es_onNativePointer", 4, args);+ for (JSValue& v : args) JS_FreeValue(h.js, v);+}++void wheel(float dx, float dy) {+ if (!booted()) return;+ HostState& h = host();+ JSValue args[2] = {JS_NewFloat64(h.js, dx), JS_NewFloat64(h.js, dy)};+ callJs(h, "es_onNativeWheel", 2, args);+ for (JSValue& v : args) JS_FreeValue(h.js, v);+}++void key(bool down, const char* code) {+ if (!booted() || !code || !code[0]) return;+ HostState& h = host();+ JSValue args[2] = {JS_NewBool(h.js, down), JS_NewString(h.js, code)};+ callJs(h, "es_onNativeKey", 2, args);+ for (JSValue& v : args) JS_FreeValue(h.js, v);+}+// The app went to background (visible=false) or returned. Suspend/resume the// audio device at the native layer — correct even while the JS tick is paused —// then push the signal to JS, where the Lifecycle plugin auto-pauses the game.diff --git a/native/host/Host.hpp b/native/host/Host.hppindex 891b87a94..aa2c48a0c 100644--- a/native/host/Host.hpp+++ b/native/host/Host.hpp@@ -82,6 +82,17 @@ struct FontFile {bool syntheticItalic = false;};+/** One gamepad in the W3C "standard mapping" layout, as GamepadSnapshot carries+ * it — a second layout would make a game's button indices mean different buttons+ * per platform. `buttons` is indexed by GamepadButton and analog in [0,1]; `axes`+ * by GamepadAxis, signed in [-1,1]. */+struct GamepadState {+ int index = 0;+ bool connected = false;+ float buttons[17]{};+ float axes[4]{};+};+/*** @brief The platform seam: what the host needs that Android and iOS answer* differently. The glue implements it; host_core owns everything else.@@ -176,6 +187,14 @@ struct Platform {* The surface OWNS the value and the selection while a field is focused —* an IME composes into it, and the app's own edits go through `write`.*/+ /**+ * The gamepads this platform can see, appended to @p out.+ *+ * POLLED, matching navigator.getGamepads(): a pad has no events, only a state+ * each frame. The default answers none — a phone's honest report.+ */+ virtual void pollGamepads(std::vector<GamepadState>& out) { out.clear(); }+virtual bool hasTextEditor() const { return false; }virtual void textEditorFocus(const std::string& /*value*/, int /*selectionStart*/,int /*selectionEnd*/, bool /*multiline*/,@@ -223,6 +242,22 @@ void frame();* Coordinates are in surface pixels, top-left origin (as on the web). */void touch(int type, int id, float x, float y);+/** @brief Feeds one mouse/pen event. @p type: 0 down / 1 move / 2 up; @p button+ * in the DOM order (0 left, 1 middle, 2 right); coordinates as for touch.+ *+ * Distinct from {@link touch} because it is distinct on the web: a touch+ * synthesizes the primary pointer, a mouse IS one and carries a button. */+void pointer(int type, int button, float x, float y);++/** @brief Feeds one wheel event, in PIXELS — the DOM `deltaMode: 0` contract, and+ * positive-down like it, so a game scrolls the same way everywhere. */+void wheel(float dx, float dy);++/** @brief Feeds one key transition. @p code is the DOM `KeyboardEvent.code` (the+ * physical key: "KeyW", "Space", "ArrowLeft"), which is what the SDK's+ * input maps are written against. */+void key(bool down, const char* code);+/** @brief The app went to background (@p visible false) or returned to foreground.* Suspends/resumes the audio device natively and pushes the signal to JS,* where the Lifecycle plugin auto-pauses the game. No-op before boot. */diff --git a/native/host/Runtime.cpp b/native/host/Runtime.cppindex e080a5aa3..a93c25b41 100644--- a/native/host/Runtime.cpp+++ b/native/host/Runtime.cpp@@ -417,6 +417,7 @@ void initRuntime(HostState& h) {registerRenderBindings(h, global);registerAssetBindings(h, global);registerAudioBindings(h, global);+ registerInputBindings(h, global);registerNetBindings(h, global);registerTextEditorBindings(h, global);diff --git a/native/host/bindings/InputBindings.cpp b/native/host/bindings/InputBindings.cppnew file mode 100644index 000000000..418671d09--- /dev/null+++ b/native/host/bindings/InputBindings.cpp@@ -0,0 +1,60 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file InputBindings.cpp+ * @brief `es_pollGamepads` — the one half of input the engine PULLS.+ * @details Everything else about input is pushed by the platform's event loop+ * (es_onNativeTouch / Pointer / Wheel / Key, see Host.hpp). A gamepad+ * has no events, only a state per frame, so it is polled exactly as+ * navigator.getGamepads() is on the web.+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the Apache License, Version 2.0.+ */+#include <vector>++#include "Bindings.hpp"+#include "Host.hpp"++namespace eshost {+namespace {++JSValue floatArray(JSContext* ctx, const float* values, int count) {+ JSValue arr = JS_NewArray(ctx);+ for (int i = 0; i < count; ++i) {+ JS_SetPropertyUint32(ctx, arr, (uint32_t)i, JS_NewFloat64(ctx, values[i]));+ }+ return arr;+}++// es_pollGamepads() -> [{ index, connected, buttons[], axes[] }]. `mapping` is+// added by the adapter, which is where the claim that this IS the standard+// layout belongs.+JSValue js_pollGamepads(JSContext* ctx, JSValueConst, int, JSValueConst*) {+ JSValue arr = JS_NewArray(ctx);+ if (!hostAlive() || !host().platform) return arr;++ std::vector<GamepadState> pads;+ host().platform->pollGamepads(pads);+ uint32_t n = 0;+ for (const GamepadState& pad : pads) {+ JSValue o = JS_NewObject(ctx);+ JS_SetPropertyStr(ctx, o, "index", JS_NewInt32(ctx, pad.index));+ JS_SetPropertyStr(ctx, o, "connected", JS_NewBool(ctx, pad.connected));+ JS_SetPropertyStr(ctx, o, "buttons", floatArray(ctx, pad.buttons, 17));+ JS_SetPropertyStr(ctx, o, "axes", floatArray(ctx, pad.axes, 4));+ JS_SetPropertyUint32(ctx, arr, n++, o);+ }+ return arr;+}++} // namespace++void registerInputBindings(HostState& h, JSValue global) {+ bindGlobal(h, global, "es_pollGamepads", js_pollGamepads, 0);+}++} // namespace eshostdiff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 388c9e083..c922d262e 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -20,6 +20,7 @@ import type {PlatformResponse,WasmInstantiateResult,InputEventCallbacks,+ GamepadSnapshot,ImageLoadResult,PlatformCanvas,PlatformImage,@@ -147,6 +148,13 @@ export class NativePlatformAdapter implements PlatformAdapter {onTouchMove: (id, x, y) => pointer.move(id, x, y),onTouchEnd: (id) => pointer.end(id),onTouchCancel: (id) => pointer.cancel(id),+ // Straight through, NOT via createPrimaryPointer: a mouse already is+ // the pointer and carries a button, and routing it through the touch+ // synthesizer would drop every button but the first.+ onPointerDown: (button, x, y) => callbacks.onPointerDown(button, x, y),+ onPointerMove: (x, y) => callbacks.onPointerMove(x, y),+ onPointerUp: (button) => callbacks.onPointerUp(button),+ onWheel: (dx, dy) => callbacks.onWheel(dx, dy),onKeyDown: (code) => callbacks.onKeyDown(code),onKeyUp: (code) => callbacks.onKeyUp(code),};@@ -224,8 +232,13 @@ export class NativePlatformAdapter implements PlatformAdapter {return new WasmVideoBackend(ctx);}- // createSocket / pollGamepads / loadSubpackage are optional and deferred to- // the shell.+ /** Whatever the shell can see; none where it reports nothing, which is the+ * same empty list a browser without navigator.getGamepads() gives. */+ pollGamepads(): GamepadSnapshot[] {+ return this.bridge_.pollGamepads?.() ?? [];+ }++ // createSocket / loadSubpackage are optional and deferred to the shell.}/** Install a {@link NativePlatformAdapter} built from the host `bridge` as thediff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex 0a5493e69..31273a200 100644--- a/sdk/src/platform/native/bridge.ts+++ b/sdk/src/platform/native/bridge.ts@@ -18,7 +18,9 @@* shell (boot spike → full host) lands. Public via the `esengine/native` entry.*/-import type { ImageLoadResult, PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions } from '../types';+import type {+ GamepadSnapshot, ImageLoadResult, PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions,+} from '../types';/*** A single fetch result from the native http stack. The adapter wraps it into a@@ -45,8 +47,19 @@ export interface NativeInputListener {onTouchMove(id: number, x: number, y: number): void;onTouchEnd(id: number): void;onTouchCancel(id: number): void;- onKeyDown?(code: string): void;- onKeyUp?(code: string): void;+ /** A mouse or pen — separate from touch because it is separate on the web:+ * a touch synthesizes the primary pointer, a mouse IS one and has a button+ * (DOM order: 0 left, 1 middle, 2 right). */+ onPointerDown(button: number, x: number, y: number): void;+ onPointerMove(x: number, y: number): void;+ onPointerUp(button: number): void;+ /** Wheel delta in PIXELS, positive-down (the DOM `deltaMode: 0` contract). */+ onWheel(deltaX: number, deltaY: number): void;+ /** The DOM `KeyboardEvent.code` — the physical key, which is what the SDK's+ * input maps are written against. NOT optional: it was, and the entry point+ * that would have fed it was never written, so no native key ever arrived. */+ onKeyDown(code: string): void;+ onKeyUp(code: string): void;}/** What the OS editing surface reports back. `state` carries the surface's whole@@ -167,6 +180,11 @@ export interface NativeBridge {/** Register the engine's input sink; returns an unsubscribe. */registerInput(listener: NativeInputListener): () => void;+ /** The gamepads the shell can see, this frame. Polled rather than pushed,+ * matching navigator.getGamepads(): a pad has a state, not events. Absent on+ * a shell with no pads to report (a phone). */+ pollGamepads?(): GamepadSnapshot[];+devicePixelRatio(): number;/** High-resolution clock. Optional — falls back to `Date.now()`. */now?(): number;diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.tsindex a1d2ca940..c229ffeda 100644--- a/sdk/src/platform/native/hostBridge.ts+++ b/sdk/src/platform/native/hostBridge.ts@@ -26,6 +26,10 @@ const TOUCH_START = 0;const TOUCH_MOVE = 1;const TOUCH_END = 2;+/** Pointer phases, same convention: a mouse has no cancel. */+const POINTER_DOWN = 0;+const POINTER_MOVE = 1;+/** The `es_*` primitives a native host binds. Required unless marked optional. */export interface NativeHostBindings {/** A packaged file's bytes, or null when it is not in the package. */@@ -58,6 +62,11 @@ export interface NativeHostBindings {/** Screen scale (1 when the host reports surface pixels directly). */es_devicePixelRatio?(): number;+ /** The gamepads this frame, in the W3C standard layout. Absent on a host with+ * no pads to report — a phone, where the SDK sees the same empty list a+ * browser without navigator.getGamepads() gives it. */+ es_pollGamepads?(): { index: number; connected: boolean; buttons: number[]; axes: number[] }[];+/** Perform an HTTP request off the main thread (native TLS stack), calling* back with the reply. Optional — a host without it stays offline (remote* asset groups and hot-update do not resolve). */@@ -138,6 +147,19 @@ export function createHostBridge(else if (type === TOUCH_END) listener.onTouchEnd(id);else listener.onTouchCancel(id);};+ scope.es_onNativePointer = (type: number, button: number, x: number, y: number): void => {+ if (!listener) return;+ if (type === POINTER_DOWN) listener.onPointerDown(button, x, y);+ else if (type === POINTER_MOVE) listener.onPointerMove(x, y);+ else listener.onPointerUp(button);+ };+ scope.es_onNativeWheel = (deltaX: number, deltaY: number): void => {+ listener?.onWheel(deltaX, deltaY);+ };+ scope.es_onNativeKey = (down: boolean, code: string): void => {+ if (!listener) return;+ if (down) listener.onKeyDown(code); else listener.onKeyUp(code);+ };const storage = hostStorage(bindings);const audio = hostAudio(bindings, scope);@@ -177,6 +199,20 @@ export function createHostBridge(return () => { listener = null; };},devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,+ ...(bindings.es_pollGamepads+ // 'standard' is asserted HERE rather than by the host: the layout is+ // this bridge's contract with the SDK, and a host that filled the+ // arrays in that order has already met it.+ ? {+ pollGamepads: () => bindings.es_pollGamepads!().map((pad) => ({+ index: pad.index,+ connected: pad.connected,+ buttons: pad.buttons,+ axes: pad.axes,+ mapping: 'standard',+ })),+ }+ : {}),...(audio ? { audio } : {}),...(textEditor ? { textEditor } : {}),...lifecycle,diff --git a/sdk/tests/input-parity.test.ts b/sdk/tests/input-parity.test.tsnew file mode 100644index 000000000..b9daadbd4--- /dev/null+++ b/sdk/tests/input-parity.test.ts@@ -0,0 +1,172 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+//+/**+ * @file The web and native adapters answer ONE input contract — driven the same+ * way, they must call InputEventCallbacks identically.+ *+ * `NativeInputListener.onKeyDown` was optional and the entry point that would+ * have fed it was never written, so no key ever reached a native game and nothing+ * said so. A per-adapter test would not have caught that: each was+ * self-consistent. Only comparing the two traces makes a missing half visible.+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { webAdapter } from '../src/platform/web';+import { NativePlatformAdapter } from '../src/platform/native';+import { createHostBridge } from '../src/platform/native/hostBridge';+import type { InputEventCallbacks } from '../src/platform/types';++/** One line per callback, so a difference reads as a diff rather than a count. */+type Trace = string[];++function recorder(): { callbacks: InputEventCallbacks; trace: Trace } {+ const trace: Trace = [];+ return {+ trace,+ callbacks: {+ onKeyDown: (code) => trace.push(`keyDown ${code}`),+ onKeyUp: (code) => trace.push(`keyUp ${code}`),+ onPointerMove: (x, y) => trace.push(`pointerMove ${x},${y}`),+ onPointerDown: (b, x, y) => trace.push(`pointerDown ${b} ${x},${y}`),+ onPointerUp: (b) => trace.push(`pointerUp ${b}`),+ onWheel: (dx, dy) => trace.push(`wheel ${dx},${dy}`),+ onTouchStart: (id, x, y) => trace.push(`touchStart ${id} ${x},${y}`),+ onTouchMove: (id, x, y) => trace.push(`touchMove ${id} ${x},${y}`),+ onTouchEnd: (id) => trace.push(`touchEnd ${id}`),+ onTouchCancel: (id) => trace.push(`touchCancel ${id}`),+ },+ };+}++/** The es_* surface the bridge insists on, stubbed to the minimum. */+function hostScope(): Record<string, unknown> {+ return {+ console, setTimeout, clearTimeout, performance, TextDecoder,+ es_readAsset: () => null,+ es_loadImagePixels: () => null,+ };+}++describe('input adapter parity (web vs native)', () => {+ let element: HTMLCanvasElement;++ beforeEach(() => {+ element = document.createElement('canvas');+ element.width = 800;+ element.height = 600;+ document.body.appendChild(element);+ });++ afterEach(() => { element.remove(); });++ /**+ * The same logical actions through each adapter's own idiom: DOM events for+ * the web, the host's es_onNative* entry points for native. Both records must+ * come out identical — that identity IS the contract.+ */+ function driveWeb(): Trace {+ const { callbacks, trace } = recorder();+ const web = webAdapter;+ web.bindInputEvents(callbacks, element);++ // offsetX/offsetY are what the web adapter reads and what a layout would+ // normally compute; there is no layout here, so they are set directly.+ const mouse = (type: string, button: number, x: number, y: number) => {+ const e = new MouseEvent(type, { button, bubbles: true });+ Object.defineProperty(e, 'offsetX', { value: x });+ Object.defineProperty(e, 'offsetY', { value: y });+ return e;+ };+ element.dispatchEvent(mouse('mousedown', 2, 10, 20));+ element.dispatchEvent(mouse('mousemove', 0, 11, 21));+ // mouseup and the keys are bound to the DOCUMENT — a button released off+ // the canvas still ends the drag — so that is where they are dispatched.+ document.dispatchEvent(mouse('mouseup', 2, 0, 0));+ element.dispatchEvent(new WheelEvent('wheel', { deltaX: 0, deltaY: 48, deltaMode: 0 }));+ document.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyW' }));+ document.dispatchEvent(new KeyboardEvent('keyup', { code: 'KeyW' }));++ web.unbindInputEvents();+ return trace;+ }++ function driveNative(): Trace {+ const { callbacks, trace } = recorder();+ const scope = hostScope();+ const bridge = createHostBridge(scope);+ const native = new NativePlatformAdapter(bridge);+ native.bindInputEvents(callbacks);++ type Pointer = (t: number, b: number, x: number, y: number) => void;+ (scope.es_onNativePointer as Pointer)(0, 2, 10, 20);+ (scope.es_onNativePointer as Pointer)(1, 0, 11, 21);+ (scope.es_onNativePointer as Pointer)(2, 2, 0, 0);+ (scope.es_onNativeWheel as (dx: number, dy: number) => void)(0, 48);+ (scope.es_onNativeKey as (down: boolean, code: string) => void)(true, 'KeyW');+ (scope.es_onNativeKey as (down: boolean, code: string) => void)(false, 'KeyW');++ native.unbindInputEvents();+ return trace;+ }++ it('mouse, wheel and keys produce the same callbacks on both', () => {+ const web = driveWeb();+ expect(web).toEqual([+ 'pointerDown 2 10,20',+ 'pointerMove 11,21',+ 'pointerUp 2',+ 'wheel 0,48',+ 'keyDown KeyW',+ 'keyUp KeyW',+ ]);+ expect(driveNative()).toEqual(web);+ });++ it('a native mouse does NOT go through the touch pointer synthesizer', () => {+ // Routing it there is the obvious shortcut and it silently drops every+ // button but the left one, because the synthesizer reports pointer 0.+ const { callbacks, trace } = recorder();+ const scope = hostScope();+ const native = new NativePlatformAdapter(createHostBridge(scope));+ native.bindInputEvents(callbacks);++ (scope.es_onNativePointer as (t: number, b: number, x: number, y: number) => void)(0, 1, 5, 6);+ expect(trace).toEqual(['pointerDown 1 5,6']);+ expect(trace.some((line) => line.startsWith('touch'))).toBe(false);+ });++ it('touch still synthesizes the primary pointer, as it does on the web', () => {+ const { callbacks, trace } = recorder();+ const scope = hostScope();+ const native = new NativePlatformAdapter(createHostBridge(scope));+ native.bindInputEvents(callbacks);++ type Touch = (t: number, id: number, x: number, y: number) => void;+ (scope.es_onNativeTouch as Touch)(0, 7, 30, 40);+ (scope.es_onNativeTouch as Touch)(1, 7, 31, 41);+ (scope.es_onNativeTouch as Touch)(2, 7, 0, 0);+ expect(trace).toEqual([+ 'touchStart 7 30,40',+ 'pointerDown 0 30,40',+ 'touchMove 7 31,41',+ 'pointerMove 31,41',+ 'touchEnd 7',+ 'pointerUp 0',+ ]);+ });++ it('gamepads read as the standard mapping, or as none', () => {+ const scope = hostScope();+ expect(new NativePlatformAdapter(createHostBridge(scope)).pollGamepads()).toEqual([]);++ scope.es_pollGamepads = () => [{+ index: 0, connected: true,+ buttons: new Array(17).fill(0), axes: [0, 0, 0, 0],+ }];+ const pads = new NativePlatformAdapter(createHostBridge(scope)).pollGamepads();+ expect(pads).toHaveLength(1);+ expect(pads[0].mapping).toBe('standard');+ expect(pads[0].buttons).toHaveLength(17);+ expect(pads[0].axes).toHaveLength(4);+ });+});