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): multi-line + alignment layout for SDF text (REARCH_GUI P1.4c)

esengine3046b0f3d852
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 32b3a4f3d..9d55d45cb 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -406,10 +406,15 @@ export { EngineAtlasPageStore } from './text/atlas-page-store';
export {
layoutLine,
layoutRichLine,
+ layoutText,
buildGlyphVertices,
+ TEXT_ALIGN_LEFT,
+ TEXT_ALIGN_CENTER,
+ TEXT_ALIGN_RIGHT,
type TextLayout,
type TextLayoutOptions,
type RichTextLayoutOptions,
+ type MultilineTextOptions,
type LaidGlyph,
type RGBA,
type GlyphVertexData,
diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.ts
index be3637fb2..91e174dfe 100644
--- a/sdk/src/ui/text/layout.ts
+++ b/sdk/src/ui/text/layout.ts
@@ -135,6 +135,61 @@ export interface RichTextLayoutOptions extends TextLayoutOptions {
color: RGBA;
}
+/** Horizontal alignment: 0 = left, 1 = center, 2 = right. */
+export const TEXT_ALIGN_LEFT = 0;
+export const TEXT_ALIGN_CENTER = 1;
+export const TEXT_ALIGN_RIGHT = 2;
+
+export interface MultilineTextOptions extends TextLayoutOptions {
+ /** Baseline-to-baseline distance in px. Default fontSizePx * 1.2. */
+ lineHeight?: number;
+ /** 0 left | 1 center | 2 right. Default left. */
+ align?: number;
+ /** Parse rich markup (`<b>` etc.) per line. */
+ rich?: boolean;
+ /** Base color (used by rich runs without their own color). */
+ color?: RGBA;
+}
+
+/**
+ * Lay out multi-line text (REARCH_GUI P1.4): splits on `\n`, lays each line out
+ * (rich or plain), stacks lines downward (y-up: line 0 on top) by `lineHeight`,
+ * and horizontally aligns each line within the widest line's block. Pure →
+ * unit-testable. (Word-wrap to a max width is a later addition.)
+ */
+export function layoutText(
+ text: string,
+ atlas: GlyphAtlas,
+ fontFamily: string,
+ opts: MultilineTextOptions,
+ style = 0,
+): TextLayout {
+ const lineHeight = opts.lineHeight ?? opts.fontSizePx * 1.2;
+ const align = opts.align ?? TEXT_ALIGN_LEFT;
+ const baseColor = opts.color ?? ([1, 1, 1, 1] as const);
+ const lines = text.split('\n');
+
+ const lineLayouts = lines.map(line => (opts.rich
+ ? 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 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)
+ : 0;
+ const dy = -i * lineHeight; // y-up: first line on top
+ for (const g of ll.glyphs) {
+ glyphs.push({ ...g, x0: g.x0 + dx, x1: g.x1 + dx, y0: g.y0 + dy, y1: g.y1 + dy });
+ }
+ }
+
+ return { glyphs, width: blockWidth, lineHeight: lines.length * lineHeight };
+}
+
/**
* Lay out a single line of rich text (REARCH_GUI P1.4): `<b>`, `<i>`,
* `<color=#rrggbb[aa]>`, `<font size=N>` runs (parsed by parseRichText) become
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index d7b6540ca..555d44d09 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -47,6 +47,8 @@ export class UITextPlugin implements Plugin {
color: [t.color.r, t.color.g, t.color.b, t.color.a],
style: t.style,
richText: t.richText,
+ align: t.align,
+ lineHeight: t.lineHeight || undefined,
},
this.matrix_,
entity as number,
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 89887c904..9409baa4f 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -12,7 +12,7 @@ import type { ESEngineModule } from '../../wasm';
import { GlyphAtlas } from './glyph-atlas';
import { CanvasGlyphRasterizer, type CanvasGlyphRasterizerOptions } from './glyph-rasterizer';
import { EngineAtlasPageStore } from './atlas-page-store';
-import { layoutLine, layoutRichLine, buildGlyphVertices, type LaidGlyph, type RGBA } from './layout';
+import { layoutText, buildGlyphVertices, type LaidGlyph, type RGBA } from './layout';
import { submitTextBatch } from './submit';
/** Receives one (vertices, indices) batch per atlas page used by the text. */
@@ -28,6 +28,12 @@ export interface DrawTextParams {
style?: number;
/** Parse `<b>/<i>/<color>/<font size>` markup (REARCH_GUI P1.4). */
richText?: boolean;
+ /** Horizontal alignment: 0 left | 1 center | 2 right. */
+ align?: number;
+ /** Baseline-to-baseline distance (px) for multi-line text. */
+ lineHeight?: number;
+ /** Extra advance between glyphs (px). */
+ letterSpacing?: number;
}
/**
@@ -36,9 +42,14 @@ export interface DrawTextParams {
* and geometry are unit-testable.
*/
export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTextParams): void {
- const layout = p.richText
- ? layoutRichLine(p.text, atlas, p.fontFamily, { fontSizePx: p.fontSizePx, color: p.color }, p.style ?? 0)
- : layoutLine(p.text, atlas, p.fontFamily, { fontSizePx: p.fontSizePx }, p.style ?? 0);
+ const layout = layoutText(p.text, atlas, p.fontFamily, {
+ fontSizePx: p.fontSizePx,
+ letterSpacing: p.letterSpacing,
+ lineHeight: p.lineHeight,
+ align: p.align,
+ rich: p.richText,
+ color: p.color,
+ }, p.style ?? 0);
if (layout.glyphs.length === 0) return;
// A string can reference glyphs across several atlas pages; each page is a
diff --git a/sdk/src/ui/text/ui-text.ts b/sdk/src/ui/text/ui-text.ts
index ca314fbfa..2418b8ab1 100644
--- a/sdk/src/ui/text/ui-text.ts
+++ b/sdk/src/ui/text/ui-text.ts
@@ -24,6 +24,10 @@ export interface UITextData {
layer: number;
/** Parse `<b>/<i>/<color>/<font size>` markup in `content`. */
richText: boolean;
+ /** Horizontal alignment: 0 left | 1 center | 2 right. */
+ align: number;
+ /** Baseline-to-baseline px for multi-line text; 0 = auto (fontSizePx × 1.2). */
+ lineHeight: number;
}
export const UIText = defineComponent<UITextData>('UIText', {
@@ -34,6 +38,8 @@ export const UIText = defineComponent<UITextData>('UIText', {
style: 0,
layer: 0,
richText: false,
+ align: 0,
+ lineHeight: 0,
});
/**
diff --git a/sdk/tests/ui-text-multiline.test.ts b/sdk/tests/ui-text-multiline.test.ts
new file mode 100644
index 000000000..a2f2c3f8d
--- /dev/null
+++ b/sdk/tests/ui-text-multiline.test.ts
@@ -0,0 +1,49 @@
+/**
+ * @file REARCH_GUI P1.4c — multi-line + alignment text layout (parity step
+ * toward retiring the Canvas2D Text path). Pure → headless-tested.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,
+} from '../src/ui/text/glyph-atlas';
+import { layoutText, TEXT_ALIGN_CENTER, TEXT_ALIGN_RIGHT } from '../src/ui/text/layout';
+
+function makeAtlas(): GlyphAtlas {
+ const rasterizer: GlyphRasterizer = {
+ renderSize: 48,
+ rasterize: (): RasterGlyph => ({ pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance: 11, bearingX: 1, bearingY: 10 }),
+ };
+ let next = 1;
+ const store: AtlasPageStore = { createPage: () => next++, uploadSubRegion: () => {} };
+ return new GlyphAtlas(rasterizer, store, { pageSize: 256, padding: 1 });
+}
+
+describe('REARCH_GUI P1.4c: multi-line + alignment', () => {
+ it('splits on \\n and stacks lines downward', () => {
+ const layout = layoutText('AB\nC', makeAtlas(), 'Arial', { fontSizePx: 24, lineHeight: 30 });
+ expect(layout.glyphs.length).toBe(3); // A,B (line0) + C (line1)
+ expect(layout.width).toBeCloseTo(11); // widest line = "AB"
+ // C is on the lower line ⇒ its y is one lineHeight below A's
+ const a = layout.glyphs[0], c = layout.glyphs[2];
+ expect(c.y0).toBeCloseTo(a.y0 - 30);
+ });
+
+ it('center-aligns shorter lines within the widest line block', () => {
+ const layout = layoutText('AB\nC', makeAtlas(), 'Arial', { fontSizePx: 24, align: TEXT_ALIGN_CENTER });
+ const left = layoutText('AB\nC', makeAtlas(), 'Arial', { fontSizePx: 24 });
+ // line "C" (width 5.5) centered in block 11 ⇒ +2.75 vs left
+ expect(layout.glyphs[2].x0).toBeCloseTo(left.glyphs[2].x0 + 2.75);
+ });
+
+ it('right-aligns shorter lines to the block edge', () => {
+ const layout = layoutText('AB\nC', makeAtlas(), 'Arial', { fontSizePx: 24, align: TEXT_ALIGN_RIGHT });
+ const left = layoutText('AB\nC', makeAtlas(), 'Arial', { fontSizePx: 24 });
+ expect(layout.glyphs[2].x0).toBeCloseTo(left.glyphs[2].x0 + 5.5);
+ });
+
+ it('single line (no newline) behaves like a left-aligned line', () => {
+ const layout = layoutText('AB', makeAtlas(), 'Arial', { fontSizePx: 24 });
+ expect(layout.glyphs.length).toBe(2);
+ expect(layout.width).toBeCloseTo(11);
+ });
+});