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.

feat(ui): single-pass Yoga layout for UINode + render, pixel-verified (REARCH_GUI F3.2)

esenginef3fcd1a7248b
diff --git a/desktop/package.json b/desktop/package.json
index 4f7748df2..86af336f5 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -18,6 +18,7 @@
"verify:render:postprocess": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/postprocess-effects.esscene ESTELLA_VERIFY_MANIFEST=/scenes/postprocess-effects.textures.json ESTELLA_VERIFY_STEPS=30 electron scripts/headless-verify.mjs",
"verify:render:text": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-sdf.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs",
"verify:render:text:rect": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-rect.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs",
+ "verify:render:uinode": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-node-flex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-node-flex.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 electron scripts/headless-verify.mjs",
"verify:smoke": "vite build && electron scripts/headless-smoke.mjs",
"mcp": "electron electron/mcp/server.mjs",
"mcp:smoke": "vite build && node electron/mcp/smoke.mjs"
diff --git a/desktop/public/scenes/ui-node-flex.esscene b/desktop/public/scenes/ui-node-flex.esscene
new file mode 100644
index 000000000..8e4913739
--- /dev/null
+++ b/desktop/public/scenes/ui-node-flex.esscene
@@ -0,0 +1,78 @@
+{
+ "version": "1.0",
+ "name": "UINode single-pass flex layout (REARCH_GUI F3.2)",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [2],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
+ { "type": "UIRect", "data": { "anchorMin": { "x": 0.5, "y": 0.5 }, "anchorMax": { "x": 0.5, "y": 0.5 }, "size": { "x": 800, "y": 600 }, "pivot": { "x": 0.5, "y": 0.5 } } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Row",
+ "parent": 1,
+ "children": [3, 4, 5],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "width": { "value": 600, "unit": 0 }, "height": { "value": 200, "unit": 0 } } },
+ { "type": "FlexContainer", "data": { "direction": 0, "justifyContent": 1, "alignItems": 1, "gap": { "x": 20, "y": 0 } } },
+ { "type": "UIRenderer", "data": { "visualType": 1, "color": { "r": 0.15, "g": 0.15, "b": 0.18, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "BoxA",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "width": { "value": 120, "unit": 0 }, "height": { "value": 120, "unit": 0 } } },
+ { "type": "UIRenderer", "data": { "visualType": 1, "color": { "r": 0.85, "g": 0.25, "b": 0.25, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "BoxB",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "width": { "value": 120, "unit": 0 }, "height": { "value": 160, "unit": 0 } } },
+ { "type": "UIRenderer", "data": { "visualType": 1, "color": { "r": 0.25, "g": 0.8, "b": 0.35, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "BoxC",
+ "parent": 2,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "width": { "value": 120, "unit": 0 }, "height": { "value": 80, "unit": 0 } } },
+ { "type": "UIRenderer", "data": { "visualType": 1, "color": { "r": 0.3, "g": 0.45, "b": 0.9, "a": 1 }, "enabled": true } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/ui-node-flex.textures.json b/desktop/public/scenes/ui-node-flex.textures.json
new file mode 100644
index 000000000..9e26dfeeb
--- /dev/null
+++ b/desktop/public/scenes/ui-node-flex.textures.json
@@ -0,0 +1 @@
+{}
\ No newline at end of file
diff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.ts
index f561de0b1..de111b387 100644
--- a/sdk/src/ui/layout/layout.ts
+++ b/sdk/src/ui/layout/layout.ts
@@ -19,7 +19,10 @@ import { defineSystem, Schedule } from '../../system';
import { SystemLabel } from '../../systemLabels';
import { Res } from '../../resource';
import { UIRect } from '../core/ui-rect';
+import { UINode } from '../core/ui-node';
import { UIRenderer } from '../core/ui-renderer';
+import { FlexContainer, FlexItem } from './flex';
+import { GridLayout } from './grid';
import { UICameraInfo } from '../UICameraInfo';
import type { UICameraData } from '../UICameraInfo';
import { UILayoutGeneration } from '../UILayoutGeneration';
@@ -33,7 +36,11 @@ export class UILayoutPlugin implements Plugin {
build(app: App): void {
registerComponent('UIRect', UIRect);
+ registerComponent('UINode', UINode);
registerComponent('UIRenderer', UIRenderer);
+ registerComponent('FlexContainer', FlexContainer);
+ registerComponent('FlexItem', FlexItem);
+ registerComponent('GridLayout', GridLayout);
const world = app.world;
const module = app.wasmModule as ESEngineModule;
diff --git a/src/esengine/ecs/UILayoutSystem.cpp b/src/esengine/ecs/UILayoutSystem.cpp
index 9b67c75a4..d7dbaf1bc 100644
--- a/src/esengine/ecs/UILayoutSystem.cpp
+++ b/src/esengine/ecs/UILayoutSystem.cpp
@@ -9,10 +9,12 @@
#include "components/FlexContainer.hpp"
#include "components/FlexItem.hpp"
#include "components/GridLayout.hpp"
+#include "components/UINode.hpp"
#include <yoga/Yoga.h>
#include <algorithm>
#include <cmath>
+#include <unordered_map>
#include <vector>
namespace esengine::ecs {
@@ -378,6 +380,164 @@ void resolveGridLayoutChildren(
}
}
+// =============================================================================
+// UINode (CSS box) → single-pass Yoga (REARCH_GUI F3)
+// =============================================================================
+//
+// A UINode subtree is laid out by ONE Yoga solve (unlike the legacy per-flex-
+// container ephemeral trees): each entity becomes a YGNode, the hierarchy is
+// mirrored, the root is sized to its parent's box, and one YGNodeCalculateLayout
+// resolves the whole subtree. Output is written as the engine's center-based,
+// y-up local Transform (implicit pivot 0.5, matching UIElementPlugin) plus
+// UINode.computed_size_ (read by the renderer/hit-test).
+
+// Dimension.unit codes — mirror the TS DimensionUnit enum.
+constexpr u8 DIM_PX = 0, DIM_PERCENT = 1, DIM_AUTO = 2;
+
+void applyWidth(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetWidthPercent(n, d.value);
+ else if (d.unit == DIM_AUTO) YGNodeStyleSetWidthAuto(n);
+ else YGNodeStyleSetWidth(n, d.value);
+}
+void applyHeight(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetHeightPercent(n, d.value);
+ else if (d.unit == DIM_AUTO) YGNodeStyleSetHeightAuto(n);
+ else YGNodeStyleSetHeight(n, d.value);
+}
+// min/max have no Yoga "auto"; Auto means "no constraint" → leave unset.
+void applyMinWidth(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetMinWidthPercent(n, d.value);
+ else if (d.unit == DIM_PX) YGNodeStyleSetMinWidth(n, d.value);
+}
+void applyMinHeight(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetMinHeightPercent(n, d.value);
+ else if (d.unit == DIM_PX) YGNodeStyleSetMinHeight(n, d.value);
+}
+void applyMaxWidth(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetMaxWidthPercent(n, d.value);
+ else if (d.unit == DIM_PX) YGNodeStyleSetMaxWidth(n, d.value);
+}
+void applyMaxHeight(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetMaxHeightPercent(n, d.value);
+ else if (d.unit == DIM_PX) YGNodeStyleSetMaxHeight(n, d.value);
+}
+void applyFlexBasis(YGNodeRef n, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetFlexBasisPercent(n, d.value);
+ else if (d.unit == DIM_AUTO) YGNodeStyleSetFlexBasisAuto(n);
+ else YGNodeStyleSetFlexBasis(n, d.value);
+}
+void applyMargin(YGNodeRef n, YGEdge edge, const Dimension& d) {
+ if (d.unit == DIM_PERCENT) YGNodeStyleSetMarginPercent(n, edge, d.value);
+ else if (d.unit == DIM_AUTO) YGNodeStyleSetMarginAuto(n, edge);
+ else YGNodeStyleSetMargin(n, edge, d.value);
+}
+
+void applyUINodeStyle(Registry& registry, Entity entity, YGNodeRef yg) {
+ auto& n = registry.get<UINode>(entity);
+ applyWidth(yg, n.width);
+ applyHeight(yg, n.height);
+ applyMinWidth(yg, n.minWidth);
+ applyMinHeight(yg, n.minHeight);
+ applyMaxWidth(yg, n.maxWidth);
+ applyMaxHeight(yg, n.maxHeight);
+ YGNodeStyleSetFlexGrow(yg, n.flexGrow);
+ YGNodeStyleSetFlexShrink(yg, n.flexShrink);
+ applyFlexBasis(yg, n.flexBasis);
+ YGNodeStyleSetAlignSelf(yg, toYGAlignSelf(n.alignSelf));
+ applyMargin(yg, YGEdgeLeft, n.marginLeft);
+ applyMargin(yg, YGEdgeTop, n.marginTop);
+ applyMargin(yg, YGEdgeRight, n.marginRight);
+ applyMargin(yg, YGEdgeBottom, n.marginBottom);
+
+ // Container properties still come from FlexContainer (folded into UILayout in F4).
+ if (auto* fc = registry.tryGet<FlexContainer>(entity)) {
+ YGNodeStyleSetFlexDirection(yg, toYGFlexDirection(fc->direction));
+ YGNodeStyleSetFlexWrap(yg, toYGWrap(fc->wrap));
+ YGNodeStyleSetJustifyContent(yg, toYGJustify(fc->justifyContent));
+ YGNodeStyleSetAlignItems(yg, toYGAlign(fc->alignItems));
+ YGNodeStyleSetAlignContent(yg, toYGAlignContent(fc->alignContent));
+ YGNodeStyleSetGap(yg, YGGutterColumn, fc->gap.x);
+ YGNodeStyleSetGap(yg, YGGutterRow, fc->gap.y);
+ YGNodeStyleSetPadding(yg, YGEdgeLeft, fc->padding.left);
+ YGNodeStyleSetPadding(yg, YGEdgeTop, fc->padding.top);
+ YGNodeStyleSetPadding(yg, YGEdgeRight, fc->padding.right);
+ YGNodeStyleSetPadding(yg, YGEdgeBottom, fc->padding.bottom);
+ }
+}
+
+// Lay out the UINode subtree rooted at tree index `rootIdx` in one Yoga solve.
+// `availW/H` + `parentPivot*` describe the parent box the root is positioned in.
+void layoutUINodeSubtree(
+ Registry& registry, UITree& tree, i32 rootIdx,
+ f32 availW, f32 availH, f32 parentPivotX, f32 parentPivotY
+) {
+ i32 begin = rootIdx;
+ i32 end = rootIdx + tree.nodes_[rootIdx].subtree_size;
+
+ std::vector<YGNodeRef> yg(static_cast<usize>(end - begin), nullptr);
+ std::unordered_map<Entity, i32> slotOf; // entity → local slot index
+ for (i32 k = begin; k < end; ++k) {
+ Entity e = tree.nodes_[k].entity;
+ if (!registry.has<UINode>(e)) continue; // subtrees are homogeneously UINode
+ YGNodeRef node = YGNodeNew();
+ applyUINodeStyle(registry, e, node);
+ yg[static_cast<usize>(k - begin)] = node;
+ slotOf[e] = k - begin;
+ }
+ YGNodeRef rootYG = yg[0];
+ if (!rootYG) return;
+
+ for (i32 k = begin + 1; k < end; ++k) {
+ YGNodeRef child = yg[static_cast<usize>(k - begin)];
+ if (!child) continue;
+ auto it = slotOf.find(tree.nodes_[k].parent);
+ if (it == slotOf.end()) continue;
+ YGNodeRef parentYG = yg[static_cast<usize>(it->second)];
+ YGNodeInsertChild(parentYG, child, YGNodeGetChildCount(parentYG));
+ }
+
+ // The root fills the available box on axes it leaves auto.
+ auto& rootNode = registry.get<UINode>(tree.nodes_[begin].entity);
+ if (rootNode.width.unit == DIM_AUTO) YGNodeStyleSetWidth(rootYG, availW);
+ if (rootNode.height.unit == DIM_AUTO) YGNodeStyleSetHeight(rootYG, availH);
+
+ YGNodeCalculateLayout(rootYG, availW, availH, YGDirectionLTR);
+
+ for (i32 k = begin; k < end; ++k) {
+ YGNodeRef node = yg[static_cast<usize>(k - begin)];
+ if (!node) continue;
+ Entity e = tree.nodes_[k].entity;
+ auto& un = registry.get<UINode>(e);
+ f32 fw = YGNodeLayoutGetWidth(node);
+ f32 fh = YGNodeLayoutGetHeight(node);
+ un.computed_size_.x = fw;
+ un.computed_size_.y = fh;
+
+ // Position frame = parent box (the root's parent box, else the parent
+ // UINode whose computed_size_ is already set — DFS order guarantees it).
+ f32 pw, ph, ppx, ppy;
+ if (k == begin) {
+ pw = availW; ph = availH; ppx = parentPivotX; ppy = parentPivotY;
+ } else {
+ auto& pn = registry.get<UINode>(tree.nodes_[k].parent);
+ pw = pn.computed_size_.x; ph = pn.computed_size_.y; ppx = 0.5f; ppy = 0.5f;
+ }
+ f32 yl = YGNodeLayoutGetLeft(node);
+ f32 yt = YGNodeLayoutGetTop(node);
+ // Center-based, y-up local position (implicit pivot 0.5).
+ f32 localX = -ppx * pw + yl + 0.5f * fw;
+ f32 localY = (1.0f - ppy) * ph - yt - 0.5f * fh;
+
+ if (auto* t = registry.tryGet<Transform>(e)) {
+ t->position.x = localX;
+ t->position.y = localY;
+ }
+ tree.nodes_[k].flags &= ~(LAYOUT_DIRTY | HAS_DIRTY_CHILD);
+ }
+
+ YGNodeFreeRecursive(rootYG);
+}
+
void unifiedLayoutPass(Registry& registry, UITree& tree, const LayoutRect& cameraRect) {
for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {
auto& node = tree.nodes_[i];
@@ -387,6 +547,28 @@ void unifiedLayoutPass(Registry& registry, UITree& tree, const LayoutRect& camer
continue;
}
+ // UINode subtree (CSS box, REARCH_GUI F3): one Yoga solve at the subtree
+ // root resolves the whole subtree, so skip past it afterward. The legacy
+ // UIRect/anchor path below is untouched.
+ if (registry.has<UINode>(node.entity)) {
+ bool parentIsUINode = node.parent != INVALID_ENTITY && registry.has<UINode>(node.parent);
+ if (!parentIsUINode) {
+ f32 availW, availH, ppx, ppy;
+ if (node.parent != INVALID_ENTITY && registry.has<UIRect>(node.parent)) {
+ auto& pr = registry.get<UIRect>(node.parent);
+ availW = pr.computed_size_.x; availH = pr.computed_size_.y;
+ ppx = pr.pivot.x; ppy = pr.pivot.y;
+ } else {
+ availW = cameraRect.right - cameraRect.left;
+ availH = cameraRect.top - cameraRect.bottom;
+ ppx = 0.5f; ppy = 0.5f;
+ }
+ layoutUINodeSubtree(registry, tree, i, availW, availH, ppx, ppy);
+ }
+ i += node.subtree_size;
+ continue;
+ }
+
if (node.flags & LAYOUT_DIRTY) {
bool parentManaged = node.parent != INVALID_ENTITY && (
registry.has<FlexContainer>(node.parent) ||
diff --git a/src/esengine/ecs/UITree.hpp b/src/esengine/ecs/UITree.hpp
index f27675524..8c9db6d3c 100644
--- a/src/esengine/ecs/UITree.hpp
+++ b/src/esengine/ecs/UITree.hpp
@@ -5,6 +5,7 @@
#include "Registry.hpp"
#include "components/Hierarchy.hpp"
#include "components/UIRect.hpp"
+#include "components/UINode.hpp"
#include "components/Canvas.hpp"
#include "components/Transform.hpp"
@@ -79,10 +80,12 @@ struct UITree {
private:
void buildDFS(Registry& reg, Entity entity, Entity layoutParent, u16 depth) {
- bool hasUIRect = reg.has<UIRect>(entity);
+ // A layout node is anything the layout pass positions: the legacy UIRect
+ // (anchor model) or the modern UINode (CSS box, REARCH_GUI F3).
+ bool isLayoutNode = reg.has<UIRect>(entity) || reg.has<UINode>(entity);
i32 nodeIndex = -1;
- if (hasUIRect) {
+ if (isLayoutNode) {
nodeIndex = static_cast<i32>(nodes_.size());
nodes_.push_back({entity, layoutParent, depth, 1, LAYOUT_DIRTY});
layoutParent = entity;
@@ -98,7 +101,7 @@ private:
}
}
- if (hasUIRect && nodeIndex >= 0) {
+ if (isLayoutNode && nodeIndex >= 0) {
nodes_[nodeIndex].subtree_size = static_cast<u16>(nodes_.size() - nodeIndex);
}
}
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cpp
index 7cf4fd574..9418919fa 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp
@@ -7,6 +7,7 @@
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/UIRenderer.hpp"
#include "../../ecs/components/UIRect.hpp"
+#include "../../ecs/components/UINode.hpp"
#include <cmath>
@@ -19,27 +20,36 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
auto& buffers = collect_ctx.buffer_pool;
auto& draw_list = collect_ctx.draw_list;
auto& ctx = collect_ctx.frame_context;
- auto uiView = registry.view<ecs::Transform, ecs::UIRenderer, ecs::UIRect>();
+ auto uiView = registry.view<ecs::Transform, ecs::UIRenderer>();
for (auto entity : uiView) {
const auto& renderer = uiView.get<ecs::UIRenderer>(entity);
if (!renderer.enabled || renderer.visualType == ecs::UIVisualType::None) continue;
+ // Geometry source: the legacy UIRect (anchor, explicit pivot) or the
+ // modern UINode (CSS box, REARCH_GUI F3 — always pivot-centered).
+ f32 w, h, pivotX, pivotY;
+ if (const auto* rect = registry.tryGet<ecs::UIRect>(entity)) {
+ w = rect->computed_size_.x; h = rect->computed_size_.y;
+ pivotX = rect->pivot.x; pivotY = rect->pivot.y;
+ } else if (const auto* node = registry.tryGet<ecs::UINode>(entity)) {
+ w = node->computed_size_.x; h = node->computed_size_.y;
+ pivotX = 0.5f; pivotY = 0.5f;
+ } else {
+ continue;
+ }
+ if (w <= 0.0f && h <= 0.0f) continue;
+
auto& transform = uiView.get<ecs::Transform>(entity);
transform.ensureDecomposed();
- const auto& rect = uiView.get<ecs::UIRect>(entity);
glm::vec3 position = transform.worldPosition;
const auto& rotation = transform.worldRotation;
const auto& scale = transform.worldScale;
- f32 w = rect.computed_size_.x;
- f32 h = rect.computed_size_.y;
- if (w <= 0.0f && h <= 0.0f) continue;
-
// UI bakes the pivot into the world position here, so the quad is emitted centered.
- f32 dx = (0.5f - rect.pivot.x) * w * scale.x;
- f32 dy = (0.5f - rect.pivot.y) * h * scale.y;
+ f32 dx = (0.5f - pivotX) * w * scale.x;
+ f32 dy = (0.5f - pivotY) * h * scale.y;
f32 sinHalf = rotation.z;
if (sinHalf * sinHalf > 1e-6f) {
f32 cosHalf = rotation.w;
@@ -92,7 +102,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {
}
}
- glm::vec2 finalSize = rect.computed_size_ * glm::vec2(scale);
+ glm::vec2 finalSize = glm::vec2(w, h) * glm::vec2(scale);
BatchDrawKey key{
.stage = ctx.current_stage,