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(text): a world Text can lay out in its own box — width, height and an anchor pivot — so labels wrap, align and clip without joining a Canvas; the Cocos import uses it

yhhcd32ca5f3bab
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 36bb161cd..cf4786773 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -140,7 +140,7 @@ function sprite(c: CocosComponent, box: UiBox | null, ctx: ComponentContext, whe
return { type: 'Sprite', data };
}
-function label(c: CocosComponent, siblings: CocosComponent[], ctx: ComponentContext, where: string): ComponentData {
+function label(c: CocosComponent, siblings: CocosComponent[], box: UiBox | null, ctx: ComponentContext, where: string): ComponentData {
const d = c.data;
const fontSize = num(d._fontSize, 40);
const lineHeight = num(d._lineHeight, fontSize);
@@ -160,6 +160,12 @@ function label(c: CocosComponent, siblings: CocosComponent[], ctx: ComponentCont
italic: d._isItalic === true,
enabled: c.enabled,
};
+ // A Label wraps, aligns and clips inside its UITransform rect, and the node origin is that rect's anchor.
+ if (box) {
+ data.boxWidth = box.width;
+ data.boxHeight = box.height;
+ data.boxPivot = { x: box.ax, y: box.ay };
+ }
if (overflow === 2 || overflow === 3) {
status = 'partial';
ctx.report.note(overflow === 2 ? 'label-shrink-overflow' : 'label-resize-height', where);
@@ -205,12 +211,14 @@ function label(c: CocosComponent, siblings: CocosComponent[], ctx: ComponentCont
return { type: 'Text', data };
}
-function richText(c: CocosComponent, ctx: ComponentContext): ComponentData {
+function richText(c: CocosComponent, box: UiBox | null, ctx: ComponentContext): ComponentData {
const d = c.data;
ctx.report.component('cc.RichText', 'partial');
+ const maxWidth = num(d._maxWidth, 0);
return {
type: 'Text',
data: {
+ ...(box && maxWidth > 0 ? { boxWidth: maxWidth, boxHeight: box.height, boxPivot: { x: box.ax, y: box.ay } } : {}),
content: typeof d._string === 'string' ? d._string : '',
fontSize: num(d._fontSize, 40),
color: color(d._fontColor),
@@ -264,10 +272,10 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strin
out = sprite(c, box, ctx, where);
break;
case 'cc.Label':
- out = label(c, node.components, ctx, where);
+ out = label(c, node.components, box, ctx, where);
break;
case 'cc.RichText':
- out = richText(c, ctx);
+ out = richText(c, box, ctx);
break;
case 'cc.Camera':
out = camera(c, ctx);
diff --git a/pipeline/tests/cocos-import.test.ts b/pipeline/tests/cocos-import.test.ts
index ab49904e8..7b6c3af2a 100644
--- a/pipeline/tests/cocos-import.test.ts
+++ b/pipeline/tests/cocos-import.test.ts
@@ -184,6 +184,8 @@ describe('importing a Cocos project', () => {
const caption = readJson('assets/cocos/ui/item.esprefab').entities.find((e: any) => e.prefabEntityId === 'capt');
expect(caption.components.find((c: any) => c.type === 'Text').data).toMatchObject({
content: 'hello', fontSize: 20, align: 1, verticalAlign: 1, overflow: 0, font: 'assets/cocos/ui/f.fnt',
+ // the Label's UITransform becomes its layout box, with the node origin at the anchor
+ boxWidth: 80, boxHeight: 20, boxPivot: { x: 0.5, y: 0.5 },
});
const written = [...files(out)].map((f) => path.relative(out, f).split(path.sep).join('/'));
expect(written, written.join(',')).toContain('assets/cocos/ui/f_0.png');
diff --git a/sdk/src/ui/core/compose.ts b/sdk/src/ui/core/compose.ts
index e7977e352..e494632d4 100644
--- a/sdk/src/ui/core/compose.ts
+++ b/sdk/src/ui/core/compose.ts
@@ -165,6 +165,9 @@ export function buildText(init: TextInit = {}): TextData {
richText: init.richText ?? false,
renderMode: init.renderMode ?? TextRenderMode.Auto,
layer: init.layer ?? 0,
+ boxWidth: init.boxWidth ?? 0,
+ boxHeight: init.boxHeight ?? 0,
+ boxPivot: init.boxPivot ?? { x: 0.5, y: 0.5 },
enabled: init.enabled ?? true,
};
}
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index c173a24fa..cd738ba31 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { defineComponent, enumOptions } from '../../ecs/component';
-import type { Color } from '../../types';
+import type { Color, Vec2 } from '../../types';
/**
* Horizontal alignment. With a layout box it aligns inside the box; without one it
@@ -118,6 +118,20 @@ export interface TextData {
* it names — with nothing in the component to reach for.
*/
layer: number;
+ /**
+ * Width of the layout box for a text with NO `UINode` — 0 (the default) means no box, and the entity origin
+ * is the box, as it always was. With a box, alignment, wrapping and overflow work inside it, exactly as
+ * under a `UINode`, while the text stays world content sorted by `layer`. A `UINode`, when present, decides
+ * the box and these three are ignored.
+ */
+ boxWidth: number;
+ /** Height of that box; 0 for none. Vertical alignment and `Clip`/`Ellipsis` need it. */
+ boxHeight: number;
+ /**
+ * Where the entity origin sits inside the box, as a fraction from its left and bottom edges: (0.5, 0.5) is
+ * the centre, (0, 1) the top-left corner. It is the anchor point of a Cocos or Unity rect transform.
+ */
+ boxPivot: Vec2;
/** Render toggle — the editor's eye and runtime hiding both flip this. */
enabled: boolean;
}
@@ -152,6 +166,9 @@ export const Text = defineComponent<TextData>('Text', {
richText: false,
renderMode: TextRenderMode.Auto,
layer: 0,
+ boxWidth: 0,
+ boxHeight: 0,
+ boxPivot: { x: 0.5, y: 0.5 },
enabled: true,
}, {
// Text draws itself (the plugin skips a disabled one) rather than through a
@@ -173,6 +190,9 @@ export const Text = defineComponent<TextData>('Text', {
tooltip: 'What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width.',
},
renderMode: { enum: enumOptions(TextRenderMode) },
+ boxWidth: { tooltip: 'Layout box width for a text with no UINode (0 = no box: the origin is the box). Alignment, wrapping and overflow work inside it. A UINode, if present, decides the box instead.' },
+ boxHeight: { tooltip: 'Layout box height (0 = none). Vertical alignment and Clip/Ellipsis need it.' },
+ boxPivot: { tooltip: 'Where the entity origin sits in the box, as a fraction from its left/bottom edge: (0.5, 0.5) is the centre, (0, 1) the top-left corner.' },
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 d96094635..105ffdcc9 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -15,6 +15,7 @@ import { defineSystem, Schedule } from '../../ecs/system';
import { SystemLabel } from '../../ecs/systemLabels';
import type { ESEngineModule, CppRegistry } from '../../wasm';
import type { Entity } from '../../types';
+import type { World } from '../../ecs/world';
import { SdfTextRenderer } from './text-renderer';
import type { RGBA } from './layout';
import { composeTRS, rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
@@ -80,10 +81,32 @@ export function glyphContentScale(projScaleX: number, vpW: number, dpr: number):
return shownSpan > 0 ? vpW / (shownSpan * dpr) : 1;
}
+/** The box a Text is laid out in, and where the entity origin sits in it. */
+export interface TextFrame {
+ w: number;
+ h: number;
+ /** Pivot as a fraction from the box's left / bottom edge. */
+ px: number;
+ py: number;
+ /** True when a UINode supplied the box: the label is then UI content, ordered by the UI tree. */
+ ui: boolean;
+}
+
+/**
+ * Where a Text gets its box. A UINode decides it, pivot-centred, as ever; without one, the Text's own box fields
+ * do, with the pivot they name — so world content can wrap, align and clip inside a rect without joining a Canvas.
+ * Pure over what it is given, apart from reading the node's computed size.
+ */
+export function textFrame(world: World, entity: Entity, t: TextData): TextFrame {
+ if (world.has(entity, UINode)) return { w: getUINodeWidth(entity), h: getUINodeHeight(entity), px: 0.5, py: 0.5, ui: true };
+ return { w: t.boxWidth || 0, h: t.boxHeight || 0, px: t.boxPivot?.x ?? 0.5, py: t.boxPivot?.y ?? 0.5, ui: false };
+}
+
/** The Text fields a retained label's geometry was laid out from; a label is rebuilt when any of them differs, and not otherwise. */
export interface TextSnapshot {
content: string; family: string; fontSize: number; bold: boolean; italic: boolean; richText: boolean; renderMode: number;
align: number; verticalAlign: number; wordWrap: boolean; overflow: number; lineHeight: number; layer: number;
+ boxW: number; boxH: number; boxPx: number; boxPy: number;
cr: number; cg: number; cb: number; ca: number;
strokeWidth: number; sr: number; sg: number; sb: number; sa: number;
shadowBlur: number; shadowX: number; shadowY: number; hr: number; hg: number; hb: number; ha: number;
@@ -101,6 +124,7 @@ export function snapshotOf(t: TextData, family: string): TextSnapshot {
return {
content: t.content, family, fontSize: t.fontSize, bold: !!t.bold, italic: !!t.italic, richText: !!t.richText, renderMode: t.renderMode,
align: t.align, verticalAlign: t.verticalAlign, wordWrap: !!t.wordWrap, overflow: t.overflow, lineHeight: t.lineHeight, layer: t.layer | 0,
+ boxW: t.boxWidth || 0, boxH: t.boxHeight || 0, boxPx: t.boxPivot?.x ?? 0.5, boxPy: t.boxPivot?.y ?? 0.5,
cr: t.color.r, cg: t.color.g, cb: t.color.b, ca: t.color.a,
strokeWidth: t.strokeWidth, sr: t.strokeColor.r, sg: t.strokeColor.g, sb: t.strokeColor.b, sa: t.strokeColor.a,
shadowBlur: t.shadowBlur, shadowX: t.shadowOffsetX, shadowY: t.shadowOffsetY,
@@ -113,6 +137,7 @@ export function sameSnapshot(s: TextSnapshot, t: TextData, family: string): bool
&& s.bold === !!t.bold && s.italic === !!t.italic && s.richText === !!t.richText && s.renderMode === t.renderMode
&& s.align === t.align && s.verticalAlign === t.verticalAlign && s.wordWrap === !!t.wordWrap
&& s.overflow === t.overflow && s.lineHeight === t.lineHeight && s.layer === (t.layer | 0)
+ && s.boxW === (t.boxWidth || 0) && s.boxH === (t.boxHeight || 0) && s.boxPx === (t.boxPivot?.x ?? 0.5) && s.boxPy === (t.boxPivot?.y ?? 0.5)
&& s.cr === t.color.r && s.cg === t.color.g && s.cb === t.color.b && s.ca === t.color.a
&& s.strokeWidth === t.strokeWidth
&& s.sr === t.strokeColor.r && s.sg === t.strokeColor.g && s.sb === t.strokeColor.b && s.sa === t.strokeColor.a
@@ -367,14 +392,11 @@ export class TextPlugin implements Plugin {
let maxWidth: number | undefined;
let boxWidth: number | undefined;
let boxHeight: number | undefined;
- let w = 0, h = 0, hasBox = false;
- if (world.has(entity, UINode)) {
- w = getUINodeWidth(entity);
- h = getUINodeHeight(entity);
- hasBox = w > 0 || h > 0;
- }
+ const frame = textFrame(world, entity, t);
+ const w = frame.w, h = frame.h;
+ const hasBox = w > 0 || h > 0;
if (hasBox) {
- const box = rectTextBox(0.5, 0.5, w, h, t.fontSize);
+ const box = rectTextBox(frame.px, frame.py, w, h, t.fontSize);
originX = box.originX;
originY = box.originY;
boxWidth = box.maxWidth; // align within the box regardless of word-wrap
@@ -418,7 +440,9 @@ export class TextPlugin implements Plugin {
shadow,
outline,
},
- entity as number, screen, hasBox, t.layer | 0, w, h,
+ // The engine orders a boxed label by the UI tree and re-lays it out when the node's size changes; a box
+ // that is the Text's own is neither, so it is reported as no box (its size reaches layout above).
+ entity as number, screen, hasBox && frame.ui, t.layer | 0, frame.ui ? w : 0, frame.ui ? h : 0,
t.renderMode !== TextRenderMode.Bitmap && t.renderMode !== TextRenderMode.Sdf,
);
appState.retained.set(entity as number, { snap: snapshotOf(t, family), screen, gen: renderer.atlas.generation, renderer });
@@ -479,22 +503,20 @@ export class TextPlugin implements Plugin {
let boxWidth: number | undefined;
let boxHeight: number | undefined;
let layer = t.layer | 0;
- let w = 0, h = 0, hasBox = false;
- if (world.has(entity, UINode)) {
- w = getUINodeWidth(entity);
- h = getUINodeHeight(entity);
- hasBox = w > 0 || h > 0;
- }
+ const frame = textFrame(world, entity, t);
+ const hasBox = frame.w > 0 || frame.h > 0;
if (hasBox) {
- const box = rectTextBox(0.5, 0.5, w, h, t.fontSize);
+ const box = rectTextBox(frame.px, frame.py, frame.w, frame.h, t.fontSize);
originX = box.originX;
originY = box.originY;
boxWidth = box.maxWidth; // align within the box regardless of word-wrap
boxHeight = box.boxHeight;
if (t.wordWrap) maxWidth = box.maxWidth; // wrap only when enabled
- const order = api?.ui_getRenderOrder?.(registry, entity as number) ?? -1;
- layer = order >= 0 ? UI_BASE_LAYER + order : UI_BASE_LAYER;
+ if (frame.ui) {
+ const order = api?.ui_getRenderOrder?.(registry, entity as number) ?? -1;
+ layer = order >= 0 ? UI_BASE_LAYER + order : UI_BASE_LAYER;
+ }
}
// A blur with no offset is still a shadow — a halo centred on the
diff --git a/sdk/tests/ui-text-retained.test.ts b/sdk/tests/ui-text-retained.test.ts
index 7ef3a72f4..59acacfc9 100644
--- a/sdk/tests/ui-text-retained.test.ts
+++ b/sdk/tests/ui-text-retained.test.ts
@@ -9,6 +9,7 @@ import { describe, expect, it, vi } from 'vitest';
import { GlyphAtlas } from '../src/ui/text/glyph-atlas';
import { SdfTextRenderer, drawTextWith, type DrawTextParams } from '../src/ui/text/text-renderer';
import { resolveTextRenderMode, sameSnapshot, snapshotOf } from '../src/ui/text/plugin';
+import { rectTextBox } from '../src/ui/text/text-transform';
import type { TextData } from '../src/ui/core/text';
import type { EngineApi } from '../src/ecs/bridge/engineApi';
import { TEXT_VERTEX_FLOATS } from '../src/ui/text/submit';
@@ -24,6 +25,7 @@ function freshText(): TextData {
align: 0, verticalAlign: 0, wordWrap: true, overflow: 0, lineHeight: 1.2, bold: false, italic: false,
strokeColor: { r: 0, g: 0, b: 0, a: 1 }, strokeWidth: 0, shadowColor: { r: 0, g: 0, b: 0, a: 1 }, shadowBlur: 0,
shadowOffsetX: 0, shadowOffsetY: 0, richText: false, renderMode: 0, layer: 0, enabled: true,
+ boxWidth: 0, boxHeight: 0, boxPivot: { x: 0.5, y: 0.5 },
} as TextData;
}
@@ -51,6 +53,10 @@ describe('which Text fields make a retained label laid out again', () => {
['richText', t => { t.richText = true; }],
['renderMode', t => { t.renderMode = 1; }],
['layer', t => { t.layer = 3; }],
+ // The box a world label lays out in: moving or resizing it moves the glyphs, so each is part of what "the same label" means.
+ ['boxWidth', t => { t.boxWidth = 120; }],
+ ['boxHeight', t => { t.boxHeight = 40; }],
+ ['boxPivot', t => { t.boxPivot = { x: 0, y: 1 }; }],
];
// font is resolved to the family and compared as that; enabled and an empty content decide whether the label exists at all; i18nKey only
// ever changes `content`.
@@ -154,3 +160,27 @@ describe('handing a label to the engine', () => {
expect([...pages].some(p => afterForget.has(p))).toBe(false);
});
});
+
+describe('where a text box puts the glyphs relative to the entity', () => {
+ // The entity origin is the box's pivot (an anchor point, from the left and the BOTTOM edge); the glyph block starts at the box's top-left
+ // corner, one ascent (0.8 em) below the top for the first baseline.
+ it('centred pivot: the box straddles the origin', () => {
+ const b = rectTextBox(0.5, 0.5, 200, 60, 20);
+ expect(b.originX).toBe(-100);
+ expect(b.originY).toBe(30 - 16);
+ expect(b.maxWidth).toBe(200);
+ expect(b.boxHeight).toBe(60);
+ });
+
+ it('top-left pivot: the box hangs right of and below the origin', () => {
+ const b = rectTextBox(0, 1, 200, 60, 20);
+ expect(b.originX).toBeCloseTo(0);
+ expect(b.originY).toBe(0 - 16);
+ });
+
+ it('bottom-right pivot: the box sits left of and above the origin', () => {
+ const b = rectTextBox(1, 0, 200, 60, 20);
+ expect(b.originX).toBe(-200);
+ expect(b.originY).toBe(60 - 16);
+ });
+});