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
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.mdxindex 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` stilcarries an older resolution than the project fit cannot lay UI out one way in theeditor 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.mdxindex 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), whenits `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 letterboxexamples, 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.mdxindex 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.mdxindex 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/)。diff --git a/examples/platformer/assets/scenes/main.esscene b/examples/platformer/assets/scenes/main.essceneindex 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.tsindex 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.tsindex 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 adaptsdiff --git a/sdk/tests/camera-pov.test.ts b/sdk/tests/camera-pov.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.essceneindex 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}