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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.mdindex 9572d2e61..821227e97 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -7057,6 +7057,7 @@ fontFamily: stringfontSize: numberi18nKey: stringitalic: boolean+layer: numberlineHeight: numberoverflow: TextOverflowrenderMode: TextRenderMode@@ -7083,6 +7084,7 @@ fontFamily: string | undefinedfontSize: number | undefinedi18nKey: string | undefineditalic: boolean | undefined+layer: number | undefinedlineHeight: number | undefinedoverflow: TextOverflow | undefinedrenderMode: TextRenderMode | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 72967931c..efa544126 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -7227,6 +7227,7 @@ fontFamily: stringfontSize: numberi18nKey: stringitalic: boolean+layer: numberlineHeight: numberoverflow: TextOverflowrenderMode: TextRenderMode@@ -7253,6 +7254,7 @@ fontFamily: string | undefinedfontSize: number | undefinedi18nKey: string | undefineditalic: boolean | undefined+layer: number | undefinedlineHeight: number | undefinedoverflow: TextOverflow | undefinedrenderMode: TextRenderMode | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f24c6ee0a..1d39d3d4f 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -7052,6 +7052,7 @@ fontFamily: stringfontSize: numberi18nKey: stringitalic: boolean+layer: numberlineHeight: numberoverflow: TextOverflowrenderMode: TextRenderMode@@ -7078,6 +7079,7 @@ fontFamily: string | undefinedfontSize: number | undefinedi18nKey: string | undefineditalic: boolean | undefined+layer: number | undefinedlineHeight: number | undefinedoverflow: TextOverflow | undefinedrenderMode: TextRenderMode | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7eea47b0d..6915cd1ed 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -7297,6 +7297,7 @@ fontFamily: stringfontSize: numberi18nKey: stringitalic: boolean+layer: numberlineHeight: numberoverflow: TextOverflowrenderMode: TextRenderMode@@ -7323,6 +7324,7 @@ fontFamily: string | undefinedfontSize: number | undefinedi18nKey: string | undefineditalic: boolean | undefined+layer: number | undefinedlineHeight: number | undefinedoverflow: TextOverflow | undefinedrenderMode: TextRenderMode | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 67fb132e4..4c1fbe787 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -7059,6 +7059,7 @@ fontFamily: stringfontSize: numberi18nKey: stringitalic: boolean+layer: numberlineHeight: numberoverflow: TextOverflowrenderMode: TextRenderMode@@ -7085,6 +7086,7 @@ fontFamily: string | undefinedfontSize: number | undefinedi18nKey: string | undefineditalic: boolean | undefined+layer: number | undefinedlineHeight: number | undefinedoverflow: TextOverflow | undefinedrenderMode: TextRenderMode | undefineddiff --git a/sdk/src/ui/core/compose.ts b/sdk/src/ui/core/compose.tsindex 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.tsindex 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.tsindex 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.tsindex 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: DrawTexconst 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.esprefabindex 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.esprefabindex 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.esprefabindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});