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(project): a project file can ask for the render policy, without asking for a camera fit
yhh264ace180a97
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex 0f3a43d59..33791f805 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -151,6 +151,11 @@ export interface ProjectFeatures {cameraScaleMode?: CameraScaleMode;/** Match-mode blend 0..1 (0 = fit width, 1 = fit height); cameraScaleMode='match' only. */cameraMatch?: number;+ /** Whether the scene renders at its own resolution and is then scaled to the+ * surface. Independent of cameraScaleMode — it takes the camera's world+ * height whatever produced it. Absent/'surface' ⇒ straight to the surface,+ * the zero-regression default. See {@link renderResolutionValue}. */+ renderResolution?: RenderResolutionMode;};/** Project mixer state (bus volumes / custom buses / effects / duck rules). */audio?: AudioProjectConfig;@@ -170,6 +175,11 @@ export type ScreenOrientation = 'portrait' | 'landscape';* the engine's CanvasScaleMode names, plus 'none' = off). See {@link cameraScaleModeValue}. */export type CameraScaleMode = 'none' | 'fixed-width' | 'fixed-height' | 'expand' | 'shrink' | 'match';+/** How the scene's own render resolution is chosen (the engine's RenderResolution+ * names). 'integer' also presents unfiltered, because the engine reads+ * whole-multiple-ness off the rect. See {@link renderResolutionValue}. */+export type RenderResolutionMode = 'surface' | 'design' | 'integer';+/** Per-platform packaging config (the platform-specific Project Settings pages).* Orientation is NOT here — it is one project-wide {@link ProjectPackaging.orientation}* consumed by every target (a landscape build is landscape everywhere). */@@ -567,6 +577,10 @@ export function parseManifest(raw: unknown): ProjectManifest {if (typeof r.cameraMatch === 'number' && Number.isFinite(r.cameraMatch)) {rendering.cameraMatch = Math.min(1, Math.max(0, r.cameraMatch));}+ // Same shape again: only the opt-in persists, 'surface' is absence.+ if (r.renderResolution === 'design' || r.renderResolution === 'integer') {+ rendering.renderResolution = r.renderResolution;+ }if (Object.keys(rendering).length > 0) features.rendering = rendering;}if (f.audio && typeof f.audio === 'object') {@@ -782,10 +796,21 @@ export function cameraScaleModeValue(m: CameraScaleMode | undefined): number {}}+/** The engine's RenderResolution, mirrored the way cameraScaleModeValue mirrors+ * CanvasScaleMode: a number, so this module stays free of the runtime. */+export function renderResolutionValue(m: RenderResolutionMode | undefined): number {+ switch (m) {+ case 'design': return 1;+ case 'integer': return 2;+ default: return 0; // 'surface'+ }+}+/** The runtime screen-fit config (createWebApp `screenFit` / ScreenScaling) for a* project: its design resolution + the mapped camera fit. `scaleMode` -1 ⇒ off. */export function resolveScreenFit(manifest: Pick<ProjectManifest, 'designResolution' | 'features'>): {designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number;+ renderPolicy: number;} {const dr = manifest.designResolution;return {@@ -793,6 +818,7 @@ export function resolveScreenFit(manifest: Pick<ProjectManifest, 'designResolutidesignHeight: dr?.height ?? 1080,scaleMode: cameraScaleModeValue(manifest.features?.rendering?.cameraScaleMode),matchWidthOrHeight: manifest.features?.rendering?.cameraMatch ?? 0.5,+ renderPolicy: renderResolutionValue(manifest.features?.rendering?.renderResolution),};}diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.tsindex ae55d9ef2..61a3c6b2a 100644--- a/pipeline/src/project/runtimeConfig.ts+++ b/pipeline/src/project/runtimeConfig.ts@@ -35,6 +35,8 @@ export interface RuntimeScreenFit {designHeight: number;scaleMode: number;matchWidthOrHeight: number;+ /** The engine's RenderResolution; 0 = straight to the surface. */+ renderPolicy: number;}/**diff --git a/pipeline/tests/project-rendering.test.ts b/pipeline/tests/project-rendering.test.tsindex 700ca41ae..b1ad08f03 100644--- a/pipeline/tests/project-rendering.test.ts+++ b/pipeline/tests/project-rendering.test.ts@@ -7,7 +7,7 @@*/import { describe, it, expect } from 'vitest';import {- parseManifest, cameraScaleModeValue, resolveScreenFit, trimSortingLayers, SORTING_LAYER_COUNT,+ parseManifest, cameraScaleModeValue, renderResolutionValue, resolveScreenFit, trimSortingLayers, SORTING_LAYER_COUNT,} from '../src/project/format';describe('parseManifest — rendering.outputTransform', () => {@@ -123,12 +123,37 @@ describe('cameraScaleModeValue / resolveScreenFit', () => {it('builds the runtime screenFit from design resolution + fit; off by default', () => {expect(resolveScreenFit({ designResolution: { width: 1280, height: 720 } }))- .toEqual({ designWidth: 1280, designHeight: 720, scaleMode: -1, matchWidthOrHeight: 0.5 });+ .toEqual({ designWidth: 1280, designHeight: 720, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0 });expect(resolveScreenFit({designResolution: { width: 1080, height: 1920 },features: { rendering: { cameraScaleMode: 'expand', cameraMatch: 0.25 } },- })).toEqual({ designWidth: 1080, designHeight: 1920, scaleMode: 2, matchWidthOrHeight: 0.25 });+ })).toEqual({ designWidth: 1080, designHeight: 1920, scaleMode: 2, matchWidthOrHeight: 0.25, renderPolicy: 0 });// No design resolution ⇒ the engine default, still off.- expect(resolveScreenFit({})).toEqual({ designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5 });+ expect(resolveScreenFit({})).toEqual({ designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0 });+ });++ it('maps the render resolution, surface by default', () => {+ expect(renderResolutionValue('design')).toBe(1);+ expect(renderResolutionValue('integer')).toBe(2);+ expect(renderResolutionValue('surface')).toBe(0);+ expect(renderResolutionValue(undefined)).toBe(0);+ });++ it('the render policy does NOT need a camera fit', () => {+ // Independent settings: the policy takes the camera's world height whatever+ // produced it. Coupling them forces a project that wants only 1:1 rendering+ // to opt into a design-resolution fit it never asked for.+ expect(resolveScreenFit({ features: { rendering: { renderResolution: 'design' } } }))+ .toEqual({ designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 1 });+ });++ it('persists only the opt-in, like every other rendering feature', () => {+ const on = parseManifest({ name: 'p', features: { rendering: { renderResolution: 'integer' } } });+ expect(on.features?.rendering?.renderResolution).toBe('integer');+ // 'surface' is the default and is expressed by absence, not by a stored word.+ expect(parseManifest({ name: 'p', features: { rendering: { renderResolution: 'surface' } } })+ .features?.rendering?.renderResolution).toBeUndefined();+ expect(parseManifest({ name: 'p', features: { rendering: { renderResolution: 'nonsense' } } })+ .features?.rendering?.renderResolution).toBeUndefined();});});diff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.tsindex 22973e89f..44d2581ed 100644--- a/pipeline/tests/runtime-config.test.ts+++ b/pipeline/tests/runtime-config.test.ts@@ -73,7 +73,7 @@ describe('packagedRuntimeFields', () => {// and a desktop window opens at it. Everything else stays absent so a build// with default settings keeps the config it has always had.expect(packagedRuntimeFields(runtimeConfigOf({}))).toEqual({- screenFit: { designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5 },+ screenFit: { designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0 },});});@@ -100,7 +100,7 @@ describe('packagedRuntimeFields', () => {'ySortLayers'],);expect(fields.screenFit).toEqual({- designWidth: 800, designHeight: 600, scaleMode: 2, matchWidthOrHeight: 0.5,+ designWidth: 800, designHeight: 600, scaleMode: 2, matchWidthOrHeight: 0.5, renderPolicy: 0});});@@ -112,7 +112,7 @@ describe('packagedRuntimeFields', () => {designResolution: { width: 1080, height: 1920 },}));expect(fields.screenFit).toEqual({- designWidth: 1080, designHeight: 1920, scaleMode: -1, matchWidthOrHeight: 0.5,+ designWidth: 1080, designHeight: 1920, scaleMode: -1, matchWidthOrHeight: 0.5, renderPolicy: 0});});diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex b75ce4b76..c35adf6da 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -37,6 +37,7 @@ import { setLinearColorSpace } from '../ecs/env';import { seedEngineComponents } from '../ecs/component';import { cameraPlugin } from '../camera/CameraPlugin';import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from '../camera/ScreenScaling';+import { RenderResolution } from '../camera/presentPlan';import { Physics2DRuntime } from '../physics/Physics2DRuntime';import { SubsystemRegistry } from './subsystems';import { DOMAIN_SCRIPTS, DOMAIN_UNATTRIBUTED, type ScopeCost, type ScopeRemainder, type SystemCost } from './frameProfile';@@ -1514,7 +1515,12 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A// 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) {+ // Either opt-in installs it. The render policy does not need a camera fit —+ // it takes the camera's world height whatever produced it — and gating one on+ // the other made a project that wanted only the policy get neither.+ if (options?.screenFit+ && (options.screenFit.scaleMode > SCREEN_FIT_OFF+ || (options.screenFit.renderPolicy ?? RenderResolution.Surface) !== RenderResolution.Surface)) {app.insertResource(ScreenScaling, { ...options.screenFit });}