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): UIRect-anchored positioning for UIText (REARCH_GUI P1.4c)

esengine8c2b30267d77
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 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.ts
index 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 top
for (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.ts
index 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.ts
index 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): Float3
out[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.ts
index 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.ts
index 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);
+ });
+});