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): the layout box has a place, not just a size
yhhc2ecacff1614
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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.jsonindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.tsindex 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.FixedHeightdiff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdxindex 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 **notused** — 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 theworld at a free zoom (raw `orthoSize`, no fit — so panning/zooming stayspredictable). If UI were laid out against those zoomed extents, every elementwould 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 thelayout is identical at any zoom, and the UI still scales visually with the scenebecause it renders through the same zoomed view. The device simulator passes apreview 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` — areexported 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): youdiff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdxindex 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.mdindex 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 | undefinedworld: 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_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 — constdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 | undefinedworld: 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_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 — constdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 | undefinedworld: 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_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 — constdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 | undefinedworld: 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_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 — constdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_update: (registry: CppRegistry) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 | undefinedworld: 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) => numbuiHitTest_pickAll: ((registry: CppRegistry, worldX: number, worldY: number) => number) | undefineduiHitTest_pickResult: ((index: number) => number) | undefineduiHitTest_update: (registry: CppRegistry, mouseWorldX: number, mouseWorldY: number, mouseDown: boolean, mousePressed: boolean, mouseReleased: boolean) => void-uiLayout_update: (registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number, propertyDirty: boolean) => void+uiLayout_update: (registry: CppRegistry, boxLeft: number, boxBottom: number, boxRight: number, boxTop: number, propertyDirty: boolean) => voiduiNode_computedHeight: (registry: CppRegistry, entity: number) => numberuiNode_computedWidth: (registry: CppRegistry, entity: number) => numberuiRenderOrder_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 — constdiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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.hppindex 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.cppindex 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 hashdiff --git a/src/esengine/ui/UILayoutSystem.hpp b/src/esengine/ui/UILayoutSystem.hppindex 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.hppindex 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