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): word-wrap (space + CJK char-break) for SDF text (REARCH_GUI P1.4c)
esenginecb345d293657
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex 9d55d45cb..7d2f7dd9d 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -407,6 +407,8 @@ export {layoutLine,layoutRichLine,layoutText,+ wrapLine,+ measureWidth,buildGlyphVertices,TEXT_ALIGN_LEFT,TEXT_ALIGN_CENTER,diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 91e174dfe..2479c6ef7 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -149,6 +149,61 @@ export interface MultilineTextOptions extends TextLayoutOptions {rich?: boolean;/** Base color (used by rich runs without their own color). */color?: RGBA;+ /** Word-wrap width in display px (plain text only). 0/undefined = no wrap. */+ maxWidth?: number;+}++/** Sum of glyph advances for a string at the given size (display px). Pure. */+export function measureWidth(+ text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number, style: number, letterSpacing = 0,+): number {+ const scale = fontSizePx / atlas.renderSize;+ let w = 0;+ for (const ch of text) {+ const cp = ch.codePointAt(0);+ if (cp === undefined) continue;+ const g = atlas.getGlyph(cp, fontFamily, style);+ if (g) w += g.advance * scale + letterSpacing;+ }+ return w;+}++/**+ * Greedy word-wrap a single line to `maxWidth` (display px). Breaks at spaces;+ * a single token wider than the line (long word, or CJK runs which have no+ * spaces) is broken character-by-character. Returns the wrapped sub-lines.+ */+export function wrapLine(+ text: string, atlas: GlyphAtlas, fontFamily: string, fontSizePx: number,+ style: number, maxWidth: number, letterSpacing = 0,+): string[] {+ const measure = (s: string) => measureWidth(s, atlas, fontFamily, fontSizePx, style, letterSpacing);+ const out: string[] = [];+ let cur = '';+ const flush = () => { const t = cur.replace(/\s+$/, ''); if (t) out.push(t); cur = ''; };+ const charBreak = (token: string) => {+ for (const ch of token) {+ if (cur && measure(cur + ch) > maxWidth) flush();+ cur += ch;+ }+ };++ for (const token of text.split(/(\s+)/)) {+ if (token === '') continue;+ if (/^\s+$/.test(token)) { if (cur) cur += token; continue; } // keep inter-word spaces, drop leading+ if (!cur) {+ if (measure(token) <= maxWidth) cur = token;+ else charBreak(token);+ } else if (measure(cur + token) <= maxWidth) {+ cur += token;+ } else {+ flush();+ if (measure(token) <= maxWidth) cur = token;+ else charBreak(token);+ }+ }+ flush();+ return out.length ? out : [''];}/**@@ -167,7 +222,11 @@ export function layoutText(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 rawLines = text.split('\n');+ // Word-wrap (plain text only) before stacking; explicit \n still hard-breaks.+ const lines = (opts.maxWidth && opts.maxWidth > 0 && !opts.rich)+ ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))+ : rawLines;const lineLayouts = lines.map(line => (opts.rich? layoutRichLine(line, atlas, fontFamily, { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor }, style)diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 555d44d09..0e55cbc02 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -49,6 +49,7 @@ export class UITextPlugin implements Plugin {richText: t.richText,align: t.align,lineHeight: t.lineHeight || undefined,+ maxWidth: t.maxWidth || undefined,},this.matrix_,entity as number,diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 9409baa4f..81bddb52d 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -34,6 +34,8 @@ export interface DrawTextParams {lineHeight?: number;/** Extra advance between glyphs (px). */letterSpacing?: number;+ /** Word-wrap width in px (plain text); 0/undefined = no wrap. */+ maxWidth?: number;}/**@@ -49,6 +51,7 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTexalign: p.align,rich: p.richText,color: p.color,+ maxWidth: p.maxWidth,}, p.style ?? 0);if (layout.glyphs.length === 0) return;diff --git a/sdk/src/ui/text/ui-text.ts b/sdk/src/ui/text/ui-text.tsindex 2418b8ab1..cbbed2748 100644--- a/sdk/src/ui/text/ui-text.ts+++ b/sdk/src/ui/text/ui-text.ts@@ -28,6 +28,8 @@ export interface UITextData {align: number;/** Baseline-to-baseline px for multi-line text; 0 = auto (fontSizePx × 1.2). */lineHeight: number;+ /** Word-wrap width in px (plain text); 0 = no wrap. */+ maxWidth: number;}export const UIText = defineComponent<UITextData>('UIText', {@@ -40,6 +42,7 @@ export const UIText = defineComponent<UITextData>('UIText', {richText: false,align: 0,lineHeight: 0,+ maxWidth: 0,});/**diff --git a/sdk/tests/ui-text-wrap.test.ts b/sdk/tests/ui-text-wrap.test.tsnew file mode 100644index 000000000..62b5aeceb--- /dev/null+++ b/sdk/tests/ui-text-wrap.test.ts@@ -0,0 +1,54 @@+/**+ * @file REARCH_GUI P1.4c — word-wrap (parity step toward retiring Canvas2D Text,+ * which has wordWrap). Greedy space-wrap + char-break for long words / CJK+ * (no spaces). Pure → headless-tested.+ */+import { describe, it, expect } from 'vitest';+import {+ GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,+} from '../src/ui/text/glyph-atlas';+import { wrapLine, measureWidth, layoutText } from '../src/ui/text/layout';++function makeAtlas(): GlyphAtlas {+ const rasterizer: GlyphRasterizer = {+ renderSize: 48,+ rasterize: (cp: number): RasterGlyph =>+ cp === 32+ ? { pixels: new Uint8Array(0), width: 0, height: 0, advance: 6, bearingX: 0, bearingY: 0 }+ : { 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 });+}++// At fontSize 24 / renderSize 48 → scale 0.5: letter advance 5.5, space advance 3.+const F = 24;++describe('REARCH_GUI P1.4c: word-wrap', () => {+ it('measureWidth sums scaled advances', () => {+ expect(measureWidth('AA', makeAtlas(), 'Arial', F, 0)).toBeCloseTo(11); // 2 × 5.5+ expect(measureWidth('AA AA', makeAtlas(), 'Arial', F, 0)).toBeCloseTo(25); // 11 + 3 + 11+ });++ it('wraps at spaces when a word would overflow', () => {+ expect(wrapLine('AA AA AA', makeAtlas(), 'Arial', F, 0, 12)).toEqual(['AA', 'AA', 'AA']);+ });++ it('keeps words on one line when they fit', () => {+ expect(wrapLine('AA AA', makeAtlas(), 'Arial', F, 0, 30)).toEqual(['AA AA']);+ });++ it('char-breaks a single token wider than the line (long word / CJK)', () => {+ expect(wrapLine('AAAA', makeAtlas(), 'Arial', F, 0, 12)).toEqual(['AA', 'AA']);+ expect(wrapLine('文文文文', makeAtlas(), 'Arial', F, 0, 12)).toEqual(['文文', '文文']);+ });++ it('layoutText applies maxWidth, producing stacked wrapped lines', () => {+ const layout = layoutText('AA AA AA', makeAtlas(), 'Arial', { fontSizePx: F, maxWidth: 12 });+ expect(layout.glyphs.length).toBe(6); // 3 lines × "AA"+ expect(layout.width).toBeCloseTo(11); // widest wrapped line+ // glyphs of line 3 sit below line 1+ expect(layout.glyphs[5].y0).toBeLessThan(layout.glyphs[0].y0);+ });+});