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.

feat(engine): text standing in the world can be ordered, and lands where it is put

yhhb8537d1607b1
diff --git a/desktop/src/i18n/messages/details.ts b/desktop/src/i18n/messages/details.ts
index 24ceccf76..fa4dc5014 100644
--- a/desktop/src/i18n/messages/details.ts
+++ b/desktop/src/i18n/messages/details.ts
@@ -14,9 +14,13 @@ export const detailsMessages = defineMessages({
en: 'UI layout owns this position — it is recomputed every relayout. Move this widget with the UI Node anchors / offsets instead.',
zh: '该位置由 UI 布局决定 —— 每次重新布局都会重算。请改用 UI 节点的锚点 / 偏移来移动此控件。',
},
+ // Both readings are legitimate, and naming only the UI one sent world content
+ // (a label on a board, a name over a character) into a Canvas it does not
+ // belong in. So say what this text IS — a label standing in the world — and
+ // which knob orders it, before offering the UI route.
'det.noticeTextNoLayoutBox': {
- en: 'No layout box — align anchors the text to the entity origin. To align within a fixed area, add a UINode and place this Text under a Canvas.',
- zh: '没有布局框 —— 对齐只会把文本吸附到实体原点。要在固定区域内对齐,请添加 UI 节点并把该文本放到画布下。',
+ en: 'No layout box — this is a label in the world, drawn at the entity origin and sorted by Text.layer (raise it to sit in front of nearby sprites / shapes). Align only anchors to that origin; to align within a fixed area, add a UINode and place this Text under a Canvas.',
+ zh: '没有布局框 —— 这是一段世界里的文字,画在实体原点,按 Text.layer 排序(调高它就能盖在附近的精灵 / 形状上面)。对齐只会把文本吸附到该原点;要在固定区域内对齐,请添加 UI 节点并把该文本放到画布下。',
},
'det.noticeLightNeedsTransform': {
en: 'Point / Spot lights need a Transform for their position — this light is skipped.',
diff --git a/desktop/tests/text-align-notice.test.ts b/desktop/tests/text-align-notice.test.ts
index a85ac1911..8041010f0 100644
--- a/desktop/tests/text-align-notice.test.ts
+++ b/desktop/tests/text-align-notice.test.ts
@@ -5,6 +5,12 @@
* under a Canvas); a boxless Text anchors to its origin instead. The inspector
* surfaces that ONLY when the user has set a non-default alignment, so the
* anchor behavior is explained rather than looking like a broken field.
+ *
+ * The notice also has to name Text.layer. A boxless Text is world content,
+ * and reading only the UI half of this ("add a UINode, put it under a
+ * Canvas") is what sends a board's pieces into a Canvas they do not belong
+ * in — while the thing actually hiding them is a sprite on the same layer
+ * drawn later.
*/
import { describe, it, expect } from 'vitest';
import { componentNotice } from '@/engine/schema';
@@ -18,7 +24,14 @@ const entity = (comps: { type: string; data?: unknown }[]) =>
describe('Text alignment notice', () => {
it('explains anchor-to-origin when a boxless Text has a non-default alignment', () => {
const e = entity([{ type: 'Transform' }, { type: 'Text', data: { align: 1, verticalAlign: 0 } }]);
- expect(componentNotice('Text', e)).toMatch(/anchors the text to the entity origin/);
+ expect(componentNotice('Text', e)).toMatch(/anchors to that origin/);
+ });
+
+ it('names Text.layer, the knob that decides whether world text is covered', () => {
+ const e = entity([{ type: 'Transform' }, { type: 'Text', data: { align: 1, verticalAlign: 0 } }]);
+ const notice = componentNotice('Text', e) ?? '';
+ expect(notice).toMatch(/label in the world/);
+ expect(notice).toMatch(/Text\.layer/);
});
it('stays silent for a default-aligned (Left/Top) boxless Text', () => {
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 9572d2e61..821227e97 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -7057,6 +7057,7 @@ fontFamily: string
fontSize: number
i18nKey: string
italic: boolean
+layer: number
lineHeight: number
overflow: TextOverflow
renderMode: TextRenderMode
@@ -7083,6 +7084,7 @@ fontFamily: string | undefined
fontSize: number | undefined
i18nKey: string | undefined
italic: boolean | undefined
+layer: number | undefined
lineHeight: number | undefined
overflow: TextOverflow | undefined
renderMode: TextRenderMode | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 72967931c..efa544126 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -7227,6 +7227,7 @@ fontFamily: string
fontSize: number
i18nKey: string
italic: boolean
+layer: number
lineHeight: number
overflow: TextOverflow
renderMode: TextRenderMode
@@ -7253,6 +7254,7 @@ fontFamily: string | undefined
fontSize: number | undefined
i18nKey: string | undefined
italic: boolean | undefined
+layer: number | undefined
lineHeight: number | undefined
overflow: TextOverflow | undefined
renderMode: TextRenderMode | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index f24c6ee0a..1d39d3d4f 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7052,6 +7052,7 @@ fontFamily: string
fontSize: number
i18nKey: string
italic: boolean
+layer: number
lineHeight: number
overflow: TextOverflow
renderMode: TextRenderMode
@@ -7078,6 +7079,7 @@ fontFamily: string | undefined
fontSize: number | undefined
i18nKey: string | undefined
italic: boolean | undefined
+layer: number | undefined
lineHeight: number | undefined
overflow: TextOverflow | undefined
renderMode: TextRenderMode | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7eea47b0d..6915cd1ed 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7297,6 +7297,7 @@ fontFamily: string
fontSize: number
i18nKey: string
italic: boolean
+layer: number
lineHeight: number
overflow: TextOverflow
renderMode: TextRenderMode
@@ -7323,6 +7324,7 @@ fontFamily: string | undefined
fontSize: number | undefined
i18nKey: string | undefined
italic: boolean | undefined
+layer: number | undefined
lineHeight: number | undefined
overflow: TextOverflow | undefined
renderMode: TextRenderMode | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 67fb132e4..4c1fbe787 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7059,6 +7059,7 @@ fontFamily: string
fontSize: number
i18nKey: string
italic: boolean
+layer: number
lineHeight: number
overflow: TextOverflow
renderMode: TextRenderMode
@@ -7085,6 +7086,7 @@ fontFamily: string | undefined
fontSize: number | undefined
i18nKey: string | undefined
italic: boolean | undefined
+layer: number | undefined
lineHeight: number | undefined
overflow: TextOverflow | undefined
renderMode: TextRenderMode | undefined
diff --git a/sdk/src/ui/core/compose.ts b/sdk/src/ui/core/compose.ts
index b55455dba..4bc0d531c 100644
--- a/sdk/src/ui/core/compose.ts
+++ b/sdk/src/ui/core/compose.ts
@@ -164,6 +164,7 @@ export function buildText(init: TextInit = {}): TextData {
shadowOffsetY: init.shadowOffsetY ?? 0,
richText: init.richText ?? false,
renderMode: init.renderMode ?? TextRenderMode.Auto,
+ layer: init.layer ?? 0,
enabled: init.enabled ?? true,
};
}
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index d8cbd51c0..f7646d5af 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -72,6 +72,21 @@ export interface TextData {
shadowOffsetY: number;
richText: boolean;
renderMode: TextRenderMode;
+ /**
+ * Draw layer, for a text with NO layout box — a label standing in the world
+ * rather than inside a Canvas. It is read the same way Sprite.layer and
+ * ShapeRenderer.layer are, so a label can be put in front of (or behind) the
+ * world content around it.
+ *
+ * Ignored under a UINode: inside a Canvas the UI render order decides, and a
+ * second knob there would let a text sort against its own panel.
+ *
+ * It exists because world text was pinned to layer 0 with no way off it, so
+ * any ShapeRenderer or Sprite that also sat on layer 0 and drew later simply
+ * covered it — a board hiding its own pieces, a name tag behind the character
+ * it names — with nothing in the component to reach for.
+ */
+ layer: number;
/** Render toggle — the editor's eye and runtime hiding both flip this. */
enabled: boolean;
}
@@ -98,6 +113,7 @@ export const Text = defineComponent<TextData>('Text', {
shadowOffsetY: 0,
richText: false,
renderMode: TextRenderMode.Auto,
+ layer: 0,
enabled: true,
}, {
// A shipped font is a real asset reference: declaring it here is what gives
@@ -112,5 +128,6 @@ export const Text = defineComponent<TextData>('Text', {
verticalAlign: { enum: enumOptions(TextVerticalAlign), tooltip: 'Vertical alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (top/middle/bottom).' },
overflow: { enum: enumOptions(TextOverflow) },
renderMode: { enum: enumOptions(TextRenderMode) },
+ layer: { tooltip: 'Draw layer for a text standing in the WORLD (no UINode) — read like Sprite/ShapeRenderer layer, so a label can sit in front of the content around it. Ignored inside a Canvas, where the UI render order decides.' },
},
});
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 0191f0e5b..644465de7 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -153,13 +153,15 @@ export class TextPlugin implements Plugin {
// The layout box: a UINode (CSS box, pivot-centered) or legacy
// UINode. Text is placed + aligned + wrapped inside it and sorted
// by the UI render order. No box ⇒ a world-space label at the
- // entity origin, layer 0.
+ // entity origin, sorted by Text.layer like any other world
+ // renderer (it used to be pinned to 0, where anything else on
+ // layer 0 drawn later covered it).
let originX: number | undefined;
let originY: number | undefined;
let maxWidth: number | undefined;
let boxWidth: number | undefined;
let boxHeight: number | undefined;
- let layer = 0;
+ let layer = t.layer | 0;
let w = 0, h = 0, hasBox = false;
if (world.has(entity, UINode)) {
w = getUINodeWidth(entity);
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 4a35afcba..f177302cf 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -108,6 +108,45 @@ export function tapAlpha(target: number, n: number): number {
return 1 - Math.pow(1 - Math.min(1, Math.max(0, target)), 1 / n);
}
+/**
+ * How far a laid-out block sits from `originY`, once vertical alignment and
+ * half-leading are applied.
+ *
+ * Split out because the boxless case was wrong in a way only arithmetic shows:
+ * `rectTextBox` hands the boxed path an origin already carrying the baseline
+ * (`-0.8em`), and the boxless path started from a bare 0. Middle therefore
+ * centred the block on a baseline rather than on the entity, and every world
+ * label sat 0.8em high — half a square, on a chessboard.
+ *
+ * @param boxHeight the layout box's height; 0 ⇒ boxless, the origin IS the box
+ * @param lineHeight the laid block's height
+ */
+export function textBlockOriginY(
+ originY: number, boxHeight: number, lineHeight: number, fontSizePx: number,
+ verticalAlign: number | undefined, lineHeightPx: number | undefined,
+): number {
+ let y = originY;
+ // Boxless: the entity origin is a zero-height box, so it gets the same
+ // baseline the boxed path already receives from rectTextBox. Applied for
+ // every alignment, not only the ones that then shift — otherwise Top means
+ // "baseline on the origin" while Middle means "block centred on it", and the
+ // three do not sit on one ladder.
+ if (boxHeight <= 0) y -= fontSizePx * 0.8;
+ // Shift the block down (y-up) by the slack between box and content. With a
+ // zero-height box the slack is -blockHeight, which anchors the block to the origin.
+ if (verticalAlign) {
+ const slack = boxHeight - lineHeight;
+ y -= verticalAlign === 1 ? slack / 2 : slack; // 1 middle, 2 bottom
+ }
+ // Half-leading. A lineHeight above 1em adds space around the text, and that
+ // space belongs half above the first baseline and half below the last — the
+ // caller hands us a baseline a flat 0.8em under the line top, which puts all
+ // of it below. The block then rides (lineHeight - 1em)/2 too high inside its
+ // own box: at the default 1.2, every centred label sits 0.1em above where it
+ // should, which on a 60px label is a visible 6px.
+ return y - Math.max(0, ((lineHeightPx ?? fontSizePx * 1.2) - fontSizePx) / 2);
+}
+
/**
* Lay out `text` against `atlas` and emit one quad batch per atlas page to
* `sink`. Pure given the atlas — no engine/Canvas dependency — so the grouping
@@ -132,20 +171,9 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex
const boxHeight = p.boxHeight ?? 0;
const boxWidth = p.boxWidth ?? 0;
- // Vertical: shift the block down (y-up) by the slack between box and content. With a
- // zero-height box the slack is -blockHeight, which anchors the block to the origin.
- let originY = p.originY ?? 0;
- if (p.verticalAlign) {
- const slack = boxHeight - layout.lineHeight;
- originY -= p.verticalAlign === 1 ? slack / 2 : slack; // 1 middle, 2 bottom
- }
- // Half-leading. A lineHeight above 1em adds space around the text, and that
- // space belongs half above the first baseline and half below the last — the
- // caller hands us a baseline a flat 0.8em under the line top, which puts all
- // of it below. The block then rides (lineHeight - 1em)/2 too high inside its
- // own box: at the default 1.2, every centred label sits 0.1em above where it
- // should, which on a 60px label is a visible 6px.
- originY -= Math.max(0, ((p.lineHeight ?? p.fontSizePx * 1.2) - p.fontSizePx) / 2);
+ const originY = textBlockOriginY(
+ p.originY ?? 0, boxHeight, layout.lineHeight, p.fontSizePx, p.verticalAlign, p.lineHeight,
+ );
// A string can reference glyphs across several atlas pages; each page is a
// distinct texture, so group by page and emit one batch per page.
diff --git a/sdk/src/ui/widgets/prefabs/Button.esprefab b/sdk/src/ui/widgets/prefabs/Button.esprefab
index f64c45361..a5a9a4a3b 100644
--- a/sdk/src/ui/widgets/prefabs/Button.esprefab
+++ b/sdk/src/ui/widgets/prefabs/Button.esprefab
@@ -403,6 +403,7 @@
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
diff --git a/sdk/src/ui/widgets/prefabs/Dropdown.esprefab b/sdk/src/ui/widgets/prefabs/Dropdown.esprefab
index 70d3b058f..4dc47ffbc 100644
--- a/sdk/src/ui/widgets/prefabs/Dropdown.esprefab
+++ b/sdk/src/ui/widgets/prefabs/Dropdown.esprefab
@@ -400,6 +400,7 @@
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
diff --git a/sdk/src/ui/widgets/prefabs/ListView.esprefab b/sdk/src/ui/widgets/prefabs/ListView.esprefab
index 250e34456..8d90a83ac 100644
--- a/sdk/src/ui/widgets/prefabs/ListView.esprefab
+++ b/sdk/src/ui/widgets/prefabs/ListView.esprefab
@@ -335,6 +335,7 @@
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
diff --git a/sdk/src/ui/widgets/prefabs/generated.ts b/sdk/src/ui/widgets/prefabs/generated.ts
index 78660d20f..308e87b7e 100644
--- a/sdk/src/ui/widgets/prefabs/generated.ts
+++ b/sdk/src/ui/widgets/prefabs/generated.ts
@@ -407,6 +407,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
@@ -2634,6 +2635,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
@@ -2985,6 +2987,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {
"shadowOffsetY": 0,
"richText": false,
"renderMode": 0,
+ "layer": 0,
"enabled": true
}
},
diff --git a/sdk/tests/ui-text-block-origin.test.ts b/sdk/tests/ui-text-block-origin.test.ts
new file mode 100644
index 000000000..b3bc2e158
--- /dev/null
+++ b/sdk/tests/ui-text-block-origin.test.ts
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui-text-block-origin.test.ts
+ * @brief Where a laid text block sits relative to its origin, for a label with
+ * a layout box and for one standing in the world without.
+ *
+ * The boxed path receives an origin that already carries the baseline
+ * (rectTextBox subtracts 0.8em); the boxless one used to start from a
+ * bare 0, so Middle centred the block on a BASELINE instead of on the
+ * entity and every world label rode 0.8em high — half a square on a
+ * chessboard, which is how it was found.
+ */
+import { describe, it, expect } from 'vitest';
+import { textBlockOriginY } from '../src/ui/text/text-renderer';
+import { rectTextBox } from '../src/ui/text/text-transform';
+
+const FS = 50;
+const LINE = FS * 1.2; // the laid block's height at the default lineHeight
+
+/** Boxed, pivot-centred: what a UINode of `h` hands the renderer. */
+const boxed = (h: number, valign: number): number =>
+ textBlockOriginY(rectTextBox(0.5, 0.5, 100, h, FS).originY, h, LINE, FS, valign, LINE);
+
+/** Boxless: the entity origin, nothing else. */
+const boxless = (valign: number): number => textBlockOriginY(0, 0, LINE, FS, valign, LINE);
+
+describe('textBlockOriginY', () => {
+ it('centres a boxless Middle label on the entity, not on its baseline', () => {
+ // The same answer a zero-height box would give, which is the definition
+ // of "the origin IS the box".
+ expect(boxless(1)).toBeCloseTo(boxed(0.000001, 1), 5);
+ // And 0.8em below where it used to land.
+ expect(boxless(1)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);
+ });
+
+ it('puts Top, Middle and Bottom on ONE ladder, hanging below to sitting above', () => {
+ expect(boxless(0)).toBeLessThan(boxless(1));
+ expect(boxless(1)).toBeLessThan(boxless(2));
+ // Each is the answer a zero-height box gives — the rule is the same one.
+ for (const valign of [0, 1, 2]) {
+ expect(boxless(valign)).toBeCloseTo(boxed(0.000001, valign), 5);
+ }
+ });
+
+ it('treats an unspecified alignment as Top, not as a third behaviour', () => {
+ expect(textBlockOriginY(0, 0, LINE, FS, undefined, LINE)).toBeCloseTo(boxless(0), 5);
+ });
+
+ it('does not touch the boxed path — a Middle label in a box is unmoved', () => {
+ // Centred in its box: the block's middle lands on the box's middle, which
+ // for a pivot-centred box is the entity. (0.8em baseline, half a line back
+ // up, less half-leading.)
+ expect(boxed(200, 1)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);
+ // Taller box, same answer: centring cannot depend on the box's height.
+ expect(boxed(400, 1)).toBeCloseTo(boxed(200, 1), 5);
+ });
+
+ it('honours half-leading only when the line is taller than the em', () => {
+ // Boxed, so the boxless baseline term is not in play — this isolates leading.
+ expect(textBlockOriginY(0, 100, FS, FS, 0, FS)).toBe(0);
+ expect(textBlockOriginY(0, 100, FS, FS, 0, FS * 0.9)).toBe(0); // never negative
+ });
+});
diff --git a/sdk/tests/ui-text-world-layer.test.ts b/sdk/tests/ui-text-world-layer.test.ts
new file mode 100644
index 000000000..178fb4a81
--- /dev/null
+++ b/sdk/tests/ui-text-world-layer.test.ts
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui-text-world-layer.test.ts
+ * @brief A Text with no layout box is a label standing in the WORLD, and it
+ * sorts by Text.layer like any other world renderer.
+ *
+ * It used to be pinned to layer 0 with nothing in the component to
+ * reach for, so anything else on layer 0 that drew later covered it —
+ * a board hiding its own pieces. Inside a Canvas the UI render order
+ * still decides, so the field must NOT leak into that path.
+ */
+import { describe, it, expect } from 'vitest';
+import { Text, buildText } from '../src/ui';
+
+describe('Text.layer', () => {
+ it('is a field of the component, defaulting to 0', () => {
+ const def = Text._default as { layer: number };
+ expect(def.layer).toBe(0);
+ });
+
+ it('carries through buildText, so a composed label can name its layer', () => {
+ expect(buildText().layer).toBe(0);
+ expect(buildText({ layer: 5 }).layer).toBe(5);
+ });
+
+ it('says in the inspector that it is the world-space knob', () => {
+ const tip = Text.fieldMeta['layer']?.tooltip ?? '';
+ expect(tip).toMatch(/world/i);
+ expect(tip).toMatch(/Canvas/i);
+ });
+});