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.

fix(camera): align canvas fitting with hierarchy and scene filters

yhh530293c5f11c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d470f35f7..52001c780 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Camera fitting and editor previews use outer canvases consistently.** A nested canvas appearing first no longer overrides the scene design resolution or becomes the default host for new UI. Scene-filtered camera collection uses a running scene's outer canvas, and preview selection queries Canvas components directly. The experimental `canvasRootEntities` helper shares root selection across runtime and editor workflows.
+
- **Nested canvases keep their parent layout and authored draw order.** Only top-level eligible canvases start traversal, so a nested canvas is not laid out again against the full screen or assigned a second draw-order range. Descendants inherit the nearest canvas's sorting layer regardless of canvas creation order.
- **UI hierarchy walks tolerate deep scene groups and broken child links.** Tree construction, screen-domain collection and draw-order assignment use iterative traversal. Repeated or cyclic child links stop revisiting entities while preserving the authored sibling order and nearest UI parent.
diff --git a/desktop b/desktop
index 33ae07ab6..1484bd35e 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 33ae07ab631e2ea26ed18fffb80183e1593c8732
+Subproject commit 1484bd35eedc457d0f59bfc39be33533806ece78
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 1f7bef6c3..c20cfe6cc 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: 115 public · 91 beta · 1554 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1555 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10413,6 +10413,11 @@ MotionDriver<AnimatorBlend2DMotion>
(module: ESEngineModule): boolean
```
+## canvasRootEntities — function @experimental
+```
+<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[]
+```
+
## captureFrame — function @experimental
```
(module: CaptureEngine, nextFrame: NextFrame, maxFrames?: number): Promise<FrameCaptureData | null>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 684b86404..966045e51 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: 115 public · 96 beta · 1573 experimental · 3 deprecated
+Symbols: 115 public · 96 beta · 1574 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10632,6 +10632,11 @@ MotionDriver<AnimatorBlend2DMotion>
(module: ESEngineModule): boolean
```
+## canvasRootEntities — function @experimental
+```
+<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[]
+```
+
## captureFrame — function @experimental
```
(module: CaptureEngine, nextFrame: NextFrame, maxFrames?: number): Promise<FrameCaptureData | null>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5acd8184a..4264ef660 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: 115 public · 93 beta · 1553 experimental · 3 deprecated
+Symbols: 115 public · 93 beta · 1554 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10408,6 +10408,11 @@ MotionDriver<AnimatorBlend2DMotion>
(module: ESEngineModule): boolean
```
+## canvasRootEntities — function @experimental
+```
+<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[]
+```
+
## captureFrame — function @experimental
```
(module: CaptureEngine, nextFrame: NextFrame, maxFrames?: number): Promise<FrameCaptureData | null>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 48ffb97cd..3a3791e25 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: 115 public · 91 beta · 1575 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1576 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10687,6 +10687,11 @@ MotionDriver<AnimatorBlend2DMotion>
(module: ESEngineModule): boolean
```
+## canvasRootEntities — function @experimental
+```
+<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[]
+```
+
## captureFrame — function @experimental
```
(module: CaptureEngine, nextFrame: NextFrame, maxFrames?: number): Promise<FrameCaptureData | null>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f2b668f6f..ae59cbbc4 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: 115 public · 91 beta · 1566 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1567 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10439,6 +10439,11 @@ MotionDriver<AnimatorBlend2DMotion>
(module: ESEngineModule): boolean
```
+## canvasRootEntities — function @experimental
+```
+<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[]
+```
+
## captureFrame — function @experimental
```
(module: CaptureEngine, nextFrame: NextFrame, maxFrames?: number): Promise<FrameCaptureData | null>
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 109188606..ed016af34 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -20,6 +20,7 @@ import { CameraCommit, cameraCommitChanged } from './CameraCommit';
import { ScreenLayout, screenLayoutRect, screenProjection } from '../ui/core/screen-layout';
import { ScreenOverlay } from '../ui/core/screen-overlay';
import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';
+import { canvasRootEntities } from '../ui/core/canvas-roots';
import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type CanvasScale } from './uiLayoutRect';
import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar, editorViewClipNear, type EditorViewData } from './EditorView';
import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';
@@ -107,13 +108,18 @@ function canvasEntityOf(
? reg.getCanvasEntities.call(registry)
: module?.registry_getCanvasEntities?.(registry);
if (all && all.length > 0) {
+ const roots = canvasRootEntities(all, entity => {
+ if (!registry.hasParent(entity)) return null;
+ const parent = registry.getParent(entity).entity;
+ return registry.valid(parent) ? parent : null;
+ });
if (world && activeScenes) {
- for (const e of all) {
+ for (const e of roots) {
const owner = world.tryGet(e as Entity, SceneOwner);
if (!owner || owner.scene === '' || activeScenes.has(owner.scene)) return e;
}
}
- return all[0];
+ return roots[0] ?? -1;
}
// A core built before the enumeration answers only the single-Canvas question.
const own = reg.getCanvasEntity;
@@ -408,7 +414,7 @@ export function collectCameras(
): CameraInfo[] {
const povs = collectCameraPOVs(module, registry, width, height, world, activeScenes);
if (povs.length === 0) return [];
- const canvas = findCanvasData(module, registry);
+ const canvas = findCanvasData(module, registry, world, activeScenes);
const cameras = povs.map((pov, i) => buildCameraInfo(pov, width, height, canvas, pool, i));
cameras.sort((a, b) => a.priority - b.priority);
return cameras;
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index 45e5dc8e3..50ffcbca9 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -1,5 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+export { canvasRootEntities } from './ui/core/canvas-roots';
/**
* @file core-ui.ts
* @brief The stable UI surface promoted into the top-level `esengine`
diff --git a/sdk/src/ui/core/canvas-roots.ts b/sdk/src/ui/core/canvas-roots.ts
new file mode 100644
index 000000000..8e234471d
--- /dev/null
+++ b/sdk/src/ui/core/canvas-roots.ts
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+
+/** Top-level canvases in input order; parentOf returns null for absent or invalid parents. @experimental */
+export function canvasRootEntities<T>(entities: readonly T[], parentOf: (entity: T) => T | null): T[] {
+ if (entities.length <= 1) return [...entities];
+ const ancestry = new Map<T, number>(entities.map(entity => [entity, 3]));
+ const roots: T[] = [];
+ const trail: T[] = [];
+ for (const entity of entities) {
+ trail.length = 0;
+ let ancestor = parentOf(entity);
+ let nested = false;
+ while (ancestor !== null) {
+ const state = ancestry.get(ancestor);
+ if (state !== undefined) { nested = state === 3; break; }
+ ancestry.set(ancestor, 1);
+ trail.push(ancestor);
+ ancestor = parentOf(ancestor);
+ }
+ for (const visited of trail) ancestry.set(visited, nested ? 3 : 2);
+ if (!nested) roots.push(entity);
+ }
+ return roots;
+}
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index dc5ac592c..7f772bf39 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -522,3 +522,4 @@ export { sdfFromAlpha } from './text/sdf';
export { submitTextBatch, TEXT_VERTEX_FLOATS } from './text/submit';
export { ScreenOverlay, type ScreenOverlayData } from './core/screen-overlay';
+export { canvasRootEntities } from './core/canvas-roots';
diff --git a/sdk/tests/canvas-roots.test.ts b/sdk/tests/canvas-roots.test.ts
new file mode 100644
index 000000000..0058654af
--- /dev/null
+++ b/sdk/tests/canvas-roots.test.ts
@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { expect, it } from 'vitest';
+import { canvasRootEntities } from '../src/ui/core/canvas-roots';
+
+it('selects independent outer canvases in input order across ordinary scene groups', () => {
+ const parents = new Map([[1, 2], [2, 3], [4, 3]]);
+ expect(canvasRootEntities([1, 5, 3, 4], entity => parents.get(entity) ?? null)).toEqual([5,3]);
+});
+it('memoizes common ancestor chains rather than walking them once per canvas', () => {
+ const parents = new Map<number,number>();
+ for (let id = 0; id < 10000; id++) parents.set(id, id + 1);
+ const canvases = Array.from({ length: 1000 }, (_, index) => index + 20000);
+ for (const canvas of canvases) parents.set(canvas, 0);
+ let calls = 0;
+ expect(canvasRootEntities(canvases, entity => { calls++; return parents.get(entity) ?? null; })).toEqual(canvases);
+ expect(calls).toBeLessThan(12000);
+});
+it('stops malformed ancestor cycles and leaves the input untouched', () => {
+ const parents = new Map([[1, 7], [7, 8], [8, 7]]), candidates = [1, 2];
+ expect(canvasRootEntities(candidates, entity => parents.get(entity) ?? null)).toEqual([1,2]);
+ expect(candidates).toEqual([1,2]);
+});
diff --git a/sdk/tests/ui-nested-canvas-wasm.test.ts b/sdk/tests/ui-nested-canvas-wasm.test.ts
index 0860b4ab1..a6ce88d0b 100644
--- a/sdk/tests/ui-nested-canvas-wasm.test.ts
+++ b/sdk/tests/ui-nested-canvas-wasm.test.ts
@@ -2,7 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
import { World } from '../src/ecs/world';
-import { Canvas, Transform } from '../src/ecs/component';
+import { Canvas, Camera, SceneOwner, Transform } from '../src/ecs/component';
+import { collectCameras } from '../src/camera/CameraPlugin';
import { UINode, UIPositionType } from '../src/ui/core/ui-node';
import { UIVisual } from '../src/ui/core/ui-visual';
import { Interactable } from '../src/ui/input/interactable';
@@ -20,6 +21,23 @@ describe.skipIf(!HAS_WASM)('nested canvas layout and ordering on real WASM', ()
for (const entity of world.getAllEntities()) if (world.valid(entity)) world.despawn(entity);
world.disconnectCpp(); registry.delete();
});
+ it('fits cameras to the outer canvas when the nested canvas was enumerated first', () => {
+ const child = world.spawn(), root = world.spawn(), camera = world.spawn();
+ world.insert(child, Canvas, { designResolution: { x: 160, y: 120 } });
+ world.insert(root, Canvas, { designResolution: { x: 800, y: 600 } });
+ world.setParent(child, root);
+ world.insert(camera, Transform); world.insert(camera, Camera, { isActive: true });
+ expect(collectCameras(engine, registry, 800, 600, world)[0].halfH).toBe(300);
+ });
+ it('uses the running scene canvas for scene-filtered camera collection', () => {
+ const paused = world.spawn(), running = world.spawn(), camera = world.spawn();
+ world.insert(paused, Canvas, { designResolution: { x: 160, y: 120 } });
+ world.insert(paused, SceneOwner, { scene: 'paused' });
+ world.insert(running, Canvas, { designResolution: { x: 800, y: 600 } });
+ world.insert(running, SceneOwner, { scene: 'running' });
+ world.insert(camera, Transform); world.insert(camera, Camera, { isActive: true });
+ expect(collectCameras(engine, registry, 800, 600, world, new Set(['running']))[0].halfH).toBe(300);
+ });
it.each([false, true])('lays out nested canvases once, even when the child was created first: %s', childFirst => {
const child = childFirst ? world.spawn() : null;
const root = world.spawn(), container = world.spawn(), nested = child ?? world.spawn();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index d7c19a8b1..da833b97d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(camera): align canvas fitting with hierarchy and scene filters':
+ { note: 'Camera fitting and editor previews use outer canvases consistently.' },
+ 'fix(editor): use outer canvases for previews and UI hosting':
+ { note: 'Camera fitting and editor previews use outer canvases consistently.' },
'fix(ui): traverse nested canvases once and inherit their layers':
{ note: 'Nested canvases keep their parent layout and authored draw order.' },
'fix(ui): bound hierarchy walks and preserve sibling order':