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
fix(ui): release gesture bindings and expire cancelled click markers
yhheb8d1a1443fc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cc1e17a64..899470d12 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **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.- **Camera fitting and editor previews use outer canvases consistently.** A nested canvas appearing first no longer overrides the scene design resolution or becomes the default host for new UI. Scene-filtered camera collection uses a running scene's outer canvas, and preview selection queries Canvas components directly. The experimental `canvasRootEntities` helper shares root selection across runtime and editor workflows.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex aee4c561f..f7aed501d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -9265,6 +9265,7 @@ pressed: boolean## UIInteractionPlugin — class @experimental```build: (app: App) => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "uiInteraction"static new (): UIInteractionPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex afa806311..f039db7af 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -9469,6 +9469,7 @@ pressed: boolean## UIInteractionPlugin — class @experimental```build: (app: App) => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "uiInteraction"static new (): UIInteractionPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 884ed6ba9..c9b3071d9 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -9260,6 +9260,7 @@ pressed: boolean## UIInteractionPlugin — class @experimental```build: (app: App) => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "uiInteraction"static new (): UIInteractionPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7719b2f5f..98024f95b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -9533,6 +9533,7 @@ pressed: boolean## UIInteractionPlugin — class @experimental```build: (app: App) => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "uiInteraction"static new (): UIInteractionPlugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 48cfac654..0fe2d5388 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -9267,6 +9267,7 @@ pressed: boolean## UIInteractionPlugin — class @experimental```build: (app: App) => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "uiInteraction"static new (): UIInteractionPlugindiff --git a/sdk/src/ui/input/gestureClick.ts b/sdk/src/ui/input/gestureClick.tsindex 75a176d6a..b32cf9b12 100644--- a/sdk/src/ui/input/gestureClick.ts+++ b/sdk/src/ui/input/gestureClick.ts@@ -20,12 +20,21 @@ const registries = new WeakMap<World, Registry>();function registryOf(world: World): Registry {let r = registries.get(world);- if (!r) registries.set(world, r = { handlers: new Map(), fired: new Set() });+ if (!r) {+ r = { handlers: new Map(), fired: new Set() };+ registries.set(world, r);+ const owned = r;+ world.onDespawn(entity => {+ owned.handlers.delete(entity);+ owned.fired.delete(entity);+ });+ }return r;}/** Run @p onClick inside the release event that clicks @p entity. */export function onGestureClick(world: World, entity: Entity, onClick: () => void): () => void {+ if (!world.valid(entity) || world.isDestructionPending?.(entity)) return () => {};const r = registryOf(world);r.handlers.set(entity, onClick);return () => {@@ -35,6 +44,7 @@ export function onGestureClick(world: World, entity: Entity, onClick: () => void/** @internal Click @p entity now, if it asked for its clicks here. */export function fireGestureClick(world: World, entity: Entity): boolean {+ if (!world.valid(entity) || world.isDestructionPending?.(entity)) return false;const r = registries.get(world);const onClick = r?.handlers.get(entity);if (!r || !onClick) return false;@@ -49,3 +59,8 @@ export function takeGestureFired(world: World, entity: Entity): boolean {const r = registries.get(world);return !!r?.fired.delete(entity);}++/** @internal Release markers whose corresponding frame click was cancelled or unobserved. */+export function expireGestureFired(world: World): void {+ registries.get(world)?.fired.clear();+}diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.tsindex 5ba5059ab..8a397f71a 100644--- a/sdk/src/ui/input/interaction.ts+++ b/sdk/src/ui/input/interaction.ts@@ -25,7 +25,7 @@ import type { CppRegistry } from '../../wasm';import { engineApi } from '../../ecs/bridge/engineApi';import { UILayoutGeneration } from '../layout/ui-layout-generation';import { UiPointerBook, UiPointerHitCache, uiPointersOf, MOUSE_POINTER, type UiPointerSample } from './pointerBook';-import { fireGestureClick } from './gestureClick';+import { fireGestureClick, expireGestureFired } from './gestureClick';import { inputRouter } from '../../input/inputRouter';import { SystemLabel, PluginName } from '../../ecs/systemLabels';import type { UILayoutGenerationData } from '../layout/ui-layout-generation';@@ -54,7 +54,17 @@ export class UIInteractionPlugin implements Plugin {name = PluginName.UIInteraction;dependencies = [PluginName.UILayout];+ private readonly releases_ = new WeakMap<App, () => void>();++ cleanup(app?: App): void {+ if (!app) return;+ const release = this.releases_.get(app);+ this.releases_.delete(app);+ release?.();+ }+build(app: App): void {+ this.cleanup(app);registerComponent('Interactable', Interactable);registerComponent('UIInteraction', UIInteraction);@@ -86,10 +96,16 @@ export class UIInteractionPlugin implements Plugin {if (world.has(held, Interactable) && !(world.get(held, Interactable) as InteractableData).enabled) return;fireGestureClick(world, held);};- inputRouter.setUIHandler({+ const unregister = inputRouter.setUIHandler({onTouchEnd: (id) => { releaseInGesture(id); },onPointerUp: (button) => { if (button === 0) releaseInGesture(MOUSE_POINTER); },});+ this.releases_.set(app, () => {+ unregister();+ book.clear();+ lastHit.clear();+ expireGestureFired(world);+ });app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([Res(Input), Res(UICameraInfo), Res(ScreenOverlay), Res(UILayoutGeneration)],@@ -229,6 +245,7 @@ export class UIInteractionPlugin implements Plugin {const entity = lastHit.get(pointer.id)?.entity;return entity != null && active(entity);});+ expireGestureFired(world);},{ name: 'UIInteractionSystem' }), { runAfter: [SystemLabel.UILayout], runIf: playModeOnly });diff --git a/sdk/tests/ui-gesture-lifecycle.test.ts b/sdk/tests/ui-gesture-lifecycle.test.tsnew file mode 100644index 000000000..b9a4aa89a--- /dev/null+++ b/sdk/tests/ui-gesture-lifecycle.test.ts@@ -0,0 +1,43 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { expect, it, vi } from 'vitest';+import { World } from '../src/ecs/world';+import { onGestureClick, fireGestureClick, takeGestureFired } from '../src/ui/input/gestureClick';++it('despawning a gesture target removes its callback and pending frame marker', () => {+ const world = new World(), entity = world.spawn(), clicked = vi.fn();+ onGestureClick(world, entity, clicked);+ expect(fireGestureClick(world, entity)).toBe(true);+ world.despawn(entity);+ expect(takeGestureFired(world, entity)).toBe(false);+ expect(fireGestureClick(world, entity)).toBe(false);+ expect(clicked).toHaveBeenCalledOnce();+});+it('does not retain a registration made for an already destroyed target', () => {+ const world = new World(), entity = world.spawn(), clicked = vi.fn();+ world.despawn(entity); onGestureClick(world, entity, clicked);+ expect(fireGestureClick(world, entity)).toBe(false);+ expect(clicked).not.toHaveBeenCalled();+});+it('does not install a gesture during the target destruction notification', () => {+ const world = new World(), entity = world.spawn(), clicked = vi.fn();+ world.onDespawn(target => onGestureClick(world, target, clicked));+ world.despawn(entity);+ expect(world.getStorageSizes().despawnCallbacks).toBe(1);+ expect(fireGestureClick(world, entity)).toBe(false);+});+it('target destruction inside its gesture clears the pending frame marker immediately', () => {+ const world = new World(), entity = world.spawn();+ onGestureClick(world, entity, () => world.despawn(entity));+ expect(fireGestureClick(world, entity)).toBe(true);+ expect(takeGestureFired(world, entity)).toBe(false);+});+it('shares one despawn observer across repeated gesture target lifetimes', () => {+ const world = new World(), before = world.getStorageSizes().despawnCallbacks;+ for (let i = 0; i < 1000; i++) {+ const entity = world.spawn(); onGestureClick(world, entity, () => {});+ fireGestureClick(world, entity); world.despawn(entity);+ expect(takeGestureFired(world, entity)).toBe(false);+ }+ expect(world.getStorageSizes().despawnCallbacks).toBe(before + 1);+});diff --git a/sdk/tests/ui-pointer-callback-wasm.test.ts b/sdk/tests/ui-pointer-callback-wasm.test.tsindex 0d86b9839..314153b12 100644--- a/sdk/tests/ui-pointer-callback-wasm.test.ts+++ b/sdk/tests/ui-pointer-callback-wasm.test.ts@@ -12,6 +12,8 @@ import { Interactable, UIInteraction } from '../src/ui/input/interactable';import { uiInteractionPlugin } from '../src/ui/input/interaction';import { UiPointerHitCache, MOUSE_POINTER } from '../src/ui/input/pointerBook';import { UIEvents } from '../src/ui/core/events';+import { onGestureClick, fireGestureClick, takeGestureFired } from '../src/ui/input/gestureClick';+import { inputRouter } from '../src/input/inputRouter';import type { CppRegistry, ESEngineModule } from '../src/wasm';import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';const hit = vi.hoisted(() => ({ entity: null as number | null }));@@ -36,10 +38,39 @@ describe.skipIf(!HAS_WASM)('pointer callback lifecycle on real WASM', () => {uiInteractionPlugin.build(app); flushPendingRegistrations(app);});afterEach(() => {+ uiInteractionPlugin.cleanup(app);vi.restoreAllMocks();for (const entity of app.world.getAllEntities()) app.world.despawn(entity);app.world.disconnectCpp(); registry.delete();});+ 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();+ onGestureClick(app.world, entity, () => {+ clicked(); app.world.update(entity, Interactable, value => { value.enabled = false; });+ });+ app.getResource(UIEvents).on(entity, 'click', () => {+ if (!takeGestureFired(app.world, entity)) clicked();+ });+ input.noteMouseDown(0); await app.tick(1 / 60); input.clearFrameState();+ inputRouter.dispatchPointerUp(0); input.noteMouseUp(0); await app.tick(1 / 60); input.clearFrameState();+ app.world.update(entity, Interactable, value => { value.enabled = true; });+ input.noteMouseDown(0); input.noteMouseUp(0); await app.tick(1 / 60);+ expect(clicked).toHaveBeenCalledTimes(2);+ });+ it('cleans gesture registrations and markers across real WASM target lifetimes', () => {+ const before = app.world.getStorageSizes().despawnCallbacks;+ for (let i = 0; i < 1000; i++) {+ const entity = app.world.spawn(); const clicked = vi.fn();+ onGestureClick(app.world, entity, clicked);+ expect(fireGestureClick(app.world, entity)).toBe(true);+ app.world.despawn(entity);+ expect(fireGestureClick(app.world, entity)).toBe(false);+ expect(takeGestureFired(app.world, entity)).toBe(false);+ expect(clicked).toHaveBeenCalledOnce();+ }+ expect(app.world.getStorageSizes().despawnCallbacks).toBe(before + 1);+ });it('does not retain past touch IDs across 1000 real interaction updates', async () => {const entity = app.world.spawn(); hit.entity = entity;app.world.insert(entity, Interactable, { enabled: true });diff --git a/sdk/tests/ui-quick-click-focus.test.ts b/sdk/tests/ui-quick-click-focus.test.tsindex 9a3c033fe..ad39e991f 100644--- a/sdk/tests/ui-quick-click-focus.test.ts+++ b/sdk/tests/ui-quick-click-focus.test.ts@@ -10,11 +10,12 @@ import { UILayoutGeneration } from '../src/ui/layout/ui-layout-generation';import { UIInteraction, Interactable } from '../src/ui/input/interactable';import { Focusable, FocusManager } from '../src/ui/input/focusable';import { focusPlugin } from '../src/ui/input/focus';-import { uiInteractionPlugin } from '../src/ui/input/interaction';+import { UIInteractionPlugin, uiInteractionPlugin } from '../src/ui/input/interaction';+import { uiLayoutPlugin } from '../src/ui/layout/layout';import { UIEvents } from '../src/ui/core/events';import { setEntityActive } from '../src/ecs/entityUtils';import { inputRouter } from '../src/input/inputRouter';-import { onGestureClick } from '../src/ui/input/gestureClick';+import { onGestureClick, takeGestureFired } from '../src/ui/input/gestureClick';import { getComponent } from '../src/ecs/component';import { inspectableTypes } from '../src/runtime/worldSnapshot';const hit = vi.hoisted(() => ({ entity: null as number | null }));@@ -24,6 +25,56 @@ vi.mock('../src/ui/util/ui-pick', () => ({}));describe('quick pointer focus through real interaction projection', () => {+ 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);+ 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();+ onGestureClick(app.world, entity, () => {+ clicked(); app.world.update(entity, Interactable, data => { data.enabled = false; });+ });+ app.getResource(UIEvents).on(entity, 'click', () => {+ if (!takeGestureFired(app.world, entity)) clicked();+ });+ input.noteMouseDown(0); await app.tick(1 / 60); input.clearFrameState();+ inputRouter.dispatchPointerUp(0); input.noteMouseUp(0); await app.tick(1 / 60);+ expect(clicked).toHaveBeenCalledOnce(); input.clearFrameState();+ app.world.update(entity, Interactable, data => { data.enabled = true; });+ input.noteMouseDown(0); input.noteMouseUp(0); await app.tick(1 / 60);+ expect(clicked).toHaveBeenCalledTimes(2); app.quit();+ });+ it('quitting an app unregisters its UI release handler', async () => {+ 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;+ input.noteMouseDown(0); await app.tick(1 / 60);+ app.quit();+ const read = vi.spyOn(app.world, 'isEntityActive');+ inputRouter.dispatchPointerUp(0);+ expect(read).not.toHaveBeenCalled(); read.mockRestore();+ });+ it('quitting an older app leaves the newer app gesture handler installed', async () => {+ const plugin = new UIInteractionPlugin();+ const capture = async () => {+ 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(plugin); flushPendingRegistrations(app);+ const entity = app.world.spawn(); app.world.insert(entity, Interactable); hit.entity = entity;+ input.noteMouseDown(0); await app.tick(1 / 60);+ return { app, entity };+ };+ const first = await capture(), second = await capture(), clicked = vi.fn();+ onGestureClick(second.app.world, second.entity, clicked);+ first.app.quit(); inputRouter.dispatchPointerUp(0);+ expect(clicked).toHaveBeenCalledOnce();+ second.app.quit();+ });it.each(['hover_enter', 'press', 'release'])('stops a queued click when %s disables the control', async phase => {const { app } = bootMockApp(); const input = new InputState();app.insertResource(Input, input);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 2502a0aa6..28cd6708c 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(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':{ note: 'Safe-area resize listeners belong to their App.' },'fix(camera): align canvas fitting with hierarchy and scene filters':