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.

feat(camera): orthoSize stays the zoom under a design-resolution fit

yhh1e6c698dcabf
diff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdx
index 249123a59..ff4915eb7 100644
--- a/docs/astro/src/content/docs/core-concepts/screen.mdx
+++ b/docs/astro/src/content/docs/core-concepts/screen.mdx
@@ -143,12 +143,14 @@ there is one design resolution in play at a time — a scene whose `Canvas` stil
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, a full-screen orthographic scene camera's authored
- `orthoSize` is **not used** — the visible half-height comes entirely from the
- design resolution and the scale mode. Sub-viewport cameras, cameras that render
- into a texture and perspective cameras keep their own zoom. Zoom by editing/tweening `orthoSize` only takes effect when no
- fit source is active (no `Canvas` in the scene and `ScreenScaling` off).
+<Aside>
+ While a fit source is active, a full-screen orthographic scene camera's `orthoSize`
+ is its half-height **at the design aspect**; the scale mode adapts it to the screen.
+ It stays the zoom, so editing or tweening it works with a `Canvas` in the scene.
+ The UI layout box is the design resolution fitted to the screen, not the camera's
+ view, so a zoom does not reflow UI. Sub-viewport cameras, cameras that render into a
+ texture and perspective cameras are not fitted. (Up to 0.97 a fit ignored
+ `orthoSize` and always used `designResolution.y / 2`.)
</Aside>
The default scene camera is authored with `orthoSize: 540 = designResolution.y / 2`
diff --git a/docs/astro/src/content/docs/graphics/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdx
index 622d6cd74..2746325c3 100644
--- a/docs/astro/src/content/docs/graphics/camera.mdx
+++ b/docs/astro/src/content/docs/graphics/camera.mdx
@@ -83,26 +83,26 @@ Use `Perspective` only for pseudo-3D layered scenes; leave 2D games on
## Design-resolution fit
-In a shipped game the main camera usually does **not** render its raw `orthoSize`.
-Each frame the engine resolves a *fit source* and, when one is active, letterboxes
-the project's design resolution (default 1920×1080) into the actual screen aspect —
-the visible half-height is computed from `designResolution.y / 2` and a scale mode,
-so world units stay design pixels on every device. The fit source is, in order:
+A shipped game runs on screens of every aspect. Each frame the engine resolves a
+*fit source* and, when one is active, adapts the main camera to the actual screen
+aspect: `orthoSize` is the camera's half-height **at the design aspect**, and the
+scale mode decides what happens on a wider or narrower screen (keep the height, keep
+the width, expand, shrink or match). The fit source is, in order:
1. the **`ScreenScaling`** resource (Settings → Project → Game → Display → Camera fit), when
its `scaleMode` is a real mode (`≥ 0`);
2. else the scene's **`Canvas`** component, if one exists;
3. else none — the camera renders its raw `orthoSize`.
-<Aside type="caution">
- While a fit source is active, the camera's authored `orthoSize` is **not used** —
- the visible area comes from the design resolution and the scale mode. Zooming via
- `orthoSize` (including the tween above) only takes effect with no `Canvas` in the
- scene and the project fit off.
-</Aside>
+`orthoSize` stays the zoom under a fit — the tween above works with a `Canvas` in the
+scene. UI does not follow the zoom: the box UI lays out in is the design resolution
+fitted to the screen, so zooming the camera never reflows it, and screen-space UI is
+drawn through its own projection.
-The default `orthoSize` of `540` is exactly `designResolution.y / 2`, so the fitted
-and unfitted views agree at the design aspect. Scale modes, worked letterbox
+Set `orthoSize` to `designResolution.y / 2` to show exactly the design frame (the
+default `540` matches the default 1080-high design). Up to 0.97 a fit ignored
+`orthoSize` and always used `designResolution.y / 2`; a scene that authored another
+value under a fit now shows that value. Scale modes, worked letterbox
examples, and the `ScreenScaling` fields are covered in
[Screen & Design Resolution](/docs/core-concepts/screen/).
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
index ed0d625b6..6c02abe44 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
@@ -130,10 +130,11 @@ const halfH = computeEffectiveOrthoSize(
场景的 `Canvas` 即使还留着比项目适配更旧的分辨率,也不会出现"编辑器里一个盒子、发行版
里另一个盒子"。
-<Aside type="caution">
- 适配源生效期间,全屏正交场景相机自己写的 `orthoSize` **不会被使用**——可见半高完全来自设计分辨率
- 与缩放模式。子视口相机、渲染到纹理的相机和透视相机保留自己的缩放。通过编辑/tween `orthoSize` 缩放,只在没有适配源时生效(场景无 `Canvas`
- 且项目适配关闭)。
+<Aside>
+ 适配源生效期间,全屏正交场景相机的 `orthoSize` 是它**在设计宽高比下**的半高,缩放模式再把它适配到
+ 实际屏幕。它仍然是缩放,场景里有 `Canvas` 时编辑或 tween 它同样生效。UI 布局框是适配到屏幕的设计
+ 分辨率,而不是相机的视野,所以缩放不会让 UI 重新排版。子视口相机、渲染到纹理的相机和透视相机不参与
+ 适配。(0.97 及之前,适配会忽略 `orthoSize`、固定使用 `designResolution.y / 2`。)
</Aside>
默认场景相机写的正是 `orthoSize: 540 = designResolution.y / 2`,所以有无适配的视图在设计
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
index 745ae33b3..03632dedd 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
@@ -77,24 +77,21 @@ const zoomIn = defineSystem([Res(Tween)], (tween) => {
## 设计分辨率适配
-发布的游戏里,主相机通常**不会**按原始 `orthoSize` 渲染。引擎每帧解析一个*适配源*,当其
-生效时,把项目的设计分辨率(默认 1920×1080)letterbox 进实际屏幕宽高比——可见半高由
-`designResolution.y / 2` 加一个缩放模式算出,让世界单位在任何设备上都是设计像素。适配源
-按此顺序:
+发布的游戏会跑在各种宽高比的屏幕上。引擎每帧解析一个*适配源*,当其生效时,把主相机适配到
+实际屏幕的宽高比:`orthoSize` 是相机**在设计宽高比下**的半高,缩放模式决定屏幕更宽或更窄时
+怎么处理(保持高度、保持宽度、扩展、收缩或按比例混合)。适配源按此顺序:
1. **`ScreenScaling`** 资源(设置 → 项目 → 游戏 → 显示 → 相机适配),当其 `scaleMode` 是真实模式
(`≥ 0`)时;
2. 否则,场景的 **`Canvas`** 组件(若存在);
3. 否则无——相机按原始 `orthoSize` 渲染。
-<Aside type="caution">
- 适配源生效期间,相机自己写的 `orthoSize` **不会被使用**——可见区域来自设计分辨率与
- 缩放模式。通过 `orthoSize` 缩放(含上面的 tween)只在场景无 `Canvas` 且项目适配关闭时
- 生效。
-</Aside>
+有适配时 `orthoSize` 仍然是缩放——场景里有 `Canvas` 时上面的 tween 同样生效。UI 不跟随缩放:
+UI 的布局框是适配到屏幕的设计分辨率,缩放相机不会让 UI 重新排版,屏幕空间 UI 也走自己的投影。
-默认 `orthoSize` 为 `540`,恰是 `designResolution.y / 2`,所以有无适配的视图在设计宽高比
-下一致。缩放模式、letterbox 实例与 `ScreenScaling` 字段详见
+想正好显示设计画面,就把 `orthoSize` 设为 `designResolution.y / 2`(默认的 `540` 对应默认 1080
+高的设计分辨率)。0.97 及之前,适配会忽略 `orthoSize`、固定使用 `designResolution.y / 2`;在适配下
+写了其它值的场景,现在会按那个值显示。缩放模式、letterbox 实例与 `ScreenScaling` 字段详见
[屏幕与设计分辨率](/docs/zh-cn/core-concepts/screen/)。
![第三人称示例:相机跟在角色身后,前方是树木之间的台阶](@/assets/guides/zh/play-third-person.png)
diff --git a/examples/platformer/assets/scenes/main.esscene b/examples/platformer/assets/scenes/main.esscene
index 9410ee3bb..03457c881 100644
--- a/examples/platformer/assets/scenes/main.esscene
+++ b/examples/platformer/assets/scenes/main.esscene
@@ -28,7 +28,7 @@
"type": "Camera",
"data": {
"projectionType": 1,
- "orthoSize": 350,
+ "orthoSize": 300,
"isActive": true,
"priority": 0
}
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 21e0cafd3..c6c7f20ee 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -307,10 +307,15 @@ export function buildCameraInfo(
if (pov.projection === ProjectionType.Orthographic) {
halfH = pov.orthoSize;
if (canvas && (pov.renderTarget ?? 0) === 0 && isFullFrame(pov.viewport)) {
- const baseOrthoSize = canvas.designResolution.y / 2;
+ // The fit adapts the camera's OWN size to the screen's aspect — it does
+ // not replace it. orthoSize is the camera's half-height at the design
+ // aspect, so it stays the zoom a script or a tween drives; it used to be
+ // discarded for designResolution.y / 2 whenever a Canvas or the project
+ // fit was active, and zooming did nothing. The UI box is the design's,
+ // not the camera's (see uiLayoutRect), so a zoom does not reflow UI.
const designAspect = canvas.designResolution.x / canvas.designResolution.y;
halfH = computeEffectiveOrthoSize(
- baseOrthoSize, designAspect, aspect,
+ pov.orthoSize, designAspect, aspect,
canvas.scaleMode, canvas.matchWidthOrHeight,
);
}
diff --git a/sdk/src/camera/uiLayoutRect.ts b/sdk/src/camera/uiLayoutRect.ts
index 906ad94f2..686563d2a 100644
--- a/sdk/src/camera/uiLayoutRect.ts
+++ b/sdk/src/camera/uiLayoutRect.ts
@@ -87,9 +87,10 @@ export const EDITOR_UI_ANCHOR = { x: 0, y: 0 } as const;
* 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 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
+ * A scene camera's extents carry its zoom (`orthoSize` fitted to the screen), so
+ * under a fit its box is the design resolution fitted to the camera's aspect and
+ * centred on the camera — UINode px map 1:1 to design px and a zoom does not reflow
+ * the UI. Without a fit the box is the camera's extents. 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
@@ -112,7 +113,18 @@ export function uiLayoutRect(
let centerX = cam.cameraX;
let centerY = cam.cameraY;
- if (cam.entity === EDITOR_VIEW_ENTITY && fit && width > 0 && height > 0) {
+ if (cam.entity !== EDITOR_VIEW_ENTITY && fit && cam.halfH > 0) {
+ // A scene camera's extents carry its zoom (orthoSize), which UI must not
+ // follow: the box is the design resolution fitted to the camera's aspect,
+ // centred where the camera looks. At orthoSize = designResolution.y / 2 it
+ // is exactly the camera's extents, as it always was.
+ const camAspect = cam.halfW / cam.halfH;
+ const designAspect = fit.designResolution.x / fit.designResolution.y;
+ halfH = computeEffectiveOrthoSize(
+ fit.designResolution.y / 2, designAspect, camAspect, fit.scaleMode, fit.matchWidthOrHeight,
+ );
+ halfW = halfH * camAspect;
+ } else 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
diff --git a/sdk/tests/camera-pov.test.ts b/sdk/tests/camera-pov.test.ts
index 585175ac3..c1dc45721 100644
--- a/sdk/tests/camera-pov.test.ts
+++ b/sdk/tests/camera-pov.test.ts
@@ -68,8 +68,13 @@ describe('camera POV → view-projection', () => {
const cam = buildCameraInfo(pov({ orthoSize: 100, ...over }), 800, 600, fit, [], 0);
expect(cam.halfH).toBe(100);
expect(ndc(cam.viewProjection, 0, 100).y).toBeCloseTo(1);
+ // The full-screen camera is fitted too, but around its OWN size: orthoSize is
+ // the zoom, and FixedHeight keeps it as the half-height.
const main = buildCameraInfo(pov({ orthoSize: 100 }), 800, 600, fit, [], 0);
- expect(main.halfH).toBe(540);
+ expect(main.halfH).toBe(100);
+ // FixedWidth keeps the design's width instead: 100 at 16:9 is 177.8 wide, on 4:3.
+ const wide = buildCameraInfo(pov({ orthoSize: 100 }), 800, 600, { ...fit, scaleMode: 0 }, [], 0);
+ expect(wide.halfW).toBeCloseTo(100 * 1920 / 1080);
});
it('rotation 0 keeps the old translation-only view (center → clip origin)', () => {
diff --git a/sdk/tests/camera-render-order.test.ts b/sdk/tests/camera-render-order.test.ts
index f2c7c11f2..970566b33 100644
--- a/sdk/tests/camera-render-order.test.ts
+++ b/sdk/tests/camera-render-order.test.ts
@@ -82,7 +82,7 @@ describe('render order: transforms resolve before cameras are read', () => {
const registry = module.getRegistry() as unknown as Record<string, unknown> & CppRegistry;
const cam = app.world.spawn('camera') as Entity;
app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 0 } });
- app.world.insert(cam, Camera, { isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 180 });
+ app.world.insert(cam, Camera, { isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 300 });
registry.getCameraEntities = () => [cam];
registry.getCanvasEntities = () => [];
app.setPipeline(new RenderPipeline());
@@ -115,10 +115,13 @@ describe('render order: transforms resolve before cameras are read', () => {
app.setPipeline(new RenderPipeline());
setRendererBackend(fakeBackend(registry, [cam]));
app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
- app.insertResource(ScreenScaling, { designWidth: 800, designHeight: 600, scaleMode: 1, matchWidthOrHeight: 0.5 });
+ // FixedWidth on a wider design than the screen: the fit changes what the
+ // camera shows, so a preview that skipped it would not match the game.
+ app.insertResource(ScreenScaling, { designWidth: 1000, designHeight: 600, scaleMode: 0, matchWidthOrHeight: 0.5 });
await app.tick(1 / 60);
const gameProjection = Array.from(lastViewProjection!);
- expect(ndcX(lastViewProjection!, 400, 0)).toBeCloseTo(1);
+ // The raw camera would put x = 400 (orthoSize 300 at 4:3) on the edge.
+ expect(Math.abs(ndcX(lastViewProjection!, 400, 0) - 1)).toBeGreaterThan(0.05);
app.world.update(cam, Camera, data => { data.isActive = false; });
expect(renderCameraFrame(app, 800, 600, cam)).toBe(true);
expect(Array.from(lastViewProjection!)).toEqual(gameProjection);
diff --git a/sdk/tests/ui-layout-rect.test.ts b/sdk/tests/ui-layout-rect.test.ts
index 17d2cb2ca..c72a680d6 100644
--- a/sdk/tests/ui-layout-rect.test.ts
+++ b/sdk/tests/ui-layout-rect.test.ts
@@ -91,3 +91,15 @@ describe('computeEffectiveOrthoSize', () => {
expect(computeEffectiveOrthoSize(base, designAspect, 2.0, CanvasScaleMode.Shrink, 0)).toBeCloseTo(480, 0);
});
});
+
+describe('uiLayoutRect under a camera zoom', () => {
+ it('keeps the design box while the scene camera zooms, centred on the camera', () => {
+ const fit = { designResolution: { x: 1920, y: 1080 }, scaleMode: 1, matchWidthOrHeight: 0.5 };
+ // Zoomed in 2x: the camera shows half the design height.
+ const rect = uiLayoutRect({ entity: 5, cameraX: 100, cameraY: -40, halfW: 270 * 16 / 9, halfH: 270 }, fit, 1920, 1080);
+ expect(rect.top - rect.bottom).toBeCloseTo(1080);
+ expect(rect.right - rect.left).toBeCloseTo(1920);
+ expect((rect.left + rect.right) / 2).toBeCloseTo(100);
+ expect((rect.top + rect.bottom) / 2).toBeCloseTo(-40);
+ });
+});
diff --git a/sdk/tests/ui-nested-canvas-wasm.test.ts b/sdk/tests/ui-nested-canvas-wasm.test.ts
index 63e251719..dca4dbebf 100644
--- a/sdk/tests/ui-nested-canvas-wasm.test.ts
+++ b/sdk/tests/ui-nested-canvas-wasm.test.ts
@@ -23,20 +23,22 @@ describe.skipIf(!HAS_WASM)('nested canvas layout and ordering on real WASM', ()
});
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 } });
+ // Different aspects under FixedWidth tell the canvases apart: the outer one
+ // (4:3 on a 4:3 screen) leaves orthoSize 300 as it is, the nested one (8:3) doubles it.
+ world.insert(child, Canvas, { designResolution: { x: 160, y: 60 }, scaleMode: 0 });
+ world.insert(root, Canvas, { designResolution: { x: 800, y: 600 }, scaleMode: 0 });
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);
+ world.insert(camera, Transform); world.insert(camera, Camera, { isActive: true, orthoSize: 300 });
+ expect(collectCameras(engine, registry, 800, 600, world)[0].halfH).toBeCloseTo(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, Canvas, { designResolution: { x: 160, y: 60 }, scaleMode: 0 });
world.insert(paused, SceneOwner, { scene: 'paused' });
- world.insert(running, Canvas, { designResolution: { x: 800, y: 600 } });
+ world.insert(running, Canvas, { designResolution: { x: 800, y: 600 }, scaleMode: 0 });
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);
+ world.insert(camera, Transform); world.insert(camera, Camera, { isActive: true, orthoSize: 300 });
+ expect(collectCameras(engine, registry, 800, 600, world, new Set(['running']))[0].halfH).toBeCloseTo(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;
diff --git a/templates/2d-platformer/assets/scenes/main.esscene b/templates/2d-platformer/assets/scenes/main.esscene
index 44c9535bc..85b022de4 100644
--- a/templates/2d-platformer/assets/scenes/main.esscene
+++ b/templates/2d-platformer/assets/scenes/main.esscene
@@ -28,7 +28,7 @@
"type": "Camera",
"data": {
"projectionType": 1,
- "orthoSize": 350,
+ "orthoSize": 300,
"isActive": true,
"priority": 0
}