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.

fix(input): preserve gestures when touch IDs are reused

yhhc2e62225112f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d1298ecf..1c0321cd1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Reused touch IDs preserve both gestures.** When a host reuses a touch ID between frames, UI releases the old gesture before capturing the new one, retains quick-tap clicks and projects the held finger's current position for dragging and scrolling.
+
- **Cancelled touch input no longer becomes a click.** Shared touch forwarding distinguishes primary cancellation from normal release, clears cancelled touch and fixed-step edges, and preserves other fingers. Mini-game hide and input teardown cancel held gestures and keys, reset the primary finger, and unregister the hide callback so resumed input starts cleanly.
- **Mini-game storage preserves empty strings.** The adapter distinguishes an explicitly stored empty string from an absent key through the host's key list, matching Web storage and preserving empty text preferences across adapter restarts. Non-empty reads keep their direct path; unavailable host storage remains a safe absent result.
diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.ts
index 0b8ccc29e..8a57d60e1 100644
--- a/sdk/src/input/input.ts
+++ b/sdk/src/input/input.ts
@@ -8,6 +8,7 @@ import { getPlatform, platformUnbindInputEvents } from '../platform';
import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';
import { inputRouter } from './inputRouter';
import { cancelPrimaryPointer, takePrimaryPointerCancellation } from './pointerCancellation';
+import { recordTouchEnd } from './touchEdges';
import type { Vec2 } from '../types';
/**
@@ -204,12 +205,12 @@ export class InputState {
return [...this.touchesEnded.values()];
}
- /** Retire a live touch, keeping where it was — the write door `onTouchEnd`
- * and `onTouchCancel` share, so the two cannot record an end differently. */
+ /** Retire a touch after a normal release, retaining its position and press edge. */
endTouch(id: number): void {
- const point = this.touches.get(id);
+ const point = this.touches.get(id) ?? { id, x: 0, y: 0 };
+ recordTouchEnd(point, this.touchesStarted.has(id));
this.touches.delete(id);
- this.touchesEnded.set(id, point ?? { id, x: 0, y: 0 });
+ this.touchesEnded.set(id, point);
}
// — Virtual (an on-screen control, or anything else that decides to be input) —
diff --git a/sdk/src/input/touchEdges.ts b/sdk/src/input/touchEdges.ts
new file mode 100644
index 000000000..52f33e145
--- /dev/null
+++ b/sdk/src/input/touchEdges.ts
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { TouchPoint } from './input';
+
+// A host can reuse an id before sampling. Keep the old gesture's press edge
+// on its point rather than looking it up under the replacement gesture's id.
+const endedPresses = new WeakMap<TouchPoint, boolean>();
+export function recordTouchEnd(point: TouchPoint, pressed: boolean): void {
+ endedPresses.set(point, pressed);
+}
+export function touchEndPressed(point: TouchPoint, fallback: boolean): boolean {
+ return endedPresses.get(point) ?? fallback;
+}
diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.ts
index db70a5188..2b9af3266 100644
--- a/sdk/src/ui/input/interaction.ts
+++ b/sdk/src/ui/input/interaction.ts
@@ -143,6 +143,7 @@ export class UIInteractionPlugin implements Plugin {
// The single-pointer resources every other consumer reads are the
// PRIMARY pointer's: the mouse, or the oldest finger on the glass.
let primaryWritten = false;
+ const hasHeldPointer = pointers.some(pointer => pointer.down);
let overUI = false;
const hit = (pointer: UiPointerSample): Entity | null => {
@@ -154,7 +155,7 @@ export class UIInteractionPlugin implements Plugin {
// drawn with, which is what keeps a click where the pixel is.
const worldPointer = camera.valid ? screenToUiWorld(camera, glX, glY) : { x: 0, y: 0 };
const layoutPointer = overlay.active ? screenToUiLayout(overlay, glX, glY) : worldPointer;
- if (!primaryWritten) {
+ if (!primaryWritten && (pointer.down || !hasHeldPointer)) {
primaryWritten = true;
camera.worldMouseX = worldPointer.x;
camera.worldMouseY = worldPointer.y;
diff --git a/sdk/src/ui/input/pointerBook.ts b/sdk/src/ui/input/pointerBook.ts
index 9b112f78b..c4b91c88c 100644
--- a/sdk/src/ui/input/pointerBook.ts
+++ b/sdk/src/ui/input/pointerBook.ts
@@ -17,6 +17,7 @@
import type { Entity } from '../../types';
import type { InputState } from '../../input/input';
import { takePrimaryPointerCancellation } from '../../input/pointerCancellation';
+import { touchEndPressed } from '../../input/touchEdges';
/** One pointer this frame. `hovers` is false for a finger that is not down: a
* finger is over a control only while it touches the glass. */
@@ -62,17 +63,24 @@ export const MOUSE_POINTER = -1;
export function uiPointersOf(input: InputState): UiPointerSample[] {
const pointers: UiPointerSample[] = [];
if (input.touches.size > 0 || input.touchesEnded.size > 0) {
+ const pushEnded = (t: { id: number; x: number; y: number }): void => {
+ pointers.push({
+ id: t.id, x: t.x, y: t.y, down: false,
+ pressed: touchEndPressed(t, input.touchesStarted.has(t.id)), released: true, hovers: false,
+ });
+ };
for (const t of input.touches.values()) {
+ // A recycled id still owes the previous gesture its release before
+ // this gesture captures a control.
+ const ended = input.touchesEnded.get(t.id);
+ if (ended) pushEnded(ended);
pointers.push({
id: t.id, x: t.x, y: t.y, down: true,
pressed: input.touchesStarted.has(t.id), released: false, hovers: true,
});
}
for (const t of input.touchesEnded.values()) {
- pointers.push({
- id: t.id, x: t.x, y: t.y, down: false,
- pressed: input.touchesStarted.has(t.id), released: true, hovers: false,
- });
+ if (!input.touches.has(t.id)) pushEnded(t);
}
return pointers;
}
diff --git a/sdk/tests/ui-multi-pointer.test.ts b/sdk/tests/ui-multi-pointer.test.ts
index 3aa285e99..f603eea83 100644
--- a/sdk/tests/ui-multi-pointer.test.ts
+++ b/sdk/tests/ui-multi-pointer.test.ts
@@ -8,7 +8,7 @@
*/
import { describe, it, expect } from 'vitest';
import { UiPointerBook, UiPointerHitCache, uiPointersOf, MOUSE_POINTER, type UiPointerSample } from '../src/ui/input/pointerBook';
-import { InputState } from '../src/input/input';
+import { InputState, inputEventCallbacks } from '../src/input/input';
import type { Entity } from '../src/types';
const BUTTON_A = 1 as Entity;
@@ -176,4 +176,25 @@ describe('the pointer set a frame of input makes', () => {
const events = new UiPointerBook().step(uiPointersOf(input), screen, () => true);
expect(kinds(events, BUTTON_A)).toEqual(['press', 'release', 'click']);
});
+ it('releases the previous use of a touch id before capturing its replacement', () => {
+ const input = new InputState(), callbacks = inputEventCallbacks(input), book = new UiPointerBook();
+ callbacks.onTouchStart!(3, 10, 0);
+ book.step(uiPointersOf(input), screen, () => true); input.clearFrameState();
+ callbacks.onTouchEnd!(3); callbacks.onTouchStart!(3, 150, 0);
+ const events = book.step(uiPointersOf(input), screen, () => true);
+ expect(kinds(events, BUTTON_A)).toContain('click');
+ expect(kinds(events, BUTTON_B)).toEqual(['hoverEnter', 'press']);
+ expect(book.pressedByPointer(3)).toBe(BUTTON_B);
+ input.clearFrameState(); callbacks.onTouchEnd!(3);
+ expect(kinds(book.step(uiPointersOf(input), screen, () => true), BUTTON_B)).toContain('click');
+ });
+ it('preserves a quick tap when its id is reused by a held finger in the same frame', () => {
+ const input = new InputState(), callbacks = inputEventCallbacks(input), book = new UiPointerBook();
+ callbacks.onTouchStart!(3, 10, 0); callbacks.onTouchEnd!(3);
+ callbacks.onTouchStart!(3, 150, 0);
+ const events = book.step(uiPointersOf(input), screen, () => true);
+ expect(kinds(events, BUTTON_A)).toEqual(['press', 'release', 'click']);
+ expect(kinds(events, BUTTON_B)).toEqual(['hoverEnter', 'press']);
+ expect(book.pressedByPointer(3)).toBe(BUTTON_B);
+ });
});
diff --git a/sdk/tests/ui-pointer-callback-wasm.test.ts b/sdk/tests/ui-pointer-callback-wasm.test.ts
index 6203e5861..f53bb52f9 100644
--- a/sdk/tests/ui-pointer-callback-wasm.test.ts
+++ b/sdk/tests/ui-pointer-callback-wasm.test.ts
@@ -19,7 +19,8 @@ import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
const hit = vi.hoisted(() => ({ entity: null as number | null }));
// Deterministic picking isolates event dispatch over the actual WASM Registry.
vi.mock('../src/ui/util/ui-pick', () => ({
- screenToUiWorld: () => ({ x: 0, y: 0 }), screenToUiLayout: () => ({ x: 0, y: 0 }),
+ screenToUiWorld: (_camera: unknown, x: number, y: number) => ({ x, y }),
+ screenToUiLayout: (_overlay: unknown, x: number, y: number) => ({ x, y }),
uiPointerRay: () => ({}), uiLayoutRay: () => ({}), uiHitTestWorld: () => hit.entity,
}));
@@ -43,6 +44,20 @@ describe.skipIf(!HAS_WASM)('pointer callback lifecycle on real WASM', () => {
for (const entity of app.world.getAllEntities()) app.world.despawn(entity);
app.world.disconnectCpp(); registry.delete();
});
+ it('keeps the replacement touch held and projects its current position', async () => {
+ const entity = app.world.spawn(); hit.entity = entity; app.world.insert(entity, Interactable);
+ const input = app.getResource(Input), callbacks = inputEventCallbacks(input);
+ callbacks.onTouchStart!(3, 10, 0); await app.tick(1 / 60); input.clearFrameState();
+ callbacks.onTouchEnd!(3); callbacks.onTouchStart!(3, 150, 0);
+ const clicks = vi.fn(); app.getResource(UIEvents).on(entity, 'click', clicks);
+ await app.tick(1 / 60);
+ expect(clicks).toHaveBeenCalledOnce();
+ expect(app.world.get(entity, UIInteraction).pressed).toBe(true);
+ expect(app.getResource(ScreenOverlay).pointerX).toBe(150);
+ input.clearFrameState(); callbacks.onTouchEnd!(3); await app.tick(1 / 60);
+ expect(clicks).toHaveBeenCalledTimes(2);
+ expect(app.world.get(entity, UIInteraction).pressed).toBe(false);
+ });
it('a consumed primary release cancels the actual WASM control instead of clicking it', async () => {
const entity = app.world.spawn(); hit.entity = entity; app.world.insert(entity, Interactable);
const input = app.getResource(Input), callbacks = inputEventCallbacks(input), clicked = vi.fn();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index eb8edea88..4c4de0b46 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(input): preserve gestures when touch IDs are reused':
+ { note: 'Reused touch IDs preserve both gestures.' },
'fix(input): cancel touch state when mini-games hide':
{ note: 'Cancelled touch input no longer becomes a click.' },
'fix(storage): preserve empty mini-game values':