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(ui): lay editor UI out in the fixed design box, not the zoomed view

yhhe47679185f79
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 30b0f2cd6..3f9aac2e8 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -15,7 +15,8 @@ import type { ESEngineModule, CppRegistry } from '../wasm';
import type { World } from '../world';
import type { Entity } from '../types';
import { UICameraInfo } from '../ui/core/ui-camera-info';
-import { ProjectionType, ScaleMode, SceneOwner, ClearFlags } from '../component';
+import { ProjectionType, SceneOwner, ClearFlags } from '../component';
+import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY } from './uiLayoutRect';
import { EditorView, DEFAULT_EDITOR_VIEW, type EditorViewData } from './EditorView';
import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';
import { RenderPipeline } from '../renderPipeline';
@@ -69,28 +70,9 @@ function findCanvasData(module: ESEngineModule, registry: CppRegistry) {
return registry.getCanvas(entity);
}
-function computeEffectiveOrthoSize(
- baseOrthoSize: number,
- designAspect: number,
- actualAspect: number,
- scaleMode: number,
- matchWidthOrHeight: number,
-): number {
- const orthoForWidth = baseOrthoSize * designAspect / actualAspect;
- const orthoForHeight = baseOrthoSize;
-
- switch (scaleMode) {
- case ScaleMode.FixedWidth: return orthoForWidth;
- case ScaleMode.FixedHeight: return orthoForHeight;
- case ScaleMode.Expand: return Math.max(orthoForWidth, orthoForHeight);
- case ScaleMode.Shrink: return Math.min(orthoForWidth, orthoForHeight);
- case ScaleMode.Match: {
- const t = matchWidthOrHeight;
- return Math.pow(orthoForWidth, 1 - t) * Math.pow(orthoForHeight, t);
- }
- default: return orthoForHeight;
- }
-}
+// computeEffectiveOrthoSize + the UI layout box math live in ./uiLayoutRect
+// (pure, unit-tested). buildCameraInfo applies the former for design-resolution
+// scaling; syncUICameraInfo uses the latter for the UI layout rect.
// =============================================================================
// Camera POV (authored view parameters, decoupled from the baked matrix)
@@ -291,10 +273,11 @@ export function editorCameraInfo(
height: number,
pool: CameraInfo[],
): CameraInfo {
- // The editor view is just another POV (synthetic entity -1, full-frame).
- // null canvas → raw orthoSize (no design-resolution scaling) for predictable zoom.
+ // The editor view is just another POV (synthetic entity, full-frame).
+ // null canvas → raw orthoSize (no design-resolution scaling) for predictable
+ // world-zoom; UI layout gets the fixed design box separately (see uiLayoutRect).
const pov: CameraPOV = {
- entity: -1,
+ entity: EDITOR_VIEW_ENTITY,
isActive: true,
x: view.x,
y: view.y,
@@ -392,10 +375,14 @@ function syncUICameraInfo(
uiCam.vpH = Math.round(vr.h * height);
uiCam.screenW = width;
uiCam.screenH = height;
- uiCam.worldLeft = cam.cameraX - cam.halfW;
- uiCam.worldRight = cam.cameraX + cam.halfW;
- uiCam.worldBottom = cam.cameraY - cam.halfH;
- uiCam.worldTop = cam.cameraY + cam.halfH;
+ // 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
+ // doesn't reflow with the zoom (see uiLayoutRect).
+ const rect = uiLayoutRect(cam, findCanvasData(module, cppRegistry), width, height);
+ uiCam.worldLeft = rect.left;
+ uiCam.worldRight = rect.right;
+ uiCam.worldBottom = rect.bottom;
+ uiCam.worldTop = rect.top;
uiCam.valid = true;
} else {
uiCam.valid = false;
diff --git a/sdk/src/camera/uiLayoutRect.ts b/sdk/src/camera/uiLayoutRect.ts
new file mode 100644
index 000000000..2cd75415e
--- /dev/null
+++ b/sdk/src/camera/uiLayoutRect.ts
@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file uiLayoutRect.ts
+ * @brief Pure geometry: the world-space box UI is laid out within, plus the
+ * design-resolution ortho scaling behind it. No engine / WASM / DOM
+ * coupling (only the generated CanvasScaleMode enum), so it unit-tests in
+ * isolation like viewportMath. CameraPlugin builds on top of it.
+ */
+
+import { CanvasScaleMode } from '../wasm.generated';
+
+/**
+ * Half-height (world units) of the visible area after fitting a design resolution
+ * into an actual aspect per @p scaleMode. `orthoForWidth` is the half-height that
+ * makes the design *width* exactly fit; `orthoForHeight` the design height.
+ */
+export function computeEffectiveOrthoSize(
+ baseOrthoSize: number,
+ designAspect: number,
+ actualAspect: number,
+ scaleMode: number,
+ matchWidthOrHeight: number,
+): number {
+ const orthoForWidth = baseOrthoSize * designAspect / actualAspect;
+ const orthoForHeight = baseOrthoSize;
+
+ switch (scaleMode) {
+ case CanvasScaleMode.FixedWidth: return orthoForWidth;
+ case CanvasScaleMode.FixedHeight: return orthoForHeight;
+ case CanvasScaleMode.Expand: return Math.max(orthoForWidth, orthoForHeight);
+ case CanvasScaleMode.Shrink: return Math.min(orthoForWidth, orthoForHeight);
+ case CanvasScaleMode.Match: {
+ const t = matchWidthOrHeight;
+ return Math.pow(orthoForWidth, 1 - t) * Math.pow(orthoForHeight, t);
+ }
+ default: return orthoForHeight;
+ }
+}
+
+/**
+ * Synthetic camera `entity` id of the editor navigation view (never a real ECS
+ * entity — see CameraPlugin.editorCameraInfo). Distinguishes the free-zoom editor
+ * view from scene cameras when deciding the UI layout box.
+ */
+export const EDITOR_VIEW_ENTITY = -1;
+
+/** The minimal camera fields the UI box needs (a subset of CameraInfo). */
+export interface CameraExtents {
+ entity: number;
+ cameraX: number;
+ cameraY: number;
+ halfW: number;
+ halfH: number;
+}
+
+/** Canvas presentation fields (a subset of the Canvas component). */
+export interface CanvasScale {
+ designResolution: { x: number; y: number };
+ scaleMode: number;
+ matchWidthOrHeight: number;
+}
+
+export interface WorldRect {
+ left: number;
+ right: number;
+ bottom: number;
+ top: number;
+}
+
+/**
+ * The world-space box the UI subtree is laid out within (UINode `px` are world
+ * units in this box), for the primary 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.
+ *
+ * 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.
+ */
+export function uiLayoutRect(
+ cam: CameraExtents,
+ canvas: CanvasScale | null,
+ width: number,
+ height: number,
+): WorldRect {
+ let halfW = cam.halfW;
+ let halfH = cam.halfH;
+
+ if (cam.entity === EDITOR_VIEW_ENTITY && canvas && height > 0) {
+ const aspect = width / height;
+ halfH = computeEffectiveOrthoSize(
+ canvas.designResolution.y / 2,
+ canvas.designResolution.x / canvas.designResolution.y,
+ aspect,
+ canvas.scaleMode,
+ canvas.matchWidthOrHeight,
+ );
+ halfW = halfH * aspect;
+ }
+
+ return {
+ left: cam.cameraX - halfW,
+ right: cam.cameraX + halfW,
+ bottom: cam.cameraY - halfH,
+ top: cam.cameraY + halfH,
+ };
+}
diff --git a/sdk/tests/ui-layout-rect.test.ts b/sdk/tests/ui-layout-rect.test.ts
new file mode 100644
index 000000000..91fc1fefb
--- /dev/null
+++ b/sdk/tests/ui-layout-rect.test.ts
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY } from '../src/camera/uiLayoutRect';
+import { CanvasScaleMode } from '../src/wasm.generated';
+
+// A 1280x720 canvas (design aspect 16:9), Expand scale mode.
+const canvas = {
+ designResolution: { x: 1280, y: 720 },
+ scaleMode: CanvasScaleMode.Expand,
+ matchWidthOrHeight: 0.5,
+};
+// A viewport at the design aspect, so the design box is exactly 1280x720 world units.
+const W = 1280, H = 720;
+
+describe('uiLayoutRect', () => {
+ it('a scene camera uses its own (already design-scaled) extents', () => {
+ const cam = { entity: 3, cameraX: 100, cameraY: 50, halfW: 640, halfH: 360 };
+ expect(uiLayoutRect(cam, canvas, W, H)).toEqual({
+ left: -540, right: 740, bottom: -310, top: 410,
+ });
+ });
+
+ it('the editor box is the fixed design box — invariant to zoom (the bug)', () => {
+ // Same editor view at two very different zooms (raw extents differ 8x)...
+ const zoomedIn = { entity: EDITOR_VIEW_ENTITY, cameraX: 0, cameraY: 0, halfW: 160, halfH: 90 };
+ const zoomedOut = { entity: EDITOR_VIEW_ENTITY, cameraX: 0, cameraY: 0, halfW: 1280, halfH: 720 };
+ const a = uiLayoutRect(zoomedIn, canvas, W, H);
+ const b = uiLayoutRect(zoomedOut, canvas, W, H);
+ expect(a).toEqual(b); // zoom must NOT move/resize the UI layout box
+ expect(a).toEqual({ left: -640, right: 640, bottom: -360, top: 360 });
+ });
+
+ it('the editor box stays centered on the editor pan', () => {
+ 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,
+ });
+ });
+
+ it('the editor box adapts to the viewport aspect via the scale mode', () => {
+ // A square viewport: Expand keeps the design width, so height grows to 1280.
+ const cam = { entity: EDITOR_VIEW_ENTITY, cameraX: 0, cameraY: 0, halfW: 160, halfH: 90 };
+ expect(uiLayoutRect(cam, canvas, 1000, 1000)).toEqual({
+ left: -640, right: 640, bottom: -640, top: 640,
+ });
+ });
+
+ it('the editor falls back to its own extents when the scene has no canvas', () => {
+ const cam = { entity: EDITOR_VIEW_ENTITY, cameraX: 0, cameraY: 0, halfW: 160, halfH: 90 };
+ expect(uiLayoutRect(cam, null, W, H)).toEqual({
+ left: -160, right: 160, bottom: -90, top: 90,
+ });
+ });
+});
+
+describe('computeEffectiveOrthoSize', () => {
+ const base = 540, designAspect = 1920 / 1080; // 16:9 design, half-height 540
+
+ it('FixedHeight ignores aspect', () => {
+ expect(computeEffectiveOrthoSize(base, designAspect, 2.0, CanvasScaleMode.FixedHeight, 0)).toBe(540);
+ });
+ it('Expand letterboxes (max) on a wider screen', () => {
+ expect(computeEffectiveOrthoSize(base, designAspect, 2.0, CanvasScaleMode.Expand, 0)).toBeCloseTo(540, 0);
+ });
+ it('Shrink crops (min) on a wider screen', () => {
+ expect(computeEffectiveOrthoSize(base, designAspect, 2.0, CanvasScaleMode.Shrink, 0)).toBeCloseTo(480, 0);
+ });
+});