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(input): data-driven .inputmap assets + UI-pointer consumption flag

esengine58acb6fa42b7
diff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.ts
index add67342c..4296a8d77 100644
--- a/sdk/src/assetTypes.ts
+++ b/sdk/src/assetTypes.ts
@@ -36,6 +36,8 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [
{ extensions: ['atlas'], contentType: 'text', editorType: 'spine-atlas', addressableType: 'binary', wechatPackInclude: true, hasTransitiveDeps: true },
{ extensions: ['skel'], contentType: 'binary', editorType: 'spine-skeleton', addressableType: 'spine', wechatPackInclude: true, hasTransitiveDeps: true },
{ extensions: ['json'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: false, hasTransitiveDeps: false },
+ // Input map (defineInputMap / loadInputMapAsset) — data-driven key/gamepad bindings.
+ { extensions: ['inputmap'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },
{ extensions: ['bmfont'], contentType: 'json', editorType: 'bitmap-font', addressableType: 'bitmap-font', wechatPackInclude: true, hasTransitiveDeps: true },
{ extensions: ['fnt'], contentType: 'text', editorType: 'bitmap-font', addressableType: 'bitmap-font', wechatPackInclude: true, hasTransitiveDeps: true },
{ extensions: ['esprefab'], contentType: 'json', editorType: 'prefab', addressableType: 'prefab', wechatPackInclude: true, hasTransitiveDeps: true },
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 7905ce499..b2cbfc6f9 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -186,6 +186,7 @@ export { GestureDetector, type SwipeDirection } from './gesture';
export {
defineInputMap,
+ loadInputMapAsset,
InputMap,
Key,
MouseButton,
@@ -200,6 +201,7 @@ export {
type Binding,
type ActionDef,
type ActionType,
+ type InputMapAsset,
type ListenOptions,
} from './inputMap';
diff --git a/sdk/src/input.ts b/sdk/src/input.ts
index f0c0fd804..0c52eb68f 100644
--- a/sdk/src/input.ts
+++ b/sdk/src/input.ts
@@ -174,6 +174,16 @@ export class InputState {
return p?.connected ? p : undefined;
}
+ /** True when the pointer is over an interactive UI element this frame (set each
+ * frame by the UI interaction system). Gameplay checks this to ignore input
+ * the UI handled — e.g. don't fire a weapon when clicking a HUD button.
+ * Unity's `EventSystem.IsPointerOverGameObject()` analog. */
+ pointerOverUI = false;
+
+ isPointerOverUI(): boolean {
+ return this.pointerOverUI;
+ }
+
/** Ingest this frame's snapshots: shift current→prev (edge detection) then
* store new values. Pads absent from `snapshots` are marked disconnected. */
updateGamepads(snapshots: GamepadSnapshot[]): void {
diff --git a/sdk/src/inputMap.ts b/sdk/src/inputMap.ts
index c8530d5ee..760ab2628 100644
--- a/sdk/src/inputMap.ts
+++ b/sdk/src/inputMap.ts
@@ -37,6 +37,15 @@ export interface ActionDef {
bindings: Binding[];
}
+/** The serialized form of a whole map — the content of an `.inputmap` asset.
+ * Data-driven input: author/ship this JSON, then {@link loadInputMapAsset}. */
+export interface InputMapAsset {
+ version: number;
+ actions: Record<string, ActionDef>;
+}
+
+const INPUT_MAP_ASSET_VERSION = 1;
+
// — Binding constructors (Capitalized, matching the engine DSL: Query/Mut/With) —
export const Key = (code: string): Binding => ({ kind: 'key', code });
export const MouseButton = (button: number): Binding => ({ kind: 'mouse', button });
@@ -188,6 +197,16 @@ export class InputMap {
for (const [name, def] of this.defs_) out[name] = def.bindings.map((b) => ({ ...b }));
return out;
}
+
+ /** Serialize the FULL map (action types + bindings) — an `.inputmap` asset's
+ * content. (vs {@link toJSON}, which is bindings-only for rebind persistence.) */
+ toAsset(): InputMapAsset {
+ const actions: Record<string, ActionDef> = {};
+ for (const [name, def] of this.defs_) {
+ actions[name] = { type: def.type, bindings: def.bindings.map((b) => ({ ...b })) };
+ }
+ return { version: INPUT_MAP_ASSET_VERSION, actions };
+ }
/** Override bindings for actions that EXIST in this map (unknown names ignored,
* so stale saved data for a removed action never resurrects it). */
loadJSON(data: Record<string, Binding[]>): void {
@@ -278,3 +297,12 @@ export function defineInputMap(actions: Record<string, ActionDef>): InputMap {
);
return map;
}
+
+/**
+ * Build a live InputMap from a loaded `.inputmap` asset (data-driven input —
+ * fetch / import the JSON, then call this). Registers the evaluation system, same
+ * as {@link defineInputMap}.
+ */
+export function loadInputMapAsset(asset: InputMapAsset): InputMap {
+ return defineInputMap(asset.actions);
+}
diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.ts
index 415514ec7..bf1d72afb 100644
--- a/sdk/src/ui/input/interaction.ts
+++ b/sdk/src/ui/input/interaction.ts
@@ -84,7 +84,7 @@ export class UIInteractionPlugin implements Plugin {
}
}
- if (!camera.valid) return;
+ if (!camera.valid) { input.pointerOverUI = false; return; }
const dpr = platformDevicePixelRatio();
const mouseGLX = input.mouseX * dpr;
@@ -129,6 +129,9 @@ export class UIInteractionPlugin implements Plugin {
hoveredEntity = null;
}
+ // Gameplay reads this (Update) to skip input the UI claimed.
+ input.pointerOverUI = hitEntity !== null;
+
if (hoveredEntity !== hitEntity) {
if (hoveredEntity !== null && world.valid(hoveredEntity) && world.has(hoveredEntity, UIInteraction)) {
const prev = world.get(hoveredEntity, UIInteraction) as UIInteractionData;
diff --git a/sdk/tests/input-map-asset.test.ts b/sdk/tests/input-map-asset.test.ts
new file mode 100644
index 000000000..cdbfe4f14
--- /dev/null
+++ b/sdk/tests/input-map-asset.test.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InputState } from '../src/input';
+import { defineInputMap, loadInputMapAsset, Axis2D, Button, Keys2D, Key } from '../src/inputMap';
+import { AppContext, setDefaultContext } from '../src/context';
+
+beforeEach(() => setDefaultContext(new AppContext()));
+
+describe('.inputmap asset (data-driven input)', () => {
+ it('round-trips through toAsset → JSON → loadInputMapAsset, preserving action types', () => {
+ const Game = defineInputMap({
+ Move: Axis2D(Keys2D('KeyW', 'KeyS', 'KeyA', 'KeyD')),
+ Jump: Button(Key('Space')),
+ });
+
+ const asset = Game.toAsset();
+ expect(asset.version).toBe(1);
+ expect(asset.actions.Move.type).toBe('axis2d');
+ expect(asset.actions.Jump.type).toBe('button');
+
+ // The on-disk .inputmap shape, reloaded into a live map.
+ const loaded = loadInputMapAsset(JSON.parse(JSON.stringify(asset)));
+
+ const input = new InputState();
+ input.keysDown.add('Space');
+ input.keysDown.add('KeyD');
+ loaded.evaluate(input);
+ expect(loaded.down('Jump')).toBe(true);
+ expect(loaded.axis2d('Move').x).toBeCloseTo(1); // KeyD → +x
+ });
+
+ it('exposes pointerOverUI for gameplay to gate on (UI-claimed input)', () => {
+ const s = new InputState();
+ expect(s.isPointerOverUI()).toBe(false);
+ s.pointerOverUI = true; // set each frame by the UI interaction system
+ expect(s.isPointerOverUI()).toBe(true);
+ });
+});