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(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.tsindex 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, whereturn { 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: ComponentContitalic: 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: ComponentContreturn { 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: strinout = 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.tsindex 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.tsindex 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.tsindex 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 Teamimport { 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.tsindex 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-wrapboxHeight = 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 thediff --git a/sdk/tests/ui-text-retained.test.ts b/sdk/tests/ui-text-retained.test.tsindex 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);+ });+});