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): render tooltips in the screen paint order

yhh0c8bd754d59a
diff --git a/desktop b/desktop
index 1191b878e..2ef4d678d 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1191b878efa169136559e1cf7a83ba037cf6dd19
+Subproject commit 2ef4d678d9d24305d4d7a9b33400c92f61fa91d5
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 81dc26439..2cacc42e4 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -2,8 +2,8 @@
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
"public": 115,
- "beta": 135,
- "experimental": 2242,
+ "beta": 141,
+ "experimental": 2236,
"deprecated": 3
},
"total": 2492,
@@ -2802,6 +2802,30 @@
"minigame"
]
},
+ {
+ "name": "TabViewHandle",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "TabViewOptions",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "ThemeColors",
"kind": "interface",
@@ -2854,6 +2878,30 @@
"tilemap"
]
},
+ {
+ "name": "TooltipHandle",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "TooltipOptions",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "TouchPoint",
"kind": "interface",
@@ -2938,6 +2986,18 @@
"minigame"
]
},
+ {
+ "name": "UITabViewData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "UITooltip",
"kind": "const",
@@ -2950,6 +3010,18 @@
"minigame"
]
},
+ {
+ "name": "UITooltipData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "UIVisual",
"kind": "const",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f659a5a8f..4640f254b 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 · 123 beta · 1618 experimental · 3 deprecated
+Symbols: 115 public · 129 beta · 1612 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -8881,7 +8881,7 @@ readonly (keyof ThemeColors)[]
Record<string, string | number>
```
-## TabViewHandle — interface @experimental
+## TabViewHandle — interface @beta
```
dispose: () => void
entity: number
@@ -8890,7 +8890,7 @@ select: (index: number) => void
tabs: readonly number[]
```
-## TabViewOptions — interface @experimental
+## TabViewOptions — interface @beta
```
events: UIEventQueue
labels: readonly string[]
@@ -9368,13 +9368,13 @@ tabIndex: number | undefined
world: World
```
-## TooltipHandle — interface @experimental
+## TooltipHandle — interface @beta
```
dispose: () => void
entity: number
```
-## TooltipOptions — interface @experimental
+## TooltipOptions — interface @beta
```
content: string | undefined
node: UINodeInit | undefined
@@ -9881,7 +9881,7 @@ value: number
ComponentDef<UITabViewData>
```
-## UITabViewData — interface @experimental
+## UITabViewData — interface @beta
```
allowSwitchOff: boolean
labels: string[]
@@ -9919,7 +9919,7 @@ allowSwitchOff: boolean
ComponentDef<UITooltipData>
```
-## UITooltipData — interface @experimental
+## UITooltipData — interface @beta
```
avoidEdges: boolean
content: string
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 879ab9f5d..4fd250d29 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 · 128 beta · 1637 experimental · 3 deprecated
+Symbols: 115 public · 134 beta · 1631 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -9094,7 +9094,7 @@ readonly (keyof ThemeColors)[]
Record<string, string | number>
```
-## TabViewHandle — interface @experimental
+## TabViewHandle — interface @beta
```
dispose: () => void
entity: number
@@ -9103,7 +9103,7 @@ select: (index: number) => void
tabs: readonly number[]
```
-## TabViewOptions — interface @experimental
+## TabViewOptions — interface @beta
```
events: UIEventQueue
labels: readonly string[]
@@ -9581,13 +9581,13 @@ tabIndex: number | undefined
world: World
```
-## TooltipHandle — interface @experimental
+## TooltipHandle — interface @beta
```
dispose: () => void
entity: number
```
-## TooltipOptions — interface @experimental
+## TooltipOptions — interface @beta
```
content: string | undefined
node: UINodeInit | undefined
@@ -10094,7 +10094,7 @@ value: number
ComponentDef<UITabViewData>
```
-## UITabViewData — interface @experimental
+## UITabViewData — interface @beta
```
allowSwitchOff: boolean
labels: string[]
@@ -10132,7 +10132,7 @@ allowSwitchOff: boolean
ComponentDef<UITooltipData>
```
-## UITooltipData — interface @experimental
+## UITooltipData — interface @beta
```
avoidEdges: boolean
content: string
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a2b57cc8f..a955b13e0 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 · 125 beta · 1617 experimental · 3 deprecated
+Symbols: 115 public · 131 beta · 1611 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8876,7 +8876,7 @@ readonly (keyof ThemeColors)[]
Record<string, string | number>
```
-## TabViewHandle — interface @experimental
+## TabViewHandle — interface @beta
```
dispose: () => void
entity: number
@@ -8885,7 +8885,7 @@ select: (index: number) => void
tabs: readonly number[]
```
-## TabViewOptions — interface @experimental
+## TabViewOptions — interface @beta
```
events: UIEventQueue
labels: readonly string[]
@@ -9363,13 +9363,13 @@ tabIndex: number | undefined
world: World
```
-## TooltipHandle — interface @experimental
+## TooltipHandle — interface @beta
```
dispose: () => void
entity: number
```
-## TooltipOptions — interface @experimental
+## TooltipOptions — interface @beta
```
content: string | undefined
node: UINodeInit | undefined
@@ -9876,7 +9876,7 @@ value: number
ComponentDef<UITabViewData>
```
-## UITabViewData — interface @experimental
+## UITabViewData — interface @beta
```
allowSwitchOff: boolean
labels: string[]
@@ -9914,7 +9914,7 @@ allowSwitchOff: boolean
ComponentDef<UITooltipData>
```
-## UITooltipData — interface @experimental
+## UITooltipData — interface @beta
```
avoidEdges: boolean
content: string
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5822acc95..c1b77e0ea 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 · 123 beta · 1639 experimental · 3 deprecated
+Symbols: 115 public · 129 beta · 1633 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -9169,7 +9169,7 @@ readonly (keyof ThemeColors)[]
Record<string, string | number>
```
-## TabViewHandle — interface @experimental
+## TabViewHandle — interface @beta
```
dispose: () => void
entity: number
@@ -9178,7 +9178,7 @@ select: (index: number) => void
tabs: readonly number[]
```
-## TabViewOptions — interface @experimental
+## TabViewOptions — interface @beta
```
events: UIEventQueue
labels: readonly string[]
@@ -9656,13 +9656,13 @@ tabIndex: number | undefined
world: World
```
-## TooltipHandle — interface @experimental
+## TooltipHandle — interface @beta
```
dispose: () => void
entity: number
```
-## TooltipOptions — interface @experimental
+## TooltipOptions — interface @beta
```
content: string | undefined
node: UINodeInit | undefined
@@ -10169,7 +10169,7 @@ value: number
ComponentDef<UITabViewData>
```
-## UITabViewData — interface @experimental
+## UITabViewData — interface @beta
```
allowSwitchOff: boolean
labels: string[]
@@ -10207,7 +10207,7 @@ allowSwitchOff: boolean
ComponentDef<UITooltipData>
```
-## UITooltipData — interface @experimental
+## UITooltipData — interface @beta
```
avoidEdges: boolean
content: string
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 5e1b0d1c2..710f6e0e1 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 · 123 beta · 1630 experimental · 3 deprecated
+Symbols: 115 public · 129 beta · 1624 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8883,7 +8883,7 @@ readonly (keyof ThemeColors)[]
Record<string, string | number>
```
-## TabViewHandle — interface @experimental
+## TabViewHandle — interface @beta
```
dispose: () => void
entity: number
@@ -8892,7 +8892,7 @@ select: (index: number) => void
tabs: readonly number[]
```
-## TabViewOptions — interface @experimental
+## TabViewOptions — interface @beta
```
events: UIEventQueue
labels: readonly string[]
@@ -9370,13 +9370,13 @@ tabIndex: number | undefined
world: World
```
-## TooltipHandle — interface @experimental
+## TooltipHandle — interface @beta
```
dispose: () => void
entity: number
```
-## TooltipOptions — interface @experimental
+## TooltipOptions — interface @beta
```
content: string | undefined
node: UINodeInit | undefined
@@ -9883,7 +9883,7 @@ value: number
ComponentDef<UITabViewData>
```
-## UITabViewData — interface @experimental
+## UITabViewData — interface @beta
```
allowSwitchOff: boolean
labels: string[]
@@ -9921,7 +9921,7 @@ allowSwitchOff: boolean
ComponentDef<UITooltipData>
```
-## UITooltipData — interface @experimental
+## UITooltipData — interface @beta
```
avoidEdges: boolean
content: string
diff --git a/sdk/src/ui/behavior/tab-view.ts b/sdk/src/ui/behavior/tab-view.ts
index d7057198a..243fb3937 100644
--- a/sdk/src/ui/behavior/tab-view.ts
+++ b/sdk/src/ui/behavior/tab-view.ts
@@ -15,7 +15,7 @@ import { moveUIFocus } from '../input/focus-transition';
import { setUIVisible } from '../core/compose';
import { Text } from '../core/text';
-/** Ordered, parallel entity lists use the same prefab remapping as MeshSkin.joints. */
+/** Ordered, parallel entity lists use the same prefab remapping as MeshSkin.joints. @beta */
export interface UITabViewData {
selectedIndex: number;
tabs: Entity[];
diff --git a/sdk/src/ui/behavior/tooltip.ts b/sdk/src/ui/behavior/tooltip.ts
index 3a62d085a..09f8c691e 100644
--- a/sdk/src/ui/behavior/tooltip.ts
+++ b/sdk/src/ui/behavior/tooltip.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { Canvas, SortingGroup, Transform, Parent, defineComponent } from '../../ecs/component';
+import { Canvas, Transform, Parent, defineComponent } from '../../ecs/component';
import { defineSystem } from '../../ecs/system';
import { Res, Time, type TimeData } from '../../ecs/resource';
import { Input, type InputState } from '../../input/input';
@@ -27,6 +27,7 @@ import { themeColors } from '../theme/tokens';
import { markThemed } from '../theme/theme-style';
import { measureText } from '../text/measure-text';
+/** Trigger and layout settings for an engine UI tooltip. @beta */
export interface UITooltipData {
content: string;
stylePrefab: string;
@@ -205,7 +206,6 @@ export function createTooltipSystem(world: World, prefabHost?: TooltipPrefabHost
const canvasData = structuredClone(world.has(ancestor, Canvas) ? world.get(ancestor, Canvas) : Canvas._default);
// The screen domain is shared; this late root is only a non-interactive paint layer.
world.insert(canvas, Canvas, canvasData);
- world.insert(canvas, SortingGroup, { layer: canvasData.layer, order: 1_000_000, enabled: true });
s.overlay = canvas;
if (d.stylePrefab && prefabHost) {
const token = {}; s.pending = token;
diff --git a/sdk/src/ui/widgets/tab-view.ts b/sdk/src/ui/widgets/tab-view.ts
index 429f415f2..0a254247f 100644
--- a/sdk/src/ui/widgets/tab-view.ts
+++ b/sdk/src/ui/widgets/tab-view.ts
@@ -13,6 +13,7 @@ import { UIEventType, type UIEventQueue } from '../core/events';
import { UINode, UIDisplay } from '../core/ui-node';
import { Name } from '../../ecs/component';
+/** Creation options for a composed tab view. @beta */
export interface TabViewOptions {
world: World;
events: UIEventQueue;
@@ -23,6 +24,7 @@ export interface TabViewOptions {
tabHeight?: number;
onChange?: (index: number, page: Entity) => void;
}
+/** A composed view and its editable children. @beta */
export interface TabViewHandle {
readonly entity: Entity;
readonly tabs: readonly Entity[];
diff --git a/sdk/src/ui/widgets/tooltip.ts b/sdk/src/ui/widgets/tooltip.ts
index 3448283a2..41819af0c 100644
--- a/sdk/src/ui/widgets/tooltip.ts
+++ b/sdk/src/ui/widgets/tooltip.ts
@@ -14,6 +14,7 @@ export function attachTooltip(world: World, target: Entity, options: Partial<UIT
world.insert(target, UITooltip, { ...structuredClone(UITooltip._default), ...options });
}
+/** Creation options for a tooltip example target. @beta */
export interface TooltipOptions {
world: World;
parent?: Entity;
@@ -21,6 +22,7 @@ export interface TooltipOptions {
content?: string;
settings?: Partial<UITooltipData>;
}
+/** A tooltip target with explicit lifetime. @beta */
export interface TooltipHandle {
readonly entity: Entity;
dispose(): void;
diff --git a/sdk/tests/ui-tab-tooltip-wasm.test.ts b/sdk/tests/ui-tab-tooltip-wasm.test.ts
index 4753469ef..f0d136052 100644
--- a/sdk/tests/ui-tab-tooltip-wasm.test.ts
+++ b/sdk/tests/ui-tab-tooltip-wasm.test.ts
@@ -3,7 +3,7 @@
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, Transform, registerComponent } from '../src/ecs/component';
+import { Canvas, Disabled, Name, Parent, 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';
@@ -107,6 +107,12 @@ describe.skipIf(!HAS_WASM)('TabView and Tooltip on real WASM', () => {
expect(app.world.get(e, UIInteraction).hovered).toBe(true);
expect(app.getResource(UIControlPointers).pointers.get(MOUSE_POINTER)?.entity).toBeNull();
expect(bubbles()).toHaveLength(1);
+ await tick();
+ const label = bubbles()[0], panel = app.world.get(label, Parent).entity, canvas = app.world.get(panel, Parent).entity;
+ for (const entity of [canvas, panel, label]) {
+ expect(engine.getUINodeComputedWidth!(registry, entity)).toBeGreaterThan(0);
+ expect(engine.getUINodeComputedHeight!(registry, entity)).toBeGreaterThan(0);
+ }
});
it('real touch capture persists after the one-frame pressedEntity edge', async () => {
const { e, x, y } = realPointerTarget(), input = app.getResource(Input);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 136560d0f..e4ff5437f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -30,6 +30,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.' },
+ 'fix(ui): render tooltips in the screen paint order': { 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.' },