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
fix(camera): align canvas fitting with hierarchy and scene filters
yhh530293c5f11c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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/desktopindex 33ae07ab6..1484bd35e 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 33ae07ab631e2ea26ed18fffb80183e1593c8732+Subproject commit 1484bd35eedc457d0f59bfc39be33533806ece78diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 Teamimport { 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.mjsindex 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':