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): 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: DrawTex
align: 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+});