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): opt-in project camera fit, independent of any UI Canvas
yhh8d65d8cf3a44
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined+screenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedwasmBaseUrl: string | undefinedySortLayers: number | undefined@@ -1752,6 +1753,11 @@ numbernumber```+## 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: numbery: 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" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined+screenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedySortLayers: number | undefined```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined+screenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedwasmBaseUrl: string | undefinedySortLayers: number | undefined@@ -1747,6 +1748,11 @@ numbernumber```+## 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: numbery: 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" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined+screenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedySortLayers: number | undefined```diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex 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): Aapp.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.tsindex 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.tsnew file mode 100644index 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.tsindex 04391e6ef..915b90653 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -42,6 +42,8 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTexturexport { 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';