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(ui): skip the UI layout solve on a fully static frame (E stage 2)
esengined08c4d01a247
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 55dcf0018..bb007ed2c 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2304,7 +2304,7 @@ uiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number) => void+uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_update: (registry: CppRegistry) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 73d530b56..a4b622e72 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2299,7 +2299,7 @@ uiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number) => void+uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_update: (registry: CppRegistry) => voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex c87806a9d..1f323d245 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -360,7 +360,7 @@ uiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number) => void+uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_update: (registry: CppRegistry) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex ff83ad860..5dfaf7c99 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2299,7 +2299,7 @@ uiHitTest_pick: ((registry: CppRegistry, worldX: number, worldY: number) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number) => void+uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_update: (registry: CppRegistry) => voiddiff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.tsindex bc39100bc..d359280df 100644--- a/sdk/src/ui/layout/layout.ts+++ b/sdk/src/ui/layout/layout.ts@@ -42,12 +42,35 @@ export class UILayoutPlugin implements Plugin {const layoutGen: UILayoutGenerationData = { generation: 0 };app.insertResource(UILayoutGeneration, layoutGen);+ // Track UINode/FlexContainer edits so an authored change is an O(1) signal+ // the C++ solve honours (skip-when-clean). Every input write goes through+ // world.set / insert / Mut-writeback, which record the change; C++ writes+ // only layout OUTPUTS, and tween-driven Transform writes are covered by the+ // engine's own anim_override_ scan — so this pair is the complete authored+ // property signal.+ world.enableChangeTracking(UINode);+ world.enableChangeTracking(FlexContainer);++ // Ticks are per-frame, and both passes run within one tick, so a change can+ // still land at the current tick after this check. Report changes strictly+ // after `solvedTick`, then only advance the watermark to the PREVIOUS tick —+ // anyChangedSince uses '>', so using the current tick would drop a same-frame+ // write. The one extra solve this costs while a change settles is negligible.+ let solvedTick = -1;+ const propertyDirty = (): boolean => {+ const dirty = world.anyChangedSince(UINode, solvedTick)+ || world.anyChangedSince(FlexContainer, solvedTick);+ solvedTick = world.getWorldTick() - 1;+ return dirty;+ };+const layoutFn = (camera: UICameraData) => {if (!camera.valid) return;module.uiLayout_update(registry,camera.worldLeft, camera.worldBottom,camera.worldRight, camera.worldTop,+ propertyDirty(),);module.transform_update(registry);layoutGen.generation++;@@ -59,6 +82,7 @@ export class UILayoutPlugin implements Plugin {registry,camera.worldLeft, camera.worldBottom,camera.worldRight, camera.worldTop,+ propertyDirty(),);layoutGen.generation++;};diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 6a97b3517..f918bcd23 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -405,7 +405,7 @@ export interface ESEngineModule {renderer_getPreviewHeight(): number;// UI Systems- uiLayout_update(registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number): void;+ uiLayout_update(registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean): void;uiHitTest_update(registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean): void;uiHitTest_getHitEntity(): number;uiHitTest_getHitEntityPrev(): number;diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.tsindex c4df57541..18543509d 100644--- a/sdk/tests/ui-components.test.ts+++ b/sdk/tests/ui-components.test.ts@@ -574,9 +574,14 @@ describe.skipIf(!HAS_WASM)('UI Components (WASM integration)', () => {expect(nodeW(registry, child)).toBeCloseTo(400, 0);- const n = registry.getUINode(child);- n.width = pct(100);- registry.addUINode(child, n);+ // Update the width through the World (the runtime mutation door): a raw+ // registry.addUINode poke bypasses change-tracking, which the layout+ // pass now consults to skip a solve on a fully static frame.+ world.insert(child, UINode, node({+ position: 1,+ insetLeft: px(0), insetTop: px(0),+ width: pct(100), height: pct(100),+ }));await app.tick(1 / 60);diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.tsindex 2441cbd5a..7783df23e 100644--- a/sdk/tests/ui-layout-integration.test.ts+++ b/sdk/tests/ui-layout-integration.test.ts@@ -11,6 +11,7 @@import { describe, it, expect, beforeAll } from 'vitest';import { App } from '../src/app';import { UINode, type UINodeData } from '../src/ui/core/ui-node';+import { FlexContainer, type FlexContainerData } from '../src/ui/layout/flex';import { Canvas } from '../src/component';import { UICameraInfo } from '../src/ui/core/ui-camera-info';import { uiLayoutPlugin } from '../src/ui/layout/layout';@@ -62,6 +63,15 @@ function makeTransform(x = 0, y = 0) {};}+/** A complete FlexContainer value-object (embind requires every member present). */+function flex(over: Partial<FlexContainerData> = {}): FlexContainerData {+ return {+ direction: 0, wrap: 0, justifyContent: 0, alignItems: 3, alignContent: 0,+ gap: { x: 0, y: 0 }, padding: { left: 0, top: 0, right: 0, bottom: 0 },+ ...over,+ } as FlexContainerData;+}+function makeSprite(w = 100, h = 100) {return {texture: 0,@@ -292,4 +302,76 @@ describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () =>disposeApp(app, registry);});++ // The skip-when-clean gate keys the solve off a structure signature + camera+ // rect + a TS-supplied property-dirty flag (UINode/FlexContainer change) + a+ // tween-activity scan. These assert the two failure modes that gate can have:+ // a bare field edit (no structural change) must still re-solve, and a clean+ // frame must leave the computed output intact.+ it('gate: a property edit with no structural change still re-solves', async () => {+ const { app, registry } = createEditorApp();+ const world = app.world;++ const root = world.spawn();+ world.insert(root, Canvas, {});+ world.insert(root, UINode, fillNode());+ world.insert(root, Transform, makeTransform());++ const child = world.spawn();+ world.setParent(child, root);+ world.insert(child, UINode, sizedNode(100, 50));+ world.insert(child, Transform, makeTransform());++ setCanvasRect(app, -400, -300, 400, 300);+ await app.tick(1 / 60);+ expect(nodeW(registry, child)).toBeCloseTo(100, 0);++ // Same entity set (identical structure signature) — only the width field+ // changes. A gate that trusted structure alone would wrongly skip here.+ // (insert is the in-place update door for a builtin the entity already has;+ // set is emplace-only for existing builtins.)+ world.insert(child, UINode, sizedNode(240, 50));+ await app.tick(1 / 60);+ expect(nodeW(registry, child)).toBeCloseTo(240, 0);++ // Nothing changed this frame → the retained output must be preserved.+ await app.tick(1 / 60);+ expect(nodeW(registry, child)).toBeCloseTo(240, 0);++ disposeApp(app, registry);+ });++ it('gate: a FlexContainer edit repositions children without a structural change', async () => {+ const { app, registry } = createEditorApp();+ const world = app.world;++ const root = world.spawn();+ world.insert(root, Canvas, {});+ world.insert(root, UINode, fillNode());+ world.insert(root, FlexContainer, flex({ direction: 1 })); // Column+ world.insert(root, Transform, makeTransform());++ const a = world.spawn();+ world.setParent(a, root);+ world.insert(a, UINode, sizedNode(100, 50));+ world.insert(a, Transform, makeTransform());++ const b = world.spawn();+ world.setParent(b, root);+ world.insert(b, UINode, sizedNode(100, 50));+ world.insert(b, Transform, makeTransform());++ setCanvasRect(app, -400, -300, 400, 300);+ await app.tick(1 / 60);+ const startY = registry.getTransform(b).position.y;++ // justify-content Start → End packs the column to the bottom: 'b' moves.+ world.insert(root, FlexContainer, flex({ direction: 1, justifyContent: 2 }));+ await app.tick(1 / 60);+ const endY = registry.getTransform(b).position.y;++ expect(Math.abs(endY - startY)).toBeGreaterThan(1);++ disposeApp(app, registry);+ });});diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex a0826d84a..624729c39 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -701,8 +701,9 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {namespace esengine {-void uiLayout_update(ecs::Registry& registry, f32 camLeft, f32 camBottom, f32 camRight, f32 camTop) {- ctx().require<ecs::UISystem>().layoutUpdate(registry, camLeft, camBottom, camRight, camTop);+void uiLayout_update(ecs::Registry& registry, f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,+ bool propertyDirty) {+ ctx().require<ecs::UISystem>().layoutUpdate(registry, camLeft, camBottom, camRight, camTop, propertyDirty);}void uiHitTest_update(ecs::Registry& registry, f32 mouseWorldX, f32 mouseWorldY,diff --git a/src/esengine/ecs/UILayoutSystem.cpp b/src/esengine/ecs/UILayoutSystem.cppindex 43a33b518..c9b14acb2 100644--- a/src/esengine/ecs/UILayoutSystem.cpp+++ b/src/esengine/ecs/UILayoutSystem.cpp@@ -334,6 +334,19 @@ void propagateHiddenInTree(Registry& registry, UITree& tree) {}}+// A tween drives Transform fields directly in C++ (TweenSystem), invisible to the+// TS change-tracking that feeds tsPropertyDirty. Scan the UINode anim_override_+// bits so the gate keeps solving while any tween is active — and, via the caller's+// lastAnimActive_, once more on the frame a tween ends (override already cleared)+// so layout reclaims the position it had ceded.+bool anyUIAnimActive(Registry& registry) {+ bool active = false;+ registry.eachLive<UINode>([&](Entity, UINode& n) {+ if (n.anim_override_ != 0) active = true;+ });+ return active;+}+void unifiedLayoutPass(Registry& registry, UITree& tree, LayoutCache& cache, const LayoutRect& cameraRect) {for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {auto& node = tree.nodes_[i];@@ -364,11 +377,36 @@ void unifiedLayoutPass(Registry& registry, UITree& tree, LayoutCache& cache, convoid UISystem::layoutUpdate(Registry& registry,- f32 camLeft, f32 camBottom, f32 camRight, f32 camTop+ f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,+ bool tsPropertyDirty) {if (!layoutCache_) layoutCache_ = std::make_unique<LayoutCache>();++ // Rebuild the DFS node list every pass: it is O(N) pointer-walking (no Yoga)+ // and yields the structure signature that detects spawn/despawn/reparent —+ // the reliable structural signal we don't otherwise have. The expensive part+ // (orphan + propagateHidden + Yoga solve + reap) is what the gate below skips.tree.rebuild(registry);+ bool animNow = anyUIAnimActive(registry);+ bool sigChanged = tree.structure_sig_ != lastSig_;+ bool rectChanged = camLeft != lastCamL_ || camBottom != lastCamB_+ || camRight != lastCamR_ || camTop != lastCamT_;+ bool wasAnimActive = lastAnimActive_;++ lastSig_ = tree.structure_sig_;+ lastCamL_ = camLeft; lastCamB_ = camBottom; lastCamR_ = camRight; lastCamT_ = camTop;+ lastAnimActive_ = animNow;++ // A fully static frame — no structural, camera, property, or tween change since+ // the last solve — leaves the retained YGNodes and every UINode's computed+ // output valid, so the whole solve is safely skipped. `wasAnimActive` forces+ // one more solve on the frame a tween just ended (see anyUIAnimActive).+ bool dirty = !layoutPrimed_ || sigChanged || rectChanged || tsPropertyDirty+ || animNow || wasAnimActive;+ layoutPrimed_ = true;+ if (!dirty) return;+// Orphan the entire retained forest up front. Each subtree then rebuilds its// own hierarchy from childless nodes, so an entity that moved between Canvas// roots since last frame is never still owned by its old parent on re-insert.diff --git a/src/esengine/ecs/UISystem.hpp b/src/esengine/ecs/UISystem.hppindex d6734240d..3088a374c 100644--- a/src/esengine/ecs/UISystem.hpp+++ b/src/esengine/ecs/UISystem.hpp@@ -64,9 +64,14 @@ public:// ---- Layout pass (defined in UILayoutSystem.cpp) ----- /** @brief Rebuild layout tree and apply layout to all dirty nodes */+ /** @brief Rebuild layout tree and apply layout to all dirty nodes.+ * @param tsPropertyDirty Set by the TS driver when any UINode/FlexContainer+ * changed since the last pass (via change-tracking). Combined with the+ * C++-detected structure/camera/animation signals to skip the whole+ * rebuild+solve on a fully static frame. */void layoutUpdate(Registry& registry,- f32 camLeft, f32 camBottom, f32 camRight, f32 camTop);+ f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,+ bool tsPropertyDirty);/** @brief Mark the tree structure as dirty (forces full rebuild next update) */void treeMarkStructureDirty();@@ -102,6 +107,14 @@ public:private:std::vector<Entity> pickResults_;++ // ---- Layout skip-when-clean gate (see layoutUpdate) ----+ // Snapshot of the last solved frame; a pass whose inputs match all of these+ // (and no tween activity) reuses the retained YGNodes and computed output.+ u64 lastSig_{0};+ f32 lastCamL_{0}, lastCamB_{0}, lastCamR_{0}, lastCamT_{0};+ bool lastAnimActive_{false};+ bool layoutPrimed_{false}; // force a solve on the very first pass};} // namespace esengine::ecsdiff --git a/src/esengine/ecs/UITree.hpp b/src/esengine/ecs/UITree.hppindex 8bae55ac4..7bf9a5888 100644--- a/src/esengine/ecs/UITree.hpp+++ b/src/esengine/ecs/UITree.hpp@@ -26,6 +26,11 @@ struct UITree {std::vector<Node> nodes_;bool structure_dirty_{true};+ // FNV-1a hash of the (entity, parent) pairs in DFS order — a compact+ // fingerprint of the tree's shape. It changes on any spawn/despawn/reparent,+ // sibling reorder, or UINode/Canvas add-remove, so the layout gate can detect+ // structural change without a reliable per-write dirty producer.+ u64 structure_sig_{0};void rebuild(Registry& reg) {nodes_.clear();@@ -34,6 +39,13 @@ struct UITree {buildDFS(reg, entity, INVALID_ENTITY, 0);});structure_dirty_ = false;++ u64 h = 1469598103934665603ULL; // FNV-1a offset basis+ for (const auto& n : nodes_) {+ h = (h ^ n.entity.id()) * 1099511628211ULL;+ h = (h ^ n.parent.id()) * 1099511628211ULL;+ }+ structure_sig_ = h;}void rebuildIfDirty(Registry& reg) {