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): the layout box has a place, not just a size

yhhc2ecacff1614
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 36531f21b..a529f55c4 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -327,6 +327,19 @@ jobs:
ESTELLA_VERIFY_MANIFEST=/scenes/ui-list-mask.textures.json \
ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 \
'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[255,0,0],"tol":60},{"x":0.9,"y":0.5,"rgb":[0,0,255],"tol":60},{"x":0.5,"y":0.85,"rgb":[0,0,255],"tol":60},{"x":0.5,"y":0.15,"rgb":[0,0,255],"tol":60}]'
+ # Where the UI layout box SITS. The camera is driven away from the origin
+ # at runtime, so the box moves without resizing: the unparented Canvas
+ # (a screen root) must travel with it — red/green stay in their quadrants —
+ # while the Canvas parented to a world entity must not, landing blue at the
+ # anchor's own world position. Before screen roots existed the whole HUD
+ # stayed at the origin and this frame came back black.
+ run_scene ui-screen-root \
+ ESTELLA_VERIFY_PLAY=1 \
+ ESTELLA_VERIFY_SCENE=/scenes/ui-screen-root.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/ui-screen-root.textures.json \
+ ESTELLA_VERIFY_W=640 ESTELLA_VERIFY_H=360 ESTELLA_VERIFY_STEPS=4 \
+ 'ESTELLA_VERIFY_MOVE={"component":"Camera","to":[5000,-800],"steps":4}' \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.25,"y":0.25,"rgb":[255,0,0],"tol":30},{"x":0.75,"y":0.75,"rgb":[0,255,0],"tol":30},{"x":0.75,"y":0.25,"rgb":[0,0,255],"tol":30},{"x":0.25,"y":0.75,"rgb":[0,0,0],"tol":30}]'
# Y-sort: same scene twice — mask on flips the overlap to the lower
# (higher-Y-key) entity; mask off preserves submission order. Both
# asserted so neither path can silently regress.
diff --git a/desktop/package.json b/desktop/package.json
index 229351755..3fe7263ab 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -32,6 +32,7 @@
"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:render:ui:screenroot": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/ui-screen-root.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-screen-root.textures.json ESTELLA_VERIFY_W=640 ESTELLA_VERIFY_H=360 ESTELLA_VERIFY_STEPS=4 ESTELLA_VERIFY_MOVE='{\"component\":\"Camera\",\"to\":[5000,-800],\"steps\":4}' ESTELLA_VERIFY_EXPECT='[{\"x\":0.25,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.75,\"y\":0.75,\"rgb\":[0,255,0],\"tol\":30},{\"x\":0.75,\"y\":0.25,\"rgb\":[0,0,255],\"tol\":30},{\"x\":0.25,\"y\":0.75,\"rgb\":[0,0,0],\"tol\":30}]' electron scripts/headless-verify.mjs",
"verify:render:uimask": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-list-mask.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-list-mask.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":60},{\\\"x\\\":0.9,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60},{\\\"x\\\":0.5,\\\"y\\\":0.85,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60},{\\\"x\\\":0.5,\\\"y\\\":0.15,\\\"rgb\\\":[0,0,255],\\\"tol\\\":60}]\" electron scripts/headless-verify.mjs",
"verify:render:filled": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-visual-filled.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-visual-filled.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.18,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.40,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40},{\\\"x\\\":0.58,\\\"y\\\":0.75,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.58,\\\"y\\\":0.25,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40},{\\\"x\\\":0.30,\\\"y\\\":0.20,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.20,\\\"y\\\":0.333,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40},{\\\"x\\\":0.30,\\\"y\\\":0.833,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40},{\\\"x\\\":0.20,\\\"y\\\":0.70,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
diff --git a/desktop/public/scenes/ui-screen-root.esscene b/desktop/public/scenes/ui-screen-root.esscene
new file mode 100644
index 000000000..16ac7e1a6
--- /dev/null
+++ b/desktop/public/scenes/ui-screen-root.esscene
@@ -0,0 +1,258 @@
+{
+ "version": "1.0",
+ "name": "Screen root tracks the camera; parented UI rides its parent. The camera starts at the origin and is driven away at runtime, so the layout box moves without resizing.",
+ "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": 540,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [
+ 2,
+ 3
+ ],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 1920,
+ "y": 1080
+ },
+ "scaleMode": 1
+ }
+ },
+ {
+ "type": "UINode",
+ "data": {}
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "TopLeftQuadrant",
+ "parent": 1,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetTop": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetLeft": {
+ "value": 0,
+ "unit": 0
+ },
+ "width": {
+ "value": 50,
+ "unit": 1
+ },
+ "height": {
+ "value": 50,
+ "unit": 1
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "BottomRightQuadrant",
+ "parent": 1,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetBottom": {
+ "value": 0,
+ "unit": 0
+ },
+ "insetRight": {
+ "value": 0,
+ "unit": 0
+ },
+ "width": {
+ "value": 50,
+ "unit": 1
+ },
+ "height": {
+ "value": 50,
+ "unit": 1
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 4,
+ "name": "WorldAnchor",
+ "parent": null,
+ "children": [
+ 5
+ ],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 5480,
+ "y": -530,
+ "z": 0
+ }
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 5,
+ "name": "WorldCanvas",
+ "parent": 4,
+ "children": [
+ 6
+ ],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Canvas",
+ "data": {
+ "designResolution": {
+ "x": 1920,
+ "y": 1080
+ },
+ "scaleMode": 1
+ }
+ },
+ {
+ "type": "UINode",
+ "data": {}
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 6,
+ "name": "WorldBadge",
+ "parent": 5,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "insetLeft": {
+ "value": 860,
+ "unit": 0
+ },
+ "insetTop": {
+ "value": 440,
+ "unit": 0
+ },
+ "width": {
+ "value": 200,
+ "unit": 0
+ },
+ "height": {
+ "value": 200,
+ "unit": 0
+ }
+ }
+ },
+ {
+ "type": "UIVisual",
+ "data": {
+ "visualType": 1,
+ "color": {
+ "r": 0,
+ "g": 0,
+ "b": 1,
+ "a": 1
+ },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/ui-screen-root.textures.json b/desktop/public/scenes/ui-screen-root.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/ui-screen-root.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/scripts/editor-checks/ui-world-anchor.mjs b/desktop/scripts/editor-checks/ui-world-anchor.mjs
new file mode 100644
index 000000000..2130295cf
--- /dev/null
+++ b/desktop/scripts/editor-checks/ui-world-anchor.mjs
@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui-world-anchor — in the editor, UI is content in the world, not a decal
+ * on the viewport.
+ *
+ * The UI layout box has a place as well as a size. In play that place is the
+ * camera, so a HUD travels with it. In the editor there is no game camera, and
+ * taking the place from the navigation view instead pins UI to the middle of the
+ * panel: pan away and the UI slides along, leaving the design-frame overlay —
+ * which is drawn at a fixed world spot — behind. Two things claiming to be the
+ * same screen, drawn in different places.
+ *
+ * So: put UI and a sprite at the same world spot, frame something far away, and
+ * require that they went out of view together.
+ */
+import path from 'node:path';
+import { cp } from 'node:fs/promises';
+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';
+
+const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');
+
+// A red UI badge centred in the design box, a green sprite beside it at the same
+// depth, and a blue sprite far off to the right to pan to.
+const SCENE = JSON.stringify({
+ version: '1.0', name: 'Main',
+ entities: [
+ {
+ id: 0, name: 'Camera', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },
+ { type: 'Camera', data: { projectionType: 1, orthoSize: 540, isActive: true, priority: 0 } },
+ ],
+ },
+ {
+ id: 1, name: 'Canvas', parent: null, children: [2], visible: true,
+ components: [
+ { type: 'Transform', data: {} },
+ { type: 'Canvas', data: { designResolution: { x: 1920, y: 1080 }, scaleMode: 1 } },
+ { type: 'UINode', data: {} },
+ ],
+ },
+ {
+ id: 2, name: 'Badge', parent: 1, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: {} },
+ {
+ type: 'UINode',
+ data: {
+ position: 1,
+ insetLeft: { value: 810, unit: 0 },
+ insetTop: { value: 390, unit: 0 },
+ width: { value: 300, unit: 0 },
+ height: { value: 300, unit: 0 },
+ },
+ },
+ { type: 'UIVisual', data: { visualType: 1, color: { r: 1, g: 0, b: 0, a: 1 }, enabled: true } },
+ ],
+ },
+ {
+ id: 3, name: 'FarAway', parent: null, children: [], visible: true,
+ components: [
+ { type: 'Transform', data: { position: { x: 12000, y: 0, z: 0 } } },
+ { type: 'Sprite', data: { size: { x: 400, y: 400 }, color: { r: 0, g: 0, b: 1, a: 1 } } },
+ ],
+ },
+ ],
+}, null, 1);
+
+export const name = 'ui-world-anchor';
+export const describes = 'editor UI stays where it is in the world when the view pans away';
+
+/** How many pixels match `want`. */
+function count(png, want, tol = 60) {
+ let n = 0;
+ for (let y = 0; y < png.h; y++) {
+ for (let x = 0; x < png.w; x++) {
+ const p = png.px(x, y);
+ if (Math.abs(p[0] - want[0]) <= tol && Math.abs(p[1] - want[1]) <= tol && Math.abs(p[2] - want[2]) <= tol) n++;
+ }
+ }
+ return n;
+}
+
+export async function run(ed) {
+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });
+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));
+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });
+ const check = checker();
+
+ await ed.open(root, 'assets/scenes/main.esscene');
+ await ed.sleep(1200);
+
+ const before = await ed.capture('ui-world-anchor-before');
+ const badgeBefore = count(before, [255, 0, 0]);
+ if (!check(badgeBefore > 200, `the UI badge is not on screen to begin with (${badgeBefore} px)`)) {
+ return check.failures;
+ }
+
+ // Frame the far-away sprite: the navigation view leaves the origin entirely.
+ const tree = await ed.json('get_scene_tree', {}, 30000);
+ const target = tree.find((e) => e.name === 'FarAway')?.id;
+ if (!check(target != null, 'the scene tree does not report the FarAway sprite')) return check.failures;
+
+ await ed.call('select', { id: target }, 20000);
+ await ed.call('run_editor_command', { id: 'view.frameSelected' }, 20000);
+ await ed.sleep(900);
+
+ const after = await ed.capture('ui-world-anchor-after');
+ const badgeAfter = count(after, [255, 0, 0]);
+
+ check(
+ badgeAfter < badgeBefore / 8,
+ `the UI badge is still filling ${badgeAfter} px after the view panned 12000 units away `
+ + `(was ${badgeBefore}) — UI is being laid out around the navigation view instead of at its `
+ + 'place in the world, so it slides with every pan and leaves the design frame behind',
+ );
+ // The pan really did happen: the sprite it framed is what is on screen now.
+ check(count(after, [0, 0, 255]) > 200, 'framing the far sprite did not bring it into view — the pan never happened');
+ return check.failures;
+}
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index bef0df66d..c4eb7813a 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -12,7 +12,7 @@ import {
tileCellCenter, tileCellOutline, isNonOrthogonal,
readColliderShapes, colliderShapeOutline, shapeCenter,
layerOrderOf,
- editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight,
+ editorViewHalfHeight, editorViewHalfExtent, setEditorViewHalfHeight, EDITOR_UI_ANCHOR,
type TilesetModel, type TileCollisionPiece, type TileGridParams,
} from 'esengine';
import type { EntityId } from '@/types';
@@ -804,7 +804,11 @@ export const ViewportController = {
/**
* The scene's Canvas singleton — the design-resolution preview source — or null.
* Reads the first entity carrying a Canvas (the same singleton-per-scene assumption
- * as the runtime's registry_getCanvasEntity), centered on its Transform.
+ * as the runtime's registry_getCanvasEntity).
+ *
+ * Centered on EDITOR_UI_ANCHOR, not on the Canvas entity's Transform: that transform
+ * is an OUTPUT of the layout pass (a screen root is placed at the box center), so
+ * reading it back would let the frame drift from the box it is drawn to describe.
*/
canvasInfo(): EditorScreenInfo | null {
const world = EngineHost.world;
@@ -818,10 +822,9 @@ export const ViewportController = {
matchWidthOrHeight: number;
backgroundColor: { r: number; g: number; b: number; a: number };
};
- const t = world.has(e, Transform) ? world.get(e, Transform) : null;
return {
- cx: t?.worldPosition.x ?? 0,
- cy: t?.worldPosition.y ?? 0,
+ cx: EDITOR_UI_ANCHOR.x,
+ cy: EDITOR_UI_ANCHOR.y,
designResolution: c.designResolution,
pixelsPerUnit: c.pixelsPerUnit || 100,
scaleMode: c.scaleMode,
@@ -841,6 +844,10 @@ export const ViewportController = {
*
* Without a Canvas the fit uses FixedHeight (the engine's Canvas default) so the
* device frame has a defined shape; once a project camera-fit is set it drives this.
+ *
+ * This resolves the fit in the same order the runtime does (CameraPlugin's
+ * resolveFitSource: project fit, else Canvas), so the drawn frame is the box the
+ * engine actually lays UI out in.
*/
screenInfo(): EditorScreenInfo {
const canvas = this.canvasInfo();
@@ -850,8 +857,8 @@ export const ViewportController = {
if (fit.scaleMode >= 0) {
const d = projectDesignSeed();
return {
- cx: canvas?.cx ?? 0,
- cy: canvas?.cy ?? 0,
+ cx: EDITOR_UI_ANCHOR.x,
+ cy: EDITOR_UI_ANCHOR.y,
designResolution: { x: d.width, y: d.height },
pixelsPerUnit: canvas?.pixelsPerUnit ?? 100,
scaleMode: fit.scaleMode,
@@ -865,7 +872,7 @@ export const ViewportController = {
if (canvas) return canvas;
const d = projectDesignSeed();
return {
- cx: 0, cy: 0,
+ cx: EDITOR_UI_ANCHOR.x, cy: EDITOR_UI_ANCHOR.y,
designResolution: { x: d.width, y: d.height },
pixelsPerUnit: 100,
scaleMode: 1, // CanvasScaleMode.FixedHeight
diff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdx
index c165b5759..bb0e7b751 100644
--- a/docs/astro/src/content/docs/core-concepts/screen.mdx
+++ b/docs/astro/src/content/docs/core-concepts/screen.mdx
@@ -137,6 +137,11 @@ in this order:
2. else the scene's **`Canvas`** component, if one exists;
3. else **no fit** — the camera renders its raw `orthoSize`.
+The camera fit and the UI layout box resolve through this **same** order, so
+there is one design resolution in play at a time — a scene whose `Canvas` still
+carries an older resolution than the project fit cannot lay UI out one way in the
+editor and another in the shipped build.
+
<Aside type="caution">
While a fit source is active, the main camera's authored `orthoSize` is **not
used** — the visible half-height comes entirely from the design resolution and
@@ -162,9 +167,8 @@ runtime image of **Project Settings → Display → Camera fit**.
| `matchWidthOrHeight` | number | `0.5` | `Match`-mode blend 0–1 (`0` = fit width, `1` = fit height); ignored by other modes. |
`DEFAULT_SCREEN_SCALING` is that off-by-default value, and `SCREEN_FIT_OFF` (`-1`)
-is the sentinel. When the project fit is on, it is **authoritative for the
-camera** while UI layout still reads the `Canvas` — so gameplay and UI can fit
-differently.
+is the sentinel. When the project fit is on it is **authoritative** — for the
+camera and for the UI layout box alike, since both resolve the fit the same way.
The shipped runtimes install it from the project config (`createWebApp`'s
`screenFit` option). Game code can read or override it live — the camera plugin
@@ -192,7 +196,7 @@ The **editor viewport** is the special case: its navigation camera renders the
world at a free zoom (raw `orthoSize`, no fit — so panning/zooming stays
predictable). If UI were laid out against those zoomed extents, every element
would rescale and reflow on each scroll-wheel tick. Instead the editor recovers
-the *fixed* design-resolution box from the `Canvas` and lays UI out there — so the
+the *fixed* design-resolution box from the fit and lays UI out there — so the
layout is identical at any zoom, and the UI still scales visually with the scene
because it renders through the same zoomed view. The device simulator passes a
preview aspect into the same math, which is why the letterboxed preview is exactly
@@ -201,6 +205,32 @@ what ships.
Both pure functions — `uiLayoutRect` and `computeEffectiveOrthoSize` — are
exported for tools and tests.
+### Where the box sits: screen roots vs world-space UI
+
+The box has a **size** (the area UI lays out in) and a **place** (where that area
+sits in the world). The place is what decides whether a HUD travels with the
+camera:
+
+- A UI root **with no parent entity** is a *screen root*: the engine places it at
+ the box's center every frame. In play that center is the camera, so the HUD
+ stays on screen no matter how far the camera scrolls. In the editor the box is
+ anchored at the world origin (`EDITOR_UI_ANCHOR`), which is exactly where the
+ design-frame overlay is drawn — pan and zoom move UI like any other content.
+- A UI root **parented to an entity** is *world-space UI*: it rides its parent's
+ transform (a health bar over a unit, a panel on a wall) and the box only sizes
+ it.
+
+So "make this HUD follow the camera" needs nothing — that is the default. To pin
+UI into the world instead, give its root a parent.
+
+<Aside type="caution">
+ Every camera renders the whole scene, UI included — there is no per-camera layer
+ mask yet. A second camera with a sub-viewport (minimap, split-screen) therefore
+ draws the HUD again inside its own viewport, at the main camera's placement.
+ Keep sub-viewport cameras pointed at scene content until per-camera UI landing
+ exists.
+</Aside>
+
## Screen size & orientation: `ScreenInfo`
`ScreenInfo` is a small helper class (not auto-installed by the runtimes): you
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
index db3bbd419..00b2937be 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
@@ -125,6 +125,10 @@ const halfH = computeEffectiveOrthoSize(
2. 否则,场景的 **`Canvas`** 组件(若存在);
3. 否则**无适配**——相机按原始 `orthoSize` 渲染。
+相机适配与 UI 布局盒走的是**同一个**顺序,所以任一时刻只有一个设计分辨率在起作用——
+场景的 `Canvas` 即使还留着比项目适配更旧的分辨率,也不会出现"编辑器里一个盒子、发行版
+里另一个盒子"。
+
<Aside type="caution">
适配源生效期间,主相机自己写的 `orthoSize` **不会被使用**——可见半高完全来自设计分辨率
与缩放模式。通过编辑/tween `orthoSize` 缩放,只在没有适配源时生效(场景无 `Canvas`
@@ -147,8 +151,7 @@ const halfH = computeEffectiveOrthoSize(
| `matchWidthOrHeight` | number | `0.5` | `Match` 模式混合值 0–1(`0` = 适配宽度,`1` = 适配高度);其余模式忽略。 |
`DEFAULT_SCREEN_SCALING` 就是这个默认关闭的值,`SCREEN_FIT_OFF`(`-1`)是哨兵值。项目
-适配开启时,它**对相机是权威的**,而 UI 布局仍读 `Canvas`——所以玩法与 UI 可以按不同方式
-适配。
+适配开启时它就是**权威**——相机和 UI 布局盒都一样,因为两者解析适配源的方式相同。
各发布运行时从项目配置安装它(`createWebApp` 的 `screenFit` 选项)。游戏代码可以实时读取
或覆盖——相机插件每帧重读:
@@ -171,12 +174,32 @@ UI 在一个世界空间矩形(`uiLayoutRect`)内布局,对场景相机而言,
**编辑器视口**是特例:它的导航相机以自由缩放渲染世界(原始 `orthoSize`,无适配——平移/缩放
才可预测)。如果 UI 按那个被缩放的范围布局,每滚一格滚轮,所有元素都会重新缩放和重排。
-编辑器改为从 `Canvas` 恢复*固定的*设计分辨率盒,并在那里布局 UI——布局在任何缩放级别都完全
+编辑器改为从适配源恢复*固定的*设计分辨率盒,并在那里布局 UI——布局在任何缩放级别都完全
一致,而 UI 仍随场景视觉缩放,因为它通过同一个缩放后的视图渲染。设备模拟器把预览宽高比传进
同一套数学,这就是 letterbox 预览与实机发布完全一致的原因。
两个纯函数——`uiLayoutRect` 与 `computeEffectiveOrthoSize`——都已导出,供工具与测试使用。
+### 盒子在哪:屏幕根 vs 世界空间 UI
+
+这个盒子既有**大小**(UI 在多大的区域内布局),也有**位置**(这块区域落在世界的什么地方)。
+位置决定了 HUD 会不会跟着相机走:
+
+- **没有父实体**的 UI 根是*屏幕根*:引擎每帧把它放在盒子中心。运行时这个中心就是相机,
+ 所以相机滚多远,HUD 都留在屏幕上。编辑器里盒子锚定在世界原点(`EDITOR_UI_ANCHOR`),
+ 也正是设计框覆盖层绘制的位置——平移缩放时 UI 和其他内容一起动。
+- **挂在某个实体下**的 UI 根是*世界空间 UI*:它跟随父级的 transform(单位头顶的血条、
+ 墙上的面板),盒子只负责给它定尺寸。
+
+所以"让这个 HUD 跟随相机"不需要做任何事——那就是默认行为。反过来要把 UI 钉在世界里,
+给它的根加一个父级即可。
+
+<Aside type="caution">
+ 每个相机都渲染整个场景,UI 也不例外——目前还没有逐相机的层遮罩。因此带子视口的第二个
+ 相机(小地图、分屏)会在自己的视口里把 HUD 再画一遍,位置沿用主相机的摆放。在逐相机
+ UI 归属做出来之前,子视口相机请只对着场景内容。
+</Aside>
+
## 屏幕尺寸与方向:`ScreenInfo`
`ScreenInfo` 是一个小工具类(运行时不会自动安装):你构造它、喂给它尺寸,它推导方向并触发
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index ca3247348..ab502d027 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1444 stable · 17 beta · 1 deprecated
+Symbols: 1445 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -2414,6 +2414,11 @@ tabIndex: number | undefined
world: World
```
+## EDITOR_UI_ANCHOR — const
+```
+{ readonly x: 0; readonly y: 0; }
+```
+
## EDITOR_VIEW_ENTITY — const
```
-1
@@ -2622,7 +2627,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
@@ -10914,7 +10919,7 @@ UILayoutPlugin
## uiLayoutRect — function
```
-(cam: CameraExtents, canvas: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
+(cam: CameraExtents, fit: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
```
## uiMaskPlugin — const
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 89e228845..afc527efc 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1463 stable · 22 beta · 1 deprecated
+Symbols: 1464 stable · 22 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -2422,6 +2422,11 @@ tabIndex: number | undefined
world: World
```
+## EDITOR_UI_ANCHOR — const
+```
+{ readonly x: 0; readonly y: 0; }
+```
+
## EDITOR_VIEW_ENTITY — const
```
-1
@@ -2630,7 +2635,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
@@ -11134,7 +11139,7 @@ UILayoutPlugin
## uiLayoutRect — function
```
-(cam: CameraExtents, canvas: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
+(cam: CameraExtents, fit: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
```
## uiMaskPlugin — const
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 007829ad5..f96746d92 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1443 stable · 19 beta · 1 deprecated
+Symbols: 1444 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2409,6 +2409,11 @@ tabIndex: number | undefined
world: World
```
+## EDITOR_UI_ANCHOR — const
+```
+{ readonly x: 0; readonly y: 0; }
+```
+
## EDITOR_VIEW_ENTITY — const
```
-1
@@ -2617,7 +2622,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
@@ -10919,7 +10924,7 @@ UILayoutPlugin
## uiLayoutRect — function
```
-(cam: CameraExtents, canvas: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
+(cam: CameraExtents, fit: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
```
## uiMaskPlugin — const
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 052723bbf..93a2371e8 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1464 stable · 17 beta · 1 deprecated
+Symbols: 1465 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2409,6 +2409,11 @@ tabIndex: number | undefined
world: World
```
+## EDITOR_UI_ANCHOR — const
+```
+{ readonly x: 0; readonly y: 0; }
+```
+
## EDITOR_VIEW_ENTITY — const
```
-1
@@ -2617,7 +2622,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
@@ -11169,7 +11174,7 @@ UILayoutPlugin
## uiLayoutRect — function
```
-(cam: CameraExtents, canvas: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
+(cam: CameraExtents, fit: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
```
## uiMaskPlugin — const
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 3754d02a2..fc95319b3 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -375,7 +375,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: 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 6e2e27751..20cbaff80 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1454 stable · 17 beta · 1 deprecated
+Symbols: 1455 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2409,6 +2409,11 @@ tabIndex: number | undefined
world: World
```
+## EDITOR_UI_ANCHOR — const
+```
+{ readonly x: 0; readonly y: 0; }
+```
+
## EDITOR_VIEW_ENTITY — const
```
-1
@@ -2617,7 +2622,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, propertyDirty: boolean) => void
+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => void
uiNode_computedHeight: (registry: CppRegistry, entity: number) => number
uiNode_computedWidth: (registry: CppRegistry, entity: number) => number
uiRenderOrder_update: (registry: CppRegistry) => void
@@ -10941,7 +10946,7 @@ UILayoutPlugin
## uiLayoutRect — function
```
-(cam: CameraExtents, canvas: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
+(cam: CameraExtents, fit: CanvasScale | null, width: number, height: number, previewAspect?: number): WorldRect
```
## uiMaskPlugin — const
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 3f5c98f28..08a0805e5 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -334,11 +334,14 @@ export function editorCameraInfo(
* so it doesn't double-advance the same frame's blend.
*/
/**
- * The design-resolution source the MAIN scene camera fits to: the project screen fit
- * (ScreenScaling) when it opts in (scaleMode ≥ 0), else the scene's UI Canvas (legacy
- * behavior), else null (raw orthoSize). The project fit works WITHOUT a Canvas and, when
- * set, is authoritative for the camera — UI layout still reads the Canvas (uiLayoutRect),
- * so gameplay and UI can scale independently.
+ * The design-resolution fit: the project screen fit (ScreenScaling) when it opts in
+ * (scaleMode ≥ 0), else the scene's UI Canvas, else null (raw orthoSize). The project
+ * fit works WITHOUT a Canvas and, when set, is authoritative.
+ *
+ * The camera and UI layout both resolve their fit here — one screen, one answer. They
+ * used to disagree: the camera preferred ScreenScaling while the editor's UI box read
+ * the Canvas alone, so a project fit whose design resolution differed from the scene's
+ * Canvas laid UI out in one box while authoring and another once it shipped.
*/
function resolveFitSource(app: App, canvas: CanvasScale | null): CanvasScale | null {
if (app.hasResource(ScreenScaling)) {
@@ -425,12 +428,15 @@ function syncUICameraInfo(
uiCam.screenW = width;
uiCam.screenH = height;
// The box UI lays out within. Scene cameras carry design-scaled extents;
- // the free-zoom editor view gets the fixed design box from the canvas so UI
+ // the free-zoom editor view gets the fixed design box from the fit so UI
// doesn't reflow with the zoom (see uiLayoutRect). In the editor a selected
// device preset overrides the box aspect (uiPreviewAspect) so UI previews how it
// adapts on that device; 0 (default / shipped games) keeps the design aspect.
+ // The fit is resolved the SAME way the camera resolves it, so edit mode, play
+ // and a shipped build lay UI out in one box.
const previewAspect = app.hasResource(EditorView) ? app.getResource(EditorView).uiPreviewAspect : 0;
- const rect = uiLayoutRect(cam, findCanvasData(module, cppRegistry), width, height, previewAspect);
+ const fit = resolveFitSource(app, findCanvasData(module, cppRegistry));
+ const rect = uiLayoutRect(cam, fit, width, height, previewAspect);
uiCam.worldLeft = rect.left;
uiCam.worldRight = rect.right;
uiCam.worldBottom = rect.bottom;
diff --git a/sdk/src/camera/ScreenScaling.ts b/sdk/src/camera/ScreenScaling.ts
index 41f594d20..1e600508e 100644
--- a/sdk/src/camera/ScreenScaling.ts
+++ b/sdk/src/camera/ScreenScaling.ts
@@ -2,18 +2,21 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ScreenScaling.ts
- * @brief Project-level camera fit — the design (reference) resolution the MAIN
- * scene camera scales against, independent of any UI Canvas.
+ * @brief Project-level screen fit — the design (reference) resolution the game
+ * scales against, independent of any UI Canvas.
*
* The design resolution used to live only on the `Canvas` (UI) component, so a
* scene without UI got no design-resolution fit (the camera kept its raw
* orthoSize). This resource makes the fit a project/screen concern: when
* `scaleMode` is a real {@link CanvasScaleMode} (0..4) the camera letterboxes the
* design resolution into the actual aspect exactly as a Canvas would — no UI layer
- * required. `scaleMode = SCREEN_FIT_OFF` (the default) keeps the legacy behavior
- * (Canvas fit when present, else raw orthoSize), so an unconfigured project is
- * unchanged. UI layout still reads the Canvas (see uiLayoutRect); only the camera
- * fit reads this, so gameplay and UI can fit differently.
+ * required. `scaleMode = SCREEN_FIT_OFF` (the default) keeps the Canvas fit when
+ * present, else the raw orthoSize, so an unconfigured project is unchanged.
+ *
+ * When it opts in it is the project's ONE design resolution: the camera fit and the
+ * UI layout box both resolve through CameraPlugin.resolveFitSource, so a scene whose
+ * Canvas still carries an older design resolution cannot lay UI out one way while
+ * authoring and another once it ships.
*
* Installed by every runtime; the shipped game / play realm / editor set it from
* the project config (design resolution + fit). Read by CameraPlugin.resolveCameras.
diff --git a/sdk/src/camera/uiLayoutRect.ts b/sdk/src/camera/uiLayoutRect.ts
index 3ca7e075a..906ad94f2 100644
--- a/sdk/src/camera/uiLayoutRect.ts
+++ b/sdk/src/camera/uiLayoutRect.ts
@@ -54,7 +54,11 @@ export interface CameraExtents {
halfH: number;
}
-/** Canvas presentation fields (a subset of the Canvas component). */
+/**
+ * The design-resolution fit UI and the camera share — the project `ScreenScaling`
+ * when it opts in, else the scene's `Canvas` (see CameraPlugin.resolveFitSource).
+ * One source for both, so what the editor lays out and what ships cannot differ.
+ */
export interface CanvasScale {
designResolution: { x: number; y: number };
scaleMode: number;
@@ -68,34 +72,47 @@ export interface WorldRect {
top: number;
}
+/**
+ * World anchor of the editor's UI box — the origin. The design frame is a fixed
+ * place in the world, not something glued to the navigation view: anchored here it
+ * stays concentric with the viewport's design-frame overlay, and pans/zooms with
+ * the scene like every other piece of content. (In play the box tracks the camera
+ * instead; see {@link uiLayoutRect}.)
+ */
+export const EDITOR_UI_ANCHOR = { x: 0, y: 0 } as const;
+
/**
* The world-space box the UI subtree is laid out within (UINode `px` are world
- * units in this box), for the primary camera.
+ * units in this box), for the primary camera. Its SIZE is the area UI lays out in;
+ * its CENTER is where that area sits in the world, which places screen roots (a UI
+ * root with no transform parent) — so in play the HUD tracks the camera.
*
- * Scene cameras already bake the canvas design resolution into halfW/halfH, so
- * their box is simply those extents — UINode px map 1:1 to design px and the UI is
- * stable. The editor view instead renders the world at a *free zoom* with a raw
- * orthoSize (editorCameraInfo passes a null canvas, for predictable navigation),
- * so laying UI out in its zoomed extents would rescale and reflow every element on
- * each zoom. For it, recover the *fixed* design-resolution box from the canvas: the
- * UI then lays out identically at any zoom, and still scales visually with the
- * scene because it renders through the same zoomed viewProjection. The box stays
- * centered on the editor pan (cameraX/Y), so panning tracks the view as before.
+ * Scene cameras already bake the fit's design resolution into halfW/halfH, so their
+ * box is simply those extents centered on the camera — UINode px map 1:1 to design
+ * px and the UI is stable. The editor view instead renders the world at a *free
+ * zoom* with a raw orthoSize (editorCameraInfo passes a null fit, for predictable
+ * navigation), so laying UI out in its zoomed extents would rescale and reflow every
+ * element on each zoom. For it, recover the *fixed* design-resolution box from the
+ * fit and anchor it at {@link EDITOR_UI_ANCHOR}: the UI then lays out identically at
+ * any zoom or pan, and still scales visually with the scene because it renders
+ * through the same zoomed viewProjection.
*
- * With no canvas (no UI in the scene) the editor falls back to its own extents —
- * there is nothing to lay out, so it doesn't matter.
+ * With no fit (no Canvas and no project fit) the editor falls back to its own
+ * extents — there is nothing to lay out, so it doesn't matter.
*/
export function uiLayoutRect(
cam: CameraExtents,
- canvas: CanvasScale | null,
+ fit: CanvasScale | null,
width: number,
height: number,
previewAspect = 0,
): WorldRect {
let halfW = cam.halfW;
let halfH = cam.halfH;
+ let centerX = cam.cameraX;
+ let centerY = cam.cameraY;
- if (cam.entity === EDITOR_VIEW_ENTITY && canvas && width > 0 && height > 0) {
+ if (cam.entity === EDITOR_VIEW_ENTITY && fit && width > 0 && height > 0) {
// Lay UI out against the *preview screen*, independent of the editor panel's aspect —
// so the editor is WYSIWYG with the design-frame overlay. `previewAspect > 0` fits the
// design resolution into a simulated device's aspect (the device simulator: UI adapts
@@ -103,18 +120,20 @@ export function uiLayoutRect(
// aspect, where every scaleMode collapses to the exact authored box (edge-anchored UI
// at the design-resolution corners). The free editor camera renders this fixed box
// through its zoomed viewProjection, so UI scales with zoom without reflowing.
- const designAspect = canvas.designResolution.x / canvas.designResolution.y;
+ const designAspect = fit.designResolution.x / fit.designResolution.y;
const aspect = previewAspect > 0 ? previewAspect : designAspect;
halfH = computeEffectiveOrthoSize(
- canvas.designResolution.y / 2, designAspect, aspect, canvas.scaleMode, canvas.matchWidthOrHeight,
+ fit.designResolution.y / 2, designAspect, aspect, fit.scaleMode, fit.matchWidthOrHeight,
);
halfW = halfH * aspect;
+ centerX = EDITOR_UI_ANCHOR.x;
+ centerY = EDITOR_UI_ANCHOR.y;
}
return {
- left: cam.cameraX - halfW,
- right: cam.cameraX + halfW,
- bottom: cam.cameraY - halfH,
- top: cam.cameraY + halfH,
+ left: centerX - halfW,
+ right: centerX + halfW,
+ bottom: centerY - halfH,
+ top: centerY + halfH,
};
}
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index ba63d1687..5989dd175 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -52,7 +52,7 @@ export { FollowTarget } from './camera/FollowTarget';
export type { FollowTargetData } from './camera/FollowTarget';
export type { CameraDirectorState } from './camera/CameraDirector';
export type { CameraPOV } from './camera/CameraPlugin';
-export { computeEffectiveOrthoSize, uiLayoutRect, EDITOR_VIEW_ENTITY } from './camera/uiLayoutRect';
+export { computeEffectiveOrthoSize, uiLayoutRect, EDITOR_VIEW_ENTITY, EDITOR_UI_ANCHOR } from './camera/uiLayoutRect';
export type { CameraExtents, CanvasScale, WorldRect } from './camera/uiLayoutRect';
// =============================================================================
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 0f72e5c6d..786b7d70d 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -223,7 +223,7 @@ export interface NativeEngineApi {
uiHitTest_pickAll?(registry: unknown, worldX: number, worldY: number): number;
uiHitTest_pickResult?(index: number): number;
uiHitTest_update?(registry: unknown, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean): void;
- uiLayout_update?(registry: unknown, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean): void;
+ uiLayout_update?(registry: unknown, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean): void;
uiNode_computedHeight?(registry: unknown, entity: number): number;
uiNode_computedWidth?(registry: unknown, entity: number): number;
uiRenderOrder_update?(registry: unknown): void;
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 22df65690..375e430ae 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -422,7 +422,7 @@ export interface ESEngineModule {
renderer_getPreviewHeight(): number;
// UI Systems
- uiLayout_update(registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean): void;
+ uiLayout_update(registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: 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-layout-rect.test.ts b/sdk/tests/ui-layout-rect.test.ts
index 4d1247786..17d2cb2ca 100644
--- a/sdk/tests/ui-layout-rect.test.ts
+++ b/sdk/tests/ui-layout-rect.test.ts
@@ -31,13 +31,26 @@ describe('uiLayoutRect', () => {
expect(a).toEqual({ left: -640, right: 640, bottom: -360, top: 360 });
});
- it('the editor box stays centered on the editor pan', () => {
+ it('the editor box is anchored in the world, not glued to the pan', () => {
+ // Panning the navigation view must not drag the UI box with it: the box is a
+ // fixed frame the design-frame overlay is drawn to, and UI pans with the scene.
const cam = { entity: EDITOR_VIEW_ENTITY, cameraX: 200, cameraY: -100, halfW: 160, halfH: 90 };
expect(uiLayoutRect(cam, canvas, W, H)).toEqual({
- left: -440, right: 840, bottom: -460, top: 260,
+ left: -640, right: 640, bottom: -360, top: 360,
});
});
+ it('a scene camera carries its box with it (the HUD tracks the camera)', () => {
+ const near = { entity: 3, cameraX: 0, cameraY: 0, halfW: 640, halfH: 360 };
+ const far = { entity: 3, cameraX: 5000, cameraY: -800, halfW: 640, halfH: 360 };
+ const a = uiLayoutRect(near, canvas, W, H);
+ const b = uiLayoutRect(far, canvas, W, H);
+ expect(b.right - b.left).toBe(a.right - a.left);
+ expect(b.top - b.bottom).toBe(a.top - a.bottom);
+ expect((b.left + b.right) / 2).toBe(5000);
+ expect((b.bottom + b.top) / 2).toBe(-800);
+ });
+
it('the editor box is the design box regardless of viewport aspect (WYSIWYG with the frame)', () => {
// A square viewport must NOT reshape the UI box — it stays the authored 1280×720, so
// edge-anchored UI sits at the design-resolution corners, matching the design frame.
diff --git a/src/esengine/bindings/UIBindings.cpp b/src/esengine/bindings/UIBindings.cpp
index 88e321706..ba74e6a91 100644
--- a/src/esengine/bindings/UIBindings.cpp
+++ b/src/esengine/bindings/UIBindings.cpp
@@ -27,9 +27,9 @@ namespace esengine {
static EstellaContext& ctx() { return activeCtx(); }
-void uiLayout_update(ecs::Registry& registry, f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,
+void uiLayout_update(ecs::Registry& registry, f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
bool propertyDirty) {
- ctx().require<ecs::UISystem>().layoutUpdate(registry, camLeft, camBottom, camRight, camTop, propertyDirty);
+ ctx().require<ecs::UISystem>().layoutUpdate(registry, boxLeft, boxBottom, boxRight, boxTop, propertyDirty);
}
void uiHitTest_update(ecs::Registry& registry, f32 mouseWorldX, f32 mouseWorldY,
diff --git a/src/esengine/bindings/UIBindings.hpp b/src/esengine/bindings/UIBindings.hpp
index 8f420d463..1c7233c83 100644
--- a/src/esengine/bindings/UIBindings.hpp
+++ b/src/esengine/bindings/UIBindings.hpp
@@ -21,9 +21,11 @@ namespace ecs {
class Registry;
}
-/** Solve the UI layout tree against the camera's world box. `propertyDirty` is
- * the SDK's O(1) "an authored UINode/FlexContainer field changed" signal. */
-void uiLayout_update(ecs::Registry& registry, f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,
+/** Solve the UI layout tree against the world-space box UI lives in — its size
+ * is the available area, its center is where screen roots are placed.
+ * `propertyDirty` is the SDK's O(1) "an authored UINode/FlexContainer field
+ * changed" signal. */
+void uiLayout_update(ecs::Registry& registry, f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
bool propertyDirty);
void uiHitTest_update(ecs::Registry& registry, f32 mouseWorldX, f32 mouseWorldY,
diff --git a/src/esengine/ui/UILayoutSystem.cpp b/src/esengine/ui/UILayoutSystem.cpp
index b13d1dd53..0d8face90 100644
--- a/src/esengine/ui/UILayoutSystem.cpp
+++ b/src/esengine/ui/UILayoutSystem.cpp
@@ -6,6 +6,7 @@
#include "../ecs/components/Transform.hpp"
#include "../ecs/components/Canvas.hpp"
#include "../ecs/components/FlexContainer.hpp"
+#include "../ecs/components/Hierarchy.hpp"
#include "../ecs/components/UINode.hpp" // UINode + AlignSelf
#include <yoga/Yoga.h>
@@ -436,20 +437,63 @@ bool anyUIAnimActive(Registry& registry) {
return active;
}
+/**
+ * Whether a subtree root IS the screen rather than something standing in the
+ * world. A root with no Transform parent has no other frame to sit in, so the
+ * layout box places it and it tracks whatever the box tracks (in play, the
+ * camera). Parenting the root to an entity is how a scene opts out and pins its
+ * UI to a thing in the world — the box then only sizes it.
+ */
+bool isScreenRoot(Registry& registry, Entity e) {
+ auto* p = registry.tryGet<Parent>(e);
+ return !p || p->entity == INVALID_ENTITY || !registry.valid(p->entity);
+}
+
+/**
+ * Place every screen root at the box's world center. Authoritative for those
+ * roots' position (it runs after the solve, which writes only the root's box
+ * within the available area), and idempotent — it assigns rather than offsets,
+ * so a pass that only moved the box can call it alone.
+ */
+void placeScreenRoots(Registry& registry, UITree& tree, LayoutCache& cache,
+ const LayoutRect& box) {
+ const f32 availW = box.width();
+ const f32 availH = box.height();
+ const f32 cx = box.centerX();
+ const f32 cy = box.centerY();
+ for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {
+ auto& node = tree.nodes_[i];
+ bool parentIsUINode = node.parent != INVALID_ENTITY && registry.has<UINode>(node.parent);
+ if (!parentIsUINode && isScreenRoot(registry, node.entity)) {
+ auto it = cache.nodes.find(node.entity);
+ auto* t = registry.tryGet<Transform>(node.entity);
+ auto* un = registry.tryGet<UINode>(node.entity);
+ if (it != cache.nodes.end() && t && un) {
+ const f32 fw = YGNodeLayoutGetWidth(it->second);
+ const f32 fh = YGNodeLayoutGetHeight(it->second);
+ const f32 localX = -0.5f * availW + YGNodeLayoutGetLeft(it->second) + 0.5f * fw;
+ const f32 localY = 0.5f * availH - YGNodeLayoutGetTop(it->second) - 0.5f * fh;
+ if (!(un->anim_override_ & UINode::ANIM_POS_X)) t->position.x = cx + localX;
+ if (!(un->anim_override_ & UINode::ANIM_POS_Y)) t->position.y = cy + localY;
+ }
+ }
+ i += node.subtree_size;
+ }
+}
+
void unifiedLayoutPass(Registry& registry, UITree& tree, LayoutCache& cache,
- const LayoutRect& cameraRect, bool structureChanged,
+ const LayoutRect& box, bool structureChanged,
bool forceWriteback) {
for (i32 i = 0; i < static_cast<i32>(tree.nodes_.size()); ) {
auto& node = tree.nodes_[i];
// Every node is a UINode. A subtree root (its parent is not a UINode —
// a top-level UI element / Canvas) is resolved in one Yoga solve over its
- // whole subtree; skip past it. The available box is the camera rect.
+ // whole subtree; skip past it. The available box is the layout box's size;
+ // where that box sits is applied by placeScreenRoots.
bool parentIsUINode = node.parent != INVALID_ENTITY && registry.has<UINode>(node.parent);
if (!parentIsUINode) {
- f32 availW = cameraRect.right - cameraRect.left;
- f32 availH = cameraRect.top - cameraRect.bottom;
- layoutUINodeSubtree(registry, tree, cache, i, availW, availH, 0.5f, 0.5f,
+ layoutUINodeSubtree(registry, tree, cache, i, box.width(), box.height(), 0.5f, 0.5f,
structureChanged, forceWriteback);
}
i += node.subtree_size;
@@ -464,7 +508,7 @@ void unifiedLayoutPass(Registry& registry, UITree& tree, LayoutCache& cache,
void UISystem::layoutUpdate(
Registry& registry,
- f32 camLeft, f32 camBottom, f32 camRight, f32 camTop,
+ f32 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
bool tsPropertyDirty
) {
// The retained nodes are keyed by entity, and entity ids restart with each
@@ -485,33 +529,43 @@ void UISystem::layoutUpdate(
// (orphan + propagateHidden + Yoga solve + reap) is what the gate below skips.
tree.rebuild(registry);
+ LayoutRect box{ boxLeft, boxBottom, boxRight, boxTop };
+
bool animNow = anyUIAnimActive(registry);
bool sigChanged = tree.structure_sig_ != lastSig_;
- bool rectChanged = camLeft != lastCamL_ || camBottom != lastCamB_
- || camRight != lastCamR_ || camTop != lastCamT_;
+ // A resized box invalidates the solve; a box that merely MOVED does not —
+ // Yoga solves against the size alone, and only the screen roots' world
+ // placement depends on where the box sits. Keeping these apart is what stops
+ // a panning camera from rewriting the whole UI tree every frame.
+ bool sizeChanged = box.width() != lastBoxW_ || box.height() != lastBoxH_;
+ bool centerChanged = box.centerX() != lastBoxCX_ || box.centerY() != lastBoxCY_;
bool wasAnimActive = lastAnimActive_;
lastSig_ = tree.structure_sig_;
- lastCamL_ = camLeft; lastCamB_ = camBottom; lastCamR_ = camRight; lastCamT_ = camTop;
+ lastBoxW_ = box.width(); lastBoxH_ = box.height();
+ lastBoxCX_ = box.centerX(); lastBoxCY_ = box.centerY();
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).
+ // A fully static frame — no structural, box-size, 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 first = !layoutPrimed_;
- bool dirty = first || sigChanged || rectChanged || tsPropertyDirty
+ bool dirty = first || sigChanged || sizeChanged || tsPropertyDirty
|| animNow || wasAnimActive;
layoutPrimed_ = true;
- if (!dirty) return;
+ if (!dirty) {
+ if (centerChanged) placeScreenRoots(registry, tree, *layoutCache_, box);
+ return;
+ }
// Two signals, because they answer different questions. The hierarchy has to
// be rebuilt when the tree's SHAPE changed. Output has to be written for
// every node when the ROOT'S FRAME changed — a subtree root positions itself
- // against the camera box, so the same Yoga result inside a resized box is a
+ // against the box, so the same Yoga result inside a resized box is a
// different world position, and Yoga would rightly report no new layout.
bool structureChanged = first || sigChanged;
- bool forceWriteback = structureChanged || rectChanged;
+ bool forceWriteback = structureChanged || sizeChanged;
// The retained hierarchy is rebuilt only when the tree's shape changed —
// which is exactly when an entity may still be owned by the parent it had
@@ -519,8 +573,8 @@ void UISystem::layoutUpdate(
// Yoga node on every pass, so no solve could ever be partial.
propagateHiddenInTree(registry, tree);
propagateInheritedUIState(registry, tree);
- LayoutRect cameraRect{ camLeft, camBottom, camRight, camTop };
- unifiedLayoutPass(registry, tree, *layoutCache_, cameraRect, structureChanged, forceWriteback);
+ unifiedLayoutPass(registry, tree, *layoutCache_, box, structureChanged, forceWriteback);
+ placeScreenRoots(registry, tree, *layoutCache_, box);
// Reaping is likewise a structural concern: with the same set of entities in
// the tree there is nothing to free, and building the live set is a hash
diff --git a/src/esengine/ui/UILayoutSystem.hpp b/src/esengine/ui/UILayoutSystem.hpp
index 6c29df3a2..adae8b51f 100644
--- a/src/esengine/ui/UILayoutSystem.hpp
+++ b/src/esengine/ui/UILayoutSystem.hpp
@@ -9,12 +9,24 @@
namespace esengine::ecs {
-// The available box (camera rect) the UI subtree is laid out within.
+/**
+ * The world-space box a UI subtree is laid out within — the "screen".
+ *
+ * Its SIZE is the available box Yoga solves against; its CENTER is where that
+ * box sits in the world, which is what places a screen root (see
+ * UILayoutSystem.cpp). Both matter: a box that only resized needs a new solve,
+ * a box that only moved needs the roots repositioned and nothing else.
+ */
struct LayoutRect {
f32 left;
f32 bottom;
f32 right;
f32 top;
+
+ [[nodiscard]] f32 width() const { return right - left; }
+ [[nodiscard]] f32 height() const { return top - bottom; }
+ [[nodiscard]] f32 centerX() const { return 0.5f * (left + right); }
+ [[nodiscard]] f32 centerY() const { return 0.5f * (bottom + top); }
};
// Layout and tree operations are methods on UISystem (see UISystem.hpp).
diff --git a/src/esengine/ui/UISystem.hpp b/src/esengine/ui/UISystem.hpp
index dfdd908f5..4de9b099d 100644
--- a/src/esengine/ui/UISystem.hpp
+++ b/src/esengine/ui/UISystem.hpp
@@ -65,12 +65,14 @@ public:
// ---- Layout pass (defined in UILayoutSystem.cpp) ----
/** @brief Rebuild layout tree and apply layout to all dirty nodes.
+ * The four bounds are the world-space box UI is laid out within: its size is
+ * what Yoga solves against, its center is where screen roots are placed.
* @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
+ * C++-detected structure/box/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 boxLeft, f32 boxBottom, f32 boxRight, f32 boxTop,
bool tsPropertyDirty);
// ---- Hit test pass (defined in UISystem.cpp) ----
@@ -106,7 +108,9 @@ private:
// 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};
+ // Size and center are tracked apart: a resized box needs a new solve, a moved
+ // box needs only the screen roots replaced (see layoutUpdate).
+ f32 lastBoxW_{0}, lastBoxH_{0}, lastBoxCX_{0}, lastBoxCY_{0};
bool lastAnimActive_{false};
bool layoutPrimed_{false}; // force a solve on the very first pass
// Which registry the retained Yoga nodes belong to — entity ids restart with