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.

test(ui): verify actual pointer dispatch in browser Play (#76)

YHHeb30c657593c
diff --git a/desktop b/desktop
index 87217f1a2..243331363 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 87217f1a2247483b24b4800a58cf21d4a2a02d60
+Subproject commit 2433313635d09e5bb5e11d1dbadb535facbef810
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 8e9de4d99..f4aa595b4 100644
--- a/examples/ui-localization-debug/README.md
+++ b/examples/ui-localization-debug/README.md
@@ -52,3 +52,23 @@ 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.
+
+
+To verify actual Play pointer delivery in an ordinary browser, build the SDK
+and editor host artifacts, then run `node tools/ui-events-play-browser.mjs`
+from the repository root and open http://127.0.0.1:5195/__events-play. This
+stages the official Play page/host, SDK and WASM through buildPlayRealm. A
+test-server-only URL substitution maps the native project URL to localhost;
+the production protocol, picking, project script and Events panel run intact.
+
+Start Play, record, and click Inside: its text counter increments and width
+alternates 120/160; its click reaches InnerMask, OuterMask and Canvas. Click
+Partial in its visible region: InnerMask stops propagation and prevents the
+default. These fixture ancestors intentionally have Interactable enabled
+with raycastTarget/blockRaycast false. Ordinary layout parents are skipped
+by UI bubbling; blockRaycast can end the walk without stopPropagation.
+
+Stop recording and click again: game reactions continue, history stays fixed.
+Toggle the panel off and read the diagnostic snapshot to verify recording is
+false. Stop/Start Play rebuilds the world; recording defaults off with no old
+history. This covers browser Play, not desktop custom-scheme or device QA.
diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.md
index 25319f685..6f2a6f5ed 100644
--- a/examples/ui-localization-debug/VALIDATION.md
+++ b/examples/ui-localization-debug/VALIDATION.md
@@ -150,3 +150,30 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.
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.
+
+
+## Actual Play pointer dispatch — 2026-10-09
+
+- Engine #75 and editor #12 merged after successful current-head checks:
+ Android API 29–36/report and editor Typecheck + tests all passed.
+- Added a separate browser fixture staging the production host via
+ buildPlayRealm, using its SDK/WASM/import-map page and real project scripts.
+ Only the native project URL/staging IPC are adapted to local HTTP.
+- Built-in browser actual coordinate clicks: Inside records press/release/click
+ and dispatches to Inside → InnerMask → OuterMask → Canvas. The project handler
+ increments Text to Clicks 1 and changes UINode width 120→160; reading the
+ selected runtime entity confirms these values. No synthetic queue emit is
+ used for these pointer checks.
+- Partial's click reaches InnerMask, where the real handler stops propagation
+ and prevents default. No OuterMask/Canvas click step is displayed for that
+ event. Filtering by click retains the matching recorded paths.
+- Stop recording: another click changes Text to Clicks 2 and width to 120,
+ while history stays at 25 rows. Panel unmount: the runtime query reports
+ recording=false. Warm Stop/Start: recording=false, rows=0; clicks and
+ propagation work again in the rebuilt world.
+- Clarified Interactable ancestor and blockRaycast semantics in the Events
+ panel. A filter with no matches now has its own empty state. 13 targeted
+ panel/recorder/i18n tests, typecheck and production build pass.
+- No Electron/native runner launched. This fixture does not establish desktop
+ custom-scheme, device, IME/accessibility, shaping or performance acceptance.
+ RM-009 remains In Progress.
diff --git a/tools/ui-events-play-browser.mjs b/tools/ui-events-play-browser.mjs
new file mode 100644
index 000000000..a9397062d
--- /dev/null
+++ b/tools/ui-events-play-browser.mjs
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// Browser-only staging of the real Play host. Never launches Electron.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const stage = path.join(root, 'output/ui-events-play-browser');
+fs.mkdirSync(stage, { recursive: true });
+const { build } = await import(pathToFileURL(path.join(root, 'desktop/node_modules/esbuild/lib/main.js')).href);
+const { createServer } = await import(pathToFileURL(path.join(root, 'desktop/node_modules/vite/dist/node/index.js')).href);
+const { default: react } = await import(pathToFileURL(path.join(root, 'desktop/node_modules/@vitejs/plugin-react/dist/index.js')).href);
+const assembly = path.join(stage, 'assemble.mjs');
+await build({ entryPoints: [path.join(root, 'desktop/electron/buildPlayRealm.ts')], outfile: assembly, bundle: true, platform: 'node', format: 'esm' });
+const { buildPlayRealm } = await import(pathToFileURL(assembly).href);
+const staged = await buildPlayRealm({ root: stage, playHostArtifact: path.join(root, 'desktop/dist-electron/hosts/playHost.js'), sdkDistDir: path.join(root, 'sdk/dist'), wasmDir: path.join(root, 'desktop/public/wasm') });
+if (!staged.ok) throw Error(staged.errors.join('\n'));
+const scripts = path.join(stage, '.esengine/cache/scripts.mjs');
+await build({ entryPoints: [path.join(root, 'tools/ui-events-play-project.ts')], outfile: scripts, bundle: true, format: 'esm', platform: 'browser', external: ['esengine', 'esengine/*'] });
+const mime = { '.html': 'text/html', '.js': 'application/javascript', '.mjs': 'application/javascript', '.wasm': 'application/wasm', '.json': 'application/json' };
+const server = await createServer({ configFile: false, root: path.join(root, 'desktop'),
+ resolve: { alias: [{find:'@',replacement:path.join(root,'desktop/src')},{find:/^esengine$/,replacement:path.join(root,'sdk/dist/index.js')}] },
+ server: { host:'127.0.0.1', port:5195, strictPort:true, fs:{allow:[root]} },
+ plugins: [react(), {
+ name:'ui-events-play-browser', enforce:'pre',
+ transform(code, id) {
+ // Only the test server substitutes the native project URL with its HTTP mount.
+ if (id.replaceAll('\\','/').endsWith('/src/engine/PlayRealm.ts')) return code.replaceAll('estella://project/', '/__project/');
+ },
+ configureServer(server) { server.middlewares.use((req,res,next)=>{
+ const url = new URL(req.url, 'http://127.0.0.1');
+ if (url.pathname.startsWith('/__project/')) {
+ const file = path.resolve(stage, '.' + url.pathname.slice('/__project'.length));
+ if (!file.startsWith(stage + path.sep)) { res.statusCode=403;res.end();return; }
+ if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {res.statusCode=404;res.end();return;}
+ res.setHeader('Content-Type',mime[path.extname(file)]??'application/octet-stream');res.end(fs.readFileSync(file));
+ } else if (url.pathname==='/__events-scene.json') {
+ res.setHeader('Content-Type','application/json');res.end(fs.readFileSync(path.join(root,'tools/ui-mask-inspection.esscene')));
+ } else if (url.pathname==='/__events-play') {
+ const entry=`/@fs/${path.join(root,'tools/ui-events-play-browser.tsx').replaceAll('\\','/')}`;
+ server.transformIndexHtml(req.url,`<html><head><title>UI Events Play verification</title></head><body><div id="root"></div><script type="module" src="${entry}"></script></body></html>`).then(html=>{res.setHeader('Content-Type','text/html');res.end(html);});
+ } else next();
+ }); }
+ }]
+});
+await server.listen();
+console.log('UI Events Play fixture: http://127.0.0.1:5195/__events-play');
diff --git a/tools/ui-events-play-browser.tsx b/tools/ui-events-play-browser.tsx
new file mode 100644
index 000000000..fd2d81959
--- /dev/null
+++ b/tools/ui-events-play-browser.tsx
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// Uses the production PlayRealm controller, realm host and Events panel.
+import { createRoot } from 'react-dom/client';
+import { useCallback, useState, useSyncExternalStore } from 'react';
+import '../desktop/src/theme/tokens.css';
+import '../desktop/src/theme/global.css';
+import '../desktop/src/theme/controls.css';
+import '../desktop/src/theme/uiTextDebug.css';
+import { PlayRealm } from '../desktop/src/engine/PlayRealm';
+import { UIDebuggerEvents } from '../desktop/src/panels/UIDebuggerEvents';
+import { useSelection } from '../desktop/src/store/selectionStore';
+// Only staging uses an adapter; the realm protocol and actual game are unchanged.
+(window as any).estella = { project: {
+ preparePlayRealm: async () => ({ ok: true, hostPath: '.esengine/play/play.html', errors: [] }),
+ buildScripts: async () => ({ ok: true }),
+} };
+const scene = await (await fetch('/__events-scene.json')).json();
+// Decorative ancestors deliberately accept bubbling, without becoming pointer targets.
+for (const entity of scene.entities) {
+ if (['InnerMask', 'OuterMask', 'Canvas'].includes(entity.name))
+ entity.components.push({ type: 'Interactable', data: { enabled: true, raycastTarget: false, blockRaycast: false } });
+}
+function Fixture() {
+ const realm = useSyncExternalStore(PlayRealm.subscribe, PlayRealm.getSnapshot);
+ const selected = useSelection(state => state.selectedRef);
+ const attach = useCallback((element: HTMLDivElement | null) => { if(element) PlayRealm.attach(element); }, []);
+ const [state, setState] = useState('Ready to start');
+ const [mounted, setMounted] = useState(true);
+ const start = async () => { setState('Starting'); try { await PlayRealm.start({ sceneData: scene, assetManifest: {}, physicsEnabled: false }); setState('Play ready'); } catch(error) { setState(String(error)); } };
+ const inspect = async () => {
+ const ref = useSelection.getState().selectedRef;
+ const data = await PlayRealm.snapshot(ref && 'live' in ref ? ref.live : null);
+ const trace = await PlayRealm.uiEvents();
+ setState(JSON.stringify({ selected: data?.selected?.name, components: data?.selected?.components.filter(component => component.type === 'Text' || component.type === 'UINode'), recording: trace?.recording, rows: trace?.rows.length, dropped: trace?.dropped }));
+ };
+ return <main style={{ padding: 16, height: '100vh', display: 'flex', flexDirection: 'column', gap: 12 }}>
+ <h2>UI Events · production Play realm browser verification</h2>
+ <div><button onClick={() => void start()}>Start Play</button> <button onClick={() => PlayRealm.stop()}>Stop Play</button> <button onClick={() => setMounted(value => !value)}>Toggle panel</button> <button onClick={() => void inspect()}>Read runtime snapshot</button></div>
+ <p role="status">{realm.playing ? 'Playing' : 'Stopped'} · {realm.ready ? 'Ready' : 'Not ready'} · {realm.error ?? ''}</p>
+ <div style={{ display: 'flex', gap: 16, flex: 1, minHeight: 0 }}>
+ <div style={{ width: 800, height: 600, flexShrink: 0 }} ref={attach} />
+ <section style={{ flex: 1, minWidth: 300, display: 'flex', flexDirection: 'column', overflow: 'auto' }}>{mounted && <UIDebuggerEvents />}</section>
+ </div>
+ <output style={{maxHeight: 90, overflow: 'auto', fontSize: 11}}>{state}</output>
+ <output aria-label="Selected runtime nodes">{JSON.stringify(selected)}</output>
+ </main>;
+}
+createRoot(document.getElementById('root')!).render(<Fixture />);
+
diff --git a/tools/ui-events-play-project.ts b/tools/ui-events-play-project.ts
new file mode 100644
index 000000000..2dfadcce9
--- /dev/null
+++ b/tools/ui-events-play-project.ts
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// Disposable browser game script: reactions are driven by real UI clicks.
+import { addSystemToSchedule, defineSystem, Schedule, Res, GetWorld, UIEvents, Text, UINode, px, type UIEventQueue, type World } from 'esengine';
+const installed = new WeakSet<World>();
+addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld()], (events: UIEventQueue, world: World) => {
+ if (installed.has(world)) return;
+ const inside = world.findEntityByName('Inside');
+ if (inside === null) return;
+ installed.add(world);
+ const partial = world.findEntityByName('Partial')!;
+ const inner = world.findEntityByName('InnerMask')!;
+ let count = 0;
+ events.on(inside, 'click', () => {
+ count++;
+ world.insert(inside, Text, { ...world.get(inside, Text), content: `Clicks ${count}` });
+ world.insert(inside, UINode, { ...world.get(inside, UINode), width: px(count % 2 ? 160 : 120) });
+ });
+ events.on(inner, 'click', event => {
+ if (event.target === partial) { event.stopPropagation(); event.preventDefault(); }
+ });
+}, { name: 'UIEventPlayVerification' }));