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(ui): retain quick-click edges for pointer focus (#81)

YHHf354bb48c4e7
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 3330a62d6..c54a77eac 100644
--- a/examples/ui-localization-debug/README.md
+++ b/examples/ui-localization-debug/README.md
@@ -106,3 +106,10 @@ R removes the test dialog. These keys run normal project systems in Play.
While the test dialog is open, H hides its parent container and V restores it.
The Focus view should free the visible page controls while the dialog is
hierarchically hidden, then restrict traversal again when its parent returns.
+
+
+T adds/removes a real createTextInput field. Click it or use Tab/Shift+Tab, enter
+mixed English/Chinese text, then Enter submits. While recording, Events shows
+actual change/submit; select its event node and Read runtime snapshot to check
+TextInput.value. Fixture keys do not run while editing. This validates character
+entry and focus handoff, not an OS IME candidate-window session.
diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.md
index 6dd705b42..e1f6fc661 100644
--- a/examples/ui-localization-debug/VALIDATION.md
+++ b/examples/ui-localization-debug/VALIDATION.md
@@ -276,3 +276,29 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.
remaining active alongside another hidden modal. No local Electron/native
runner launched. Modal stacking order, real devices, IME/accessibility,
desktop custom-scheme, text shaping and cache performance remain open.
+
+
+## Quick click focus and actual text entry — 2026-10-09
+
+- Engine #80 merged after current-head Android API 29–36, packaging and report
+ checks all passed. This is emulator boot evidence, not device input acceptance.
+- Actual Web input exposed a quick-click bug: press/release/click events were
+ emitted, but a press and release both arriving before a frame left
+ UIInteraction.justPressed/justReleased false. FocusSystem could miss a real
+ click on a text field. Preserve the projected edges until the next frame,
+ even when the final held pressed state is false.
+- A regression using the real interaction plugin, pointer book and FocusPlugin
+ fails before the fix, then passes: actual press/release/click order, both edge
+ flags, pointer focus without keyboard highlight, and next-frame edge reset.
+ The host hit result is mocked in this test; real Web hit testing is below.
+- Production Play host/SDK/WASM in the built-in browser: T adds createTextInput.
+ Clicking it now focuses Runtime input. Native m/d/e and inserted Chinese text
+ produce mde 中文 without triggering fixture hotkeys. Ctrl+A replacement to
+ hello 中文 and Enter run actual change/submit handlers; Events records these
+ and selecting its spawned-world row reads TextInput.value=hello 中文,
+ cursorPos=8, focused=false after submit. Tab/Shift+Tab leave and return to the
+ native editing surface correctly. Fixture shortcuts are ignored while editing.
+- 88 targeted SDK tests, SDK build and 16 API/built declaration checks pass.
+ No Electron/native runner launched. Character entry does not establish a
+ real IME candidate-window session. Device IME/accessibility, modal stacking,
+ desktop custom-scheme, text shaping and cache performance remain open.
diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.ts
index 6e69ee3f1..81ba70eb4 100644
--- a/sdk/src/ui/input/interaction.ts
+++ b/sdk/src/ui/input/interaction.ts
@@ -163,9 +163,14 @@ export class UIInteractionPlugin implements Plugin {
break;
case 'press':
ensureComponent(world, event.entity, UIInteraction);
+ // A complete click may arrive between frames. Preserve its
+ // edge even when the final held-state is already false.
+ world.insert(event.entity, UIInteraction, { ...world.get(event.entity, UIInteraction), justPressed: true });
emitWithBubbling(world, events, event.entity, UIEventType.Press);
break;
case 'release':
+ if (world.has(event.entity, UIInteraction))
+ world.insert(event.entity, UIInteraction, { ...world.get(event.entity, UIInteraction), justReleased: true });
emitWithBubbling(world, events, event.entity, UIEventType.Release);
break;
case 'click':
diff --git a/sdk/tests/ui-quick-click-focus.test.ts b/sdk/tests/ui-quick-click-focus.test.ts
new file mode 100644
index 000000000..fba6067e5
--- /dev/null
+++ b/sdk/tests/ui-quick-click-focus.test.ts
@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+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 { 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';
+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 { UIEvents } from '../src/ui/core/events';
+const hit = vi.hoisted(() => ({ entity: null as number | null }));
+vi.mock('../src/ui/util/ui-pick', () => ({
+ screenToUiWorld: () => ({ x: 0, y: 0 }), screenToUiLayout: () => ({ x: 0, y: 0 }),
+ uiPointerRay: () => ({}), uiLayoutRay: () => ({}), uiHitTestWorld: () => hit.entity,
+}));
+
+describe('quick pointer focus through real interaction projection', () => {
+ it('preserves press/release edges when the whole click ends before a frame', 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.insertResource(UILayoutGeneration, { generation: 0 });
+ uiInteractionPlugin.build(app);
+ focusPlugin.build(app);
+ flushPendingRegistrations(app);
+ const entity = app.world.spawn();
+ app.world.insert(entity, Interactable, { enabled: true });
+ app.world.insert(entity, Focusable, {});
+ hit.entity = entity;
+ const kinds: string[] = [];
+ for (const kind of ['press', 'release', 'click']) app.getResource(UIEvents).on(entity, kind, () => kinds.push(kind));
+ input.noteMouseDown(0);
+ input.noteMouseUp(0);
+ await app.tick(1 / 60);
+ expect(kinds).toEqual(['press', 'release', 'click']);
+ expect(app.world.get(entity, UIInteraction)).toMatchObject({ pressed: false, justPressed: true, justReleased: true });
+ expect(app.getResource(FocusManager).focusedEntity).toBe(entity);
+ expect(app.getResource(FocusManager).focusVisible).toBe(false);
+ input.clearFrameState();
+ await app.tick(1 / 60);
+ expect(app.world.get(entity, UIInteraction)).toMatchObject({ justPressed: false, justReleased: false });
+ expect(app.getResource(FocusManager).focusedEntity).toBe(entity);
+ });
+});
diff --git a/tools/ui-events-play-browser.tsx b/tools/ui-events-play-browser.tsx
index 48a158494..ec5ad98a2 100644
--- a/tools/ui-events-play-browser.tsx
+++ b/tools/ui-events-play-browser.tsx
@@ -36,12 +36,12 @@ function Fixture() {
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 }));
+ setState(JSON.stringify({ selected: data?.selected?.name, components: data?.selected?.components.filter(component => component.type === 'Text' || component.type === 'UINode' || component.type === 'TextInput'), 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={() => { PlayInspect.stop(); PlayRealm.stop(); }}>Stop Play</button> <button onClick={() => setMounted(value => !value)}>Toggle panel</button> <button onClick={() => void inspect()}>Read runtime snapshot</button> <button onClick={() => setView('events')}>Events</button> <button onClick={() => setView('focus')}>Focus</button> <button onClick={() => setView('elements')}>Elements</button></div>
- <small>Game keys: M opens the runtime button as a dialog; R closes it; D disables current focus; E restores disabled controls; H hides the dialog parent; V shows it again.</small>
+ <small>Game keys: M opens the runtime button as a dialog; R closes it; D disables current focus; E restores disabled controls; H hides the dialog parent; V shows it again; T toggles a real text input (outside text editing).</small>
<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} />
diff --git a/tools/ui-events-play-project.ts b/tools/ui-events-play-project.ts
index 5284e3fc8..3beb248f8 100644
--- a/tools/ui-events-play-project.ts
+++ b/tools/ui-events-play-project.ts
@@ -1,6 +1,6 @@
// 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, Transform, UIVisual, Interactable, Focusable, px, Input, FocusManager, UIDialog, UIDisplay, type InputState, type FocusManagerState, type Entity, type UIEventQueue, type World } from 'esengine';
+import { addSystemToSchedule, defineSystem, Schedule, Res, GetWorld, UIEvents, Text, UINode, Transform, UIVisual, Interactable, Focusable, px, Input, FocusManager, UIDialog, UIDisplay, createTextInput, Name, TextInput, type TextInputHandle, type InputState, type FocusManagerState, type Entity, type UIEventQueue, type World } from 'esengine';
const installed = new WeakMap<World, () => void>();
addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Res(Input), Res(FocusManager)], (events: UIEventQueue, world: World, input: InputState, focus: FocusManagerState) => {
const update = installed.get(world);
@@ -10,8 +10,23 @@ addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Re
const partial = world.findEntityByName('Partial')!;
const inner = world.findEntityByName('InnerMask')!;
let count = 0, dynamic: Entity | null = null, dialogHost: Entity | null = null;
+ let textField: TextInputHandle | null = null;
const restore = new Set<Entity>();
installed.set(world, () => {
+ // Fixture shortcuts must not react to letters typed into an engine field.
+ if (focus.focusedEntity !== null && world.has(focus.focusedEntity, TextInput)) return;
+ if (input.isKeyPressed('KeyT')) {
+ if (textField) { textField.dispose(); textField = null; }
+ else {
+ textField = createTextInput({ world, events, parent: world.findEntityByName('Canvas')!,
+ node: { position: 1, width: px(260), height: px(34), insetLeft: px(40), insetTop: px(420) },
+ placeholder: 'Type English / 中文', fontFamily: 'Arial', fontSize: 18, tabIndex: 3,
+ onChange: value => world.insert(inside, Text, { ...world.get(inside, Text), content: `Input ${value}` }),
+ onSubmit: value => world.insert(inside, Text, { ...world.get(inside, Text), content: `Submit ${value}` }),
+ });
+ world.insert(textField.entity, Name, { value: 'Runtime input' });
+ }
+ }
if (input.isKeyPressed('KeyM') && dynamic !== null && world.valid(dynamic)) {
world.insert(dynamic, UIDialog, { closeOnEscape: false, closeOnBackdrop: false });
world.insert(dynamic, Text, { ...world.get(dynamic, Text), content: 'Dialog confirm' });