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.

refactor(render): a device says what it can do, a project says what it should

esengine1ec585758fcc
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index 33791f805..d1052d3e3 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -140,6 +140,10 @@ export interface ProjectFeatures {
* 'aces' engages the capture on its own, so it applies with an empty effect
* stack. Absent ⇒ none, which is the exact round trip flat content wants. */
outputTransform?: 'aces';
+ /** Multisampling for the scene target: 1 turns it off, 4 is the default and
+ * what a browser gives its own drawing buffer. Clamped by what the device
+ * supports. A low-end target turns this down; nothing else should. */
+ msaa?: 1 | 2 | 4 | 8;
/** GPU backend a shipped build asks for. 'webgpu' takes it where the machine
* serves one and falls back to WebGL2 where it does not, so a project can
* opt in without giving up the browsers that have neither. Absent ⇒ WebGL2,
@@ -567,6 +571,8 @@ export function parseManifest(raw: unknown): ProjectManifest {
if (r.colorSpace === 'linear') rendering.colorSpace = 'linear';
// Same shape: only the curve persists, no transform is absence.
if (r.outputTransform === 'aces') rendering.outputTransform = 'aces';
+ // Only a NON-default count persists; 4 is absence, like the fields above.
+ if (r.msaa === 1 || r.msaa === 2 || r.msaa === 8) rendering.msaa = r.msaa;
// Same shape: only the opt-in persists, WebGL2 is absence.
if (r.backend === 'webgpu') rendering.backend = 'webgpu';
// Camera fit — 'none' (off) is the default, expressed by absence.
diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.ts
index 61a3c6b2a..a881bb026 100644
--- a/pipeline/src/project/runtimeConfig.ts
+++ b/pipeline/src/project/runtimeConfig.ts
@@ -71,6 +71,9 @@ export interface RuntimeProjectConfig {
colorSpace: 'gamma' | 'linear';
/** The curve on the way to the display; 'none' is the default. */
outputTransform: 'none' | 'aces';
+ /** Scene-target multisampling the project asks for; 4 is the default. The
+ * device clamps it — this is the policy half, never the capability. */
+ msaaSamples: number;
/** GPU backend the build asks for; 'webgl2' is the default. Boot-fixed, and a
* request for 'webgpu' still falls back where the machine has none. */
renderBackend: 'webgl2' | 'webgpu';
@@ -78,6 +81,11 @@ export interface RuntimeProjectConfig {
screenFit: RuntimeScreenFit;
}
+/** Only the counts a target can actually be created with; anything else is 4. */
+function msaaOf(v: unknown): number {
+ return v === 1 || v === 2 || v === 8 ? v : 4;
+}
+
/** Bit i set ⇒ sorting layer i is in `list`. Layers outside 0..31 have no bit. */
function layerMask(list: readonly number[] | undefined): number {
let mask = 0;
@@ -147,6 +155,7 @@ export function runtimeConfigOf(
depthLayers: layerMask(f?.rendering?.depthLayers),
colorSpace: f?.rendering?.colorSpace === 'linear' ? 'linear' : 'gamma',
outputTransform: f?.rendering?.outputTransform === 'aces' ? 'aces' : 'none',
+ msaaSamples: msaaOf(f?.rendering?.msaa),
renderBackend: f?.rendering?.backend === 'webgpu' ? 'webgpu' : 'webgl2',
screenFit: resolveScreenFit(manifest),
};
@@ -156,6 +165,7 @@ export function runtimeConfigOf(
export type PackagedRuntimeFields = Pick<
PackagedGameConfig,
'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'renderBackend' | 'screenFit'
+ | 'msaaSamples'
| 'uiTheme' | 'uiThemeColors'
| 'physicsEnabled' | 'physicsConfig' | 'audioConfig' | 'achievements' | 'steamAppId'
>;
@@ -175,6 +185,7 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime
...(rc.depthLayers ? { depthLayers: rc.depthLayers } : {}),
...(rc.colorSpace === 'linear' ? { colorSpace: rc.colorSpace } : {}),
...(rc.outputTransform === 'aces' ? { outputTransform: rc.outputTransform } : {}),
+ ...(rc.msaaSamples !== 4 ? { msaaSamples: rc.msaaSamples } : {}),
...(rc.renderBackend === 'webgpu' ? { renderBackend: rc.renderBackend } : {}),
// ALWAYS, even with the fit off (`scaleMode < 0`): it carries the design
// resolution, which is what a desktop window opens at. One representation, or
diff --git a/pipeline/tests/project-rendering.test.ts b/pipeline/tests/project-rendering.test.ts
index b1ad08f03..ffb1c2bdd 100644
--- a/pipeline/tests/project-rendering.test.ts
+++ b/pipeline/tests/project-rendering.test.ts
@@ -26,6 +26,25 @@ describe('parseManifest — rendering.outputTransform', () => {
});
});
+describe('parseManifest — rendering.msaa', () => {
+ // The parser is a whitelist, and a field the TYPE declares but the parser
+ // never reads is dropped in silence: the setting rides the manifest, survives
+ // the type check, and reaches the export as nothing at all.
+ it('keeps a non-default sample count', () => {
+ for (const v of [1, 2, 8] as const) {
+ const m = parseManifest({ name: 'X', features: { rendering: { msaa: v } } });
+ expect(m.features?.rendering?.msaa).toBe(v);
+ }
+ });
+
+ it('drops 4 (default = absence) and counts no target can be made with', () => {
+ for (const v of [4, 3, 16, 0, -1, '4', true, null]) {
+ const m = parseManifest({ name: 'X', features: { rendering: { msaa: v } } });
+ expect(m.features?.rendering?.msaa).toBeUndefined();
+ }
+ });
+});
+
describe('parseManifest — rendering.colorSpace', () => {
it("keeps 'linear'", () => {
const m = parseManifest({ name: 'X', features: { rendering: { colorSpace: 'linear' } } });
diff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.ts
index 44d2581ed..cc5e1fa3f 100644
--- a/pipeline/tests/runtime-config.test.ts
+++ b/pipeline/tests/runtime-config.test.ts
@@ -20,6 +20,9 @@ describe('runtimeConfigOf', () => {
expect(rc.ySortLayers).toBe(0);
expect(rc.depthLayers).toBe(0);
expect(rc.colorSpace).toBe('gamma');
+ // The device clamps this later; 4 is what the project asks for by default,
+ // which is what a browser gives its own drawing buffer.
+ expect(rc.msaaSamples).toBe(4);
expect(rc.outputTransform).toBe('none');
expect(rc.uiTheme).toBe('dark');
expect(rc.uiThemeColors).toEqual({});
@@ -90,14 +93,14 @@ describe('packagedRuntimeFields', () => {
features: {
rendering: {
ySortLayers: [1], depthLayers: [2], colorSpace: 'linear',
- outputTransform: 'aces', cameraScaleMode: 'expand',
+ outputTransform: 'aces', cameraScaleMode: 'expand', msaa: 1,
},
ui: { theme: 'light', colors: { accent: '#ff0000ff' } },
},
}));
expect(Object.keys(fields).sort()).toEqual(
- ['colorSpace', 'depthLayers', 'outputTransform', 'screenFit', 'uiTheme', 'uiThemeColors',
- 'ySortLayers'],
+ ['colorSpace', 'depthLayers', 'msaaSamples', 'outputTransform', 'screenFit', 'uiTheme',
+ 'uiThemeColors', 'ySortLayers'],
);
expect(fields.screenFit).toEqual({
designWidth: 800, designHeight: 600, scaleMode: 2, matchWidthOrHeight: 0.5, renderPolicy: 0
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 231ec6171..4aec7628d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2334,6 +2334,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -5312,6 +5313,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
+msaaSamples: number | undefined
outputTransform: "none" | "aces" | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
@@ -6050,6 +6052,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setMsaaSamples: (samples: number) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setPresentRequired: (required: boolean) => void
@@ -9652,6 +9655,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -11695,7 +11699,7 @@ NavPlugin
## packagedAppOptions — function @experimental
```
-(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; msaaSamples?: number; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
```
## packagedRuntimeInit — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c8c0eaeec..44445021b 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2342,6 +2342,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -5495,6 +5496,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
+msaaSamples: number | undefined
outputTransform: "none" | "aces" | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
@@ -6233,6 +6235,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setMsaaSamples: (samples: number) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setPresentRequired: (required: boolean) => void
@@ -9845,6 +9848,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -11938,7 +11942,7 @@ NavPlugin
## packagedAppOptions — function @experimental
```
-(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; msaaSamples?: number; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
```
## packagedRuntimeInit — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 01cb063cf..af7079455 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2329,6 +2329,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -5307,6 +5308,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
+msaaSamples: number | undefined
outputTransform: "none" | "aces" | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
@@ -6045,6 +6047,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setMsaaSamples: (samples: number) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setPresentRequired: (required: boolean) => void
@@ -9647,6 +9650,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -11700,7 +11704,7 @@ NodePlatformAdapter
## packagedAppOptions — function @experimental
```
-(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; msaaSamples?: number; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
```
## packagedRuntimeInit — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index cdff07604..52c5f942f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2329,6 +2329,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -5553,6 +5554,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
+msaaSamples: number | undefined
outputTransform: "none" | "aces" | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
@@ -6291,6 +6293,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setMsaaSamples: (samples: number) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setPresentRequired: (required: boolean) => void
@@ -9899,6 +9902,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -11957,7 +11961,7 @@ NavPlugin
## packagedAppOptions — function @experimental
```
-(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; msaaSamples?: number; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
```
## packagedRuntimeInit — function @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index cf3505de7..f3788fb3b 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -324,6 +324,7 @@ postprocess_init: (width: number, height: number) => boolean
postprocess_isInitialized: () => boolean
postprocess_resize: (width: number, height: number) => void
postprocess_setBypass: (bypass: boolean) => void
+postprocess_setMsaaSamples: (samples: number) => void
postprocess_setOutputTransform: ((transform: number) => void) | undefined
postprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => void
postprocess_setPassScale: (name: string, scale: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8cb12419b..f7fa6ee7f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2329,6 +2329,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -5314,6 +5315,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
entryScene: string
hotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined
+msaaSamples: number | undefined
outputTransform: "none" | "aces" | undefined
physicsConfig: Physics2DPluginConfig | undefined
physicsEnabled: boolean | undefined
@@ -6052,6 +6054,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setMsaaSamples: (samples: number) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setPresentRequired: (required: boolean) => void
@@ -9675,6 +9678,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+msaaSamples: number | undefined
outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
@@ -11723,7 +11727,7 @@ NavPlugin
## packagedAppOptions — function @experimental
```
-(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
+(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces"; msaaSamples?: number; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }
```
## packagedRuntimeInit — function @experimental
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index d8df71890..24f568dd2 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -1628,6 +1628,12 @@ export interface WebAppOptions {
* is not yet a field of the project manifest. See {@link OutputTransform}.
*/
outputTransform?: OutputTransform;
+ /**
+ * Scene-target multisampling (Project Settings → Rendering). 1 turns it off;
+ * 4 is the default and what a browser gives its own drawing buffer. The
+ * device clamps it, so this is what the project WANTS, not what it gets.
+ */
+ msaaSamples?: number;
/**
* Seed the engine's randomness so this run reproduces — a replay, a bug
* report, a pixel assertion. Absent, every run differs, which is what a
@@ -1695,6 +1701,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
// pipeline is created by the renderer, and a curve declared before it exists
// reaches nothing.
module.postprocess_setOutputTransform?.(outputTransformCode(options?.outputTransform));
+ module.postprocess_setMsaaSamples?.((options?.msaaSamples ?? 4) >>> 0);
app.addPlugin(corePlugin);
app.setPipeline(new RenderPipeline());
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 77168a796..8f618f66d 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -93,6 +93,7 @@ export interface NativeEngineApi {
postprocess_isInitialized?(): boolean;
postprocess_resize?(width: number, height: number): void;
postprocess_setBypass?(bypass: boolean): void;
+ postprocess_setMsaaSamples?(samples: number): void;
postprocess_setOutputTransform?(transform: number): void;
postprocess_setOutputViewport?(x: number, y: number, w: number, h: number): void;
postprocess_setPassScale?(passName: string, scale: number): void;
@@ -330,6 +331,7 @@ export function createNativeEngineApi(
bind('postprocess_isInitialized', 'es_postprocess_isInitialized', false);
bind('postprocess_resize', 'es_postprocess_resize', false);
bind('postprocess_setBypass', 'es_postprocess_setBypass', false);
+ bind('postprocess_setMsaaSamples', 'es_postprocess_setMsaaSamples', false);
bind('postprocess_setOutputTransform', 'es_postprocess_setOutputTransform', false);
bind('postprocess_setOutputViewport', 'es_postprocess_setOutputViewport', false);
bind('postprocess_setPassScale', 'es_postprocess_setPassScale', false);
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index bfa1e04eb..033e05530 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -19,7 +19,8 @@ type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
| 'postprocess_clearPasses' | 'postprocess_addPass' | 'postprocess_setPassScale'
| 'postprocess_setPassTexture'
| 'postprocess_setUniformFloat' | 'postprocess_setUniformVec4'
- | 'postprocess_setBypass' | 'postprocess_setOutputTransform' | 'postprocess_setPresentRequired'
+ | 'postprocess_setBypass' | 'postprocess_setOutputTransform' | 'postprocess_setMsaaSamples'
+ | 'postprocess_setPresentRequired'
| 'postprocess_setOutputViewport'
| 'postprocess_beginScreenCapture' | 'postprocess_endScreenCapture'
| 'postprocess_executeScreenPasses' | 'postprocess_addScreenPass'
@@ -256,6 +257,19 @@ export class PostProcessAPI {
}
}
+ /**
+ * Multisampling the scene target should rasterise with; 1 turns it off. The
+ * device clamps it, so this is the project's ASK, not what it gets — a
+ * backend with no MSAA answers 1 whatever is set here.
+ */
+ setMsaaSamples(samples: number): void {
+ try {
+ getModule().postprocess_setMsaaSamples(samples >>> 0);
+ } catch (e) {
+ handleWasmError(e, 'PostProcess.setMsaaSamples');
+ }
+ }
+
begin(): void {
try {
getModule().postprocess_begin();
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index 28878eb8c..03e2f5d5e 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -55,6 +55,9 @@ export interface PackagedGameConfig {
colorSpace?: 'gamma' | 'linear';
/** The curve the frame applies on the way to the display; absent = none. */
outputTransform?: 'none' | 'aces';
+ /** Scene-target multisampling the project asked for; absent ⇒ 4. Clamped by
+ * the device, which answers capability and never policy. */
+ msaaSamples?: number;
/** GPU backend the build asks for; absent ⇒ WebGL2. A request for
* 'webgpu' falls back where the machine cannot serve one. */
renderBackend?: 'webgl2' | 'webgpu';
@@ -161,12 +164,14 @@ export function registerPackagedSideModules(config: Pick<PackagedGameConfig, 'si
*/
export function packagedAppOptions(
config: Pick<PackagedGameConfig,
- 'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'screenFit'>,
+ 'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'screenFit'
+ | 'msaaSamples'>,
): {
ySortLayers?: number;
depthLayers?: number;
colorSpace?: 'gamma' | 'linear';
outputTransform?: 'none' | 'aces';
+ msaaSamples?: number;
/** GPU backend the build asks for; absent ⇒ WebGL2. A request for
* 'webgpu' falls back where the machine cannot serve one. */
renderBackend?: 'webgl2' | 'webgpu';
@@ -177,6 +182,7 @@ export function packagedAppOptions(
depthLayers: config.depthLayers,
colorSpace: config.colorSpace,
outputTransform: config.outputTransform,
+ msaaSamples: config.msaaSamples,
screenFit: config.screenFit,
};
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 3c0986794..b81c021cb 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -397,6 +397,7 @@ export interface ESEngineModule {
postprocess_resize(width: number, height: number): void;
postprocess_addPass(name: string, shaderHandle: number): number;
postprocess_setPassScale(name: string, scale: number): void;
+ postprocess_setMsaaSamples(samples: number): void;
postprocess_setUniformFloat(passName: string, uniform: string, value: number): void;
postprocess_setPassTexture(passName: string, uniform: string, textureHandle: number): void;
postprocess_setUniformVec4(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index 739870618..dec077b08 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -65,6 +65,10 @@ u32 postprocess_addPass(const std::string& name, u32 shaderHandle) {
return g_postProcessPipeline->addPass(name, resource::ShaderHandle(shaderHandle));
}
+void postprocess_setMsaaSamples(u32 samples) {
+ if (g_postProcessPipeline) g_postProcessPipeline->setRequestedSamples(samples);
+}
+
void postprocess_setPassScale(const std::string& passName, f32 scale) {
if (g_postProcessPipeline) {
g_postProcessPipeline->setPassScale(passName, scale);
diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hpp
index 0db9f2514..d9d8f37ba 100644
--- a/src/esengine/bindings/PostProcessBindings.hpp
+++ b/src/esengine/bindings/PostProcessBindings.hpp
@@ -12,6 +12,9 @@ bool postprocess_init(u32 width, u32 height);
void postprocess_shutdown();
void postprocess_resize(u32 width, u32 height);
u32 postprocess_addPass(const std::string& name, u32 shaderHandle);
+/** The project's multisampling request for the scene target; 1 = off. Clamped
+ * by what the device supports — the device answers capability, not policy. */
+void postprocess_setMsaaSamples(u32 samples);
/** Draw a pass at a fraction of the chain size; the next pass upsamples it. */
void postprocess_setPassScale(const std::string& passName, f32 scale);
void postprocess_setUniformFloat(const std::string& passName,
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 5741155c9..2e86f782b 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -572,6 +572,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("postprocess_resize", &esengine::postprocess_resize);
emscripten::function("postprocess_addPass", &esengine::postprocess_addPass);
emscripten::function("postprocess_setPassScale", &esengine::postprocess_setPassScale);
+ emscripten::function("postprocess_setMsaaSamples", &esengine::postprocess_setMsaaSamples);
emscripten::function("postprocess_setUniformFloat", &esengine::postprocess_setUniformFloat);
emscripten::function("postprocess_setUniformVec4", &esengine::postprocess_setUniformVec4);
emscripten::function("postprocess_setPassTexture", &esengine::postprocess_setPassTexture);
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index e0ddddb44..bff013902 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -63,9 +63,7 @@ void PostProcessPipeline::init(u32 width, u32 height) {
return;
}
- // Capped at 4: what a browser offers a drawing buffer, past which a sample
- // buys less than its bandwidth. A backend with no MSAA answers 1.
- scene_samples_ = std::min(4u, device_.maxSamples());
+ applySampleRequest();
initialized_ = true;
}
@@ -242,6 +240,21 @@ u32 PostProcessPipeline::addPass(const std::string& name, resource::ShaderHandle
return static_cast<u32>(passes_.size() - 1);
}
+/**
+ * The device answers what it CAN do; the project says what it SHOULD do. The
+ * effective count is the second clamped by the first — a backend must never
+ * pick the quality level, or every low-end target inherits whatever its driver
+ * happens to allow.
+ */
+void PostProcessPipeline::applySampleRequest() {
+ scene_samples_ = std::clamp(requested_samples_, 1u, device_.maxSamples());
+}
+
+void PostProcessPipeline::setRequestedSamples(u32 samples) {
+ requested_samples_ = samples < 1u ? 1u : samples;
+ if (initialized_) applySampleRequest();
+}
+
void PostProcessPipeline::setPassScale(const std::string& passName, f32 scale) {
if (auto* pass = findPass(passName)) {
// A pass that draws at zero has no pixels and one that draws above the
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index 0d9a248a3..807688eae 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -133,6 +133,8 @@ public:
* @return Index of the added pass
*/
u32 addPass(const std::string& name, resource::ShaderHandle shader);
+ /// The project's multisampling request; 1 = off. Clamped by the device.
+ void setRequestedSamples(u32 samples);
/// Draw @p passName at @p scale of the chain size (clamped to (0, 1]).
void setPassScale(const std::string& passName, f32 scale);
@@ -402,8 +404,13 @@ private:
bool bypass_ = false;
bool linear_output_ = false;
bool scene_needs_depth_ = false;
- /// Samples the scene target rasterises with; the backend's ceiling, capped.
+ /// What the PROJECT asked for (policy). 4 matches what a browser gives its
+ /// own drawing buffer, which is the quality a chain-less frame always had.
+ u32 requested_samples_ = 4;
+ /// What the scene target actually rasterises with: the request clamped by
+ /// the device's ceiling. Never read the ceiling as if it were the answer.
u32 scene_samples_ = 1;
+ void applySampleRequest();
OutputTransform output_transform_ = OutputTransform::None;
/// The graph resource the scene is drawn into, live between begin() and end().
rg::ResourceId sceneResource_ = rg::kNoResource;
diff --git a/tools/check-postfx-aa.mjs b/tools/check-postfx-aa.mjs
index b3b694917..8b66fa04c 100644
--- a/tools/check-postfx-aa.mjs
+++ b/tools/check-postfx-aa.mjs
@@ -30,28 +30,44 @@ const findings = [];
const pipe = read(PIPE_CPP);
// 1. The scene target — the one target geometry is rasterised into — takes its
-// sample count from the member, never from a literal.
+// sample count from the effective member, never from a literal.
const assign = /sceneDesc\.samples\s*=\s*([^;]+);/.exec(pipe);
if (!assign) {
findings.push(`${PIPE_CPP}: the scene target sets no sample count — a post chain would `
+ 'draw the scene single-sampled and the frame would lose its edges.');
} else if (assign[1].trim() !== 'scene_samples_') {
findings.push(`${PIPE_CPP}: the scene target's sample count is \`${assign[1].trim()}\`, not `
- + 'scene_samples_. A literal here is how the chain silently drops antialiasing; '
- + 'the count belongs to the target and comes from the device.');
+ + 'scene_samples_. A literal here is how the chain silently drops antialiasing.');
}
-// 2. scene_samples_ is the DEVICE's answer, not a constant somebody picked.
+// 2. The effective count is a REQUEST clamped by a CAPABILITY. A device that
+// decides quality drags every low-end target up to whatever its driver
+// allows; a request nobody clamps asks for samples that cannot be created.
const derived = /scene_samples_\s*=\s*([^;]+);/.exec(pipe);
if (!derived) {
findings.push(`${PIPE_CPP}: scene_samples_ is never assigned.`);
-} else if (!/maxSamples\s*\(\s*\)/.test(derived[1])) {
- findings.push(`${PIPE_CPP}: scene_samples_ is \`${derived[1].trim()}\`, which never asks the `
- + 'device. A backend with no multisampling must be able to answer 1, and one with '
- + 'multisampling must not be capped by a guess.');
+} else {
+ const expr = derived[1].replace(/\s+/g, ' ').trim();
+ if (!/maxSamples\s*\(\s*\)/.test(expr)) {
+ findings.push(`${PIPE_CPP}: the effective sample count \`${expr}\` is never clamped by `
+ + 'device.maxSamples(). A target cannot be created with more samples than the '
+ + 'backend has.');
+ }
+ if (!/requested_samples_/.test(expr)) {
+ findings.push(`${PIPE_CPP}: the effective sample count \`${expr}\` does not come from a `
+ + 'request. maxSamples() answers what the device CAN do, never what the project '
+ + 'SHOULD do — let it decide and every low-end target inherits its driver.');
+ }
}
-// 3. A multisampled target resolves ITSELF. Without the resolve attachments a
+// 3. The request reaches the pipeline from outside it. Without a setter the
+// policy is a constant in the renderer, which is the same mistake one level up.
+if (!/void PostProcessPipeline::setRequestedSamples/.test(pipe)) {
+ findings.push(`${PIPE_CPP}: nothing outside the renderer can set the multisampling `
+ + 'request, so the policy lives in the backend after all.');
+}
+
+// 4. A multisampled target resolves ITSELF. Without the resolve attachments a
// sampler reads the multisampled side, which cannot be sampled at all.
const fb = read(FB_CPP);
if (!/resolveColor_\s*=\s*device_->createTexture/.test(fb)) {
@@ -64,6 +80,21 @@ if (!/createFramebuffer\(\{[^}]*resolveColor_/s.test(fb)) {
+ 'createFramebuffer, so the device has nothing to resolve into.');
}
+// 5. WebGPU answers 1 because it has no MSAA. That API resolves COLOUR only, so
+// raising the ceiling without an engine-owned depth resolve hands every
+// depth-reading effect an attachment it cannot sample.
+const WGPU_CPP = 'src/esengine/renderer/webgpu/WebGPUDevice.cpp';
+const wgpu = read(WGPU_CPP);
+const ceiling = /u32 WebGPUDevice::maxSamples\(\)\s*\{\s*return\s+([^;]+);/.exec(wgpu);
+if (!ceiling) {
+ findings.push(`${WGPU_CPP}: WebGPUDevice::maxSamples() is gone or unrecognisable.`);
+} else if (ceiling[1].trim() !== '1' && !/texture_depth_multisampled_2d|resolveDepth/.test(wgpu)) {
+ findings.push(`${WGPU_CPP}: maxSamples() now answers \`${ceiling[1].trim()}\` with no depth `
+ + 'resolve in sight. WebGPU resolves colour only, and a multisampled colour attachment '
+ + 'forces a multisampled depth one that no post effect can sample — SSAO, fog and '
+ + 'depth-outline would read an attachment they cannot read.');
+}
+
if (findings.length) {
console.error('check-postfx-aa: the chain may cost the frame its antialiasing.\n');
for (const f of findings) console.error(` - ${f}`);
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index a9108d774..d85790477 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -92,6 +92,7 @@ const PARSE_KEY = {
outputTransform: 'r.outputTransform',
renderBackend: 'r.backend',
screenFit: 'r.cameraScaleMode',
+ msaaSamples: 'r.msaa',
};
/** Field names of the RuntimeProjectConfig interface, in declaration order. */