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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* A label's glyph quads are handed to the engine once and submitted by it every frame, so what decides "the label is the same" has to be right in
* both directions: a field that changes the layout and is missing from the comparison leaves the old text on screen, and one that does not change
* it and is in the comparison relays the label out for nothing.
*/
import { describe, expect, it, vi } from 'vitest';
import { GlyphAtlas } from '../src/ui/text/glyph-atlas';
import { SdfTextRenderer, drawTextWith, type DrawTextParams } from '../src/ui/text/text-renderer';
import { resolveTextRenderMode, sameSnapshot, snapshotOf } from '../src/ui/text/plugin';
import { rectTextBox } from '../src/ui/text/text-transform';
import { Text, type TextData } from '../src/ui/core/text';
import type { EngineApi } from '../src/ecs/bridge/engineApi';
import { TEXT_VERTEX_FLOATS } from '../src/ui/text/submit';
vi.mock('../src/platform', () => ({
platformHasGlyphRasterizer: () => false,
platformCreateCanvas: (width: number, height: number) => ({ width, height, getContext: () => null }),
}));
// From the component itself, so a field Text gains is a key here without anyone remembering to add it.
function freshText(): TextData {
return { ...structuredClone(Text._default), content: 'hello', fontFamily: 'Arial' };
}
describe('which Text fields make a retained label laid out again', () => {
// Every field of the component is either compared or has a stated reason it is not. A field added to Text lands here as a failure until
// someone decides which.
const compared: Array<[string, (t: TextData) => void]> = [
['content', t => { t.content = 'world'; }],
['fontFamily', t => { t.fontFamily = 'Courier'; }],
['fontSize', t => { t.fontSize = 30; }],
['color', t => { t.color = { r: 0.5, g: 1, b: 1, a: 1 }; }],
['align', t => { t.align = 1; }],
['verticalAlign', t => { t.verticalAlign = 1; }],
['wordWrap', t => { t.wordWrap = false; }],
['overflow', t => { t.overflow = 1; }],
['lineHeight', t => { t.lineHeight = 1.5; }],
['letterSpacing', t => { t.letterSpacing = 2; }],
['underline', t => { t.underline = true; }],
['bold', t => { t.bold = true; }],
['italic', t => { t.italic = true; }],
['strokeColor', t => { t.strokeColor = { r: 1, g: 0, b: 0, a: 1 }; }],
['strokeWidth', t => { t.strokeWidth = 2; }],
['shadowColor', t => { t.shadowColor = { r: 0, g: 1, b: 0, a: 1 }; }],
['shadowBlur', t => { t.shadowBlur = 3; }],
['shadowOffsetX', t => { t.shadowOffsetX = 2; }],
['shadowOffsetY', t => { t.shadowOffsetY = 2; }],
['richText', t => { t.richText = true; }],
['renderMode', t => { t.renderMode = 1; }],
['layer', t => { t.layer = 3; }],
// The box a world label lays out in: moving or resizing it moves the glyphs, so each is part of what "the same label" means.
['boxWidth', t => { t.boxWidth = 120; }],
['boxHeight', t => { t.boxHeight = 40; }],
['boxPivot', t => { t.boxPivot = { x: 0, y: 1 }; }],
];
// font is resolved to the family and compared as that; enabled and an empty content decide whether the label exists at all; i18nKey only
// ever changes `content`.
const elsewhere = ['font', 'enabled', 'i18nKey'];
it('accounts for every field of the component', () => {
const all = Object.keys(freshText()).sort();
expect([...compared.map(([k]) => k), ...elsewhere].sort()).toEqual(all);
});
it.each(compared)('%s changes the comparison', (_key, change) => {
const t = freshText();
const snap = snapshotOf(t, 'Arial');
expect(sameSnapshot(snap, t, 'Arial')).toBe(true);
const changed = freshText();
change(changed);
expect(sameSnapshot(snap, changed, changed.fontFamily)).toBe(false);
});
it('treats the resolved family as the font', () => {
const t = freshText();
expect(sameSnapshot(snapshotOf(t, 'Arial'), t, 'Georgia')).toBe(false);
});
});
describe('the glyph pipeline an automatic label gets', () => {
// The engine decides it from the world scale (RetainedText.hpp, retainedTextAutoIsSdf) and this table is pinned there too: float32 values,
// as the engine holds them.
const table: Array<[number, 'bitmap' | 'sdf']> = [[1.0, 'bitmap'], [1.02, 'bitmap'], [0.98, 'bitmap'], [1.021, 'sdf'], [0.97, 'sdf'], [2.0, 'sdf'], [0.5, 'sdf'], [0.0, 'bitmap'], [-1.0, 'bitmap'], [Infinity, 'bitmap'], [NaN, 'bitmap']];
it.each(table)('scale %s draws with %s', (scale, kind) => {
expect(resolveTextRenderMode(undefined, Math.fround(scale))).toBe(kind);
});
});
describe('handing a label to the engine', () => {
function engine() {
const heap = new Uint8Array(1 << 20);
let top = 8;
const batches: Array<{ entity: number; vertices: number[]; indices: number[]; vertexCount: number; pageId: number }> = [];
const calls: string[] = [];
const api = {
HEAPU8: heap,
_malloc: (n: number) => { const p = top; top += (n + 7) & ~7; return p; },
_free: () => {},
renderer_retainedTextBegin: (...a: number[]) => { calls.push(`begin ${a.join(',')}`); },
renderer_retainedTextBatch: (entity: number, vPtr: number, vertexCount: number, iPtr: number, indexCount: number, pageId: number) => {
calls.push(`batch ${entity} ${vertexCount} ${indexCount} ${pageId}`);
batches.push({
entity, vertexCount, pageId,
vertices: Array.from(new Float32Array(heap.buffer.slice(vPtr, vPtr + vertexCount * TEXT_VERTEX_FLOATS * 4))),
indices: Array.from(new Uint16Array(heap.buffer.slice(iPtr, iPtr + indexCount * 2))),
});
},
} as unknown as EngineApi;
return { api, batches, calls };
}
function rendererWith(atlas: GlyphAtlas): SdfTextRenderer {
const renderer = new SdfTextRenderer(null, { sdf: false, metricsOnly: true });
Object.defineProperty(renderer, 'atlas', { value: atlas });
return renderer;
}
const makeAtlas = () => {
let page = 500;
return new GlyphAtlas({ renderSize: 48, spread: 0, rasterize: () => ({
pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance: 11, bearingX: 1, bearingY: 10,
}) }, { createPage: () => page++, uploadSubRegion: () => {} }, { pageSize: 1024, padding: 1, sdf: false });
};
const params: DrawTextParams = { text: 'ABC', fontFamily: 'Arial', fontSizePx: 24, color: [1, 1, 1, 1] };
it('begins the label once and sends the quads the layout makes, whole', () => {
const atlas = makeAtlas();
const renderer = rendererWith(atlas);
const { api, batches, calls } = engine();
renderer.retain(api, params, 42, true, true, 7, 120, 30, true);
expect(calls[0]).toBe('begin 42,0,1,1,7,120,30,1');
const expected: Array<{ v: number[]; i: number[]; page: number }> = [];
drawTextWith(atlas, (v, i, page) => expected.push({ v: Array.from(v), i: Array.from(i), page }), { ...params, opacity: 1 });
expect(batches.map(b => ({ v: b.vertices, i: b.indices, page: b.pageId }))).toEqual(expected);
expect(batches.every(b => b.entity === 42)).toBe(true);
});
it('keeps the atlas pages of a label that is not rebuilt, and lets them go when it is forgotten', () => {
const atlas = makeAtlas();
const renderer = rendererWith(atlas);
const retain = vi.spyOn(atlas, 'retainPages');
const { api, batches } = engine();
renderer.retain(api, params, 5, false, false, 0, 0, 0, false);
const pages = new Set(batches.map(b => b.pageId));
expect(pages.size).toBeGreaterThan(0);
// Frames that do not draw it again (an Update with no render, a frame the label is unchanged) must not release its pages.
renderer.beginFrame();
renderer.beginFrame();
const kept = (retain.mock.calls.at(-1)![0] as Set<number>);
expect([...pages].every(p => kept.has(p))).toBe(true);
renderer.forget(5);
renderer.beginFrame();
const afterForget = (retain.mock.calls.at(-1)![0] as Set<number>);
expect([...pages].some(p => afterForget.has(p))).toBe(false);
});
});
describe('where a text box puts the glyphs relative to the entity', () => {
// The entity origin is the box's pivot (an anchor point, from the left and the BOTTOM edge); the glyph block starts at the box's top-left
// corner, one ascent (0.8 em) below the top for the first baseline.
it('centred pivot: the box straddles the origin', () => {
const b = rectTextBox(0.5, 0.5, 200, 60, 20);
expect(b.originX).toBe(-100);
expect(b.originY).toBe(30 - 16);
expect(b.maxWidth).toBe(200);
expect(b.boxHeight).toBe(60);
});
it('top-left pivot: the box hangs right of and below the origin', () => {
const b = rectTextBox(0, 1, 200, 60, 20);
expect(b.originX).toBeCloseTo(0);
expect(b.originY).toBe(0 - 16);
});
it('bottom-right pivot: the box sits left of and above the origin', () => {
const b = rectTextBox(1, 0, 200, 60, 20);
expect(b.originX).toBe(-200);
expect(b.originY).toBe(60 - 16);
});
});