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): UIText component + pre-flush SDF render plugin (REARCH_GUI P1.3c)

esengine7f16051ce490
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 545470622..c25fd0780 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -365,6 +365,58 @@ export {
type ResolvedImage,
} from './ImageResolver';
+// ─── SDF glyph-atlas text (REARCH_GUI P1) ───────────────────────────────────
+
+export {
+ UIText,
+ UI_TEXT_BOLD,
+ UI_TEXT_ITALIC,
+ composeTRS,
+ type UITextData,
+} from './text/ui-text';
+
+export { UITextPlugin, uiTextPlugin } from './text/plugin';
+
+export {
+ SdfTextRenderer,
+ drawTextWith,
+ type DrawTextParams,
+ type GlyphBatchSink,
+ type TextRendererOptions,
+} from './text/text-renderer';
+
+export {
+ GlyphAtlas,
+ type GlyphRasterizer,
+ type AtlasPageStore,
+ type RasterGlyph,
+ type GlyphEntry,
+ type GlyphAtlasOptions,
+} from './text/glyph-atlas';
+
+export {
+ CanvasGlyphRasterizer,
+ extractAlpha,
+ sdfToAtlasRgba,
+ type CanvasGlyphRasterizerOptions,
+} from './text/glyph-rasterizer';
+
+export { EngineAtlasPageStore } from './text/atlas-page-store';
+
+export {
+ layoutLine,
+ buildGlyphVertices,
+ type TextLayout,
+ type TextLayoutOptions,
+ type LaidGlyph,
+ type RGBA,
+ type GlyphVertexData,
+} from './text/layout';
+
+export { ShelfPacker, type Packer, type PackPos } from './text/atlas-packer';
+export { sdfFromAlpha } from './text/sdf';
+export { submitTextBatch, TEXT_VERTEX_FLOATS } from './text/submit';
+
export const AnimOverride = {
POS_X: 1,
POS_Y: 2,
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
new file mode 100644
index 000000000..e5b33939b
--- /dev/null
+++ b/sdk/src/ui/text/plugin.ts
@@ -0,0 +1,60 @@
+/**
+ * @file ui/text/plugin.ts
+ * @brief UITextPlugin — wires the dynamic SDF text path into the frame
+ * (REARCH_GUI P1.3c). A pre-flush callback scans UIText entities,
+ * composes each entity's world transform, and draws it through the
+ * TextRenderer (glyph atlas → batched SDF quads). The renderer is
+ * created lazily, so apps with no UIText pay nothing.
+ */
+import type { App, Plugin } from '../../app';
+import { Transform, type TransformData } from '../../component';
+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';
+
+export class UITextPlugin implements Plugin {
+ name = 'uiText';
+
+ private renderer_: SdfTextRenderer | null = null;
+ private readonly matrix_ = new Float32Array(16);
+
+ build(app: App): void {
+ registerComponent('UIText', UIText);
+
+ const pipeline = app.pipeline;
+ if (!pipeline) return; // no render pipeline (e.g. logic-only host) → nothing to draw
+
+ const world = app.world;
+ pipeline.addPreFlushCallback(() => {
+ const entities = world.getEntitiesWithComponents([UIText, Transform]);
+ for (const e of entities) {
+ const entity = e as Entity;
+ const t = world.get(entity, UIText) as UITextData;
+ if (!t.content) continue;
+
+ if (!this.renderer_) {
+ this.renderer_ = new SdfTextRenderer(app.wasmModule as ESEngineModule);
+ }
+ const tr = world.get(entity, Transform) as TransformData;
+ composeTRS(this.matrix_, tr.worldPosition, tr.worldRotation, tr.worldScale);
+ this.renderer_.drawText(
+ {
+ text: t.content,
+ fontFamily: t.fontFamily,
+ fontSizePx: t.fontSizePx,
+ color: [t.color.r, t.color.g, t.color.b, t.color.a],
+ style: t.style,
+ },
+ this.matrix_,
+ entity as number,
+ t.layer,
+ tr.worldPosition.z,
+ );
+ }
+ });
+ }
+}
+
+export const uiTextPlugin = new UITextPlugin();
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 6150be1b8..fe99b142c 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -56,7 +56,7 @@ export interface TextRendererOptions extends CanvasGlyphRasterizerOptions {
pageSize?: number;
}
-export class TextRenderer {
+export class SdfTextRenderer {
readonly atlas: GlyphAtlas;
constructor(private readonly module: ESEngineModule, opts: TextRendererOptions = {}) {
diff --git a/sdk/src/ui/text/ui-text.ts b/sdk/src/ui/text/ui-text.ts
new file mode 100644
index 000000000..5c62c7aa1
--- /dev/null
+++ b/sdk/src/ui/text/ui-text.ts
@@ -0,0 +1,54 @@
+/**
+ * @file ui/text/ui-text.ts
+ * @brief UIText component — the opt-in driver for the dynamic SDF text path
+ * (REARCH_GUI P1.3c). Authored on entities (serializes via the scene
+ * system); the UITextPlugin pre-flush system renders it. Kept separate
+ * from the legacy core/text.ts Text (Canvas2D per-entity) so the two
+ * don't double-render; P1.4 migrates Text → UIText and retires the old
+ * path.
+ */
+import { defineComponent } from '../../component';
+import type { Color, Vec3, Quat } from '../../types';
+
+/** Style bit flags — bold | italic. */
+export const UI_TEXT_BOLD = 1;
+export const UI_TEXT_ITALIC = 2;
+
+export interface UITextData {
+ content: string;
+ fontFamily: string;
+ fontSizePx: number;
+ color: Color;
+ /** Bit flags: UI_TEXT_BOLD | UI_TEXT_ITALIC. */
+ style: number;
+ layer: number;
+}
+
+export const UIText = defineComponent<UITextData>('UIText', {
+ content: '',
+ fontFamily: 'sans-serif',
+ fontSizePx: 24,
+ color: { r: 1, g: 1, b: 1, a: 1 },
+ style: 0,
+ layer: 0,
+});
+
+/**
+ * Compose a column-major mat4 into `out` from translation, rotation quaternion,
+ * and scale — the entity world transform applied to glyph local positions at
+ * submit. Pure (gl-matrix fromRotationTranslationScale), so it is unit-testable.
+ */
+export function composeTRS(out: Float32Array, t: Vec3, q: Quat, s: Vec3): Float32Array {
+ const { x, y, z, w } = q;
+ const x2 = x + x, y2 = y + y, z2 = z + z;
+ const xx = x * x2, xy = x * y2, xz = x * z2;
+ const yy = y * y2, yz = y * z2, zz = z * z2;
+ const wx = w * x2, wy = w * y2, wz = w * z2;
+ const sx = s.x, sy = s.y, sz = s.z;
+
+ out[0] = (1 - (yy + zz)) * sx; out[1] = (xy + wz) * sx; out[2] = (xz - wy) * sx; out[3] = 0;
+ out[4] = (xy - wz) * sy; out[5] = (1 - (xx + zz)) * sy; out[6] = (yz + wx) * sy; out[7] = 0;
+ out[8] = (xz + wy) * sz; out[9] = (yz - wx) * sz; out[10] = (1 - (xx + yy)) * sz; out[11] = 0;
+ out[12] = t.x; out[13] = t.y; out[14] = t.z; out[15] = 1;
+ return out;
+}
diff --git a/sdk/src/uiPlugins.ts b/sdk/src/uiPlugins.ts
index 039c71599..628abef29 100644
--- a/sdk/src/uiPlugins.ts
+++ b/sdk/src/uiPlugins.ts
@@ -10,6 +10,7 @@ import { scrollViewPlugin } from './ui/ScrollViewPlugin';
import { focusPlugin } from './ui/FocusPlugin';
import { safeAreaPlugin } from './ui/SafeAreaPlugin';
import { uiRenderOrderPlugin } from './ui/UIRenderOrderPlugin';
+import { uiTextPlugin } from './ui/text/plugin';
import type { Plugin } from './app';
export const uiPlugins: Plugin[] = [
@@ -19,4 +20,7 @@ export const uiPlugins: Plugin[] = [
textInputPlugin,
focusPlugin, safeAreaPlugin,
uiRenderOrderPlugin,
+ // REARCH_GUI P1.3c: SDF glyph-atlas text path. Opt-in via the UIText
+ // component; renders nothing unless an entity carries one.
+ uiTextPlugin,
];
diff --git a/sdk/tests/ui-text-uitext.test.ts b/sdk/tests/ui-text-uitext.test.ts
new file mode 100644
index 000000000..32fa31aa3
--- /dev/null
+++ b/sdk/tests/ui-text-uitext.test.ts
@@ -0,0 +1,31 @@
+/**
+ * @file REARCH_GUI P1.3c — composeTRS, the world-transform matrix the UIText
+ * pre-flush system feeds to submitTextBatch. Pure → unit-tested here; the
+ * full on-screen path (UITextPlugin → render) is render-host-verified.
+ */
+import { describe, it, expect } from 'vitest';
+import { composeTRS } from '../src/ui/text/ui-text';
+
+const IDQ = { x: 0, y: 0, z: 0, w: 1 };
+
+describe('REARCH_GUI P1.3c: composeTRS', () => {
+ it('builds a column-major TRS matrix (identity rotation)', () => {
+ const m = composeTRS(new Float32Array(16), { x: 10, y: 20, z: 30 }, IDQ, { x: 2, y: 3, z: 4 });
+ expect(Array.from(m)).toEqual([
+ 2, 0, 0, 0,
+ 0, 3, 0, 0,
+ 0, 0, 4, 0,
+ 10, 20, 30, 1,
+ ]);
+ });
+
+ it('encodes a 90° z-rotation in the upper-left 2x2 (column-major)', () => {
+ const s = Math.SQRT1_2; // sin(45°) = cos(45°)
+ const m = composeTRS(new Float32Array(16), { x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: s, w: s }, { x: 1, y: 1, z: 1 });
+ expect(m[0]).toBeCloseTo(0); // cosθ
+ expect(m[1]).toBeCloseTo(1); // sinθ
+ expect(m[4]).toBeCloseTo(-1); // -sinθ
+ expect(m[5]).toBeCloseTo(0); // cosθ
+ expect(m[15]).toBe(1);
+ });
+});