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(events): expose immutable dispatch observations for UI debugger (#75)
YHHfff60ed5ba29
diff --git a/desktop b/desktopindex 211335e64..87217f1a2 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 211335e643b447e7360942dc7336294ea4123ea5+Subproject commit 87217f1a2247483b24b4800a58cf21d4a2a02d60diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 0058db530..137c9270f 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 103,- "experimental": 2168,+ "experimental": 2169,"deprecated": 3},- "total": 2386,+ "total": 2387,"subsystems": [{"id": "ecs",diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.mdindex e0e64713a..8e9de4d99 100644--- a/examples/ui-localization-debug/README.md+++ b/examples/ui-localization-debug/README.md@@ -37,5 +37,18 @@ not proof of actual game event delivery. Only one hovered editor element getsan extra outline. No clipping estimates or automatic input-success verdictsare presented. Text and Focus order remain auxiliary snapshot views.-This is a partial RM-009 delivery. Actual event tracing, platform shaping,+This is a partial RM-009 delivery. Actual running-game event acceptance, platform shaping,IME/device acceptance and layout cache performance remain separate work.+++Events is an opt-in recorder of the entity event channel used by UI, including+custom event types. Start recording during Play, operate the game, then stop+to inspect the recorded target and actual dispatch nodes. Each node records+propagation/default flags after its handlers. Filter retains all recorded+steps of matching events; selecting a node opens its runtime details.++The recorder keeps at most 200 dispatch rows and reports discarded rows, so+a displayed path can be incomplete. It excludes payloads, never drains the+game queue and detaches on stop or session teardown. No records alone are+not a fault verdict. Ordinary Web fixture dispatch checks do not establish+actual game pointer delivery or device acceptance.diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.mdindex f3e86b30a..25319f685 100644--- a/examples/ui-localization-debug/VALIDATION.md+++ b/examples/ui-localization-debug/VALIDATION.md@@ -126,3 +126,27 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.Select show no UI resize handles; Rect shows them; switching back hides them.Clicking adjacent Partial selects it. Show all restores the camera icon andselected-only hides it again. No local Electron/native runner was launched.+++## UI Debugger event observation — 2026-10-09++- Engine #74 and editor #11 merged after successful current-head checks.+ Engine Android API 29–36 checks passed; editor Typecheck + tests passed.+- SDK observer reports immutable post-handler dispatch facts without payload+ or event mutation methods. It does not register a game listener or consume+ pending events. Root and actual bubble dispatches share an identity.+- SDK: 4 observer tests plus 18 existing UI event tests pass. Editor: 26+ recorder/panel/picking/i18n/menu tests pass, including stop/clear, queue+ replacement, bounded retention, payload exclusion and runtime selection.+- Built-in WebGL2 fixture: 32/32 passes. Five new checks use the real SDK+ queue and handlers for propagation/default prevention. They do not simulate+ actual pointer hit-testing or establish running-game delivery acceptance.+- Manual browser check: Events tab is disabled outside Play and explains its+ empty state without a fault verdict. Theme styling matches the panel.+- Recording defaults off, stores at most 200 dispatch rows, polls at 250 ms+ with requests coalesced and releases on stop/unmount/session teardown.+ History truncation is explicit. Filtering retains matching event paths.+- Typecheck, production build, CSS-variable gate, SDK build and 16 built API+ declaration checks pass. No local Electron/native runner was launched.+- Actual Play pointer dispatch, devices, IME/accessibility, shaping and+ performance acceptance remain open. RM-009 remains In Progress.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 3bfde7b92..d46c29b1c 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: 115 public · 91 beta · 1552 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1553 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3447,6 +3447,16 @@ type: string(event: EntityEvent<TData>) => void```+## EntityEventObservation — interface @experimental+```+currentTarget: number+defaultPrevented: boolean+eventId: number+propagationStopped: boolean+target: number+type: string+```+## EntityEventQueue — class @experimental```clear: () => void@@ -3454,6 +3464,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => void@@ -9200,6 +9211,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c6423114c..9542c8fe1 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: 115 public · 96 beta · 1571 experimental · 3 deprecated+Symbols: 115 public · 96 beta · 1572 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3455,6 +3455,16 @@ type: string(event: EntityEvent<TData>) => void```+## EntityEventObservation — interface @experimental+```+currentTarget: number+defaultPrevented: boolean+eventId: number+propagationStopped: boolean+target: number+type: string+```+## EntityEventQueue — class @experimental```clear: () => void@@ -3462,6 +3472,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => void@@ -9401,6 +9412,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 13b64c056..b9e4c9906 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: 115 public · 93 beta · 1551 experimental · 3 deprecated+Symbols: 115 public · 93 beta · 1552 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3442,6 +3442,16 @@ type: string(event: EntityEvent<TData>) => void```+## EntityEventObservation — interface @experimental+```+currentTarget: number+defaultPrevented: boolean+eventId: number+propagationStopped: boolean+target: number+type: string+```+## EntityEventQueue — class @experimental```clear: () => void@@ -3449,6 +3459,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => void@@ -9195,6 +9206,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex b96d44f1e..7b4f49dc6 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: 115 public · 91 beta · 1573 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1574 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3442,6 +3442,16 @@ type: string(event: EntityEvent<TData>) => void```+## EntityEventObservation — interface @experimental+```+currentTarget: number+defaultPrevented: boolean+eventId: number+propagationStopped: boolean+target: number+type: string+```+## EntityEventQueue — class @experimental```clear: () => void@@ -3449,6 +3459,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => void@@ -9468,6 +9479,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 881887eea..9f46a56c9 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: 115 public · 91 beta · 1564 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1565 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3442,6 +3442,16 @@ type: string(event: EntityEvent<TData>) => void```+## EntityEventObservation — interface @experimental+```+currentTarget: number+defaultPrevented: boolean+eventId: number+propagationStopped: boolean+target: number+type: string+```+## EntityEventQueue — class @experimental```clear: () => void@@ -3449,6 +3459,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => void@@ -9202,6 +9213,7 @@ drain: () => readonly EntityEvent[]emit: <TData = unknown>(entity: Entity, type: string, data?: TData) => EntityEvent<TData>emitBubbled: (ancestor: Entity, rootEvent: EntityEvent) => EntityEventhasListenersFor: (type: string) => boolean+observe: (handler: (event: EntityEventObservation) => void) => Unsubscribeon: { (entity: Entity, type: string, handler: EntityEventHandler): Unsubscribe; (type: string, handler: EntityEventHandler): Unsubscribe; }query: (type: string) => readonly EntityEvent[]removeAll: (entity: Entity) => voiddiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 8db3e16df..9ff0c83df 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -383,6 +383,7 @@ export {EntityEvents,type EntityEvent,type EntityEventHandler,+ type EntityEventObservation,} from './ecs/entityEvents';// Authored event → action wiring (the data form of `events.on(e, 'click', …)`).diff --git a/sdk/src/ecs/entityEvents.ts b/sdk/src/ecs/entityEvents.tsindex ffc7f5a9b..397c07249 100644--- a/sdk/src/ecs/entityEvents.ts+++ b/sdk/src/ecs/entityEvents.ts@@ -43,6 +43,16 @@ export interface EntityEvent<TData = unknown> {preventDefault(): void;}+/** Immutable dispatch facts for debugger observers; no payload or mutation methods. */+export interface EntityEventObservation {+ readonly eventId: number;+ readonly type: string;+ readonly target: Entity;+ readonly currentTarget: Entity;+ readonly propagationStopped: boolean;+ readonly defaultPrevented: boolean;+}+export type EntityEventHandler<TData = unknown> = (event: EntityEvent<TData>) => void;export type Unsubscribe = () => void;@@ -123,6 +133,17 @@ export class EntityEventQueue {private pending_: EntityEvent[] = [];private readonly activeKeys_ = new Set<string>();+ private readonly observers_ = new Set<(event: EntityEventObservation) => void>();+ private readonly eventIds_ = new WeakMap<EntityEvent, number>();+ private nextEventId_ = 0;++ /** Observe actual dispatch after handlers, without subscribing as a game listener.+ * Observers cannot stop propagation, prevent defaults or change the payload. */+ observe(handler: (event: EntityEventObservation) => void): Unsubscribe {+ this.observers_.add(handler);+ return () => { this.observers_.delete(handler); };+ }+/*** Subscribe to an entity-specific event.* Returns an unsubscribe function.@@ -229,6 +250,7 @@ export class EntityEventQueue {data?: TData,): EntityEvent<TData> {const event = new EmittedEvent<TData>(type, entity, entity, data as TData);+ if (this.observers_.size) this.eventIds_.set(event, ++this.nextEventId_);this.pending_.push(event);this.dispatch_(entity, event);return event;@@ -247,6 +269,11 @@ export class EntityEventQueue {const bubbled = new BubbledEvent(rootEvent.type, rootEvent.target, ancestor, rootEvent.data, rootEvent);+ if (this.observers_.size) {+ const id = this.eventIds_.get(rootEvent) ?? ++this.nextEventId_;+ this.eventIds_.set(rootEvent, id);+ this.eventIds_.set(bubbled, id);+ }this.pending_.push(bubbled);this.dispatch_(ancestor, bubbled);return bubbled;@@ -273,6 +300,7 @@ export class EntityEventQueue {this.globalHandlers_.clear();this.pending_ = [];this.activeKeys_.clear();+ this.observers_.clear();}private dispatch_(entity: Entity, event: EntityEvent): void {@@ -318,6 +346,16 @@ export class EntityEventQueue {}} finally {this.activeKeys_.delete(key);+ if (this.observers_.size) {+ const eventId = this.eventIds_.get(event) ?? ++this.nextEventId_;+ this.eventIds_.set(event, eventId);+ const observation = Object.freeze({ eventId, type: event.type, target: event.target,+ currentTarget: event.currentTarget, propagationStopped: event.propagationStopped,+ defaultPrevented: event.defaultPrevented });+ for (const observer of [...this.observers_]) {+ try { observer(observation); } catch (err) { log.error('ui', 'Entity event observer error', err); }+ }+ }}}}diff --git a/sdk/tests/entity-event-observation.test.ts b/sdk/tests/entity-event-observation.test.tsnew file mode 100644index 000000000..000cb045e--- /dev/null+++ b/sdk/tests/entity-event-observation.test.ts@@ -0,0 +1,32 @@+// SPDX-License-Identifier: Apache-2.0+import { describe, expect, it } from 'vitest';+import { EntityEventQueue } from '../src/ecs/entityEvents';+import type { Entity, EntityEventObservation } from '../src';+describe('dispatch observation', () => {+ it('records completed target and actual bubble steps with one event identity', () => {+ const q = new EntityEventQueue(), seen: EntityEventObservation[] = [];+ q.on(2 as Entity, 'click', event => { event.preventDefault(); event.stopPropagation(); });+ q.observe(event => seen.push(event));+ const root = q.emit(1 as Entity, 'click', { privateText: 'not recorded' });+ q.emitBubbled(2 as Entity, root); q.emitBubbled(3 as Entity, root);+ expect(seen.map(row => row.currentTarget)).toEqual([1, 2]);+ expect(seen[1].eventId).toBe(seen[0].eventId);+ expect(seen[1]).toMatchObject({ target: 1, propagationStopped: true, defaultPrevented: true });+ expect(seen[0]).toMatchObject({ propagationStopped: false, defaultPrevented: false });+ expect(Object.isFrozen(seen[0])).toBe(true); expect('data' in seen[0]).toBe(false);+ expect(q.drain()).toHaveLength(2);+ });+ it('does not become a producer listener and detaches without draining', () => {+ const q = new EntityEventQueue(), seen: EntityEventObservation[] = [];+ const off = q.observe(event => seen.push(event)); expect(q.hasListenersFor('shown')).toBe(false);+ q.emit(1 as Entity, 'shown'); off(); off(); q.emit(1 as Entity, 'shown');+ expect(seen).toHaveLength(1); expect(q.query('shown')).toHaveLength(2);+ });+ it('keeps nested events distinct and omits suppressed recursive dispatch', () => {+ const q = new EntityEventQueue(), seen: EntityEventObservation[] = [];+ q.observe(event => seen.push(event)); q.on(1 as Entity, 'click', () => { q.emit(1 as Entity, 'click'); q.emit(2 as Entity, 'change'); });+ q.emit(1 as Entity, 'click'); expect(seen.map(row => row.type)).toEqual(['change', 'click']);+ expect(seen[0].eventId).not.toBe(seen[1].eventId); expect(q.drain()).toHaveLength(3);+ });+ it('clear releases observers', () => { const q = new EntityEventQueue(), seen: unknown[] = []; q.observe(e=>seen.push(e)); q.clear(); q.emit(1 as Entity,'click'); expect(seen).toHaveLength(0); });+});diff --git a/tools/ui-localization-browser.tsx b/tools/ui-localization-browser.tsxindex fdd97f1c1..f59d865fe 100644--- a/tools/ui-localization-browser.tsx+++ b/tools/ui-localization-browser.tsx@@ -6,8 +6,9 @@ import { SceneModel } from '../desktop/src/engine/SceneModel';import { SceneCommands } from '../desktop/src/engine/SceneCommands';import { ViewportController } from '../desktop/src/engine/ViewportController';import { uiDebuggerTree, readUIElement } from '../desktop/src/panels/uiDebuggerData';+import { UIEventTrace } from '../desktop/src/engine/uiEventTrace';import { useEditorStore } from '../desktop/src/store/editorStore';-import { inspectTextLayout, pseudoLocalize, MaskMode } from 'esengine';+import { inspectTextLayout, pseudoLocalize, MaskMode, EntityEventQueue } from 'esengine';const status = document.createElement('pre');status.style.cssText = 'position:fixed;left:20px;bottom:20px;z-index:1001;max-width:600px;background:#19191d;color:white;padding:12px';@@ -72,6 +73,21 @@ const canvasRect = EngineHost.canvas!.getBoundingClientRect();const point = { x: canvasRect.left + screenRect.x + screenRect.w / 2, y: canvasRect.top + screenRect.y + screenRect.h / 2 };check(ViewportController.pickUIEntity(point.x, point.y) === inside.entity, 'Debugger selection uses the real engine editor picker');check(JSON.stringify(SceneModel.serialize()) === maskBefore, 'Debugger reads and editor picking preserve scene data');+// Actual SDK dispatch/bubbling through the recorder; not a pointer-delivery assertion.+const queue = new EntityEventQueue();+const eventTrace = new UIEventTrace(id => `Node${id}`);+queue.on(2 as never, 'click', event => { event.stopPropagation(); event.preventDefault(); });+eventTrace.control(queue, 'start');+const click = queue.emit(1 as never, 'click', { text: 'payload excluded' });+queue.emitBubbled(2 as never, click); queue.emitBubbled(3 as never, click);+const trace = eventTrace.control(queue, 'read');+check(trace.rows.map(row => row.currentTarget).join(',') === '1,2', 'Trace records only actual dispatch nodes');+check(trace.rows[0].eventId === trace.rows[1].eventId, 'Target and bubble share one event identity');+check(trace.rows[1].propagationStopped && trace.rows[1].defaultPrevented, 'Trace captures flags after real handlers');+check(!('data' in trace.rows[0]) && queue.drain().length === 2, 'Observer excludes payload and does not consume game events');+eventTrace.control(queue, 'stop'); queue.emit(1 as never, 'release');+check(eventTrace.control(queue, 'read').rows.length === 2, 'Stopped recorder receives no new events');+eventTrace.dispose();status.textContent += `RESULT ${passed} passed, ${failed} failed · ${EngineHost.activeBackend}`;const dismiss = document.createElement('button');dismiss.textContent = 'Dismiss verification report';