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
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.jsonindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 000000000..9e26dfeeb--- /dev/null+++ b/desktop/public/scenes/ui-node-flex.textures.json@@ -0,0 +1 @@+{}\ No newline at end of filediff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.tsindex 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.cppindex 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& camercontinue;}+ // 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.hppindex 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.cppindex 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,