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(text): preserve full transforms in SDK label rendering

yhh2e5f0644e61c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f46441d02..77bb3424f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **SDK text follows the full parent transform and skips collapsed labels.** Bitmap and SDF labels copy the engine's complete matrix instead of reconstructing decomposed TRS, retaining shear and mirrors. The shared Web/native bridge rejects known zero-area labels before atlas creation or layout, uses one reusable scratch matrix per render pass and handles childless roots without a stale matrix cache. Legacy cores retain their existing fallback.
+
- **Collapsed 2D hierarchies skip geometry and recover reliably.** Transform composition propagates authored zero-area state through planar rotations and transformless groups, preventing floating-point residue from reviving degenerate boxes. Sprite, UI, native bitmap text, picking and empty scissor/stencil subtrees share the guard. Valid tiny spans and children that regain area through a 3D tilt remain available; hidden bitmap runs skip font layout and submission.
- **Web audio preserves the latest device pause intent.** Late browser resume/suspend operations cannot undo a newer takeover request; initial autoplay-unlock gestures and ensureResumed respect explicit suspension. Reconciliation stops at the current request and ignores disposed contexts, preserving the user mixer and avoiding retry loops for blocked playback.
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index a58d44537..0c6cb2e8e 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -508,6 +508,7 @@ tilemap_setTiles: ((entity: number, tilesPtr: number, count: number) => void) |
trail_clear: ((registry: CppRegistry, entity: number) => void) | undefined
trail_update: ((registry: CppRegistry, dt: number) => void) | undefined
transform_compositionChanges: (() => { serial: number; tracking: boolean; overflowed: boolean; count: number; visited: number; ptr: number; }) | undefined
+transform_copyFlatRenderMatrix: ((registry: CppRegistry, entity: number, outputPtr: number) => boolean) | undefined
transform_ensureComposed: ((registry: CppRegistry) => void) | undefined
transform_epochAddress: (() => number) | undefined
transform_setChangeTracking: ((on: boolean) => void) | undefined
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 4687c4d89..c47251a8e 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -269,6 +269,7 @@ export interface NativeEngineApi {
tilemap_worldToTile?(entity: number, wx: number, wy: number, originX: number, originY: number): number;
trail_clear?(registry: unknown, entity: number): void;
trail_update?(registry: unknown, dt: number): void;
+ transform_copyFlatRenderMatrix?(registry: unknown, entity: number, outputPtr: number): boolean;
transform_update?(registry: unknown): void;
uiHitTest_getHitEntity?(): number;
uiHitTest_pick?(registry: unknown, worldX: number, worldY: number): number;
@@ -554,6 +555,7 @@ export function createNativeEngineApi(
bind('tilemap_worldToTile', 'es_tilemap_worldToTile', false);
bind('trail_clear', 'es_trail_clear', true);
bind('trail_update', 'es_trail_update', true);
+ bind('transform_copyFlatRenderMatrix', 'es_transform_copyFlatRenderMatrix', true);
bind('transform_update', 'es_transform_update', true);
bind('uiHitTest_getHitEntity', 'es_uiHitTest_getHitEntity', false);
bind('uiHitTest_pick', 'es_uiHitTest_pick', true);
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index d6478e3c9..b3a7c1689 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -27,6 +27,7 @@ import { getUINodeWidth, getUINodeHeight, ensureUIVisual } from '../util/helpers
import { resolveTextFamily } from './font-registry';
import { platformDevicePixelRatio } from '../../platform';
import { engineApi } from '../../ecs/bridge/engineApi';
+import { withScratch } from '../../wasm/wasmScratch';
// UI quads use layer = base + uiOrder, off the C++ declaration that owns it.
import { UI_BASE_LAYER } from '../../wasm/constants.generated';
@@ -93,6 +94,7 @@ export class TextPlugin implements Plugin {
private readonly world_: TextDomainState = { bitmap: null, sdf: null };
private readonly screen_: TextDomainState = { bitmap: null, sdf: null };
private readonly matrix_ = new Float32Array(16);
+ private matrixHeap_: Float32Array | null = null;
build(app: App): void {
registerComponent('Text', Text);
@@ -135,6 +137,28 @@ export class TextPlugin implements Plugin {
* spelling of that rule in TS is a second rule.
*/
private drawDomain(app: App, screen: boolean): void {
+ const api = engineApi(app);
+ if (!api?.transform_copyFlatRenderMatrix || !api.HEAPU8 || !api._malloc || !api._free) {
+ this.drawDomainWithMatrix(app, screen);
+ return;
+ }
+ const registry = app.world.getCppRegistry() as CppRegistry;
+ withScratch({ _malloc: size => api._malloc!(size), _free: ptr => api._free!(ptr) }, alloc => {
+ let pointer = 0;
+ this.drawDomainWithMatrix(app, screen, entity => {
+ if (!pointer) pointer = alloc(16 * 4);
+ if (!pointer) throw new Error('Could not allocate text transform scratch.');
+ if (!api.transform_copyFlatRenderMatrix!(registry, entity, pointer)) return false;
+ const heap = api.HEAPU8!;
+ if (this.matrixHeap_?.buffer !== heap.buffer) this.matrixHeap_ = new Float32Array(heap.buffer);
+ const offset = (heap.byteOffset + pointer) / 4;
+ for (let i = 0; i < 16; i++) this.matrix_[i] = this.matrixHeap_[offset + i]!;
+ return true;
+ });
+ });
+ }
+
+ private drawDomainWithMatrix(app: App, screen: boolean, readMatrix?: (entity: number) => boolean): void {
const world = app.world;
const registry = world.getCppRegistry() as CppRegistry;
// Through engineApi, not app.wasmModule: a device has no wasm module, and
@@ -163,6 +187,7 @@ export class TextPlugin implements Plugin {
if (api?.getUINodeHiddenInTree?.(registry, entity)) continue;
const groupAlpha = api?.getUINodeAlphaInTree?.(registry, entity) ?? 1;
if (groupAlpha <= 0) continue;
+ if (readMatrix && !readMatrix(entity as number)) continue;
seen.add(entity as number);
const tr = world.get(entity, Transform) as TransformData;
@@ -171,7 +196,7 @@ export class TextPlugin implements Plugin {
resolveTextRenderMode(t.renderMode, tr.worldScale.x),
contentScale,
);
- composeTRS(this.matrix_, tr.worldPosition, tr.worldRotation, tr.worldScale);
+ if (!readMatrix) composeTRS(this.matrix_, tr.worldPosition, tr.worldRotation, tr.worldScale);
const style = (t.bold ? UI_TEXT_BOLD : 0) | (t.italic ? UI_TEXT_ITALIC : 0);
// Text.lineHeight is a ratio of fontSize (legacy convention).
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index b97be8198..d6a2b7c3f 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -766,6 +766,7 @@ export interface ESEngineModule {
/** Subtree opacity resolved by the layout pass (UINode.opacity multiplied down). */
getUINodeAlphaInTree?(registry: CppRegistry, entity: number): number;
transform_update(registry: CppRegistry): void;
+ transform_copyFlatRenderMatrix?(registry: CppRegistry, entity: number, outputPtr: number): boolean;
// Animation (Tween) API
anim_createTween(registry: CppRegistry, entity: number, targetProp: number,
diff --git a/sdk/tests/native-text.test.ts b/sdk/tests/native-text.test.ts
index fdfb2c5ff..f213c9fa0 100644
--- a/sdk/tests/native-text.test.ts
+++ b/sdk/tests/native-text.test.ts
@@ -177,6 +177,38 @@ function buildScene(app: ReturnType<typeof createNativeApp>, setScene: (canvas:
}
describe('a frame on the native core', () => {
+ it('copies the full text basis and skips collapsed labels before rasterization', async () => {
+ const { scope, submitSpy, rasterizeSpy, setScene } = makeHostScope();
+ const heap = new ArrayBuffer(65536), frees = vi.fn();
+ let cursor = 64, drawable = false;
+ const matrix = [2, 1, 0, 0, 3, 4, 0, 0, 0, 0, 1, 0, 13, 17, 0, 1];
+ scope.es_heap = () => heap;
+ scope.es_malloc = (bytes: number) => { const offset = cursor; cursor += Math.ceil(bytes / 8) * 8; return offset; };
+ scope.es_free = frees;
+ scope.es_transform_copyFlatRenderMatrix = (_entity: number, pointer: number) => {
+ if (!drawable) return false;
+ new Float32Array(heap, pointer, 16).set(matrix);
+ return true;
+ };
+ const app = createNativeApp(makeBridge(scope), scope);
+ await app.tick(0);
+ const label = buildScene(app, setScene);
+ app.world.insert(label, Text, { content: 'Z', fontSize: 32, renderMode: TextRenderMode.Sdf });
+ await app.tick(1 / 60);
+ expect(rasterizeSpy).not.toHaveBeenCalled();
+ expect(submitSpy).not.toHaveBeenCalled();
+ expect(frees).toHaveBeenCalled();
+ drawable = true;
+ await app.tick(1 / 60);
+ expect(submitSpy).toHaveBeenCalled();
+ expect(Array.from(submitSpy.mock.calls[0][5] as Float32Array)).toEqual(matrix);
+ rasterizeSpy.mockClear(); submitSpy.mockClear();
+ drawable = false;
+ await app.tick(1 / 60);
+ expect(rasterizeSpy).not.toHaveBeenCalled();
+ expect(submitSpy).not.toHaveBeenCalled();
+ });
+
it('fades text fill, shadow and outline together and skips transparent subtrees', async () => {
const { scope, submitSpy, setScene } = makeHostScope();
let alpha = 0.5;
diff --git a/src/esengine/bindings/UIBindings.cpp b/src/esengine/bindings/UIBindings.cpp
index dca722770..e4dde1924 100644
--- a/src/esengine/bindings/UIBindings.cpp
+++ b/src/esengine/bindings/UIBindings.cpp
@@ -22,6 +22,8 @@
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/UINode.hpp"
#include "../ecs/components/UIVisual.hpp"
+#include "../ecs/FlatGeometry.hpp"
+#include <cstring>
namespace esengine {
@@ -134,6 +136,13 @@ f32 getUINodeComputedHeight(ecs::Registry& registry, u32 entity) {
return node->computed_size_.y;
}
+bool transform_copyFlatRenderMatrix(ecs::Registry& registry, u32 entity, uintptr_t outputPtr) {
+ glm::mat4 matrix;
+ if (!outputPtr || !ecs::copyFlatRenderMatrix(registry, Entity::fromRaw(entity), matrix)) return false;
+ std::memcpy(reinterpret_cast<void*>(outputPtr), glm::value_ptr(matrix), sizeof(glm::mat4));
+ return true;
+}
+
void transform_update(ecs::Registry& registry) {
esengine::World world{registry, ctx().services(), 0.0f};
if (auto* ts = ctx().tryGet<ecs::TransformSystem>()) {
diff --git a/src/esengine/bindings/UIBindings.hpp b/src/esengine/bindings/UIBindings.hpp
index 4729c4ffa..69b070329 100644
--- a/src/esengine/bindings/UIBindings.hpp
+++ b/src/esengine/bindings/UIBindings.hpp
@@ -85,4 +85,8 @@ f32 getUINodeComputedHeight(ecs::Registry& registry, u32 entity);
/** Compose world transforms now (the UI layout pass reads them). */
void transform_update(ecs::Registry& registry);
+/** Copy a drawable entity's complete world matrix to 16 caller-owned floats.
+ * False for missing or collapsed geometry; leaves the output unchanged. */
+bool transform_copyFlatRenderMatrix(ecs::Registry& registry, u32 entity, uintptr_t outputPtr);
+
} // namespace esengine
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index d5e0f5a79..0d1ce82a8 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -834,6 +834,7 @@ EMSCRIPTEN_BINDINGS(esengine_ui_systems) {
emscripten::function("getUINodeComputedWidth", &esengine::getUINodeComputedWidth);
emscripten::function("getUINodeComputedHeight", &esengine::getUINodeComputedHeight);
emscripten::function("transform_update", &esengine::transform_update);
+ emscripten::function("transform_copyFlatRenderMatrix", &esengine::transform_copyFlatRenderMatrix);
// Tweens (AnimationBindings.hpp) — the same declarations the native
// wrappers are generated from.
diff --git a/src/esengine/ecs/FlatGeometry.hpp b/src/esengine/ecs/FlatGeometry.hpp
index b69ed4317..5fc8cb223 100644
--- a/src/esengine/ecs/FlatGeometry.hpp
+++ b/src/esengine/ecs/FlatGeometry.hpp
@@ -32,4 +32,12 @@ inline bool hasFlatGeometryArea(Registry& registry, Entity entity, Transform& tr
&& hasFlatGeometryArea(transform, registry.has<Parent>(entity));
}
+inline bool copyFlatRenderMatrix(Registry& registry, Entity entity, glm::mat4& output) {
+ auto* transform = registry.tryGet<Transform>(entity);
+ if (!transform || !hasFlatGeometryArea(registry, entity, *transform)) return false;
+ output = registry.has<Parent>(entity) ? transform->cachedMatrix_
+ : math::compose(transform->worldPosition, transform->worldRotation, transform->worldScale);
+ return true;
+}
+
} // namespace esengine::ecs
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index 2424ca59b..17508cbf8 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -737,6 +737,33 @@ TEST_CASE("bitmap text: collapsed parent bases skip long glyph runs and recover"
resources.shutdown();
}
+TEST_CASE("text transform bridge: full parent basis and childless root TRS reach the caller") {
+ ecs::Registry registry;
+ const auto parent = registry.create(), child = registry.create();
+ registry.emplace<ecs::Parent>(child).entity = parent;
+ auto& transform = registry.emplace<ecs::Transform>(child);
+ transform.cachedMatrix_[0] = {2, 1, 0, 0};
+ transform.cachedMatrix_[1] = {3, 4, 0, 0};
+ transform.cachedMatrix_[3] = {13, 17, 0, 1};
+ transform.decomposed_ = false;
+ glm::mat4 output(9);
+ CHECK(ecs::copyFlatRenderMatrix(registry, child, output));
+ CHECK(output == transform.cachedMatrix_);
+ registry.emplace<ecs::FlatGeometryCollapsed>(child);
+ const auto retained = output;
+ CHECK_FALSE(ecs::copyFlatRenderMatrix(registry, child, output));
+ CHECK(output == retained);
+ CHECK_FALSE(ecs::copyFlatRenderMatrix(registry, INVALID_ENTITY, output));
+ const auto root = registry.create();
+ auto& rootTransform = registry.emplace<ecs::Transform>(root);
+ rootTransform.worldPosition = {4, 7, 2};
+ rootTransform.worldScale = {-2, 3, 4};
+ rootTransform.worldRotation = glm::angleAxis(.7f, glm::vec3(0, 1, 0));
+ CHECK(ecs::copyFlatRenderMatrix(registry, root, output));
+ CHECK(output == math::compose(rootTransform.worldPosition, rootTransform.worldRotation, rootTransform.worldScale));
+ CHECK(rootTransform.cachedMatrix_ == glm::mat4(1));
+}
+
TEST_CASE("sprites: tile budget applies before integer conversion") {
struct Case { glm::vec2 tile, spacing; u32 quads; };
const Case cases[] = {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index cbfdc252e..e7c844fae 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -34,6 +34,8 @@ export const NOTED = {
{ note: 'Poki training reports authored gameplay and ad outcomes.' },
'feat(editor): point Poki settings to the training example':
{ note: 'Poki training reports authored gameplay and ad outcomes.' },
+ 'fix(text): preserve full transforms in SDK label rendering':
+ { note: 'SDK text follows the full parent transform and skips collapsed labels.' },
'feat(web): connect Poki channel exports to ads services':
{ note: 'Web exports can select the Poki channel.' },
'feat(editor): expose Poki Web distribution channel':