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(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.ts
index 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, 'designResoluti
designHeight: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 });
}