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): retire held state when release events are consumed

yhha3afe925fa46
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 899470d12..2db724d73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Claimed input releases cannot leave gameplay controls held.** Keyboard, mouse and touch releases consumed by an editor or UI handler silently retire the previous held state without manufacturing gameplay release edges. UI capture receives primary-pointer cancellation instead of a click, even across frame-edge clearing; unowned touch moves and releases do not create ghost contacts.
+
- **UI gesture bindings expire with their targets and App.** App cleanup unregisters only its own input handler and clears captures. Despawn removes gesture callbacks and pending markers through one shared World observer; a cancelled frame click no longer suppresses a later click after the control is re-enabled.
- **Safe-area resize listeners belong to their App.** Quitting an older App no longer removes a newer App's browser listener or leaves its own behind. Rebuilding replaces the same App's binding, cleanup uses the original host and WeChat callback identity, and older hosts without an unsubscribe API revoke the retained callback.
diff --git a/sdk/src/input/input.ts b/sdk/src/input/input.ts
index 9af0d2c17..e1979d0ff 100644
--- a/sdk/src/input/input.ts
+++ b/sdk/src/input/input.ts
@@ -7,6 +7,7 @@ import { claimsKeyDefault, recordTabModifiers, clearTabModifiers } from './keyDe
import { getPlatform, platformUnbindInputEvents } from '../platform';
import type { GamepadSnapshot, InputEventCallbacks } from '../platform/types';
import { inputRouter } from './inputRouter';
+import { cancelPrimaryPointer, takePrimaryPointerCancellation } from './pointerCancellation';
import type { Vec2 } from '../types';
/**
@@ -161,6 +162,7 @@ export class InputState {
}
noteMouseDown(button: number): void {
+ if (button === 0) takePrimaryPointerCancellation(this);
this.mouseButtons.add(button);
this.mouseButtonsPressed.add(button);
this.mouseButtonsPressedFixed.add(button);
@@ -398,6 +400,10 @@ export const Input = defineResource<InputState>(new InputState(), 'Input');
* One implementation, so the injected event and the real one cannot diverge.
*/
export function inputEventCallbacks(state: InputState): InputEventCallbacks {
+ const finishTouch = (id: number, consumed: boolean): void => {
+ if (consumed) state.touches.delete(id);
+ else if (state.touches.has(id)) state.endTouch(id);
+ };
return {
onKeyDown(code) {
if (inputRouter.dispatchKeyDown(code)) return true;
@@ -405,8 +411,8 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
return claimsKeyDefault(state, code);
},
onKeyUp(code) {
- if (inputRouter.dispatchKeyUp(code)) return;
- state.noteKeyUp(code);
+ if (inputRouter.dispatchKeyUp(code)) state.keysDown.delete(code);
+ else if (state.keysDown.has(code)) state.noteKeyUp(code);
},
onPointerMove(x, y) {
// Pointer position tracks the cursor even when consumed so
@@ -424,8 +430,11 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
state.noteMouseDown(button);
},
onPointerUp(button) {
- if (inputRouter.dispatchPointerUp(button)) return;
- state.noteMouseUp(button);
+ if (inputRouter.dispatchPointerUp(button)) {
+ state.mouseButtons.delete(button);
+ if (button === 0) cancelPrimaryPointer(state);
+ }
+ else if (state.mouseButtons.has(button)) state.noteMouseUp(button);
},
onWheel(deltaX, deltaY) {
if (inputRouter.dispatchWheel(deltaX, deltaY)) return;
@@ -444,17 +453,13 @@ export function inputEventCallbacks(state: InputState): InputEventCallbacks {
if (existing) {
existing.x = x;
existing.y = y;
- } else {
- state.touches.set(id, { id, x, y });
}
},
onTouchEnd(id) {
- if (inputRouter.dispatchTouchEnd(id)) return;
- state.endTouch(id);
+ finishTouch(id, inputRouter.dispatchTouchEnd(id));
},
onTouchCancel(id) {
- if (inputRouter.dispatchTouchCancel(id)) return;
- state.endTouch(id);
+ finishTouch(id, inputRouter.dispatchTouchCancel(id));
},
};
}
diff --git a/sdk/src/input/inputRouter.ts b/sdk/src/input/inputRouter.ts
index c417e8468..76f1d002d 100644
--- a/sdk/src/input/inputRouter.ts
+++ b/sdk/src/input/inputRouter.ts
@@ -8,8 +8,8 @@
* the SDK. Before those events land in the `InputState` that gameplay code
* polls, they pass through the router's tier-1 (editor) and tier-2 (UI)
* handlers. Either tier can return `true` from a callback to consume the
- * event; consumed events do not update InputState and do not propagate to
- * later tiers.
+ * event; consumed events do not propagate to later tiers. Consumed releases
+ * silently clear previously held gameplay state without adding release edges.
*
* Tier-3 (game) is implicit — it is the InputState resource itself. Code
* that calls `state.isKeyDown(...)` / `state.isMouseButtonDown(...)` sees
diff --git a/sdk/src/input/pointerCancellation.ts b/sdk/src/input/pointerCancellation.ts
new file mode 100644
index 000000000..5e2c81df3
--- /dev/null
+++ b/sdk/src/input/pointerCancellation.ts
@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+const cancelled = new WeakSet<object>();
+
+/** Keep cancellation until the next UI pointer sample, even across a frame-edge clear. */
+export function cancelPrimaryPointer(input: object): void { cancelled.add(input); }
+export function takePrimaryPointerCancellation(input: object): boolean { return cancelled.delete(input); }
diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.ts
index 8a397f71a..db70a5188 100644
--- a/sdk/src/ui/input/interaction.ts
+++ b/sdk/src/ui/input/interaction.ts
@@ -230,7 +230,8 @@ export class UIInteractionPlugin implements Plugin {
const isHovered = isActive && hovered.has(entity);
const isPressed = isActive && pressed.has(entity);
const justPressed = isActive && (data.justPressed || (isPressed && !wasPressed.has(entity)));
- const justReleased = isActive && (data.justReleased || (!isPressed && wasPressed.has(entity)));
+ const justReleased = isActive && (data.justReleased
+ || (!isPressed && wasPressed.has(entity) && !book.cancelled.has(entity)));
if (data.hovered === isHovered && data.pressed === isPressed
&& data.justPressed === justPressed && data.justReleased === justReleased) continue;
data.hovered = isHovered;
diff --git a/sdk/src/ui/input/pointerBook.ts b/sdk/src/ui/input/pointerBook.ts
index 35ebe504e..9b112f78b 100644
--- a/sdk/src/ui/input/pointerBook.ts
+++ b/sdk/src/ui/input/pointerBook.ts
@@ -16,6 +16,7 @@
*/
import type { Entity } from '../../types';
import type { InputState } from '../../input/input';
+import { takePrimaryPointerCancellation } from '../../input/pointerCancellation';
/** 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. */
@@ -27,6 +28,7 @@ export interface UiPointerSample {
pressed: boolean;
released: boolean;
hovers: boolean;
+ cancelled?: boolean;
}
/** Per-pointer raycast results, retained only while the input frame carries the pointer. */
@@ -74,19 +76,24 @@ export function uiPointersOf(input: InputState): UiPointerSample[] {
}
return pointers;
}
- pointers.push({
+ const mouse: UiPointerSample = {
id: MOUSE_POINTER, x: input.mouseX, y: input.mouseY,
down: input.isMouseButtonDown(0),
pressed: input.isMouseButtonPressed(0),
released: input.isMouseButtonReleased(0),
hovers: true,
- });
+ };
+ if (takePrimaryPointerCancellation(input)) mouse.cancelled = true;
+ pointers.push(mouse);
return pointers;
}
export class UiPointerBook {
private hoveredBy_ = new Map<number, Entity>();
private pressedBy_ = new Map<number, Entity>();
+ private cancelled_ = new Set<Entity>();
+
+ get cancelled(): ReadonlySet<Entity> { return this.cancelled_; }
/** Entities at least one pointer is over. */
get hovered(): ReadonlySet<Entity> {
@@ -122,10 +129,16 @@ export class UiPointerBook {
alive: (entity: Entity) => boolean,
): UiPointerEvent[] {
const out: UiPointerEvent[] = [];
+ this.cancelled_.clear();
const live = new Set<number>();
for (const p of pointers) {
live.add(p.id);
+ if (p.cancelled) {
+ const held = this.pressedBy_.get(p.id);
+ if (held !== undefined) this.cancelled_.add(held);
+ this.pressedBy_.delete(p.id);
+ }
const under = hit(p);
const was = this.hoveredBy_.get(p.id) ?? null;
@@ -137,7 +150,7 @@ export class UiPointerBook {
else this.hoveredBy_.set(p.id, now);
}
- if (p.pressed && under !== null) {
+ if (p.pressed && !p.cancelled && under !== null) {
this.pressedBy_.set(p.id, under);
out.push({ kind: 'press', entity: under, pointer: p.id });
}
@@ -183,6 +196,7 @@ export class UiPointerBook {
/** Forget every pointer — a realm tearing its UI down owes no events. */
clear(): void {
+ this.cancelled_.clear();
this.hoveredBy_.clear();
this.pressedBy_.clear();
}
diff --git a/sdk/tests/input-callbacks.test.ts b/sdk/tests/input-callbacks.test.ts
index dfb11f237..fa4ef5b2c 100644
--- a/sdk/tests/input-callbacks.test.ts
+++ b/sdk/tests/input-callbacks.test.ts
@@ -35,6 +35,48 @@ describe('inputEventCallbacks', () => {
expect(state.isMouseButtonDown(0)).toBe(false);
expect(state.isMouseButtonReleased(0)).toBe(true);
});
+ it('a consumed key release clears held state without forwarding a release edge', () => {
+ const cb = inputEventCallbacks(state); cb.onKeyDown('ArrowRight');
+ const off = inputRouter.setEditorHandler({ onKeyUp: () => true });
+ try {
+ cb.onKeyUp('ArrowRight');
+ expect(state.isKeyDown('ArrowRight')).toBe(false);
+ expect(state.isKeyReleased('ArrowRight')).toBe(false);
+ state.beginFixedStep(); expect(state.isKeyReleased('ArrowRight')).toBe(false); state.endFixedStep();
+ } finally { off(); }
+ });
+ it('a consumed mouse release stops holding the button without a gameplay release edge', () => {
+ const cb = inputEventCallbacks(state); cb.onPointerDown(0, 1, 2);
+ const off = inputRouter.setUIHandler({ onPointerUp: () => true });
+ try {
+ cb.onPointerUp(0);
+ expect(state.isMouseButtonDown(0)).toBe(false);
+ expect(state.isMouseButtonReleased(0)).toBe(false);
+ state.beginFixedStep(); expect(state.isMouseButtonReleased(0)).toBe(false); state.endFixedStep();
+ } finally { off(); }
+ });
+ it.each(['onTouchEnd', 'onTouchCancel'] as const)('a consumed %s retires its live touch without an end edge', kind => {
+ const cb = inputEventCallbacks(state); cb.onTouchStart?.(1, 10, 20); cb.onTouchStart?.(2, 30, 40);
+ const off = inputRouter.setUIHandler({ [kind]: () => true });
+ try {
+ cb[kind]?.(1);
+ expect(state.isTouchActive(1)).toBe(false);
+ expect(state.isTouchActive(2)).toBe(true);
+ expect(state.touchesEnded.has(1)).toBe(false);
+ } finally { off(); }
+ });
+ it('does not manufacture release edges for presses owned by the editor', () => {
+ const cb = inputEventCallbacks(state);
+ const off = inputRouter.setEditorHandler({ onKeyDown: () => true, onPointerDown: () => true, onTouchStart: () => true });
+ try { cb.onKeyDown('Space'); cb.onPointerDown(0, 0, 0); cb.onTouchStart?.(3, 0, 0); }
+ finally { off(); }
+ cb.onTouchMove?.(3, 10, 20);
+ expect(state.isTouchActive(3)).toBe(false);
+ cb.onKeyUp('Space'); cb.onPointerUp(0); cb.onTouchEnd?.(3);
+ expect(state.isKeyReleased('Space')).toBe(false);
+ expect(state.isMouseButtonReleased(0)).toBe(false);
+ expect(state.touchesEnded.size).toBe(0);
+ });
it('tracks the cursor on a move without pressing anything', () => {
const cb = inputEventCallbacks(state);
diff --git a/sdk/tests/ui-pointer-callback-wasm.test.ts b/sdk/tests/ui-pointer-callback-wasm.test.ts
index 314153b12..6203e5861 100644
--- a/sdk/tests/ui-pointer-callback-wasm.test.ts
+++ b/sdk/tests/ui-pointer-callback-wasm.test.ts
@@ -4,7 +4,7 @@ import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vite
import { App, flushPendingRegistrations } from '../src/app/app';
import { AppContext, setDefaultContext } from '../src/ecs/context';
import { setEditorMode, setPlayMode } from '../src/ecs/env';
-import { Input, InputState } from '../src/input/input';
+import { Input, InputState, inputEventCallbacks } from '../src/input/input';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { ScreenOverlay } from '../src/ui/core/screen-overlay';
import { UILayoutGeneration } from '../src/ui/layout/ui-layout-generation';
@@ -43,6 +43,17 @@ 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('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();
+ app.getResource(UIEvents).on(entity, 'click', clicked);
+ callbacks.onPointerDown(0, 0, 0); await app.tick(1 / 60); input.clearFrameState();
+ const off = inputRouter.setEditorHandler({ onPointerUp: () => true });
+ try { callbacks.onPointerUp(0); } finally { off(); }
+ input.clearFrameState(); await app.tick(1 / 60);
+ expect(clicked).not.toHaveBeenCalled();
+ expect(app.world.get(entity, UIInteraction)).toMatchObject({ pressed: false, justReleased: false });
+ });
it('expires a cancelled gesture marker before a later quick click on real WASM', async () => {
const entity = app.world.spawn(); hit.entity = entity; app.world.insert(entity, Interactable);
const input = app.getResource(Input), clicked = vi.fn();
diff --git a/sdk/tests/ui-quick-click-focus.test.ts b/sdk/tests/ui-quick-click-focus.test.ts
index ad39e991f..53344e919 100644
--- a/sdk/tests/ui-quick-click-focus.test.ts
+++ b/sdk/tests/ui-quick-click-focus.test.ts
@@ -3,7 +3,7 @@
import { describe, it, expect, vi } from 'vitest';
import { bootMockApp } from './helpers/mockApp';
import { flushPendingRegistrations } from '../src/app/app';
-import { Input, InputState } from '../src/input/input';
+import { Input, InputState, inputEventCallbacks } from '../src/input/input';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
import { ScreenOverlay } from '../src/ui/core/screen-overlay';
import { UILayoutGeneration } from '../src/ui/layout/ui-layout-generation';
@@ -25,6 +25,25 @@ vi.mock('../src/ui/util/ui-pick', () => ({
}));
describe('quick pointer focus through real interaction projection', () => {
+ it.each(['quick', 'held', 'cleared'])('a consumed release cancels UI capture without clicking through: %s', async phase => {
+ const { app } = bootMockApp(); const input = new InputState();
+ app.insertResource(Input, input); app.insertResource(UICameraInfo, { valid: false } as any);
+ app.insertResource(ScreenOverlay, { active: true, surfaceH: 600 } as any);
+ app.addPlugin(uiLayoutPlugin); app.addPlugin(new UIInteractionPlugin()); flushPendingRegistrations(app);
+ const entity = app.world.spawn(); app.world.insert(entity, Interactable); hit.entity = entity;
+ const clicked = vi.fn(); app.getResource(UIEvents).on(entity, 'click', clicked);
+ const callbacks = inputEventCallbacks(input);
+ callbacks.onPointerDown(0, 0, 0);
+ if (phase !== 'quick') { await app.tick(1 / 60); input.clearFrameState(); }
+ const off = inputRouter.setEditorHandler({ onPointerUp: () => true });
+ try { callbacks.onPointerUp(0); } finally { off(); }
+ if (phase === 'cleared') input.clearFrameState();
+ await app.tick(1 / 60);
+ expect(clicked).not.toHaveBeenCalled();
+ expect(app.world.get(entity, UIInteraction).pressed).toBe(false);
+ expect(app.world.get(entity, UIInteraction).justPressed).toBe(false);
+ app.quit();
+ });
it('does not let a disabled gesture suppress a later quick tap after re-enabling', async () => {
const { app } = bootMockApp(); const input = new InputState();
app.insertResource(Input, input); app.insertResource(UICameraInfo, { valid: false } as any);
diff --git a/sdk/tests/web-keyboard-handoff.test.ts b/sdk/tests/web-keyboard-handoff.test.ts
index 021a4bf56..db366da46 100644
--- a/sdk/tests/web-keyboard-handoff.test.ts
+++ b/sdk/tests/web-keyboard-handoff.test.ts
@@ -3,6 +3,8 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import { webAdapter } from '../src/platform/web';
import { createWebTextEditor } from '../src/platform/webTextEditor';
+import { InputState, inputEventCallbacks } from '../src/input/input';
+import { inputRouter } from '../src/input/inputRouter';
function bind() {
const canvas = document.createElement('canvas');
@@ -25,6 +27,17 @@ afterEach(() => {
});
describe('Web keyboard handoff', () => {
+ it('blur clears a gameplay key even when the editor claims the release', () => {
+ const canvas = document.createElement('canvas'); document.body.appendChild(canvas);
+ const state = new InputState(); webAdapter.bindInputEvents(inputEventCallbacks(state), canvas);
+ key(document.body, 'ArrowRight'); expect(state.isKeyDown('ArrowRight')).toBe(true);
+ const off = inputRouter.setEditorHandler({ onKeyUp: () => true });
+ try {
+ window.dispatchEvent(new Event('blur'));
+ expect(state.isKeyDown('ArrowRight')).toBe(false);
+ expect(state.isKeyReleased('ArrowRight')).toBe(false);
+ } finally { off(); }
+ });
it('cancels defaults only when the callback claims the key', () => {
const callbacks = bind();
expect(key(document.body, 'Tab').defaultPrevented).toBe(true);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 28cd6708c..bf6dbc099 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): retire held state when release events are consumed':
+ { note: 'Claimed input releases cannot leave gameplay controls held.' },
'fix(ui): release gesture bindings and expire cancelled click markers':
{ note: 'UI gesture bindings expire with their targets and App.' },
'fix(ui): scope safe-area resize subscriptions to their apps':