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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ScreenScaling.ts
* @brief Project-level screen fit — the design (reference) resolution the game
* 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 Canvas fit when
* present, else the raw orthoSize, so an unconfigured project is unchanged.
*
* When it opts in it is the project's ONE design resolution: the camera fit and the
* UI layout box both resolve through CameraPlugin.resolveFitSource, so a scene whose
* Canvas still carries an older design resolution cannot lay UI out one way while
* authoring and another once it ships.
*
* 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 '../ecs/resource';
import { RenderResolution } from './presentPlan';
/** `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;
/**
* Whether the scene renders at its own resolution and is then scaled to the
* surface, or straight to the surface. See {@link RenderResolution}. Optional
* because a project file written before it existed must still read; absent
* means `Surface`, which is the behaviour every project already had.
*/
renderPolicy?: RenderResolution;
}
/** 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,
renderPolicy: RenderResolution.Surface,
};
export const ScreenScaling = defineResource<ScreenScalingData>({ ...DEFAULT_SCREEN_SCALING }, 'ScreenScaling');