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.

perf(text): bound page-free glyph caches

yhhd94d107c691e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e8971a3e6..53757e0ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **Page-free text glyph caches stay bounded.** Missing and oversized glyphs, whitespace metrics and measurement-only entries use a 4096-entry least-recently-used cache. Historical fonts and sizes retire without touching live drawable pages or cached layout coordinates; recently used measurements remain cached and retired entries rasterize again on demand.
+
## [0.85.0] - 2026-10-15
### Added
diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.ts
index 8f5241d55..405110b6e 100644
--- a/sdk/src/ui/text/glyph-atlas.ts
+++ b/sdk/src/ui/text/glyph-atlas.ts
@@ -110,7 +110,8 @@ export class GlyphAtlas {
private dpr: number;
private contentScale_ = 1;
private generation_ = 0;
- private readonly cache = new Map<string, GlyphEntry | null>();
+ private readonly cache = new Map<string, GlyphEntry>();
+ private readonly cpuCache = new Map<string, GlyphEntry | null>();
private readonly pages: number[] = [];
private readonly packers: Packer[] = [];
private readonly placements: GlyphPlacement[][] = [];
@@ -139,6 +140,7 @@ export class GlyphAtlas {
this.packers.length = 0;
this.placements.length = 0;
this.cache.clear();
+ this.cpuCache.clear();
this.mute_.clear();
this.generation_++;
const errors: unknown[] = [];
@@ -230,12 +232,18 @@ export class GlyphAtlas {
/**
* Get a glyph's atlas entry, rasterizing + packing it on first use. Returns
* null for glyphs the rasterizer cannot produce (caller skips / uses fallback).
- * The result is cached (including the null), so a miss is paid once.
+ * Drawable entries follow page lifetime; page-free entries use a bounded LRU.
*/
getGlyph(codepoint: number, fontFamily: string, style = 0, pixelSize = this.renderSize): GlyphEntry | null {
const k = this.key(codepoint, fontFamily, style, pixelSize);
const hit = this.cache.get(k);
if (hit !== undefined) return hit;
+ const cpuHit = this.cpuCache.get(k);
+ if (cpuHit !== undefined) {
+ this.cpuCache.delete(k);
+ this.cpuCache.set(k, cpuHit);
+ return cpuHit;
+ }
const raster = this.rasterizer.rasterize(codepoint, fontFamily, style, pixelSize);
if (!raster) {
@@ -247,7 +255,7 @@ export class GlyphAtlas {
log.warn('text', `no glyph for U+${codepoint.toString(16).toUpperCase()} in `
+ `"${fontFamily}" — this family produced none, so its text draws nothing`);
}
- this.cache.set(k, null);
+ this.cacheCPU(k, null);
return null;
}
@@ -259,13 +267,13 @@ export class GlyphAtlas {
width: 0, height: 0,
advance: raster.advance, bearingX: raster.bearingX, bearingY: raster.bearingY,
};
- this.cache.set(k, entry);
+ this.cacheCPU(k, entry);
return entry;
}
if (!this.store) {
if (raster.width + this.padding > this.pageSize || raster.height + this.padding > this.pageSize) {
- this.cache.set(k, null);
+ this.cacheCPU(k, null);
return null;
}
const entry: GlyphEntry = {
@@ -273,14 +281,14 @@ export class GlyphAtlas {
width: raster.width, height: raster.height,
advance: raster.advance, bearingX: raster.bearingX, bearingY: raster.bearingY,
};
- this.cache.set(k, entry);
+ this.cacheCPU(k, entry);
return entry;
}
const placed = this.place(raster.width, raster.height);
if (!placed) {
// Glyph larger than a whole page — cannot atlas it. Cache null.
- this.cache.set(k, null);
+ this.cacheCPU(k, null);
return null;
}
@@ -308,6 +316,14 @@ export class GlyphAtlas {
return entry;
}
+ /** Page-free entries can be recreated without changing any live layout or UV. */
+ private cacheCPU(key: string, glyph: GlyphEntry | null): void {
+ this.cpuCache.set(key, glyph);
+ if (this.cpuCache.size > 4096) {
+ this.cpuCache.delete(this.cpuCache.keys().next().value!);
+ }
+ }
+
/** Reserve a w×h cell across pages, opening a new page when the last is full. */
private place(w: number, h: number): { page: number; x: number; y: number } | null {
const cellW = w + this.padding;
diff --git a/sdk/tests/ui-glyph-atlas.test.ts b/sdk/tests/ui-glyph-atlas.test.ts
index 6094ce216..2f5d41ab7 100644
--- a/sdk/tests/ui-glyph-atlas.test.ts
+++ b/sdk/tests/ui-glyph-atlas.test.ts
@@ -260,3 +260,37 @@ describe('GlyphAtlas: a page painted again is the page that was uploaded', () =>
expect(repainted).toEqual(images[0]);
});
});
+
+
+describe('page-free glyph cache lifetime', () => {
+ it.each(['missing', 'whitespace', 'oversized', 'measurement'] as const)(
+ 'bounds historical %s entries while keeping recently used metrics and drawable glyphs', kind => {
+ const rasterizer = makeRasterizer();
+ const store = makeStore();
+ const atlas = new GlyphAtlas(rasterizer, kind === 'measurement' ? null : store, { pageSize: 64 });
+ const cp = { missing: UNKNOWN, whitespace: SPACE, oversized: HUGE, measurement: 65 }[kind];
+ const first = atlas.getGlyph(cp, 'Arial', 0, 1);
+ const hot = atlas.getGlyph(cp, 'Arial', 0, 2);
+ const drawable = kind === 'measurement' ? null : atlas.getGlyph(66, 'Arial');
+ for (let size = 3; size < 12003; size++) {
+ atlas.getGlyph(cp, 'Arial', 0, size);
+ expect(atlas.getGlyph(cp, 'Arial', 0, 2)).toBe(hot);
+ }
+ const calls = rasterizer.rasterize.mock.calls.length;
+ atlas.getGlyph(cp, 'Arial', 0, 1);
+ expect(rasterizer.rasterize.mock.calls.length).toBe(calls + 1);
+ const entries = Object.values(atlas).filter(v => v instanceof Map)
+ .reduce((total, map) => total + map.size, 0);
+ expect(entries).toBeLessThanOrEqual(4097);
+ expect(atlas.getGlyph(cp, 'Arial', 0, 2)).toBe(hot);
+ if (drawable) {
+ expect(atlas.getGlyph(66, 'Arial')).toBe(drawable);
+ expect(store.uploadSubRegion).toHaveBeenCalledTimes(1);
+ expect(atlas.pageCount).toBe(1);
+ } else expect(atlas.pageCount).toBe(0);
+ atlas.dispose();
+ const afterDispose = rasterizer.rasterize.mock.calls.length;
+ expect(atlas.getGlyph(cp, 'Arial', 0, 2)).toEqual(first);
+ expect(rasterizer.rasterize.mock.calls.length).toBe(afterDispose + 1);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 665aa0bd5..27e4a9365 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(text): bound page-free glyph caches':
+ { note: 'Page-free text glyph caches stay bounded.' },
'feat(viewport): highlight transform handles under the pointer':
{ note: "Transform handles preview the pointer's target before a drag." },
'fix(checks): report non-TypeScript example failures':