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): 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.tsindex 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.tsindex 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) becomediff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 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.tsindex 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 adiff --git a/sdk/src/ui/text/ui-text.ts b/sdk/src/ui/text/ui-text.tsindex 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.tsnew file mode 100644index 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);+ });+});