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): UIRect-anchored positioning for UIText (REARCH_GUI P1.4c)
esengine8c2b30267d77
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex 7d2f7dd9d..1cd1bef7f 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -372,6 +372,7 @@ export {UI_TEXT_BOLD,UI_TEXT_ITALIC,composeTRS,+ rectTextBox,type UITextData,} from './text/ui-text';diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 2479c6ef7..b1e55b406 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -232,13 +232,15 @@ export function layoutText(? layoutRichLine(line, atlas, fontFamily, { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor }, style): layoutLine(line, atlas, fontFamily, opts, style)));- const blockWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);+ const contentWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);+ // Align within the wrap/rect box when one is given, else within the widest line.+ const alignWidth = (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth : contentWidth;const glyphs: LaidGlyph[] = [];for (let i = 0; i < lineLayouts.length; i++) {const ll = lineLayouts[i];- const dx = align === TEXT_ALIGN_CENTER ? (blockWidth - ll.width) / 2- : align === TEXT_ALIGN_RIGHT ? (blockWidth - ll.width)+ const dx = align === TEXT_ALIGN_CENTER ? (alignWidth - ll.width) / 2+ : align === TEXT_ALIGN_RIGHT ? (alignWidth - ll.width): 0;const dy = -i * lineHeight; // y-up: first line on topfor (const g of ll.glyphs) {@@ -246,7 +248,7 @@ export function layoutText(}}- return { glyphs, width: blockWidth, lineHeight: lines.length * lineHeight };+ return { glyphs, width: contentWidth, lineHeight: lines.length * lineHeight };}/**diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 0e55cbc02..79d84b252 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -12,7 +12,9 @@ import { registerComponent } from '../../component';import type { ESEngineModule } from '../../wasm';import type { Entity } from '../../types';import { SdfTextRenderer } from './text-renderer';-import { UIText, type UITextData, composeTRS } from './ui-text';+import { UIText, type UITextData, composeTRS, rectTextBox } from './ui-text';+import { UIRect, type UIRectData } from '../core/ui-rect';+import { getEffectiveWidth, getEffectiveHeight } from '../uiHelpers';export class UITextPlugin implements Plugin {name = 'uiText';@@ -39,6 +41,22 @@ export class UITextPlugin implements Plugin {}const tr = world.get(entity, Transform) as TransformData;composeTRS(this.matrix_, tr.worldPosition, tr.worldRotation, tr.worldScale);++ // In a UIRect (UI canvas), place + align + wrap the text inside the+ // rect box; otherwise it's a world-space label at the entity origin.+ let originX: number | undefined;+ let originY: number | undefined;+ let maxWidth = t.maxWidth || undefined;+ if (world.has(entity, UIRect)) {+ const rect = world.get(entity, UIRect) as UIRectData;+ const w = getEffectiveWidth(rect, entity);+ const h = getEffectiveHeight(rect, entity);+ const box = rectTextBox(rect.pivot.x, rect.pivot.y, w, h, t.fontSizePx);+ originX = box.originX;+ originY = box.originY;+ if (!maxWidth) maxWidth = box.maxWidth;+ }+this.renderer_.drawText({text: t.content,@@ -49,7 +67,9 @@ export class UITextPlugin implements Plugin {richText: t.richText,align: t.align,lineHeight: t.lineHeight || undefined,- maxWidth: t.maxWidth || undefined,+ maxWidth,+ originX,+ originY,},this.matrix_,entity as number,diff --git a/sdk/src/ui/text/ui-text.ts b/sdk/src/ui/text/ui-text.tsindex cbbed2748..178371c97 100644--- a/sdk/src/ui/text/ui-text.ts+++ b/sdk/src/ui/text/ui-text.ts@@ -64,3 +64,20 @@ export function composeTRS(out: Float32Array, t: Vec3, q: Quat, s: Vec3): Float3out[12] = t.x; out[13] = t.y; out[14] = t.z; out[15] = 1;return out;}++/**+ * Place a text block inside a UIRect (REARCH_GUI P1.4c). The entity Transform+ * sits at the rect's pivot (UI layout positions the pivot), so glyph local+ * positions (baseline y=0, y-up) need offsetting to the rect's top-left, and the+ * rect width becomes the wrap/align box. Top-vertical-aligned; first line's+ * baseline sits one ascent below the rect top (ascent ≈ fontSize × 0.8). Pure.+ */+export function rectTextBox(+ pivotX: number, pivotY: number, width: number, height: number, fontSizePx: number,+): { originX: number; originY: number; maxWidth: number } {+ return {+ originX: -pivotX * width, // rect left edge, local to the pivot+ originY: (1 - pivotY) * height - fontSizePx * 0.8, // rect top (y-up) minus first-line ascent+ maxWidth: width,+ };+}diff --git a/sdk/tests/ui-text-multiline.test.ts b/sdk/tests/ui-text-multiline.test.tsindex a2f2c3f8d..75a3d47ee 100644--- a/sdk/tests/ui-text-multiline.test.ts+++ b/sdk/tests/ui-text-multiline.test.ts@@ -46,4 +46,10 @@ describe('REARCH_GUI P1.4c: multi-line + alignment', () => {expect(layout.glyphs.length).toBe(2);expect(layout.width).toBeCloseTo(11);});++ it('centers within the box (maxWidth) when given, not just the line width', () => {+ const boxed = layoutText('AB', makeAtlas(), 'Arial', { fontSizePx: 24, align: TEXT_ALIGN_CENTER, maxWidth: 100 });+ // line width 11 centered in a 100 box ⇒ +44.5 from the left-aligned x0 (0.5)+ expect(boxed.glyphs[0].x0).toBeCloseTo(0.5 + (100 - 11) / 2);+ });});diff --git a/sdk/tests/ui-text-uitext.test.ts b/sdk/tests/ui-text-uitext.test.tsindex 32fa31aa3..1f7790f64 100644--- a/sdk/tests/ui-text-uitext.test.ts+++ b/sdk/tests/ui-text-uitext.test.ts@@ -4,7 +4,7 @@* full on-screen path (UITextPlugin → render) is render-host-verified.*/import { describe, it, expect } from 'vitest';-import { composeTRS } from '../src/ui/text/ui-text';+import { composeTRS, rectTextBox } from '../src/ui/text/ui-text';const IDQ = { x: 0, y: 0, z: 0, w: 1 };@@ -29,3 +29,18 @@ describe('REARCH_GUI P1.3c: composeTRS', () => {expect(m[15]).toBe(1);});});++describe('REARCH_GUI P1.4c: rectTextBox (UIRect text placement)', () => {+ it('offsets a center-pivot rect to its top-left + wrap box', () => {+ const box = rectTextBox(0.5, 0.5, 200, 100, 24);+ expect(box.originX).toBeCloseTo(-100); // left of a center-pivoted 200-wide rect+ expect(box.originY).toBeCloseTo(50 - 24 * 0.8); // rect top (y-up) minus first-line ascent+ expect(box.maxWidth).toBe(200);+ });++ it('top-left-pivot rect: left edge at the pivot', () => {+ const box = rectTextBox(0, 1, 200, 100, 24);+ expect(box.originX).toBeCloseTo(0);+ expect(box.originY).toBeCloseTo(-24 * 0.8);+ });+});