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
import { describe, it, expect, vi } from 'vitest';
import { Text, TextRenderMode, resolveTextRenderMode, glyphContentScale, buildText } from '../src/ui';
describe('TextRenderMode', () => {
it('defines Auto / Bitmap / Sdf', () => {
expect(TextRenderMode.Auto).toBe(0);
expect(TextRenderMode.Bitmap).toBe(1);
expect(TextRenderMode.Sdf).toBe(2);
});
it('Text defaults to Auto and declares the editor dropdown', () => {
expect((Text._default as { renderMode: number }).renderMode).toBe(TextRenderMode.Auto);
const meta = Text.fieldMeta['renderMode'];
expect(meta?.enum?.map(o => o.label)).toEqual(['Auto', 'Bitmap', 'Sdf']);
});
it('Text defaults enabled (the render toggle the editor eye flips)', () => {
expect((Text._default as { enabled: boolean }).enabled).toBe(true);
});
it('buildText defaults renderMode to Auto and passes overrides through', () => {
expect(buildText().renderMode).toBe(TextRenderMode.Auto);
expect(buildText({ renderMode: TextRenderMode.Sdf }).renderMode).toBe(TextRenderMode.Sdf);
expect(buildText().enabled).toBe(true);
expect(buildText({ enabled: false }).enabled).toBe(false);
});
});
describe('text too large on screen for a bitmap glyph', () => {
const flat = (contentScale: number) => ({ contentScale, perspective: false });
const unscaled = { worldScale: { x: 1, y: 1, z: 1 } } as never;
it('leaves the bitmap pipeline once it would rasterize past the limit', async () => {
const { glyphKind } = await import('../src/ui/text/plugin');
const label = { renderMode: TextRenderMode.Auto, fontSize: 10 };
expect(glyphKind(label, unscaled, 'Arial', flat(1))).toBe('bitmap');
expect(glyphKind(label, unscaled, 'Arial', flat(12.7))).toBe('bitmap');
expect(glyphKind(label, unscaled, 'Arial', flat(12.8))).toBe('large');
expect(glyphKind(label, unscaled, 'Arial', flat(58))).toBe('large');
expect(glyphKind(label, unscaled, 'Arial', flat(6.4), 2)).toBe('large');
expect(glyphKind(label, unscaled, 'Arial', flat(1))).toBe('bitmap');
});
it('does not override a mode the author chose, or a view it does not apply to', async () => {
const { glyphKind, drawsLarge } = await import('../src/ui/text/plugin');
expect(glyphKind({ renderMode: TextRenderMode.Bitmap, fontSize: 10 }, unscaled, 'Arial', flat(58))).toBe('bitmap');
expect(glyphKind({ renderMode: TextRenderMode.Sdf, fontSize: 10 }, unscaled, 'Arial', flat(58))).toBe('sdf');
expect(drawsLarge({ renderMode: TextRenderMode.Auto, fontSize: 200 }, 'Arial', { contentScale: 1, perspective: true }, 1)).toBe(false);
});
it('holds a ring as wide as a fifth of the em in its distance field', async () => {
const { LARGE_GLYPH_ATLAS } = await import('../src/ui/text/plugin');
expect(LARGE_GLYPH_ATLAS.padding).toBeGreaterThanOrEqual(0.2 * LARGE_GLYPH_ATLAS.renderSize);
});
});
describe('resolveTextRenderMode', () => {
it('forced modes win regardless of scale', () => {
expect(resolveTextRenderMode(TextRenderMode.Bitmap, 3)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Sdf, 1)).toBe('sdf');
});
it('Auto keeps bitmap for unscaled entities (within 2% of 1)', () => {
// The canvas design-fit is NOT part of this input — the bitmap atlas
// compensates it via setContentScale, so only the entity's own world
// scale routes here.
expect(resolveTextRenderMode(TextRenderMode.Auto, 1)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Auto, 1.019)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Auto, 0.981)).toBe('bitmap');
});
it('Auto switches to SDF once the entity itself is scaled', () => {
// e.g. a pressed-state scale tween or an animated pop-in.
expect(resolveTextRenderMode(TextRenderMode.Auto, 0.82)).toBe('sdf');
expect(resolveTextRenderMode(TextRenderMode.Auto, 1.5)).toBe('sdf');
expect(resolveTextRenderMode(TextRenderMode.Auto, 0.5)).toBe('sdf');
});
it('Auto falls back to bitmap on unknown / degenerate scales', () => {
expect(resolveTextRenderMode(TextRenderMode.Auto, 0)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Auto, -1)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Auto, NaN)).toBe('bitmap');
expect(resolveTextRenderMode(TextRenderMode.Auto, Infinity)).toBe('bitmap');
});
it('treats a missing mode (pre-upgrade scene data) as Auto', () => {
expect(resolveTextRenderMode(undefined, 1)).toBe('bitmap');
expect(resolveTextRenderMode(undefined, 0.82)).toBe('sdf');
});
});
describe('GlyphAtlas content scale (bitmap rasterization density)', () => {
it('refreshes bitmap DPR and invalidates layouts only when the density changes', async () => {
const { GlyphAtlas } = await import('../src/ui/text/glyph-atlas');
const source = { renderSize: 48, spread: 0, rasterize: () => null };
const atlas = new GlyphAtlas(source, null, { sdf: false });
atlas.setContentScale(0.75);
const initial = atlas.generation;
for (const [density, size, generation] of [[1, 24, initial], [2, 48, initial + 1],
[2, 48, initial + 1], [3, 72, initial + 2], [1, 24, initial + 3]]) {
atlas.setDevicePixelRatio(density);
expect(atlas.pixelSizeFor(32)).toBe(size);
expect(atlas.generation).toBe(generation);
}
atlas.setDevicePixelRatio(NaN);
atlas.setDevicePixelRatio(Infinity);
atlas.setDevicePixelRatio(0);
expect(atlas.pixelSizeFor(32)).toBe(24);
expect(atlas.generation).toBe(initial + 3);
const invalid = new GlyphAtlas(source, null, { sdf: false, dpr: Infinity });
expect(invalid.pixelSizeFor(32)).toBe(32);
const sdf = new GlyphAtlas(source, null, { sdf: true });
sdf.setDevicePixelRatio(3);
expect(sdf.pixelSizeFor(32)).toBe(48);
expect(sdf.generation).toBe(0);
});
it('folds the content scale into bitmap pixel sizes, but never SDF', async () => {
const { GlyphAtlas } = await import('../src/ui/text/glyph-atlas');
const fakeRasterizer = { renderSize: 48, rasterize: () => null };
const fakeStore = { createPage: () => 1, uploadRegion: () => {} };
const bitmap = new GlyphAtlas(fakeRasterizer as never, fakeStore as never, { sdf: false, dpr: 2 });
expect(bitmap.pixelSizeFor(13)).toBe(26); // 13 × dpr2
bitmap.setContentScale(0.823); // 800×600 design in a smaller view
expect(bitmap.pixelSizeFor(13)).toBe(21); // 13 × 2 × 0.823 ≈ 21.4 → hinted at final px
bitmap.setContentScale(NaN); // degenerate input resets to 1
expect(bitmap.pixelSizeFor(13)).toBe(26);
const sdf = new GlyphAtlas(fakeRasterizer as never, fakeStore as never, { sdf: true });
sdf.setContentScale(0.5);
expect(sdf.pixelSizeFor(13)).toBe(48); // SDF is one fixed source
});
});
describe('glyphContentScale (what size to rasterize FOR)', () => {
// Element 0 of an orthographic projection: 2 / the span it shows. It takes
// the PROJECTION, not a camera — world text asks with the camera's and screen
// text with the overlay's.
const projFor = (span: number) => 2 / span;
it('is device pixels per world unit, so a 1:1 view rasterizes 1:1', () => {
expect(glyphContentScale(projFor(1920), 1920, 1)).toBeCloseTo(1, 5);
expect(glyphContentScale(projFor(1920), 1920, 2)).toBeCloseTo(0.5, 5); // dpr folded in by the atlas
});
// The editor holds the layout box at the design size on purpose, so UI does
// not reflow while the view zooms. Reading the span from that box asked for
// design-sized glyphs and let the camera scale them — the blur this fixes.
it('follows the projection when it shows less than the layout box (zoomed in)', () => {
expect(glyphContentScale(projFor(480), 1920, 1)).toBeCloseTo(4, 5); // 4x in
});
it('follows the projection when it shows more than the layout box (zoomed out)', () => {
expect(glyphContentScale(projFor(3840), 1920, 1)).toBeCloseTo(0.5, 5); // 2x out
});
it('is 1 when the projection says nothing, rather than guessing from a box', () => {
expect(glyphContentScale(0, 1920, 1)).toBe(1);
expect(glyphContentScale(NaN, 1920, 1)).toBe(1);
});
it('is 1 with no viewport, or a nonsense dpr', () => {
expect(glyphContentScale(projFor(1920), 0, 1)).toBe(1);
expect(glyphContentScale(projFor(1920), 1920, 0)).toBe(1);
});
});
describe('world text under a perspective camera', () => {
const ortho = (span: number) => { const m = new Float32Array(16); m[0] = 2 / span; m[5] = 2 / span; m[10] = -1; m[15] = 1; return m; };
const perspective = (fovDeg: number, aspect: number) => {
const f = 1 / Math.tan((fovDeg * Math.PI) / 360);
const m = new Float32Array(16);
m[0] = f / aspect; m[5] = f; m[10] = -1.0002; m[11] = -1; m[14] = -0.2;
return m;
};
it('has no single scale to rasterize for, and says it is a perspective', async () => {
const { domainViewOf } = await import('../src/ui/text/plugin');
expect(domainViewOf(perspective(55, 2670 / 1200), 2670, 2.75)).toEqual({ contentScale: 1, perspective: true });
const flat = domainViewOf(ortho(960), 1920, 1);
expect(flat.perspective).toBe(false);
expect(flat.contentScale).toBeCloseTo(2, 5);
});
it('draws Auto text as SDF there, at any scale, and keeps a forced mode', async () => {
const { domainViewOf, glyphKind } = await import('../src/ui/text/plugin');
const view = domainViewOf(perspective(55, 16 / 9), 1920, 1);
const at = (scale: number, renderMode: TextRenderMode = TextRenderMode.Auto) =>
glyphKind({ renderMode, fontSize: 32 }, { worldScale: { x: scale, y: scale, z: scale } }, 'sans-serif', view);
expect(at(1)).toBe('sdf');
expect(at(1.5)).toBe('sdf');
expect(at(1, TextRenderMode.Bitmap)).toBe('bitmap');
const flat = domainViewOf(ortho(1920), 1920, 1);
expect(glyphKind({ renderMode: TextRenderMode.Auto, fontSize: 32 }, { worldScale: { x: 1, y: 1, z: 1 } }, 'sans-serif', flat)).toBe('bitmap');
});
it('never rasterizes a bitmap glyph larger than half an atlas page, and says so once', async () => {
const { GlyphAtlas } = await import('../src/ui/text/glyph-atlas');
const { log } = await import('../src/util/logger');
const warn = vi.spyOn(log, 'warn').mockImplementation(() => {});
const atlas = new GlyphAtlas({ renderSize: 48, rasterize: () => null } as never, { createPage: () => 1, uploadRegion: () => {} } as never, { sdf: false, dpr: 2.75 });
atlas.setContentScale(380);
expect(atlas.pixelSizeFor(32)).toBe(512);
expect(atlas.pixelSizeFor(48)).toBe(512);
expect(warn).toHaveBeenCalledTimes(1);
atlas.setContentScale(1);
expect(atlas.pixelSizeFor(32)).toBe(88);
warn.mockRestore();
});
});