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.

fix(ui): escape text cache parameter boundaries (#86)

YHHb90536f85679
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 0eef34a66..0e3e9400c 100644
--- a/examples/ui-localization-debug/README.md
+++ b/examples/ui-localization-debug/README.md
@@ -137,3 +137,7 @@ R closes the fixture's dialogs. Independent modal stacking is not covered here.
Click Inside, then press O repeatedly to cycle Clip → Ellipsis → Visible on
the same long text. The layout must change without changing the text or box.
Visible may still be clipped by the fixture's actual ancestor mask.
+
+Press K twice while the game has focus to change Inside from `A|B` / `Arial`
+to `A` / `B|Arial`. Text and font family change together; the canvas must show
+only `A` after the second press. Elements → Inside → Text exposes both values.
diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.md
index 3276464a8..545645d78 100644
--- a/examples/ui-localization-debug/VALIDATION.md
+++ b/examples/ui-localization-debug/VALIDATION.md
@@ -382,3 +382,18 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.
- This is cache correctness evidence, not a performance benchmark. Same-device
cache/reflow timings, complex shaping and device acceptance remain open.
No local Electron/native runner launched; RM-009 remains In Progress.
+
+## Text cache key collision — 2026-10-09
+
+- Pipe-joining unescaped text and font family produced the same key for
+ `A|B` / `Arial` and `A` / `B|Arial`, allowing stale geometry after both changed.
+ Serialize the parameter tuple with JSON escaping to preserve field boundaries.
+- The real renderer regression fails before the fix (three cached glyphs instead
+ of the new single glyph), then passes. An unchanged subsequent draw keeps the
+ same batch without glyph reads. 36 renderer/cache tests, SDK build and all
+ 16 source/built API checks pass.
+- Built-in browser production Play/SDK/WASM: K twice changes the same entity
+ between those pairs; the canvas shows only A after the second press, and
+ Elements → Inside → Text shows content A and fontFamily B|Arial.
+- No local Electron/native runner launched. This proves cache correctness;
+ cache/reflow performance, shaping and device acceptance remain open.
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 37394bfe0..79b4c3172 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -340,7 +340,7 @@ export function signatureOf(p: DrawTextParams): string {
? `${p.shadow.color.join(',')}:${p.shadow.dx}:${p.shadow.dy}:${p.shadow.blur ?? 0}`
: '';
const outline = p.outline ? `${p.outline.color.join(',')}:${p.outline.width}` : '';
- return [
+ return JSON.stringify([
p.text, p.fontFamily, p.fontSizePx, p.style ?? 0,
p.richText ? 1 : 0, p.align ?? 0, p.verticalAlign ?? 0,
p.lineHeight ?? 0, p.letterSpacing ?? 0,
@@ -348,5 +348,5 @@ export function signatureOf(p: DrawTextParams): string {
p.overflow ?? TextOverflow.Visible,
p.originX ?? 0, p.originY ?? 0,
p.color.join(','), shadow, outline,
- ].join('|');
+ ]);
}
diff --git a/sdk/tests/ui-text-overflow-cache.test.ts b/sdk/tests/ui-text-overflow-cache.test.ts
index 2b5ea9b4c..bcc81d50e 100644
--- a/sdk/tests/ui-text-overflow-cache.test.ts
+++ b/sdk/tests/ui-text-overflow-cache.test.ts
@@ -40,3 +40,30 @@ it('rebuilds only changed overflow geometry while other static text keeps its ca
expect(reads).not.toHaveBeenCalled();
}
});
+
+it('invalidates cached geometry when text and font names contain field delimiters', () => {
+ const atlas = new GlyphAtlas({ renderSize: 48, spread: 0, rasterize: () => ({
+ pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12,
+ advance: 11, bearingX: 1, bearingY: 10,
+ }) }, { createPage: () => 1000, uploadSubRegion: () => {} }, { pageSize: 1024, padding: 1, sdf: false });
+ const renderer = Object.assign(Object.create(SdfTextRenderer.prototype), {
+ atlas, sdf: false, module: null, cache_: new Map(),
+ }) as SdfTextRenderer;
+ const transform = new Float32Array(16);
+ const submit = vi.mocked(submitTextBatch);
+ const first: DrawTextParams = { text: 'A|B', fontFamily: 'Arial', fontSizePx: 48, color: [1, 1, 1, 1] };
+ renderer.drawText(first, transform, 1, 0, 0);
+ const next = { ...first, text: 'A', fontFamily: 'B|Arial' };
+ submit.mockClear();
+ renderer.drawText(next, transform, 1, 0, 0);
+ const expected: Float32Array[] = [];
+ drawTextWith(atlas, vertices => expected.push(vertices), next);
+ expect(submit.mock.calls.map(call => Array.from(call[1])))
+ .toEqual(expected.map(vertices => Array.from(vertices)));
+ const updated = submit.mock.calls[0][1];
+ submit.mockClear();
+ const reads = vi.spyOn(atlas, 'getGlyph');
+ renderer.drawText(next, transform, 1, 0, 0);
+ expect(submit.mock.calls[0][1]).toBe(updated);
+ expect(reads).not.toHaveBeenCalled();
+});
diff --git a/tools/ui-events-play-browser.tsx b/tools/ui-events-play-browser.tsx
index 7a3113f1c..068172e74 100644
--- a/tools/ui-events-play-browser.tsx
+++ b/tools/ui-events-play-browser.tsx
@@ -38,7 +38,7 @@ function Fixture() {
return <main style={{ padding: 16, height: '100vh', display: 'flex', flexDirection: 'column', gap: 12 }}>
<h2>UI Events · production Play realm browser verification</h2>
<div><button onClick={() => void start()}>Start Play</button> <button onClick={() => { PlayInspect.stop(); PlayRealm.stop(); }}>Stop Play</button> <button onClick={() => setMounted(value => !value)}>Toggle panel</button> <button onClick={() => void inspect()}>Read runtime snapshot</button></div>
- <small>Game keys: M opens a dialog; N opens a nested confirmation; R closes dialogs; D disables current focus; E restores controls; H hides the dialog parent; V shows it; T toggles a text input (outside text editing).</small>
+ <small>Game keys: M opens a dialog; N opens a nested confirmation; R closes dialogs; D disables current focus; E restores controls; H hides the dialog parent; V shows it; O cycles text overflow; K changes text/font cache keys; T toggles a text input (outside text editing).</small>
<p role="status">{realm.playing ? 'Playing' : 'Stopped'} · {realm.ready ? 'Ready' : 'Not ready'} · {realm.error ?? ''}</p>
<div style={{ display: 'flex', gap: 16, flex: 1, minHeight: 0 }}>
<div style={{ width: 800, height: 600, flexShrink: 0 }} ref={attach} />
diff --git a/tools/ui-events-play-project.ts b/tools/ui-events-play-project.ts
index 4098447bd..ba4d9704d 100644
--- a/tools/ui-events-play-project.ts
+++ b/tools/ui-events-play-project.ts
@@ -15,6 +15,12 @@ addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Re
installed.set(world, () => {
// Fixture shortcuts must not react to letters typed into an engine field.
if (focus.focusedEntity !== null && world.has(focus.focusedEntity, TextInput)) return;
+ if (input.isKeyPressed('KeyK')) {
+ const text = world.get(inside, Text);
+ const first = text.content !== 'A|B';
+ world.insert(inside, Text, { ...text, content: first ? 'A|B' : 'A',
+ fontFamily: first ? 'Arial' : 'B|Arial' });
+ }
if (input.isKeyPressed('KeyO')) {
const text = world.get(inside, Text);
world.insert(inside, Text, { ...text, content: 'Overflow mode changes cached text',