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
fix(text): refresh bitmap glyph density when device pixel ratio changes
yhh7d93fea4b464
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 34d363d3c..c73b28a3e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -26,6 +26,8 @@ published separately; it ships inside the editor.### Fixed+- **Bitmap text follows device pixel ratio changes during an App.** World and screen text refresh bitmap atlas density from the current frame, rebuilding cached geometry for changed pixel sizes without restarting the App. Stable frames keep cached glyphs, SDF retains its fixed source size, and existing frame-boundary page retirement keeps referenced textures alive during transitions.+- **Nested UI stencil masks intersect their parents and restore clipping.** Child masks enter only matching parent stencil pixels, and leaving a subtree replays its original geometry to restore the parent before siblings draw. Rotated and alpha-cutout shapes keep their intersections; mask replays preserve sampler bindings. Depth references are reused across siblings, with up to 255 nested levels when no SpriteMask references are reserved. Shared reference overflow clips affected subtrees instead of aliasing; restoration adds draws without allocating mask textures or duplicate vertices.## [0.84.0] - 2026-10-15diff --git a/sdk/src/ui/text/glyph-atlas.ts b/sdk/src/ui/text/glyph-atlas.tsindex 39285549d..8f5241d55 100644--- a/sdk/src/ui/text/glyph-atlas.ts+++ b/sdk/src/ui/text/glyph-atlas.ts@@ -107,7 +107,7 @@ export class GlyphAtlas {private readonly pageSize: number;private readonly padding: number;private readonly sdf: boolean;- private readonly dpr: number;+ private dpr: number;private contentScale_ = 1;private generation_ = 0;private readonly cache = new Map<string, GlyphEntry | null>();@@ -123,7 +123,8 @@ export class GlyphAtlas {this.pageSize = opts.pageSize ?? 1024;this.padding = opts.padding ?? 1;this.sdf = opts.sdf ?? true;- this.dpr = opts.dpr ?? 1;+ const dpr = opts.dpr ?? 1;+ this.dpr = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;}/** A null store keeps metrics in CPU memory without drawable atlas pages. */@@ -170,7 +171,7 @@ export class GlyphAtlas {/*** Bumped only when a change can alter the atlas coordinates of glyphs that- * are already placed — i.e. a bitmap content-scale change (glyphs re-rasterize+ * are already placed — i.e. a bitmap density change (glyphs re-rasterize* at a new pixel size). Placement is append-only, so adding a *new* glyph never* moves an existing one; callers cache laid-out geometry against this counter.*/@@ -201,6 +202,16 @@ export class GlyphAtlas {}}+ /** Refresh bitmap density without retiring pages still owned by submitted layouts. */+ setDevicePixelRatio(dpr: number): void {+ if (this.sdf) return;+ const next = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;+ if (next !== this.dpr) {+ this.dpr = next;+ this.generation_++;+ }+ }+/** Rasterization size for a display size: SDF uses one fixed source;* bitmap rasterizes per size at the effective on-screen density. */pixelSizeFor(displaySize: number): number {diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex dff1181ff..e1ad4b28f 100644--- a/sdk/src/ui/text/plugin.ts+++ b/sdk/src/ui/text/plugin.ts@@ -229,6 +229,7 @@ export class TextPlugin implements Plugin {app, state,resolveTextRenderMode(t.renderMode, tr.worldScale.x),contentScale,+ dpr,);if (!readMatrix) composeTRS(appState.matrix, tr.worldPosition, tr.worldRotation, tr.worldScale);@@ -347,6 +348,7 @@ export class TextPlugin implements Plugin {state: TextDomainState,kind: 'bitmap' | 'sdf',contentScale: number,+ dpr: number,): SdfTextRenderer {const module = app.wasmModule as ESEngineModule | null;if (kind === 'sdf') {@@ -354,11 +356,11 @@ export class TextPlugin implements Plugin {return state.sdf;}if (!state.bitmap) {- const dpr = platformDevicePixelRatio();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;}diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 62c5fc26b..e3927c00f 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -314,6 +314,10 @@ export class SdfTextRenderer {this.atlas.setContentScale(scale);}+ setDevicePixelRatio(dpr: number): void {+ this.atlas.setDevicePixelRatio(dpr);+ }+/** Previous frame has submitted; remove unused layouts and their GPU pages. */beginFrame(): void {if (this.atlas.metricsOnly) return;diff --git a/sdk/tests/native-text.test.ts b/sdk/tests/native-text.test.tsindex d9e9a75fa..57d3b7049 100644--- a/sdk/tests/native-text.test.ts+++ b/sdk/tests/native-text.test.ts@@ -21,6 +21,7 @@ import { setNativeTextSubmit, TEXT_VERTEX_FLOATS } from '../src/ui/text/submit';import { Camera, Canvas, Transform } from '../src/ecs/component';import { SdfTextRenderer } from '../src/ui/text/text-renderer';import { Text, TextRenderMode } from '../src/ui/core/text';+import { UICameraInfo } from '../src/ui/core/ui-camera-info';import { PTR_ACCESSORS } from '../src/ecs/bridge/ptrAccessors.generated';import type { PlatformGlyphRequest } from '../src/platform/types';import type { NativeBridge } from '../src/platform/native/bridge';@@ -178,6 +179,39 @@ function buildScene(app: ReturnType<typeof createNativeApp>, setScene: (canvas:}describe('a frame on the native core', () => {+ it('keeps bitmap geometry aligned with the native viewport after DPR changes', async () => {+ const host = makeHostScope();+ let density = 1;+ const bridge = makeBridge(host.scope);+ bridge.devicePixelRatio = () => density;+ host.scope.es_renderer_surfaceSize = () => ({ width: 800 * density, height: 600 * density });+ const app = createNativeApp(bridge, host.scope);+ await app.tick(0);+ const label = buildScene(app, host.setScene);+ app.world.insert(label, Text, { content: 'A', fontSize: 32, renderMode: TextRenderMode.Bitmap });+ for (const next of [1, 2, 3, 1]) {+ density = next;+ host.rasterizeSpy.mockClear();+ host.submitSpy.mockClear();+ await app.tick(1 / 60);+ const camera = app.getResource(UICameraInfo);+ const expected = Math.round(32 * Math.abs(camera.viewProjection[0]) * camera.vpW / 2);+ expect(expected).toBeGreaterThan(0);+ const request = host.rasterizeSpy.mock.calls.at(-1)?.[0];+ if (request) expect(request.pixelSize).toBe(expected);+ expect(host.submitSpy).toHaveBeenCalled();+ const vertices = host.submitSpy.mock.calls[0][0] as Float32Array;+ expect(Math.abs(vertices[TEXT_VERTEX_FLOATS] - vertices[0])).toBeCloseTo(8 * 32 / expected);+ expect(host.textures.size).toBeLessThanOrEqual(2);+ host.rasterizeSpy.mockClear();+ await app.tick(1 / 60);+ expect(host.rasterizeSpy).not.toHaveBeenCalled();+ expect(host.textures.size).toBe(1);+ }+ app.quit({ keepRenderer: true });+ expect(host.textures.size).toBe(0);+ });+it('reclaims obsolete glyph pages at frame boundaries without rerasterizing live text', async () => {const host = makeHostScope();const app = createNativeApp(makeBridge(host.scope), host.scope);diff --git a/sdk/tests/ui-text-render-mode.test.ts b/sdk/tests/ui-text-render-mode.test.tsindex 27b42fd8a..2d6466afa 100644--- a/sdk/tests/ui-text-render-mode.test.ts+++ b/sdk/tests/ui-text-render-mode.test.ts@@ -64,6 +64,31 @@ describe('resolveTextRenderMode', () => {});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 };diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 5a9d504e4..6ec916676 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -34,6 +34,8 @@ export const NOTED = {{ note: 'The Playable Ad starter includes a complete editable game.' },'test(youtube): verify hosting CSP and negative control':{ note: 'YouTube headless checks enforce the documented hosting policy.' },+ 'fix(text): refresh bitmap glyph density when device pixel ratio changes':+ { note: 'Bitmap text follows device pixel ratio changes during an App.' },'feat(youtube): validate export bundle constraints':{ note: 'YouTube exports check stored bundle constraints.' },'feat(youtube): connect Playables readiness pause and cloud saves':