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): opt-in project camera fit, independent of any UI Canvas

yhh8d65d8cf3a44
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index c86101467..f1ecc2575 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: 1165 stable · 17 beta · 1 deprecated
+Symbols: 1169 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -1675,6 +1675,7 @@ colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
+screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
wasmBaseUrl: string | undefined
ySortLayers: number | undefined
@@ -1752,6 +1753,11 @@ number
number
```
+## DEFAULT_SCREEN_SCALING — const
+```
+ScreenScalingData
+```
+
## DEFAULT_SPINE_SKIN — const
```
"default"
@@ -5051,6 +5057,11 @@ ComponentDef<{}>
"1.0"
```
+## SCREEN_FIT_OFF — const
+```
+-1
+```
+
## SIDE_MODULES — const
```
Record<SideModuleId, SideModuleDescriptor>
@@ -5353,6 +5364,19 @@ x: number
y: number
```
+## ScreenScaling — const
+```
+ResourceDef<ScreenScalingData>
+```
+
+## ScreenScalingData — interface
+```
+designHeight: number
+designWidth: number
+matchWidthOrHeight: number
+scaleMode: number
+```
+
## ScrollContainer — class
```
dispose: () => void
@@ -7098,6 +7122,7 @@ colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
+screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index fa8e0898c..ba6c8b76e 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: 1164 stable · 19 beta · 1 deprecated
+Symbols: 1168 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -1670,6 +1670,7 @@ colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
+screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
wasmBaseUrl: string | undefined
ySortLayers: number | undefined
@@ -1747,6 +1748,11 @@ number
number
```
+## DEFAULT_SCREEN_SCALING — const
+```
+ScreenScalingData
+```
+
## DEFAULT_SPINE_SKIN — const
```
"default"
@@ -5046,6 +5052,11 @@ ComponentDef<{}>
"1.0"
```
+## SCREEN_FIT_OFF — const
+```
+-1
+```
+
## SIDE_MODULES — const
```
Record<SideModuleId, SideModuleDescriptor>
@@ -5348,6 +5359,19 @@ x: number
y: number
```
+## ScreenScaling — const
+```
+ResourceDef<ScreenScalingData>
+```
+
+## ScreenScalingData — interface
+```
+designHeight: number
+designWidth: number
+matchWidthOrHeight: number
+scaleMode: number
+```
+
## ScrollContainer — class
```
dispose: () => void
@@ -7093,6 +7117,7 @@ colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
+screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
```
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 79c882662..d0bdb7582 100644
--- a/sdk/src/app.ts
+++ b/sdk/src/app.ts
@@ -26,6 +26,7 @@ import { getDefaultContext } from './context';
import { setLinearColorSpace } from './env';
import { seedEngineComponents } from './component';
import { cameraPlugin } from './camera/CameraPlugin';
+import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from './camera/ScreenScaling';
import { PhysicsRuntime } from './physics/PhysicsRuntime';
import { SubsystemRegistry } from './subsystems';
import type { SideModuleHost } from './sideModules/host';
@@ -1031,6 +1032,14 @@ export interface WebAppOptions {
* Must be declared at app creation — shaders compile against it.
*/
colorSpace?: 'gamma' | 'linear';
+ /**
+ * Project camera fit (Project Settings → Display). When set with a real
+ * scaleMode (≥ 0), the MAIN scene camera letterboxes this design resolution
+ * into the actual aspect regardless of any UI Canvas; omitted / scaleMode = -1
+ * keeps the legacy behavior (Canvas fit when present, else raw orthoSize). See
+ * {@link ScreenScaling}.
+ */
+ screenFit?: ScreenScalingData;
}
export function createWebApp(module: ESEngineModule, options?: WebAppOptions): App {
@@ -1077,6 +1086,13 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
app.addPlugins(options.plugins);
}
+ // Project camera fit: only install the resource when the project opts in (a real
+ // scaleMode). Absent ⇒ CameraPlugin.resolveFitSource sees no resource and keeps
+ // the legacy Canvas-or-raw fit, so an unconfigured game is byte-for-byte unchanged.
+ if (options?.screenFit && options.screenFit.scaleMode > SCREEN_FIT_OFF) {
+ app.insertResource(ScreenScaling, { ...options.screenFit });
+ }
+
return app;
}
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index b64ed5085..bf47ee0cc 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -16,8 +16,9 @@ import type { World } from '../world';
import type { Entity } from '../types';
import { UICameraInfo } from '../ui/core/ui-camera-info';
import { ProjectionType, SceneOwner, ClearFlags } from '../component';
-import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY } from './uiLayoutRect';
+import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type CanvasScale } from './uiLayoutRect';
import { EditorView, DEFAULT_EDITOR_VIEW, type EditorViewData } from './EditorView';
+import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';
import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';
import { RenderPipeline } from '../renderPipeline';
import { Renderer } from '../renderer';
@@ -149,7 +150,7 @@ export function buildCameraInfo(
pov: CameraPOV,
width: number,
height: number,
- canvas: ReturnType<typeof findCanvasData>,
+ canvas: CanvasScale | null,
pool: CameraInfo[],
index: number,
): CameraInfo {
@@ -305,6 +306,27 @@ export function editorCameraInfo(
* `advance` ticks the director's blend; the early UICameraInfo sync peeks (false)
* so it doesn't double-advance the same frame's blend.
*/
+/**
+ * The design-resolution source the MAIN scene camera fits to: the project screen fit
+ * (ScreenScaling) when it opts in (scaleMode ≥ 0), else the scene's UI Canvas (legacy
+ * behavior), else null (raw orthoSize). The project fit works WITHOUT a Canvas and, when
+ * set, is authoritative for the camera — UI layout still reads the Canvas (uiLayoutRect),
+ * so gameplay and UI can scale independently.
+ */
+function resolveFitSource(app: App, canvas: CanvasScale | null): CanvasScale | null {
+ if (app.hasResource(ScreenScaling)) {
+ const s = app.getResource(ScreenScaling);
+ if (s.scaleMode > SCREEN_FIT_OFF) {
+ return {
+ designResolution: { x: s.designWidth, y: s.designHeight },
+ scaleMode: s.scaleMode,
+ matchWidthOrHeight: s.matchWidthOrHeight,
+ };
+ }
+ }
+ return canvas;
+}
+
function resolveCameras(
app: App,
module: ESEngineModule,
@@ -326,7 +348,7 @@ function resolveCameras(
const povs = collectCameraPOVs(module, cppRegistry, width, height, world, activeScenes);
if (povs.length === 0) return [];
- const canvas = findCanvasData(module, cppRegistry);
+ const canvas = resolveFitSource(app, findCanvasData(module, cppRegistry));
const fullFrame = povs.filter((p) => isFullFrame(p.viewport));
const overlays = povs.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);
diff --git a/sdk/src/camera/ScreenScaling.ts b/sdk/src/camera/ScreenScaling.ts
new file mode 100644
index 000000000..1f444702a
--- /dev/null
+++ b/sdk/src/camera/ScreenScaling.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ScreenScaling.ts
+ * @brief Project-level camera fit — the design (reference) resolution the MAIN
+ * scene camera scales against, independent of any UI Canvas.
+ *
+ * The design resolution used to live only on the `Canvas` (UI) component, so a
+ * scene without UI got no design-resolution fit (the camera kept its raw
+ * orthoSize). This resource makes the fit a project/screen concern: when
+ * `scaleMode` is a real {@link CanvasScaleMode} (0..4) the camera letterboxes the
+ * design resolution into the actual aspect exactly as a Canvas would — no UI layer
+ * required. `scaleMode = SCREEN_FIT_OFF` (the default) keeps the legacy behavior
+ * (Canvas fit when present, else raw orthoSize), so an unconfigured project is
+ * unchanged. UI layout still reads the Canvas (see uiLayoutRect); only the camera
+ * fit reads this, so gameplay and UI can fit differently.
+ *
+ * Installed by every runtime; the shipped game / play realm / editor set it from
+ * the project config (design resolution + fit). Read by CameraPlugin.resolveCameras.
+ */
+import { defineResource } from '../resource';
+
+/** `scaleMode` sentinel: no camera fit — the camera uses its own orthoSize (default). */
+export const SCREEN_FIT_OFF = -1;
+
+export interface ScreenScalingData {
+ /** Design (reference) resolution width in px — the horizontal reference the fit uses. */
+ designWidth: number;
+ /** Design (reference) resolution height in px. */
+ designHeight: number;
+ /** A {@link CanvasScaleMode} (FixedWidth=0 … Match=4), or {@link SCREEN_FIT_OFF} (-1). */
+ scaleMode: number;
+ /** Match-mode blend 0..1 (0 = fit width, 1 = fit height); ignored for other modes. */
+ matchWidthOrHeight: number;
+}
+
+/** Off by default (scaleMode = -1) ⇒ zero behavior change for a project that never
+ * opts into a camera fit. Dimensions default to the engine's Canvas default. */
+export const DEFAULT_SCREEN_SCALING: ScreenScalingData = {
+ designWidth: 1920,
+ designHeight: 1080,
+ scaleMode: SCREEN_FIT_OFF,
+ matchWidthOrHeight: 0.5,
+};
+
+export const ScreenScaling = defineResource<ScreenScalingData>({ ...DEFAULT_SCREEN_SCALING }, 'ScreenScaling');
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 04391e6ef..915b90653 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -42,6 +42,8 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
export { CameraView, CameraViewApi } from './camera/Camera';
export { EditorView, DEFAULT_EDITOR_VIEW } from './camera/EditorView';
export type { EditorViewData } from './camera/EditorView';
+export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';
+export type { ScreenScalingData } from './camera/ScreenScaling';
export { EditorGrid, DEFAULT_EDITOR_GRID } from './camera/EditorGrid';
export type { EditorGridData, GridColor } from './camera/EditorGrid';
export { installEditorGrid } from './camera/editorGridRenderer';