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(input): the only input a phone has
esengine3b504965dcdd
diff --git a/desktop/scripts/inputScript.mjs b/desktop/scripts/inputScript.mjsindex a9cc05b0b..29ffc751c 100644--- a/desktop/scripts/inputScript.mjs+++ b/desktop/scripts/inputScript.mjs@@ -15,11 +15,17 @@/*** JS source that plays `spec` and then lets the game run on.- * `{ keys?, pointer?, frames?, taps?: [{key, at}], holds?: [{key, from, to}] }`+ * `{ keys?, pointer?, frames?, taps?: [{key, at}], holds?: [{key, from, to}],+ * touches?: [{ from, to, x, y, toX?, toY? }] }`** `keys` hold for the whole run, `taps` press at a frame index, `holds` hold over* a frame range. A playthrough is a sequence, not a posture: "walk there, turn* round, hit it" cannot be said by keys all pressed at frame zero.+ *+ * `touches` are real TouchEvents — what a phone sends and what the web platform+ * binds; a mouse pointer proves nothing about playing with a thumb. Each presses+ * at (x, y) and optionally drags to (toX, toY) over its frame range, in+ * fractions of the surface.*/export function inputScript(spec) {const keys = JSON.stringify(spec.keys ?? []);@@ -28,6 +34,17 @@ export function inputScript(spec) {const taps = JSON.stringify((spec.taps ?? []).map((t) => ({ key: String(t.key), at: Number(t.at) || 0 })),);+ const touches = JSON.stringify(+ (spec.touches ?? []).map((t, i) => ({+ id: i + 1,+ from: Number(t.from) || 0,+ to: Number(t.to ?? frames),+ x: Number(t.x) || 0,+ y: Number(t.y) || 0,+ toX: t.toX === undefined ? Number(t.x) || 0 : Number(t.toX),+ toY: t.toY === undefined ? Number(t.y) || 0 : Number(t.toY),+ })),+ );const holds = JSON.stringify((spec.holds ?? []).map((h) => ({key: String(h.key), from: Number(h.from) || 0, to: Number(h.to ?? frames),@@ -70,14 +87,64 @@ export function inputScript(spec) {for (let i = 0; i < 4; i++) await raf();firePointer('up', pointer.x, pointer.y);}+ let touchBroken = null;+ const fireTouch = (type, id, x, y, live) => {+ if (!canvas || touchBroken) return;+ try {+ const r = canvas.getBoundingClientRect();+ // Real Touch instances: TouchEvent's lists reject plain objects, and a+ // constructor that throws leaves the driver's promise unresolved — the+ // harness hangs rather than failing.+ const make = (t) => new Touch({+ identifier: t.id, target: canvas,+ clientX: r.left + r.width * t.x, clientY: r.top + r.height * t.y,+ pageX: r.left + r.width * t.x, pageY: r.top + r.height * t.y,+ screenX: r.left + r.width * t.x, screenY: r.top + r.height * t.y,+ });+ const changed = [make({ id, x, y })];+ // The full list is every finger still down; the changed list only the+ // ones this event is about. A handler reading the wrong one loses a+ // second finger, so the harness fills both.+ const all = live.map((t) => make(t));+ canvas.dispatchEvent(new TouchEvent(type, {+ bubbles: true, cancelable: true,+ touches: all, targetTouches: all, changedTouches: changed,+ }));+ } catch (e) {+ touchBroken = String(e);+ console.log('[engine] touch events unavailable: ' + touchBroken);+ }+ };+const taps = ${taps};const holds = ${holds};+ const touches = ${touches};+ const live = [];const down = new Set();for (let i = 0; i < ${frames}; i++) {for (const h of holds) {if (h.from === i) { fireKey('keydown', h.key); down.add(h.key); }if (h.to === i && down.has(h.key)) { fireKey('keyup', h.key); down.delete(h.key); }}+ for (const t of touches) {+ if (i === t.from) {+ live.push({ id: t.id, x: t.x, y: t.y });+ fireTouch('touchstart', t.id, t.x, t.y, live);+ } else if (i > t.from && i < t.to) {+ const k = (i - t.from) / Math.max(1, t.to - t.from);+ const at = live.find((l) => l.id === t.id);+ if (at) {+ at.x = t.x + (t.toX - t.x) * k;+ at.y = t.y + (t.toY - t.y) * k;+ fireTouch('touchmove', t.id, at.x, at.y, live);+ }+ } else if (i === t.to) {+ const at = live.find((l) => l.id === t.id);+ const idx = live.indexOf(at);+ if (idx >= 0) live.splice(idx, 1);+ fireTouch('touchend', t.id, at ? at.x : t.toX, at ? at.y : t.toY, live);+ }+ }for (const t of taps) {if (t.at !== i) continue;fireKey('keydown', t.key);@@ -91,7 +158,7 @@ export function inputScript(spec) {for (const k of down) fireKey('keyup', k);for (const k of keys) fireKey('keyup', k);await raf();- return keys.length + taps.length + holds.length + (pointer ? 1 : 0);+ return keys.length + taps.length + holds.length + touches.length + (pointer ? 1 : 0);})()`;}diff --git a/desktop/scripts/launch-export.mjs b/desktop/scripts/launch-export.mjsindex 3952bc5ac..8ec935d47 100644--- a/desktop/scripts/launch-export.mjs+++ b/desktop/scripts/launch-export.mjs@@ -21,6 +21,9 @@* --timeout <ms> how long to wait for the first frame (default 30000)* --allow-flat accept a single-colour frame (a deliberately blank scene)* --input <json> drive it: {"keys":["ArrowRight"]} or {"pointer":{"x":.5,"y":.5}}+ * --touch present as a touch device (maxTouchPoints > 0), so a+ * build that puts its on-screen controls up for one can+ * be driven the way a phone would drive it* --log <regex> also print console lines matching this (the engine's own* warnings say why a subsystem sat out; only `[engine]`* lines are forwarded otherwise, which means diagnosing@@ -38,6 +41,13 @@ import { inputScript } from './inputScript.mjs';// capturePage pixels go through the OS display profile; pin sRGB so a colour// judgement reads the same on a wide-gamut machine as on a CI runner.app.commandLine.appendSwitch('force-color-profile', 'srgb');+// A desktop Chromium reports no touch hardware, so a game that only shows its+// on-screen controls to a touch device shows them to nobody here. This is the+// emulation a phone would make true.+if (process.argv.includes('--touch')) {+ app.commandLine.appendSwitch('touch-events', 'enabled');+ app.commandLine.appendSwitch('enable-features', 'TouchpadAndWheelScrollLatching');+}const argv = process.argv.slice(2);const flag = (name, fallback) => {diff --git a/desktop/scripts/play-through.mjs b/desktop/scripts/play-through.mjsindex 7a251f1e5..47ebfde36 100644--- a/desktop/scripts/play-through.mjs+++ b/desktop/scripts/play-through.mjs@@ -214,6 +214,7 @@ async function main() {let lastGap = Infinity;let stuckFor = 0;let was = null;+ let deaths = 0;let plan = [];let replan = 0;let last = null;@@ -275,6 +276,9 @@ async function main() {// Pressed and did not move: back off the dead band so the other axis// comes into play, and re-plan sooner.const moved = was ? Math.hypot(me.x - was.x, me.y - was.y) : Infinity;+ // Nobody walks 600 units in eight frames: that is a death putting her+ // back at the area's entrance, and the leg deserves its time again.+ if (moved > 600 && was) { deaths++; spent = 0; plan = []; }stuckFor = moved < 6 ? stuckFor + STEP : 0;was = me;if (stuckFor > 64) { replan = 0; }@@ -303,7 +307,8 @@ async function main() {if (!arrived) {failure = `${label} — ${spent >= timeout ? 'ran out of leg budget' : 'ran out of run budget'} after ${spent} frames`+ (last ? `; last seen ${Math.round(last.me.x)},${Math.round(last.me.y)} with the goal at `- + `${Math.round(last.goal.x)},${Math.round(last.goal.y)} (${Math.round(last.gap)} away)` : '; never saw both');+ + `${Math.round(last.goal.x)},${Math.round(last.goal.y)} (${Math.round(last.gap)} away)` : '; never saw both')+ + (deaths ? `; died ${deaths}x on this leg` : '');break;}done.push(label);diff --git a/examples/celestial-heights/assets/scenes/hud.esscene b/examples/celestial-heights/assets/scenes/hud.essceneindex 6128c1c24..551ae1171 100644--- a/examples/celestial-heights/assets/scenes/hud.esscene+++ b/examples/celestial-heights/assets/scenes/hud.esscene@@ -12,7 +12,8 @@60,70,80,- 84+ 84,+ 86],"visible": true,"components": [@@ -829,6 +830,221 @@}}]+ },+ {+ "id": 86,+ "name": "TouchLayer",+ "parent": 50,+ "children": [+ 87,+ 89+ ],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "display": 1,+ "insetLeft": {+ "value": 0,+ "unit": 0+ },+ "insetRight": {+ "value": 0,+ "unit": 0+ },+ "insetTop": {+ "value": 0,+ "unit": 0+ },+ "insetBottom": {+ "value": 0,+ "unit": 0+ }+ }+ },+ {+ "type": "TouchLayer",+ "data": {}+ }+ ]+ },+ {+ "id": 87,+ "name": "TouchStick",+ "parent": 86,+ "children": [+ 88+ ],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "insetLeft": {+ "value": 120,+ "unit": 0+ },+ "insetBottom": {+ "value": 120,+ "unit": 0+ },+ "width": {+ "value": 280,+ "unit": 0+ },+ "height": {+ "value": 280,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "visualType": 1,+ "color": {+ "r": 0.925,+ "g": 0.906,+ "b": 0.98,+ "a": 0.16+ },+ "enabled": true+ }+ },+ {+ "type": "Interactable",+ "data": {}+ },+ {+ "type": "Draggable",+ "data": {}+ },+ {+ "type": "TouchStick",+ "data": {}+ }+ ]+ },+ {+ "id": 88,+ "name": "TouchKnob",+ "parent": 87,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "insetLeft": {+ "value": 90,+ "unit": 0+ },+ "insetBottom": {+ "value": 90,+ "unit": 0+ },+ "width": {+ "value": 100,+ "unit": 0+ },+ "height": {+ "value": 100,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "visualType": 1,+ "color": {+ "r": 0.925,+ "g": 0.906,+ "b": 0.98,+ "a": 0.5+ },+ "enabled": true+ }+ },+ {+ "type": "TouchKnob",+ "data": {}+ }+ ]+ },+ {+ "id": 89,+ "name": "TouchStrike",+ "parent": 86,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "UINode",+ "data": {+ "position": 1,+ "insetRight": {+ "value": 140,+ "unit": 0+ },+ "insetBottom": {+ "value": 150,+ "unit": 0+ },+ "width": {+ "value": 200,+ "unit": 0+ },+ "height": {+ "value": 200,+ "unit": 0+ }+ }+ },+ {+ "type": "UIVisual",+ "data": {+ "visualType": 1,+ "color": {+ "r": 0.906,+ "g": 0.353,+ "b": 0.412,+ "a": 0.42+ },+ "enabled": true+ }+ },+ {+ "type": "Interactable",+ "data": {}+ },+ {+ "type": "TouchButton",+ "data": {+ "action": "Attack"+ }+ }+ ]}]}diff --git a/examples/celestial-heights/playthrough.json.meta b/examples/celestial-heights/playthrough.json.metanew file mode 100644index 000000000..c20a955e7--- /dev/null+++ b/examples/celestial-heights/playthrough.json.meta@@ -0,0 +1,6 @@+{+ "uuid": "872928a8-83fd-413f-8521-fd524232cf88",+ "version": "2.0",+ "type": "json",+ "importer": {}+}diff --git a/examples/celestial-heights/src/actions.ts b/examples/celestial-heights/src/actions.tsindex 3e8611b03..58701e614 100644--- a/examples/celestial-heights/src/actions.ts+++ b/examples/celestial-heights/src/actions.ts@@ -1,5 +1,5 @@import {- defineInputMap, Axis2D, Button, Keys2D, Stick, Key, GpButton, GamepadButton,+ defineInputMap, Axis2D, Button, Keys2D, Stick, Key, GpButton, GamepadButton, Virtual,} from 'esengine';/**@@ -12,8 +12,9 @@ export const Actions = defineInputMap({Keys2D('KeyW', 'KeyS', 'KeyA', 'KeyD'),Keys2D('ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'),Stick('left'),+ Virtual('move'),),- Attack: Button(Key('Space'), GpButton(GamepadButton.West)),+ Attack: Button(Key('Space'), GpButton(GamepadButton.West), Virtual('touch.Attack')),Pause: Button(Key('Escape'), GpButton(GamepadButton.Start)),Pack: Button(Key('Tab'), GpButton(GamepadButton.North)),Language: Button(Key('KeyL')),diff --git a/examples/celestial-heights/src/components.ts b/examples/celestial-heights/src/components.tsindex 84f6b3864..ea3928cb7 100644--- a/examples/celestial-heights/src/components.ts+++ b/examples/celestial-heights/src/components.ts@@ -105,6 +105,24 @@ export const VitalityMeter = defineTag('VitalityMeter');/** The panel shown while the game is paused. */export const PauseOverlay = defineTag('PauseOverlay');+/**+ * The on-screen controls, and the layer holding them. Shown once the game has+ * been touched at all: a thumb is the only input a phone has, and a stick drawn+ * over a keyboard player's world is clutter they never asked for.+ */+export const TouchLayer = defineTag('TouchLayer');++/** The stick's base — dragged, and the drag is where the movement comes from. */+export const TouchStick = defineTag('TouchStick');++/** The part of the stick that follows the thumb. */+export const TouchKnob = defineTag('TouchKnob');++/** An on-screen button, naming the action it stands for. */+export const TouchButton = defineComponent('TouchButton', {+ action: '',+});+/** The screen shown for the couple of seconds a run takes to end and restart. */export const FallenOverlay = defineTag('FallenOverlay');diff --git a/examples/celestial-heights/src/main.ts b/examples/celestial-heights/src/main.tsindex c22516c69..3728833ad 100644--- a/examples/celestial-heights/src/main.ts+++ b/examples/celestial-heights/src/main.ts@@ -19,6 +19,7 @@ import {} from './systems/world';import { pauseInputSystem, pauseTimeSystem, pauseOverlaySystem } from './systems/pause';import { fallenSystem, fallenOverlaySystem } from './systems/fallen';+import { touchLayerSystem, touchStickSystem, touchButtonSystem } from './systems/touch';import { applySettingsSystem, cycleLanguageSystem } from './systems/settings';import {saveRunSystem, loadRunSystem, applyRestoreSystem, rememberRosterSystem, vitalitySystem,@@ -68,6 +69,9 @@ addSystemSetToSchedule(Schedule.PostUpdate, defineSystemSet('combat', {// The pause itself and everything that reports state keep running: one has to be// able to lift the pause, the rest have to be able to show it.+addSystemToSchedule(Schedule.PreUpdate, touchLayerSystem);+addSystemToSchedule(Schedule.PreUpdate, touchStickSystem);+addSystemToSchedule(Schedule.PreUpdate, touchButtonSystem);addSystemToSchedule(Schedule.Update, pauseInputSystem);addSystemToSchedule(Schedule.Update, fallenSystem);addSystemToSchedule(Schedule.Update, pauseTimeSystem);diff --git a/examples/celestial-heights/src/state.ts b/examples/celestial-heights/src/state.tsindex 94590f61d..3445c236b 100644--- a/examples/celestial-heights/src/state.ts+++ b/examples/celestial-heights/src/state.ts@@ -17,6 +17,8 @@ export const session = {inventoryOpen: false,/** Settings: whether hit sparks and other flourishes are drawn. */effects: true,+ /** Whether this run has been touched — what puts the on-screen controls up. */+ touched: false,/** Seconds left of the fallen screen; > 0 means the run is over and waiting. */fallenFor: 0,/**diff --git a/examples/celestial-heights/src/systems/touch.ts b/examples/celestial-heights/src/systems/touch.tsnew file mode 100644index 000000000..f07ab8113--- /dev/null+++ b/examples/celestial-heights/src/systems/touch.ts@@ -0,0 +1,69 @@+import {+ defineSystem, Query, Mut, Res, Input, Transform, UINode, UIDisplay,+ DragState, UIInteraction,+} from 'esengine';+import { TouchButton, TouchKnob, TouchLayer, TouchStick } from '../components';+import { session } from '../state';++/** How far the knob travels from the base's centre, in design pixels. */+const STICK_TRAVEL = 90;++/**+ * Reveals the controls once the game has been touched, and never hides them+ * again. Asking "is this a touch device" is a question about hardware; whether+ * someone is playing with a thumb is a question about what they just did.+ */+export const touchLayerSystem = defineSystem(+ [Query(Mut(UINode), TouchLayer), Res(Input)],+ (layers, input) => {+ // Asked of the device, not of what has happened: controls that appear+ // after the first touch make the first touch land on nothing.+ if (input.touchAvailable || input.touches.size > 0) session.touched = true;+ const display = session.touched ? UIDisplay.Flex : UIDisplay.None;+ for (const [, node] of layers) {+ if (node.display !== display) node.display = display;+ }+ },+ { name: 'TouchLayerSystem' },+);++/**+ * Turns the on-screen stick into the same `Move` the keyboard and the gamepad+ * produce. The engine's drag gives a world-space delta from where the thumb+ * went down, which is what a stick is; the knob is drawn from the same number,+ * so what is under the thumb and what the game reads cannot disagree.+ */+export const touchStickSystem = defineSystem(+ [Query(DragState, TouchStick), Query(Mut(Transform), TouchKnob), Res(Input)],+ (sticks, knobs, input) => {+ if (!session.touched) return;+ let x = 0;+ let y = 0;+ for (const [, drag] of sticks) {+ if (!drag.isDragging) break;+ x = drag.totalDeltaWorld.x / STICK_TRAVEL;+ y = drag.totalDeltaWorld.y / STICK_TRAVEL;+ const over = Math.hypot(x, y);+ if (over > 1) { x /= over; y /= over; }+ break;+ }+ input.setVirtual('move', x, y);+ for (const [, transform] of knobs) {+ transform.position.x = x * STICK_TRAVEL;+ transform.position.y = y * STICK_TRAVEL;+ }+ },+ { name: 'TouchStickSystem' },+);++/** Turns an on-screen button into the action it names. */+export const touchButtonSystem = defineSystem(+ [Query(UIInteraction, TouchButton), Res(Input)],+ (buttons, input) => {+ if (!session.touched) return;+ for (const [, interaction, button] of buttons) {+ if (button.action) input.setVirtual(`touch.${button.action}`, interaction.pressed ? 1 : 0);+ }+ },+ { name: 'TouchButtonSystem' },+);diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex b1398b9bb..c4c31e4e1 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: 1483 stable · 17 beta · 1 deprecated+Symbols: 1484 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -1037,6 +1037,7 @@ p2y: number| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string }```## BitmapCache — interface@@ -3689,6 +3690,7 @@ static prototype: InputRouter```beginFixedStep: () => voidclearFrameState: () => void+clearVirtual: () => voidendFixedStep: () => voidgamepadButtonThreshold: numbergamepadDeadzone: number@@ -3701,6 +3703,7 @@ getScrollDelta: () => { x: number; y: number; }getTouch: (id: number) => TouchPoint | nullgetTouchCount: () => numbergetTouches: () => TouchPoint[]+getVirtual: (id: string) => Vec2isGamepadButtonDown: (button: number, pad?: number) => booleanisGamepadButtonPressed: (button: number, pad?: number) => booleanisGamepadButtonReleased: (button: number, pad?: number) => boolean@@ -3732,6 +3735,8 @@ noteMouseUp: (button: number) => voidpointerOverUI: booleanscrollDeltaX: numberscrollDeltaY: number+setVirtual: (id: string, x: number, y?: number) => void+touchAvailable: booleantouches: Map<number, TouchPoint>touchesEnded: Set<number>touchesStarted: Map<number, TouchPoint>@@ -5150,6 +5155,7 @@ family: "minigame" | undefinedfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+hasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -8604,6 +8610,11 @@ x: numbery: number```+## Virtual — const+```+(id: string) => Binding+```+## WangIndex — interface```byKey: Map<number, number>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a7b3bd894..7e64dfe56 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: 1502 stable · 22 beta · 1 deprecated+Symbols: 1503 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -1037,6 +1037,7 @@ p2y: number| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string }```## BitmapCache — interface@@ -3697,6 +3698,7 @@ static prototype: InputRouter```beginFixedStep: () => voidclearFrameState: () => void+clearVirtual: () => voidendFixedStep: () => voidgamepadButtonThreshold: numbergamepadDeadzone: number@@ -3709,6 +3711,7 @@ getScrollDelta: () => { x: number; y: number; }getTouch: (id: number) => TouchPoint | nullgetTouchCount: () => numbergetTouches: () => TouchPoint[]+getVirtual: (id: string) => Vec2isGamepadButtonDown: (button: number, pad?: number) => booleanisGamepadButtonPressed: (button: number, pad?: number) => booleanisGamepadButtonReleased: (button: number, pad?: number) => boolean@@ -3740,6 +3743,8 @@ noteMouseUp: (button: number) => voidpointerOverUI: booleanscrollDeltaX: numberscrollDeltaY: number+setVirtual: (id: string, x: number, y?: number) => void+touchAvailable: booleantouches: Map<number, TouchPoint>touchesEnded: Set<number>touchesStarted: Map<number, TouchPoint>@@ -5333,6 +5338,7 @@ family: "minigame" | undefinedfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+hasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -8797,6 +8803,11 @@ x: numbery: number```+## Virtual — const+```+(id: string) => Binding+```+## WangIndex — interface```byKey: Map<number, number>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d7b3f35de..041acfeae 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: 1482 stable · 19 beta · 1 deprecated+Symbols: 1483 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -1032,6 +1032,7 @@ p2y: number| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string }```## BitmapCache — interface@@ -3684,6 +3685,7 @@ static prototype: InputRouter```beginFixedStep: () => voidclearFrameState: () => void+clearVirtual: () => voidendFixedStep: () => voidgamepadButtonThreshold: numbergamepadDeadzone: number@@ -3696,6 +3698,7 @@ getScrollDelta: () => { x: number; y: number; }getTouch: (id: number) => TouchPoint | nullgetTouchCount: () => numbergetTouches: () => TouchPoint[]+getVirtual: (id: string) => Vec2isGamepadButtonDown: (button: number, pad?: number) => booleanisGamepadButtonPressed: (button: number, pad?: number) => booleanisGamepadButtonReleased: (button: number, pad?: number) => boolean@@ -3727,6 +3730,8 @@ noteMouseUp: (button: number) => voidpointerOverUI: booleanscrollDeltaX: numberscrollDeltaY: number+setVirtual: (id: string, x: number, y?: number) => void+touchAvailable: booleantouches: Map<number, TouchPoint>touchesEnded: Set<number>touchesStarted: Map<number, TouchPoint>@@ -5145,6 +5150,7 @@ family: "minigame" | undefinedfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+hasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -8599,6 +8605,11 @@ x: numbery: number```+## Virtual — const+```+(id: string) => Binding+```+## WangIndex — interface```byKey: Map<number, number>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 807835ace..3b4e5eaf1 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: 1503 stable · 17 beta · 1 deprecated+Symbols: 1504 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -1032,6 +1032,7 @@ p2y: number| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string }```## BitmapCache — interface@@ -3684,6 +3685,7 @@ static prototype: InputRouter```beginFixedStep: () => voidclearFrameState: () => void+clearVirtual: () => voidendFixedStep: () => voidgamepadButtonThreshold: numbergamepadDeadzone: number@@ -3696,6 +3698,7 @@ getScrollDelta: () => { x: number; y: number; }getTouch: (id: number) => TouchPoint | nullgetTouchCount: () => numbergetTouches: () => TouchPoint[]+getVirtual: (id: string) => Vec2isGamepadButtonDown: (button: number, pad?: number) => booleanisGamepadButtonPressed: (button: number, pad?: number) => booleanisGamepadButtonReleased: (button: number, pad?: number) => boolean@@ -3727,6 +3730,8 @@ noteMouseUp: (button: number) => voidpointerOverUI: booleanscrollDeltaX: numberscrollDeltaY: number+setVirtual: (id: string, x: number, y?: number) => void+touchAvailable: booleantouches: Map<number, TouchPoint>touchesEnded: Set<number>touchesStarted: Map<number, TouchPoint>@@ -5390,6 +5395,7 @@ family: "minigame" | undefinedfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+hasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -8844,6 +8850,11 @@ x: numbery: number```+## Virtual — const+```+(id: string) => Binding+```+## WangIndex — interface```byKey: Map<number, number>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 38ed6b8ad..1241d9349 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: 1493 stable · 17 beta · 1 deprecated+Symbols: 1494 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -1032,6 +1032,7 @@ p2y: number| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }| { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string }```## BitmapCache — interface@@ -3691,6 +3692,7 @@ static prototype: InputRouter```beginFixedStep: () => voidclearFrameState: () => void+clearVirtual: () => voidendFixedStep: () => voidgamepadButtonThreshold: numbergamepadDeadzone: number@@ -3703,6 +3705,7 @@ getScrollDelta: () => { x: number; y: number; }getTouch: (id: number) => TouchPoint | nullgetTouchCount: () => numbergetTouches: () => TouchPoint[]+getVirtual: (id: string) => Vec2isGamepadButtonDown: (button: number, pad?: number) => booleanisGamepadButtonPressed: (button: number, pad?: number) => booleanisGamepadButtonReleased: (button: number, pad?: number) => boolean@@ -3734,6 +3737,8 @@ noteMouseUp: (button: number) => voidpointerOverUI: booleanscrollDeltaX: numberscrollDeltaY: number+setVirtual: (id: string, x: number, y?: number) => void+touchAvailable: booleantouches: Map<number, TouchPoint>touchesEnded: Set<number>touchesStarted: Map<number, TouchPoint>@@ -5152,6 +5157,7 @@ family: "minigame" | undefinedfetch: (url: string, options?: PlatformRequestOptions) => Promise<PlatformResponse>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+hasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>language: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -8606,6 +8612,11 @@ x: numbery: number```+## Virtual — const+```+(id: string) => Binding+```+## WangIndex — interface```byKey: Map<number, number>diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 99eef62cf..962f41a51 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -238,6 +238,7 @@ export {Keys1D,Keys2D,Stick,+ Virtual,Button,Axis1D,Axis2D,diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.tsindex 16b718fd2..f97756672 100644--- a/sdk/src/input/input.ts+++ b/sdk/src/input/input.ts@@ -6,6 +6,7 @@ import type { App, Plugin } from '../app/app';import { getPlatform, platformUnbindInputEvents } from '../platform';import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';import { inputRouter } from './inputRouter';+import type { Vec2 } from '../types';export interface TouchPoint {id: number;@@ -54,6 +55,8 @@ interface PadState {axes: number[];}+const ZERO_VIRTUAL: Vec2 = { x: 0, y: 0 };+export class InputState {keysDown = new Set<string>();keysPressed = new Set<string>();@@ -66,6 +69,9 @@ export class InputState {scrollDeltaX = 0;scrollDeltaY = 0;+ /** Whether the device can be touched — asked of the platform, not of history. */+ touchAvailable = false;+touches = new Map<number, TouchPoint>();touchesStarted = new Map<number, TouchPoint>();touchesEnded = new Set<number>();@@ -165,6 +171,30 @@ export class InputState {return this.touches.has(id);}+ // — Virtual (an on-screen control, or anything else that decides to be input) —+ /**+ * Named 2D values a game writes itself — an on-screen control, the only+ * input a touch device has. Named rather than a screen rectangle, so what+ * is touched and what is read stay one object when the layout moves.+ */+ private virtual_ = new Map<string, Vec2>();++ /** Set a named virtual input; held until overwritten, so stopping means+ * writing zero. `y` defaults to 0 for button/1D use. */+ setVirtual(id: string, x: number, y = 0): void {+ const v = this.virtual_.get(id);+ if (v) { v.x = x; v.y = y; } else this.virtual_.set(id, { x, y });+ }++ getVirtual(id: string): Vec2 {+ return this.virtual_.get(id) ?? ZERO_VIRTUAL;+ }++ /** Drop every virtual input — used when a control layer is torn down. */+ clearVirtual(): void {+ this.virtual_.clear();+ }+// — Gamepad (polled each frame; edges via current/prev diff, not events) —/** Per-index pad state; an index persists across disconnect so a reconnect resumes. */gamepads = new Map<number, PadState>();@@ -370,6 +400,7 @@ export class InputPlugin implements Plugin {const state = new InputState();app.insertResource(Input, state);+ state.touchAvailable = getPlatform().hasTouch?.() ?? false;getPlatform().bindInputEvents(inputEventCallbacks(state), this.target_ ?? undefined);// Gamepads are polled (no DOM events). Web supplies pollGamepads; platformsdiff --git a/sdk/src/input/inputMap.ts b/sdk/src/input/inputMap.tsindex 05eb301ca..b86fbd6c3 100644--- a/sdk/src/input/inputMap.ts+++ b/sdk/src/input/inputMap.ts@@ -28,7 +28,8 @@ export type Binding =| { kind: 'gpAxis'; axis: number; pad?: number; scale?: number }| { kind: 'keys1d'; neg: string; pos: string }| { kind: 'keys2d'; up: string; down: string; left: string; right: string }- | { kind: 'stick'; stick: 'left' | 'right'; pad?: number };+ | { kind: 'stick'; stick: 'left' | 'right'; pad?: number }+ | { kind: 'virtual'; id: string };export type ActionType = 'button' | 'axis' | 'axis2d';@@ -58,6 +59,12 @@ export const Keys2D = (up: string, down: string, left: string, right: string): B({ kind: 'keys2d', up, down, left, right });/** A gamepad stick → a 2D axis (up = +y; the raw Y axis is inverted to match Keys2D). */export const Stick = (stick: 'left' | 'right', pad?: number): Binding => ({ kind: 'stick', stick, pad });+/**+ * A named value the game writes itself (`Input.setVirtual`) — an on-screen+ * stick or button, which is the only input a touch device has. Works as a+ * scalar or a 2D source, so one kind covers both.+ */+export const Virtual = (id: string): Binding => ({ kind: 'virtual', id });// — Action constructors —export const Button = (...bindings: Binding[]): ActionDef => ({ type: 'button', bindings });@@ -88,6 +95,7 @@ function evalScalar(b: Binding, input: InputState): number {case 'gpButton': return input.getGamepadButtonValue(b.button, b.pad ?? 0);case 'keys1d': return (input.isKeyDown(b.pos) ? 1 : 0) - (input.isKeyDown(b.neg) ? 1 : 0);case 'gpAxis': return input.getGamepadAxis(b.axis, b.pad ?? 0) * (b.scale ?? 1);+ case 'virtual': return input.getVirtual(b.id).x;default: return 0; // keys2d / stick are 2D sources — no scalar contribution}}@@ -105,6 +113,10 @@ function evalVec(b: Binding, input: InputState): Vec2 {// Gamepad Y is +down; invert so up = +y (matches Keys2D).return { x: input.getGamepadAxis(xAxis, pad), y: -input.getGamepadAxis(yAxis, pad) };}+ case 'virtual': {+ const v = input.getVirtual(b.id);+ return { x: v.x, y: v.y };+ }default: return { x: 0, y: 0 };}}diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 39272b181..927f16bac 100644--- a/sdk/src/platform/types.ts+++ b/sdk/src/platform/types.ts@@ -427,6 +427,14 @@ export interface PlatformAdapter {bindInputEvents(callbacks: InputEventCallbacks, target?: unknown): void;+ /**+ * Whether this device can be touched at all. A game that only shows its+ * on-screen controls after the first touch asks its player to touch the+ * screen twice, the first time at nothing — so the question has to be+ * answerable before anyone has touched anything. Absent means no.+ */+ hasTouch?(): boolean;+/** Tear down the listeners {@link bindInputEvents} registered. Optional — a* headless host that never binds input (node) omits it. */unbindInputEvents?(): void;diff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.tsindex c0cee4f53..52a9fd87a 100644--- a/sdk/src/platform/web.ts+++ b/sdk/src/platform/web.ts@@ -37,6 +37,11 @@ class WebPlatformAdapter implements PlatformAdapter {readonly name = 'web' as const;private inputCleanup_: (() => void) | null = null;+ hasTouch(): boolean {+ return typeof navigator !== 'undefined'+ && ((navigator.maxTouchPoints ?? 0) > 0 || 'ontouchstart' in globalThis);+ }+async fetch(url: string, options?: PlatformRequestOptions): Promise<PlatformResponse> {const response = await globalThis.fetch(url, {method: options?.method ?? 'GET',diff --git a/sdk/tests/input-map-virtual.test.ts b/sdk/tests/input-map-virtual.test.tsnew file mode 100644index 000000000..1cc048b87--- /dev/null+++ b/sdk/tests/input-map-virtual.test.ts@@ -0,0 +1,77 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The input a touch device actually has.+ *+ * A phone has no keys and no sticks. What it has is a thumb on a control the+ * game drew, and that control knows where it is because the UI put it there —+ * so it feeds its value in by name rather than an action being bound to a+ * rectangle of the screen, which is a rectangle that goes stale the first time+ * the layout moves.+ */+import { describe, it, expect } from 'vitest';+import { InputState } from '../src/input/input';+import { InputMap, Button, Axis2D, Key, Keys2D, Virtual } from '../src/input/inputMap';++describe('Virtual bindings', () => {+ it('drives a 2D action with no keyboard in sight', () => {+ const map = new InputMap({ Move: Axis2D(Keys2D('KeyW', 'KeyS', 'KeyA', 'KeyD'), Virtual('move')) });+ const input = new InputState();++ map.evaluate(input);+ expect(map.axis2d('Move')).toEqual({ x: 0, y: 0 });++ input.setVirtual('move', 0.6, -0.8);+ map.evaluate(input);+ expect(map.axis2d('Move').x).toBeCloseTo(0.6);+ expect(map.axis2d('Move').y).toBeCloseTo(-0.8);+ });++ it('drives a button, edges and all', () => {+ const map = new InputMap({ Attack: Button(Key('Space'), Virtual('attack')) });+ const input = new InputState();++ input.setVirtual('attack', 1);+ map.evaluate(input);+ expect(map.pressed('Attack')).toBe(true);+ expect(map.down('Attack')).toBe(true);++ map.evaluate(input);+ expect(map.pressed('Attack'), 'a held control keeps re-pressing').toBe(false);+ expect(map.down('Attack')).toBe(true);++ // A control that stops reporting has to say so, exactly like a key+ // coming up — nothing clears these between frames.+ input.setVirtual('attack', 0);+ map.evaluate(input);+ expect(map.released('Attack')).toBe(true);+ });++ it('adds to the same action a key drives, and stays clamped', () => {+ const map = new InputMap({ Attack: Button(Key('Space'), Virtual('attack')) });+ const input = new InputState();+ input.keysDown.add('Space');+ input.setVirtual('attack', 1);+ map.evaluate(input);+ expect(map.value('Attack')).toBe(1);+ });++ it('reads zero for a name nobody ever wrote', () => {+ const map = new InputMap({ Move: Axis2D(Virtual('never-set')) });+ const input = new InputState();+ map.evaluate(input);+ expect(map.axis2d('Move')).toEqual({ x: 0, y: 0 });+ });++ // The binding model is the serialization format, so a rebind or a shipped+ // `.inputmap` carries on-screen controls like anything else.+ it('survives a round trip through the binding format', () => {+ const map = new InputMap({ Move: Axis2D(Virtual('move')) });+ const back = new InputMap({ Move: Axis2D(Key('KeyW')) });+ back.loadJSON(map.toJSON());+ const input = new InputState();+ input.setVirtual('move', 1, 0);+ back.evaluate(input);+ expect(back.axis2d('Move').x).toBeCloseTo(1);+ });+});diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjsindex ddbe94684..faffe4641 100644--- a/tools/goldenProjects.mjs+++ b/tools/goldenProjects.mjs@@ -71,7 +71,6 @@ export const CAPABILITIES = [* coverage — the same bargain check-project-settings strikes.*/export const KNOWN_GAPS = {- touch: 'no example drives synthetic touch; input-actions is keyboard + gamepad — Celestial Heights P5','safe-area': 'safe-area insets are exercised by the UI mode viewport, not by a project — Celestial Heights P5','pause-resume': 'lifecycle suspend/resume is covered by native hosts, not by a golden project — Celestial Heights P3',rollback: 'hot-update-demo swaps forward; nothing exercises a failed manifest rolling back',@@ -172,15 +171,21 @@ export const GOLDEN = [certifies: ['tilemap', 'tile-collision', 'navigation', 'behavior-tree','scene-transition', 'y-sort', 'localization', 'ui-layout', 'text',- 'persistence', 'ui-inventory', 'achievements',+ 'persistence', 'ui-inventory', 'achievements', 'touch',],targets: ['web', 'desktop'],// Nightly, not pr: a project earns the release gate by having run, and this// one has not run anywhere yet. It is also the biggest thing in the corpus.tier: 'nightly',- // The camera follows Lyra, so walking scrolls the whole screen — no reading- // of a small sprite is needed to see that the key arrived.- interact: { keys: ['KeyD'], frames: 60 },+ // The thumb drags the on-screen stick a touch device gets. Stricter than+ // the default because this game moves on its own: a thumb on the stick+ // measures 0.65, a thumb on empty background 0.40.+ interact: {+ keys: ['KeyD'],+ frames: 60,+ responds: 0.55,+ touches: [{ from: 4, to: 58, x: 0.13, y: 0.78, toX: 0.30, toY: 0.78 }],+ },},{id: 'input-actions',@@ -255,6 +260,7 @@ export function interactFor(g) {return {keys: g.interact.keys ?? [],pointer: g.interact.pointer ?? null,+ touches: g.interact.touches ?? null,frames: g.interact.frames ?? 40,responds: g.interact.responds ?? DEFAULT_RESPONDS,};diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjsindex 4b9b12a49..00550bb4a 100644--- a/tools/verify-golden.mjs+++ b/tools/verify-golden.mjs@@ -180,33 +180,63 @@ for (const { id, target } of pairs) {continue;}- const drivenPng = path.join(WORK, `${id}-${target}-driven.png`);- const drive = spawnSync('npx', [- 'electron', path.join('scripts', LAUNCHER(target)),- '--dir', out, '--out', drivenPng,- '--w', String(editor.w), '--h', String(editor.h),- '--input', JSON.stringify({ keys: input.keys, pointer: input.pointer, frames: input.frames }),- ], { encoding: 'utf8', cwd: DESKTOP });- if (drive.status !== 0) {- results.push({ id, target, stage: 'interact', ok: false, why: 'the driven launch failed' });- console.log(`✗ ${id} ${target} — the driven launch failed`);- continue;+ // Each input the project claims is driven ALONE. Sent together, a package+ // whose touch controls do nothing still answers the keyboard, and the gate+ // reads that as both of them working.+ const gestures = [];+ if (input.keys.length || input.pointer) {+ gestures.push({+ what: [input.keys.join('+'), input.pointer && `tap ${input.pointer.x}×${input.pointer.y}`]+ .filter(Boolean).join(' + '),+ spec: { keys: input.keys, pointer: input.pointer, frames: input.frames },+ touch: false,+ });+ }+ if (input.touches) {+ gestures.push({+ what: `${input.touches.length} touch(es)`,+ spec: { touches: input.touches, frames: input.frames },+ touch: true,+ });}- let response;- try {- response = frameCellMax(readFileSync(packagePng), readFileSync(drivenPng));- } catch (e) {- results.push({ id, target, stage: 'interact', ok: false, why: e.message });- console.log(`✗ ${id} ${target} — interact: ${e.message}`);- continue;+ let allAnswered = true;+ for (const gesture of gestures) {+ const drivenPng = path.join(WORK, `${id}-${target}-driven-${gesture.touch ? 'touch' : 'keys'}.png`);+ const drive = spawnSync('npx', [+ 'electron', path.join('scripts', LAUNCHER(target)),+ '--dir', out, '--out', drivenPng,+ '--w', String(editor.w), '--h', String(editor.h),+ ...(gesture.touch ? ['--touch'] : []),+ '--input', JSON.stringify(gesture.spec),+ ], { encoding: 'utf8', cwd: DESKTOP });+ if (drive.status !== 0) {+ results.push({ id, target, stage: 'interact', ok: false, why: `the driven launch failed (${gesture.what})` });+ console.log(`✗ ${id} ${target} — the driven launch failed for ${gesture.what}`);+ allAnswered = false;+ continue;+ }++ let response;+ try {+ response = frameCellMax(readFileSync(packagePng), readFileSync(drivenPng));+ } catch (e) {+ results.push({ id, target, stage: 'interact', ok: false, why: e.message });+ console.log(`✗ ${id} ${target} — interact: ${e.message}`);+ allAnswered = false;+ continue;+ }+ const answered = response >= input.responds;+ allAnswered = allAnswered && answered;+ results.push({+ id, target, stage: 'interact', ok: answered,+ why: answered ? '' : `${gesture.what}: response ${response.toFixed(4)} < ${input.responds}`,+ });+ console.log(`${answered ? '✓' : '✗'} ${id} ${target} — parity ${distance.toFixed(4)}, `+ + `responds ${response.toFixed(4)} to ${gesture.what}`);+ if (!answered) console.log(` the package did not visibly answer it; compare ${packagePng} and ${drivenPng}`);}- const answered = response >= input.responds;- results.push({ id, target, stage: 'interact', ok: answered, why: answered ? '' : `response ${response.toFixed(4)} < ${input.responds}` });- const gesture = [input.keys.join('+'), input.pointer && `tap ${input.pointer.x}×${input.pointer.y}`]- .filter(Boolean).join(' + ');- console.log(`${answered ? '✓' : '✗'} ${id} ${target} — parity ${distance.toFixed(4)}, responds ${response.toFixed(4)} to ${gesture}`);- if (!answered) console.log(` the package did not visibly answer the key; compare ${packagePng} and ${drivenPng}`);+ void allAnswered;}const bad = results.filter((r) => !r.ok);