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
perf(text): bound page-free glyph caches
yhhd94d107c691e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Addeddiff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.tsindex 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.tsindex 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.mjsindex 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':