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(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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});