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): use hover state and sustained captures for tooltips

yhh7fe947f533ae
diff --git a/sdk/src/ui/behavior/tooltip.ts b/sdk/src/ui/behavior/tooltip.ts
index 51aeb0f93..3a62d085a 100644
--- a/sdk/src/ui/behavior/tooltip.ts
+++ b/sdk/src/ui/behavior/tooltip.ts
@@ -19,7 +19,7 @@ import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
import { UIControlPointers, type ControlPointer } from '../input/control-pointers';
import { MOUSE_POINTER } from '../input/pointerBook';
import { Focusable, type FocusManagerState, FocusManager } from '../input/focusable';
-import { Interactable } from '../input/interactable';
+import { Interactable, UIInteraction } from '../input/interactable';
import { createLiveVisibilityQuery } from '../util/live-visibility';
import { isFocusEligible } from '../input/focus-inspection';
import { isScreenEntity, uiWorldToScreen, screenToUiLayout } from '../util/ui-pick';
@@ -104,6 +104,7 @@ export function previewTooltip(world: World, target: Entity): () => void {
export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost, isPlaying = () => true) {
const states = new Map<Entity, TooltipState>();
let disposed = false, owner: EngineApi | null = null, matrixPtr = 0, cancellation = -1;
+ let touchBlocksHover = false, touchMouseX = 0, touchMouseY = 0;
const close = (s: TooltipState) => {
s.pending = undefined;
if (s.overlay !== undefined && world.valid(s.overlay)) world.despawn(s.overlay);
@@ -150,6 +151,14 @@ export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost
const version = primaryPointerCancellationVersion(input);
const cancelled = cancellation !== -1 && version !== cancellation;
cancellation = version;
+ const mousePointer = pointers.pointers.get(MOUSE_POINTER);
+ if (input.touches.size || input.touchesEnded.size || [...pointers.pointers.values()].some(p => p.id !== MOUSE_POINTER && p.down)) {
+ touchBlocksHover = true; touchMouseX = input.mouseX; touchMouseY = input.mouseY;
+ } else if (input.mouseX !== touchMouseX || input.mouseY !== touchMouseY || mousePointer?.pressed) {
+ // The host may leave its synthesized mouse over the lifted finger.
+ // Resume hover only on fresh mouse activity, never from that stale position.
+ touchBlocksHover = false;
+ }
const hidden = createLiveVisibilityQuery(world, () => false);
const live = new Set(world.getEntitiesWithComponents([UITooltip, UINode]));
for (const [e, s] of states) if (!live.has(e)) { close(s); states.delete(e); }
@@ -160,8 +169,9 @@ export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost
const preview = !isPlaying() && !!previews.get(world)?.has(e);
const available = layout.valid && overlay.active && !hidden(e) && world.isEntityActive(e)
&& !world.isDestructionPending(e) && (!world.has(e, Interactable) || world.get(e, Interactable).enabled);
- const touch = [...pointers.pointers.values()].find(p => p.id !== MOUSE_POINTER && p.down && p.pressedEntity === e);
+ const touch = [...pointers.pointers.values()].find(p => p.id !== MOUSE_POINTER && p.down && p.entity === e);
const mouse = pointers.pointers.get(MOUSE_POINTER);
+ const hovered = world.has(e, UIInteraction) && world.get(e, UIInteraction).hovered;
let trigger: TooltipState['trigger'] = null;
if (cancelled && touch) { s.moved = true; s.pointer = touch.id; }
if (available && d.content && preview) trigger = 'focus';
@@ -173,7 +183,7 @@ export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost
if (Math.hypot(touch.layoutX - s.startX, touch.layoutY - s.startY) * layout.scale > 8) s.moved = true;
if (!s.moved && touch.entity === e) trigger = 'touch';
} else if (d.focus && focus.isVisiblyFocused(e) && isFocusEligible(world, e)) trigger = 'focus';
- else if (d.hover && mouse?.entity === e && !mouse.down && input.touches.size === 0) trigger = 'hover';
+ else if (d.hover && hovered && mouse?.down === false && !touchBlocksHover) trigger = 'hover';
}
if (!touch) { s.pointer = -2; s.moved = false; }
if (trigger !== s.trigger) { close(s); s.elapsed = 0; s.trigger = trigger; }
diff --git a/sdk/src/ui/input/control-pointers.ts b/sdk/src/ui/input/control-pointers.ts
index 213eb3f5e..a44399a74 100644
--- a/sdk/src/ui/input/control-pointers.ts
+++ b/sdk/src/ui/input/control-pointers.ts
@@ -6,7 +6,9 @@ export interface ControlPointer {
id: number;
down: boolean;
pressed: boolean;
+ /** Captured control while held; null on a released/hover-only pointer. */
entity: Entity | null;
+ /** Press edge target, only populated in the frame the capture starts. */
pressedEntity: Entity | null;
layoutX: number;
layoutY: number;
diff --git a/sdk/tests/ui-tab-tooltip-wasm.test.ts b/sdk/tests/ui-tab-tooltip-wasm.test.ts
index 9e8f7d158..4753469ef 100644
--- a/sdk/tests/ui-tab-tooltip-wasm.test.ts
+++ b/sdk/tests/ui-tab-tooltip-wasm.test.ts
@@ -3,11 +3,11 @@
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { App } from '../src/app/app';
import { AppContext, setDefaultContext } from '../src/ecs/context';
-import { Canvas, Disabled, Name, registerComponent } from '../src/ecs/component';
+import { Canvas, Disabled, Name, Transform, registerComponent } from '../src/ecs/component';
import { Schedule } from '../src/ecs/system';
import { setEditorMode, setPlayMode } from '../src/ecs/env';
import { Input, InputState } from '../src/input/input';
-import { UIEventQueue } from '../src/ui/core/events';
+import { UIEventQueue, UIEvents } from '../src/ui/core/events';
import { UITabView, createTabViewSystem } from '../src/ui/behavior/tab-view';
import { UIToggle, UIToggleGroup, createToggleSystem } from '../src/ui/behavior/toggle';
import { UITooltip, createTooltipSystem, placeTooltip } from '../src/ui/behavior/tooltip';
@@ -21,7 +21,8 @@ import { UIVisual } from '../src/ui/core/ui-visual';
import { FocusManager, FocusManagerState, Focusable } from '../src/ui/input/focusable';
import { UIControlPointers, type ControlPointer } from '../src/ui/input/control-pointers';
import { MOUSE_POINTER } from '../src/ui/input/pointerBook';
-import { Interactable } from '../src/ui/input/interactable';
+import { Interactable, UIInteraction } from '../src/ui/input/interactable';
+import { UIInteractionPlugin } from '../src/ui/input/interaction';
import { ScreenLayout, screenLayoutRect, screenProjection } from '../src/ui/core/screen-layout';
import { ScreenOverlay, defaultScreenOverlay } from '../src/ui/core/screen-overlay';
import { UICameraInfo } from '../src/ui/core/ui-camera-info';
@@ -52,11 +53,13 @@ describe('tooltip placement', () => {
describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
let engine: ESEngineModule, registry: CppRegistry, app: App, events: UIEventQueue;
let tooltips: ReturnType<typeof createTooltipSystem>;
+ let interaction: UIInteractionPlugin | undefined;
beforeAll(async () => { engine = await loadWasmModule(); });
beforeEach(() => {
setDefaultContext(new AppContext()); setEditorMode(false); setPlayMode(false);
registry = new engine.Registry(); app = App.new(); app.connectCpp(registry, engine);
events = new UIEventQueue();
+ app.insertResource(UIEvents, events);
for (const c of [UITabView, UIToggle, UIToggleGroup, Focusable, ThemeStyle, UIController, UIGear, Text, Name]) registerComponent(c._name, c);
app.insertResource(Input, new InputState()); app.insertResource(FocusManager, new FocusManagerState());
const layout = screenLayoutRect(null, 800, 600);
@@ -69,11 +72,12 @@ describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
tooltips = createTooltipSystem(app.world);
app.addSystemToSchedule(Schedule.Update, tooltips.system);
});
- afterEach(() => { tooltips.dispose(); app.quit({ keepRenderer: true }); registry.delete(); });
+ afterEach(() => { interaction?.cleanup(app); interaction = undefined; tooltips.dispose(); app.quit({ keepRenderer: true }); registry.delete(); });
const tick = async (delta = 0.1) => {
engine.uiLayout_update(registry, -400, -300, 400, 300, true); engine.transform_update(registry);
await app.tick(delta);
app.getResource(Input).keysPressed.clear();
+ for (const p of app.getResource(UIControlPointers).pointers.values()) p.pressedEntity = null;
};
const view = () => createTabView({ world: app.world, events, labels: ['Graphics', 'Audio', 'Controls'] });
const displays = (v: ReturnType<typeof view>) => v.pages.map(e => app.world.get(e, UINode).display);
@@ -83,11 +87,43 @@ describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
return createTooltip({ world: app.world, parent: root, content: 'Volume controls the music.' }).entity;
};
const pointer = (entity: number, id = MOUSE_POINTER, down = false) => {
- const p: ControlPointer = { id, down, pressed: down, entity, pressedEntity: down ? entity : null,
+ app.world.insert(entity, UIInteraction, { hovered: true, pressed: down, justPressed: down });
+ const p: ControlPointer = { id, down, pressed: down, entity: down ? entity : null, pressedEntity: down ? entity : null,
layoutX: 0, layoutY: 0, worldX: 0, worldY: 0 };
app.getResource(UIControlPointers).pointers.set(id, p); return p;
};
const bubbles = () => app.world.getEntitiesWithComponents([Text]).filter(e => app.world.get(e, Text).content === 'Volume controls the music.');
+ const realPointerTarget = () => {
+ interaction = new UIInteractionPlugin(); interaction.build(app);
+ const e = target();
+ engine.uiLayout_update(registry, -400, -300, 400, 300, true); engine.transform_update(registry);
+ const at = app.world.get(e, Transform).worldPosition;
+ return { e, x: at.x + 400, y: 300 - at.y };
+ };
+ it('real hit testing supplies hover after the capture has been released', async () => {
+ const { e, x, y } = realPointerTarget(), input = app.getResource(Input);
+ input.mouseX = x; input.mouseY = y;
+ await tick(0.2); await tick(0.2); await tick(0.2);
+ expect(app.world.get(e, UIInteraction).hovered).toBe(true);
+ expect(app.getResource(UIControlPointers).pointers.get(MOUSE_POINTER)?.entity).toBeNull();
+ expect(bubbles()).toHaveLength(1);
+ });
+ it('real touch capture persists after the one-frame pressedEntity edge', async () => {
+ const { e, x, y } = realPointerTarget(), input = app.getResource(Input);
+ const point = { id: 7, x, y }; input.touches.set(7, point); input.touchesStarted.set(7, point);
+ await tick(0.3); input.touchesStarted.clear(); await tick(0.3);
+ const p = app.getResource(UIControlPointers).pointers.get(7)!;
+ expect(p.entity).toBe(e); expect(p.pressedEntity).toBeNull(); expect(bubbles()).toHaveLength(1);
+ });
+ it('a lifted touch cannot reopen a hint through its stale synthesized mouse', async () => {
+ const { x, y } = realPointerTarget(), input = app.getResource(Input);
+ input.mouseX = x; input.mouseY = y;
+ const point = { id: 7, x, y }; input.touches.set(7, point); input.touchesStarted.set(7, point);
+ await tick(0.3); input.touchesStarted.clear(); await tick(0.3); expect(bubbles()).toHaveLength(1);
+ input.touches.delete(7); input.touchesEnded.set(7, point); await tick(); input.touchesEnded.clear();
+ for (let i = 0; i < 7; i++) await tick(); expect(bubbles()).toHaveLength(0);
+ input.mouseX += 1; for (let i = 0; i < 6; i++) await tick(); expect(bubbles()).toHaveLength(1);
+ });
it('click and programmatic selection keep ToggleGroup and page visibility in agreement', async () => {
const v = view(); await tick(); events.emit(v.tabs[1], 'click'); await tick();
expect(displays(v)).toEqual([1, 0, 1]); expect(app.world.get(v.entity, UITabView).selectedIndex).toBe(1);
@@ -144,7 +180,7 @@ describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
const canvas = app.world.getEntitiesWithComponents([Canvas]).at(-1)!;
expect(app.world.get(canvas, UINode).pointerEvents).toBe(UIPointerEvents.None);
expect(app.world.has(bubbles()[0], Focusable)).toBe(false); expect(app.world.has(bubbles()[0], Interactable)).toBe(false);
- p.entity = null; await tick(); expect(bubbles()).toHaveLength(0);
+ p.entity = null; app.world.update(e, UIInteraction, d => { d.hovered = false; }); await tick(); expect(bubbles()).toHaveLength(0);
});
it('keyboard focus shows immediately and hides when a page closes', async () => {
const e = target(); app.getResource(FocusManager).focus(e, true); await tick(); expect(bubbles()).toHaveLength(1);
@@ -156,7 +192,7 @@ describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
if (kind === 'cancel') cancelPrimaryPointer(app.getResource(Input));
if (kind === 'release') p.down = false;
await tick(0.3); await tick(0.3); expect(bubbles()).toHaveLength(0);
- expect(p.pressedEntity).toBe(e);
+ expect(p.entity).toBe(e);
});
it('stationary long press uses its delay and releases its popup on lift', async () => {
const e = target(), p = pointer(e, 7, true); await tick(0.3); await tick(0.3); expect(bubbles()).toHaveLength(1);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 497c6e630..136560d0f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -29,6 +29,7 @@ export const NOTES_FLOOR = 'v0.65.0';
*/
export const NOTED = {
'feat: add TabView and Tooltip UI controls': { note: 'UI tabs and tooltips.' },
+ 'fix(ui): use hover state and sustained captures for tooltips': { note: 'UI tabs and tooltips.' },
'feat(editor): add TabView and Tooltip authoring and previews': { note: 'UI tabs and tooltips.' },
'fix(editor): keep advanced joint property searches scoped to matching fields': { note: '3D swing/twist and six-axis joints.' },
'feat: add SwingTwist and SixDOF 3D joints': { note: '3D swing/twist and six-axis joints.' },