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): preserve full transforms in SDK label rendering
yhh2e5f0644e61c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex 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) | undefinedtrail_update: ((registry: CppRegistry, dt: number) => void) | undefinedtransform_compositionChanges: (() => { serial: number; tracking: boolean; overflowed: boolean; count: number; visited: number; ptr: number; }) | undefined+transform_copyFlatRenderMatrix: ((registry: CppRegistry, entity: number, outputPtr: number) => boolean) | undefinedtransform_ensureComposed: ((registry: CppRegistry) => void) | undefinedtransform_epochAddress: (() => number) | undefinedtransform_setChangeTracking: ((on: boolean) => void) | undefineddiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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/helpersimport { 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.tsindex 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) APIanim_createTween(registry: CppRegistry, entity: number, targetProp: number,diff --git a/sdk/tests/native-text.test.ts b/sdk/tests/native-text.test.tsindex 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.cppindex 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.hppindex 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 esenginediff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 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.hppindex 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::ecsdiff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex 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.mjsindex 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':