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): 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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);+ });+});