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.

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.md
index 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) => numb
uiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefined
uiHitTest_pickResult: ((index: number) => number) | undefined
uiHitTest_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) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => numb
uiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefined
uiHitTest_pickResult: ((index: number) => number) | undefined
uiHitTest_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) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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) => numb
uiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefined
uiHitTest_pickResult: ((index: number) => number) | undefined
uiHitTest_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) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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) => numb
uiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefined
uiHitTest_pickResult: ((index: number) => number) | undefined
uiHitTest_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) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
diff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cpp
index 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.cpp
index 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, con
void 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.hpp
index 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::ecs
diff --git a/src/esengine/ecs/UITree.hpp b/src/esengine/ecs/UITree.hpp
index 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) {