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(native): the input seam answers the same contract the web does

esengine082b35376672
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index b10a4f85f..9dad66702 100644
--- a/native/CMakeLists.txt
+++ b/native/CMakeLists.txt
@@ -263,6 +263,7 @@ if(ESTELLA_QUICKJS_DIR)
host/bindings/RenderBindings.cpp
host/bindings/AssetBindings.cpp
host/bindings/AudioBindings.cpp
+ host/bindings/InputBindings.cpp
host/bindings/NetBindings.cpp
host/bindings/TextEditorBindings.cpp
host/media/native_audio.cpp
diff --git a/native/host/Bindings.hpp b/native/host/Bindings.hpp
index 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.cpp
index 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.hpp
index 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.cpp
index 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.cpp
new file mode 100644
index 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 eshost
diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.ts
index 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 the
diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.ts
index 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+});