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.

34.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/text/plugin.ts
 * @brief   TextPlugin — renders the `Text` component via the dynamic glyph
 *          atlas. A pre-flush callback scans Text entities, places the text
 *          inside its UINode box (rendering never mutates layout) and draws
 *          batched glyph quads, layered with sibling UI elements. Two glyph
 *          pipelines — hinted bitmap vs SDF — routed per Text by
 *          {@link resolveTextRenderMode}.
 */
import type { App, Plugin } from '../../app/app';
import { Transform, type TransformData, registerComponent } from '../../ecs/component';
import { defineSystem, Schedule } from '../../ecs/system';
import { SystemLabel } from '../../ecs/systemLabels';
import type { ESEngineModule, CppRegistry } from '../../wasm';
import type { Entity } from '../../types';
import type { World } from '../../ecs/world';
import { SdfTextRenderer } from './text-renderer';
import { composeTRS } from './text-transform';
import { textDrawParams, textStyleBits } from './text-params';
import { Text, TextOverflow, TextRenderMode, type TextData } from '../core/text';
import { ContentRect } from '../core/content-rect';
import { bitmapFontOf } from './bitmap-font';
import { UINode } from '../core/ui-node';
import { Localization } from '../../i18n/Localization';
import { applyTextLocalization, type TextWorldView } from './localize';
import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';
import { ScreenOverlay } from '../core/screen-overlay';
import { getUINodeWidth, getUINodeHeight, ensureUIVisual } from '../util/helpers';
import { resolveTextFamily } from './font-registry';
import { DEFAULT_PRELOAD_BUDGET_MS, GlyphPreloadJob, preloadCodepoints, type GlyphPreload, type GlyphPreloadOptions } from './glyph-preload';
import { platformDevicePixelRatio, platformNow } from '../../platform';
import { engineApi, type EngineApi } from '../../ecs/bridge/engineApi';
import { withScratch } from '../../wasm/wasmScratch';
// UI quads use layer = base + uiOrder, off the C++ declaration that owns it.
import { UI_BASE_LAYER } from '../../wasm/constants.generated';

// Base glyph rasterization size in CSS px; the real source is this × DPR so text
// stays crisp on HiDPI displays. 64 covers common UI sizes at 1:1 or finer.
const GLYPH_BASE_SIZE = 64;



// Auto tolerance: a bitmap glyph still reads as pixel-exact within ±2% of 1:1.
const BITMAP_SCALE_EPSILON = 0.02;
const LARGE_GLYPH_PX = 128;
export const LARGE_GLYPH_ATLAS = { sdf: true, renderSize: 64, padding: 16 };

/**
 * Pure: which glyph pipeline a Text draws with. `effectiveScale` is the
 * entity's own world scale — the residual the bitmap path can't fold into
 * rasterization (the canvas fit is, via {@link GlyphAtlas.setContentScale}).
 * Auto keeps unscaled text on hinted bitmaps and sends scaled text to SDF.
 */
export function resolveTextRenderMode(
    mode: TextRenderMode | undefined,
    effectiveScale: number,
    perspective = false,
): 'bitmap' | 'sdf' {
    if (mode === TextRenderMode.Bitmap) return 'bitmap';
    if (mode === TextRenderMode.Sdf) return 'sdf';
    if (perspective) return 'sdf';
    if (!Number.isFinite(effectiveScale) || effectiveScale <= 0) return 'bitmap';
    return Math.abs(effectiveScale - 1) <= BITMAP_SCALE_EPSILON ? 'bitmap' : 'sdf';
}

/**
 * Pure: how many CSS pixels one unit of a DOMAIN covers, which is the size
 * bitmap glyphs must be rasterized at to land on screen pixels.
 *
 * It comes from the projection that will DRAW the text, not from the box the
 * text was laid out in: the editor's free-zoom view holds that box fixed on
 * purpose, so reading the span off it asks for design-sized glyphs and leaves the
 * projection to scale the result — which is soft text at every zoom but "fit".
 *
 * Two domains call this with their own projections. World text sharpens as the
 * camera zooms in, which is correct; screen text follows the overlay, which is
 * what keeps a 3D camera's field of view out of a HUD's glyphs.
 *
 * @param projScaleX element 0 of the projection: 2 / the span it shows.
 * @param vpW        the pixel width that span lands in.
 */
export function projectionIsPerspective(viewProjection: ArrayLike<number> | undefined): boolean {
    if (!viewProjection || viewProjection.length < 16) return false;
    return Math.abs(viewProjection[3]) + Math.abs(viewProjection[7]) + Math.abs(viewProjection[11]) > 1e-6;
}

export interface DomainView {
    contentScale: number;
    perspective: boolean;
}

const FLAT_VIEW: DomainView = { contentScale: 1, perspective: false };

export function domainViewOf(viewProjection: ArrayLike<number> | undefined, vpW: number, dpr: number): DomainView {
    if (projectionIsPerspective(viewProjection)) return { contentScale: 1, perspective: true };
    return { contentScale: glyphContentScale(viewProjection?.[0] ?? 0, vpW, dpr), perspective: false };
}

export type GlyphKind = 'bitmap' | 'sdf' | 'large';

export function drawsLarge(t: Pick<TextData, 'renderMode' | 'fontSize'>, family: string, view: DomainView, dpr: number): boolean {
    if (t.renderMode === TextRenderMode.Bitmap || t.renderMode === TextRenderMode.Sdf) return false;
    if (view.perspective || bitmapFontOf(family)) return false;
    return t.fontSize * dpr * view.contentScale >= LARGE_GLYPH_PX;
}

export function glyphKind(t: Pick<TextData, 'renderMode' | 'fontSize'>, tr: Pick<TransformData, 'worldScale'>, family: string, view: DomainView, dpr = 1): GlyphKind {
    if (bitmapFontOf(family)) return 'bitmap';
    const kind = resolveTextRenderMode(t.renderMode, tr.worldScale.x, view.perspective);
    return kind === 'bitmap' && drawsLarge(t, family, view, dpr) ? 'large' : kind;
}

export function glyphContentScale(projScaleX: number, vpW: number, dpr: number): number {
    if (!(dpr > 0) || !(vpW > 0)) return 1;
    if (!Number.isFinite(projScaleX) || projScaleX === 0) return 1;
    const shownSpan = Math.abs(2 / projScaleX);
    return shownSpan > 0 ? vpW / (shownSpan * dpr) : 1;
}

/** The box a Text is laid out in, and where the entity origin sits in it. */
export interface TextFrame {
    w: number;
    h: number;
    /** Pivot as a fraction from the box's left / bottom edge. */
    px: number;
    py: number;
    /** True when a UINode supplied the box: the label is then UI content, ordered by the UI tree. */
    ui: boolean;
}

/**
 * Where a Text gets its box. A UINode decides it, pivot-centred, as ever; without one, the Text's own box fields
 * do, with the pivot they name — so world content can wrap, align and clip inside a rect without joining a Canvas.
 * Pure over what it is given, apart from reading the node's computed size.
 */
export function textFrame(world: World, entity: Entity, t: TextData): TextFrame {
    if (world.has(entity, UINode)) return { w: getUINodeWidth(entity), h: getUINodeHeight(entity), px: 0.5, py: 0.5, ui: true };
    return { w: t.boxWidth || 0, h: t.boxHeight || 0, px: t.boxPivot?.x ?? 0.5, py: t.boxPivot?.y ?? 0.5, ui: false };
}

/** The Text fields a retained label's geometry was laid out from; a label is rebuilt when any of them differs, and not otherwise. */
export interface TextSnapshot {
    content: string; family: string; fontSize: number; bold: boolean; italic: boolean; richText: boolean; renderMode: number;
    align: number; verticalAlign: number; wordWrap: boolean; overflow: number; lineHeight: number; letterSpacing: number; layer: number; underline: boolean;
    boxW: number; boxH: number; boxPx: number; boxPy: number;
    cr: number; cg: number; cb: number; ca: number;
    strokeWidth: number; sr: number; sg: number; sb: number; sa: number;
    shadowBlur: number; shadowX: number; shadowY: number; hr: number; hg: number; hb: number; ha: number;
}

/** A label whose glyph quads the engine holds (see RetainedText.hpp): what TS needs to know whether those quads are still the right ones. */
interface RetainedLabel {
    snap: TextSnapshot;
    screen: boolean;
    gen: number;
    renderer: SdfTextRenderer;
    kind: GlyphKind;
}

export function snapshotOf(t: TextData, family: string): TextSnapshot {
    return {
        content: t.content, family, fontSize: t.fontSize, bold: !!t.bold, italic: !!t.italic, richText: !!t.richText, renderMode: t.renderMode,
        align: t.align, verticalAlign: t.verticalAlign, wordWrap: !!t.wordWrap, overflow: t.overflow, lineHeight: t.lineHeight, letterSpacing: t.letterSpacing || 0, layer: t.layer | 0, underline: !!t.underline,
        boxW: t.boxWidth || 0, boxH: t.boxHeight || 0, boxPx: t.boxPivot?.x ?? 0.5, boxPy: t.boxPivot?.y ?? 0.5,
        cr: t.color.r, cg: t.color.g, cb: t.color.b, ca: t.color.a,
        strokeWidth: t.strokeWidth, sr: t.strokeColor.r, sg: t.strokeColor.g, sb: t.strokeColor.b, sa: t.strokeColor.a,
        shadowBlur: t.shadowBlur, shadowX: t.shadowOffsetX, shadowY: t.shadowOffsetY,
        hr: t.shadowColor.r, hg: t.shadowColor.g, hb: t.shadowColor.b, ha: t.shadowColor.a,
    };
}

export function sameSnapshot(s: TextSnapshot, t: TextData, family: string): boolean {
    return s.content === t.content && s.family === family && s.fontSize === t.fontSize
        && s.bold === !!t.bold && s.italic === !!t.italic && s.richText === !!t.richText && s.renderMode === t.renderMode
        && s.align === t.align && s.verticalAlign === t.verticalAlign && s.wordWrap === !!t.wordWrap
        && s.overflow === t.overflow && s.lineHeight === t.lineHeight && s.letterSpacing === (t.letterSpacing || 0) && s.layer === (t.layer | 0) && s.underline === !!t.underline
        && s.boxW === (t.boxWidth || 0) && s.boxH === (t.boxHeight || 0) && s.boxPx === (t.boxPivot?.x ?? 0.5) && s.boxPy === (t.boxPivot?.y ?? 0.5)
        && s.cr === t.color.r && s.cg === t.color.g && s.cb === t.color.b && s.ca === t.color.a
        && s.strokeWidth === t.strokeWidth
        && s.sr === t.strokeColor.r && s.sg === t.strokeColor.g && s.sb === t.strokeColor.b && s.sa === t.strokeColor.a
        && s.shadowBlur === t.shadowBlur && s.shadowX === t.shadowOffsetX && s.shadowY === t.shadowOffsetY
        && s.hr === t.shadowColor.r && s.hg === t.shadowColor.g && s.hb === t.shadowColor.b && s.ha === t.shadowColor.a;
}

/** How many frames a preload waits for the projection before it takes the size it can get. */
const PRELOAD_PROJECTION_FRAMES = 30;

/** One preload and where it stands. The object is also what holds its atlas pages. */
interface PreloadRun {
    entity: Entity;
    framesWaited: number;
    renderer: SdfTextRenderer | null;
    job: GlyphPreloadJob;
}

/** The two domains a Text can belong to, and the state each keeps. */
interface TextDomainState {
    bitmap: SdfTextRenderer | null;
    sdf: SdfTextRenderer | null;
    large: SdfTextRenderer | null;
}

export class TextPlugin implements Plugin {
    name = 'text';

    private readonly states_ = new WeakMap<App, {
        world: TextDomainState;
        screen: TextDomainState;
        matrix: Float32Array;
        matrixHeap: Float32Array | null;
        retained: Map<number, RetainedLabel>;
        preloads: PreloadRun[];
    }>();

    /** Apps this plugin was built on: only those step a preload. */
    private readonly built_ = new WeakSet<App>();

    private stateFor(app: App) {
        let state = this.states_.get(app);
        if (!state) {
            state = {
                world: { bitmap: null, sdf: null, large: null },
                screen: { bitmap: null, sdf: null, large: null },
                matrix: new Float32Array(16), matrixHeap: null,
                retained: new Map(),
                preloads: [],
            };
            this.states_.set(app, state);
        }
        return state;
    }

    cleanup(app?: App): void {
        if (!app) return;
        const state = this.states_.get(app);
        if (!state) return;
        this.states_.delete(app);
        for (const run of state.preloads) run.job.finish();
        const errors: unknown[] = [];
        // The engine keeps these by entity number and may outlive this app: a replay in the same realm numbers its entities afresh,
        // and a label left behind would draw on whichever one has its number now, from an atlas released below.
        const api = engineApi(app);
        for (const entity of state.retained.keys()) {
            try { api?.renderer_retainedTextClear?.(entity); } catch (error) { errors.push(error); }
        }
        for (const renderer of [state.world.bitmap, state.world.sdf, state.world.large, state.screen.bitmap, state.screen.sdf, state.screen.large]) {
            try { renderer?.dispose(); } catch (error) { errors.push(error); }
        }
        if (errors.length) throw new Error(`Failed to release text resources: ${errors.map(String).join('; ')}`);
    }

    build(app: App): void {
        registerComponent('Text', Text);
        this.built_.add(app);

        const world = app.world;

        app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
            const state = this.states_.get(app);
            if (!state) return;
            for (const renderer of [state.world.bitmap, state.world.sdf, state.world.large, state.screen.bitmap, state.screen.sdf, state.screen.large]) {
                renderer?.beginFrame();
            }
        }, { name: 'TextPageLifetimeSystem', runWhenPaused: true }));

        app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
            const state = this.states_.get(app);
            if (state && state.preloads.length > 0) this.stepPreloads(app, state.preloads);
        }, { name: 'TextGlyphPreloadSystem', runWhenPaused: true }));

        // A Text node inside a UINode is a UI render node: ensure it carries a
        // UIVisual (visualType None — not drawn as a quad) so the UI
        // render-order pass assigns it a uiOrder and the SDF glyphs sort with
        // sibling UI elements. Idempotent; runs before the PostUpdate order pass.
        const ensureTextRenderNodes = (): void => {
            for (const e of world.getEntitiesWithComponents([Text, UINode])) {
                ensureUIVisual(world, e as Entity);
            }
        };
        app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], ensureTextRenderNodes, { name: 'TextRenderNodeSystem', runWhenPaused: true }));
        // A Text spawned in Update is not seen by the PreUpdate pass, so it would
        // reach the order pass with no UIVisual, take no uiOrder, and be drawn at
        // the base layer — under every panel — for its first frame. The late pass
        // gives it one before the order is assigned.
        app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], ensureTextRenderNodes, {
            name: 'TextRenderNodeLateSystem',
            runWhenPaused: true,
            runBefore: [SystemLabel.UIRenderOrder],
        }));

        // Localized text: an `i18nKey` binds content to the Localization
        // resource. Gated per frame on the resource so localizationPlugin
        // stays opt-in and install order doesn't matter; without it, authored
        // content stands (see ui/text/localize.ts for the resolve contract).
        app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
            if (!app.hasResource(Localization)) return;
            applyTextLocalization(world as unknown as TextWorldView, app.getResource(Localization));
        }, { name: 'TextLocalizeSystem', runWhenPaused: true }));

        const pipeline = app.pipeline;
        if (!pipeline) return; // logic-only host → nothing to draw

        // Two passes, because there are two lists: the world's glyphs go into the
        // camera being collected, the screen's into the frame's overlay.
        pipeline.addPreFlushCallback((_registry, projection) => app.measureFrameScope('render.text', () => this.drawDomain(app, false, projection)));
        pipeline.addScreenOverlayCallback((_registry, projection) => app.measureFrameScope('render.text', () => this.drawDomain(app, true, projection)));
    }

    /**
     * Draw every Text belonging to one domain, into whichever list is open.
     *
     * The domain is asked of the engine, not derived here: it is resolved once at
     * a UI subtree's root and inherited (UISystem::screenDomain), and a second
     * spelling of that rule in TS is a second rule.
     */
    private drawDomain(app: App, screen: boolean, projection?: Float32Array): void {
        const appState = this.stateFor(app);
        const api = engineApi(app);
        if (this.canRetain(api)) {
            this.drawRetained(app, api!, screen, projection);
            return;
        }
        if (!api?.transform_copyFlatRenderMatrix || !api.HEAPU8 || !api._malloc || !api._free) {
            this.drawDomainWithMatrix(app, screen, undefined, projection);
            return;
        }
        const registry = app.world.getCppRegistry() as CppRegistry;
        withScratch({ _malloc: size => api._malloc!(size), _free: ptr => api._free!(ptr) }, alloc => {
            let pointer = 0;
            this.drawDomainWithMatrix(app, screen, entity => {
                if (!pointer) pointer = alloc(16 * 4);
                if (!pointer) throw new Error('Could not allocate text transform scratch.');
                if (!api.transform_copyFlatRenderMatrix!(registry, entity, pointer)) return false;
                const heap = api.HEAPU8!;
                if (appState.matrixHeap?.buffer !== heap.buffer) appState.matrixHeap = new Float32Array(heap.buffer);
                const offset = (heap.byteOffset + pointer) / 4;
                for (let i = 0; i < 16; i++) appState.matrix[i] = appState.matrixHeap[offset + i]!;
                return true;
            }, projection);
        });
    }

    /**
     * Whether the engine can keep a label's glyph quads and submit them itself. A core without the entry points (an older native host) takes the
     * path that hands every label over every frame.
     */
    private canRetain(api: EngineApi | null): boolean {
        return !!api && !!api.renderer_retainedTextBegin && !!api.renderer_retainedTextBatch && !!api.renderer_retainedTextClear
            && !!api.renderer_retainedTextStale && !!api.renderer_retainedTextSubmit && !!api.ui_isScreenDomain
            && !!api.HEAPU8 && !!api._malloc && !!api._free;
    }

    /**
     * One domain's Text, with the glyph quads kept by the engine: a label that is the same as the last time costs a comparison here and the
     * engine's own loop, and is laid out again only when its text, style or box changed.
     */
    private drawRetained(app: App, api: EngineApi, screen: boolean, projection?: Float32Array): void {
        const appState = this.stateFor(app);
        const world = app.world;
        const registry = world.getCppRegistry() as CppRegistry;
        const dpr = platformDevicePixelRatio();
        const view = this.domainView(app, screen, dpr);
        const contentScale = view.contentScale;
        const state = screen ? appState.screen : appState.world;
        const retained = appState.retained;
        // The atlas rasterizes for the projection that draws it: bring each existing renderer up to this pass's before asking whether its
        // generation moved.
        if (state.bitmap) {
            state.bitmap.setDevicePixelRatio(dpr);
            state.bitmap.setContentScale(contentScale);
        }

        // What the engine says no longer matches the world: a box that was resized, a label that moved between domains.
        this.rebuildStale(app, api, registry);

        const seen = new Set<number>();
        for (const e of world.getEntitiesWithComponents([Text, Transform])) {
            const entity = e as Entity;
            const label = retained.get(entity as number);
            if (label && label.screen !== screen) continue; // the other domain's pass owns it
            const t = world.get(entity, Text) as TextData;
            if (!t.content || t.enabled === false) continue; // not seen: swept below
            if (!label && api.ui_isScreenDomain!(registry, entity as number) !== screen) continue;
            const family = resolveTextFamily(t.font, t.fontFamily);
            seen.add(entity as number);
            // Which glyph pipeline an automatic label gets follows its world scale, which the engine watches (renderer_retainedTextStale): the
            // transform is not read here every frame for every label to find out.
            if (label && label.gen === label.renderer.atlas.generation && sameSnapshot(label.snap, t, family)
                && (label.kind === 'sdf' || (label.kind === 'large') === drawsLarge(t, family, view, dpr))) {
                label.renderer.markDrawn(entity as number);
                continue;
            }
            this.layoutRetained(app, api, registry, entity, t, screen);
        }
        for (const [entity, label] of retained) {
            if (label.screen !== screen || seen.has(entity)) continue;
            api.renderer_retainedTextClear!(entity);
            label.renderer.forget(entity);
            retained.delete(entity);
        }

        withScratch({ _malloc: size => api._malloc!(size), _free: ptr => api._free!(ptr) }, alloc => {
            let projectionPtr = 0;
            if (projection && projection.length >= 16) {
                projectionPtr = alloc(16 * 4);
                api.HEAPU8!.set(new Uint8Array(projection.buffer, projection.byteOffset, 16 * 4), projectionPtr);
            }
            api.renderer_retainedTextSubmit!(registry, screen ? 1 : 0, projectionPtr);
        });
    }

    /** Lay the labels the engine reports stale out again, in the domain they are in now. */
    private rebuildStale(app: App, api: EngineApi, registry: CppRegistry): void {
        const appState = this.stateFor(app);
        const world = app.world;
        const CAPACITY = 256;
        for (let round = 0; round < 8; round++) {
            const stale: number[] = [];
            withScratch({ _malloc: size => api._malloc!(size), _free: ptr => api._free!(ptr) }, alloc => {
                const ptr = alloc(CAPACITY * 4);
                const count = api.renderer_retainedTextStale!(registry, ptr, CAPACITY);
                const ids = new Uint32Array(api.HEAPU8!.buffer, ptr, count);
                for (let i = 0; i < count; i++) stale.push(ids[i]!);
            });
            for (const entity of stale) {
                const label = appState.retained.get(entity);
                const alive = world.valid(entity as Entity) && world.has(entity as Entity, Text);
                const t = alive ? world.get(entity as Entity, Text) as TextData : null;
                if (!t || !t.content || t.enabled === false) {
                    api.renderer_retainedTextClear!(entity);
                    label?.renderer.forget(entity);
                    appState.retained.delete(entity);
                    continue;
                }
                this.layoutRetained(app, api, registry, entity as Entity, t, api.ui_isScreenDomain!(registry, entity));
            }
            if (stale.length < CAPACITY) return;
        }
    }

    /** Lay one label out in @p screen's domain and give the engine its quads. */
    private layoutRetained(
        app: App, api: EngineApi, registry: CppRegistry,
        entity: Entity, t: TextData, screen: boolean,
    ): void {
        const appState = this.stateFor(app);
        const world = app.world;
        const dpr = platformDevicePixelRatio();
        const view = this.domainView(app, screen, dpr);
        const state = screen ? appState.screen : appState.world;
        const tr = world.get(entity, Transform) as TransformData;
        const family = resolveTextFamily(t.font, t.fontFamily);
        const kind = glyphKind(t, tr, family, view, dpr);
        const renderer = this.rendererFor(app, state, kind, view.contentScale, dpr);
        const previous = appState.retained.get(entity as number);
        if (previous && previous.renderer !== renderer) previous.renderer.forget(entity as number);

        const frame = textFrame(world, entity, t);
        const w = frame.w, h = frame.h;
        const hasBox = w > 0 || h > 0;
        const blockHeight = renderer.retain(
            api,
            textDrawParams(t, family, frame),
            // The engine orders a boxed label by the UI tree and re-lays it out when the node's size changes; a box
            // that is the Text's own is neither, so it is reported as no box (its size reaches layout above).
            entity as number, screen, hasBox && frame.ui, t.layer | 0, frame.ui ? w : 0, frame.ui ? h : 0,
            t.renderMode !== TextRenderMode.Bitmap && t.renderMode !== TextRenderMode.Sdf && !bitmapFontOf(family),
        );
        appState.retained.set(entity as number, { snap: snapshotOf(t, family), screen, gen: renderer.atlas.generation, renderer, kind });
        // A box that grows to its text: the rectangle the entity occupies takes the height the lines laid out to. The sprite and text follow the
        // rectangle on the next frame, where the box is the same height and nothing changes again.
        if (t.overflow === TextOverflow.ResizeHeight && blockHeight > 0) {
            const rect = world.tryGet(entity, ContentRect);
            if (rect && Math.abs(rect.size.y - blockHeight) > 0.5) world.set(entity, ContentRect, { ...rect, size: { x: rect.size.x, y: blockHeight } });
        }
    }

    private drawDomainWithMatrix(app: App, screen: boolean, readMatrix?: (entity: number) => boolean, projection?: Float32Array): void {
        const appState = this.stateFor(app);
        const world = app.world;
        const registry = world.getCppRegistry() as CppRegistry;
        // Through engineApi, not app.wasmModule: a device has no wasm module, and
        // asking for one leaves every Text at the base UI layer (ecs/engineApi.ts).
        const api = engineApi(app);
        // A core that cannot answer has not partitioned anything either, so every
        // Text is world content and the screen pass draws nothing.
        const isScreen = (entity: number): boolean =>
            api?.ui_isScreenDomain?.(registry, entity) ?? false;
        if (screen && !api?.ui_isScreenDomain) return;

        const dpr = platformDevicePixelRatio();
        const view = this.domainView(app, screen, dpr);
        const state = screen ? appState.screen : appState.world;

        const seen = new Set<number>();
        for (const e of world.getEntitiesWithComponents([Text, Transform])) {
            const entity = e as Entity;
            if (isScreen(entity as number) !== screen) continue;
            const t = world.get(entity, Text) as TextData;
            // enabled === false: pre-upgrade data lacks the field → visible.
            if (!t.content || t.enabled === false) continue;
            // display:none anywhere up the UI tree hides this text too.
            if (api?.getUINodeHiddenInTree?.(registry, entity)) continue;
            const groupAlpha = api?.getUINodeAlphaInTree?.(registry, entity) ?? 1;
            if (groupAlpha <= 0) continue;
            if (readMatrix && !readMatrix(entity as number)) continue;
            seen.add(entity as number);

            const tr = world.get(entity, Transform) as TransformData;
            const family = resolveTextFamily(t.font, t.fontFamily);
            const renderer = this.rendererFor(
                app, state,
                glyphKind(t, tr, family, view, dpr),
                view.contentScale,
                dpr,
            );
            if (!readMatrix) composeTRS(appState.matrix, tr.worldPosition, tr.worldRotation, tr.worldScale);

            // The layout box: a UINode (CSS box, pivot-centered), which places,
            // aligns and wraps the text and sorts it by UI render order. No box ⇒
            // a world label at the entity origin, sorted by Text.layer.
            let layer = t.layer | 0;
            const frame = textFrame(world, entity, t);
            if ((frame.w > 0 || frame.h > 0) && frame.ui) {
                const order = api?.ui_getRenderOrder?.(registry, entity as number) ?? -1;
                layer = order >= 0 ? UI_BASE_LAYER + order : UI_BASE_LAYER;
            }

            renderer.drawText(
                // Subtree opacity (UINode.opacity) is resolved in C++ by the
                // layout pass; text is drawn here, so it multiplies the same
                // inherited alpha in and fades with its panel like visuals do.
                { ...textDrawParams(t, family, frame), opacity: groupAlpha },
                appState.matrix,
                entity as number,
                layer,
                // Screen draws all share one depth: their order is the UI tree's,
                // and a z left on a screen root would otherwise outrank a sibling.
                screen ? 0 : tr.worldPosition.z,
                api?.ui_getCullBit?.(registry, entity as number) ?? 0,
                projection,
            );
        }

        // Release cached geometry for text that vanished / hid this frame. Per
        // domain, because each keeps its own atlases: retaining across the two
        // would have each pass evict the other's glyphs every frame.
        state.bitmap?.retainOnly(seen);
        state.sdf?.retainOnly(seen);
        state.large?.retainOnly(seen);
    }

    /**
     * Put the glyphs of @p text on the atlas ahead of time, a slice a frame, as @p entity's Text will draw them: its font, size, style and
     * pipeline, in its domain. Everything is read from the Text rather than asked for again, since a glyph at another size or in another
     * atlas is a different cell and preloading it would buy nothing. See {@link preloadGlyphs}.
     */
    preload(app: App, entity: Entity, text: string, options: GlyphPreloadOptions = {}): GlyphPreload {
        const budgetMs = options.budgetMs !== undefined && options.budgetMs > 0 ? options.budgetMs : DEFAULT_PRELOAD_BUDGET_MS;
        const state = this.stateFor(app);
        const run: PreloadRun = {
            entity,
            framesWaited: 0,
            renderer: null,
            job: new GlyphPreloadJob(preloadCodepoints(text), budgetMs, () => {
                run.renderer?.releasePreload(run);
                const at = state.preloads.indexOf(run);
                if (at >= 0) state.preloads.splice(at, 1);
            }),
        };
        // With nothing to draw with (a logic-only host) there is no atlas to fill.
        if (!this.built_.has(app) || !app.pipeline) run.job.finish();
        if (!run.job.finished) state.preloads.push(run);
        return run.job;
    }

    private stepPreloads(app: App, runs: PreloadRun[]): void {
        // One at a time, so that the budget is the frame's and not each preload's.
        const run = runs.find((r) => !r.job.finished);
        if (!run) return;
        const world = app.world;
        if (!world.valid(run.entity) || !world.has(run.entity, Text) || !world.has(run.entity, Transform)) {
            run.job.finish();
            return;
        }
        const api = engineApi(app);
        const registry = world.getCppRegistry() as CppRegistry | null;
        const screen = !!(api?.ui_isScreenDomain && registry) && api.ui_isScreenDomain(registry, run.entity as number);
        // Bitmap glyphs are rasterized for the projection that draws them, which is known from the first frame on. Asked before it, they would
        // be another size than the ones drawn. A scene that never has one draws no text, so this does not wait for ever.
        if (!this.projectionKnown(app, screen) && run.framesWaited++ < PRELOAD_PROJECTION_FRAMES) return;

        const t = world.get(run.entity, Text) as TextData;
        const tr = world.get(run.entity, Transform) as TransformData;
        const family = resolveTextFamily(t.font, t.fontFamily);
        const dpr = platformDevicePixelRatio();
        const view = this.domainView(app, screen, dpr);
        const appState = this.stateFor(app);
        const renderer = this.rendererFor(app, screen ? appState.screen : appState.world, glyphKind(t, tr, family, view, dpr), view.contentScale, dpr);
        run.renderer = renderer;
        const style = textStyleBits(t);
        run.job.step((codepoint) => renderer.preloadGlyph(run, codepoint, family, style, t.fontSize), platformNow);
    }

    private projectionKnown(app: App, screen: boolean): boolean {
        if (screen) return app.hasResource(ScreenOverlay) && app.getResource(ScreenOverlay).active;
        return !!(app.getResource(UICameraInfo) as UICameraData | undefined)?.valid;
    }

    private domainView(app: App, screen: boolean, dpr: number): DomainView {
        if (screen) {
            if (!app.hasResource(ScreenOverlay)) return FLAT_VIEW;
            const overlay = app.getResource(ScreenOverlay);
            return overlay.active ? domainViewOf(overlay.projection, overlay.vpW, dpr) : FLAT_VIEW;
        }
        const cam = app.getResource(UICameraInfo) as UICameraData | undefined;
        return cam?.valid ? domainViewOf(cam.viewProjection, cam.vpW, dpr) : FLAT_VIEW;
    }

    /** The two glyph pipelines of one domain, created lazily; they share layout,
     *  page store, and batch submit — only the atlas contents and shader
     *  coverage differ. */
    private rendererFor(
        app: App,
        state: TextDomainState,
        kind: GlyphKind,
        contentScale: number,
        dpr: number,
    ): SdfTextRenderer {
        const module = app.wasmModule as ESEngineModule | null;
        if (kind === 'sdf') {
            if (!state.sdf) state.sdf = new SdfTextRenderer(module, { sdf: true });
            return state.sdf;
        }
        if (kind === 'large') {
            if (!state.large) state.large = new SdfTextRenderer(module, LARGE_GLYPH_ATLAS);
            return state.large;
        }
        if (!state.bitmap) {
            state.bitmap = new SdfTextRenderer(module, {
                sdf: false, dpr, renderSize: Math.round(GLYPH_BASE_SIZE * dpr),
            });
        }
        state.bitmap.setDevicePixelRatio(dpr);
        state.bitmap.setContentScale(contentScale);
        return state.bitmap;
    }
}

export const textPlugin = new TextPlugin();

/**
 * Put the glyphs of @p text on the atlas before they are shown, so the frame that shows them does not pay for them. The first page of a
 * novel is hundreds of new characters, and they all land in one frame otherwise. Give it what is coming (a chapter, the next scene's
 * lines) on a loading screen and wait on `done`, or let it run behind the game: it spends `budgetMs` a frame.
 *
 * @param entity The Text that will show them, which says how they are drawn. It need not be visible.
 * @param text   Repeated characters cost nothing. Text in a rich-text size or an outline is another cell, and is made when it first shows.
 * @returns      Call `release()` when the text is over: the glyphs hold their atlas pages until then.
 */
export function preloadGlyphs(app: App, entity: Entity, text: string, options?: GlyphPreloadOptions): GlyphPreload {
    return textPlugin.preload(app, entity, text, options);
}