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
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.tsindex 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.tsindex 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, ordiff --git a/pipeline/tests/project-rendering.test.ts b/pipeline/tests/project-rendering.test.tsindex 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.tsindex 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: 0diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 231ec6171..4aec7628d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2334,6 +2334,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefined@@ -5312,6 +5313,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedentryScene: stringhotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined+msaaSamples: number | undefinedoutputTransform: "none" | "aces" | undefinedphysicsConfig: Physics2DPluginConfig | undefinedphysicsEnabled: boolean | undefined@@ -6050,6 +6052,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setMsaaSamples: (samples: number) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetPresentRequired: (required: boolean) => void@@ -9652,6 +9655,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c8c0eaeec..44445021b 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -2342,6 +2342,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefined@@ -5495,6 +5496,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedentryScene: stringhotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined+msaaSamples: number | undefinedoutputTransform: "none" | "aces" | undefinedphysicsConfig: Physics2DPluginConfig | undefinedphysicsEnabled: boolean | undefined@@ -6233,6 +6235,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setMsaaSamples: (samples: number) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetPresentRequired: (required: boolean) => void@@ -9845,6 +9848,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 01cb063cf..af7079455 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2329,6 +2329,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefined@@ -5307,6 +5308,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedentryScene: stringhotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined+msaaSamples: number | undefinedoutputTransform: "none" | "aces" | undefinedphysicsConfig: Physics2DPluginConfig | undefinedphysicsEnabled: boolean | undefined@@ -6045,6 +6047,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setMsaaSamples: (samples: number) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetPresentRequired: (required: boolean) => void@@ -9647,6 +9650,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex cdff07604..52c5f942f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -2329,6 +2329,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefined@@ -5553,6 +5554,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedentryScene: stringhotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined+msaaSamples: number | undefinedoutputTransform: "none" | "aces" | undefinedphysicsConfig: Physics2DPluginConfig | undefinedphysicsEnabled: boolean | undefined@@ -6291,6 +6293,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setMsaaSamples: (samples: number) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetPresentRequired: (required: boolean) => void@@ -9899,6 +9902,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: 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 @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => booleanpostprocess_isInitialized: () => booleanpostprocess_resize: (width: number, height: number) => voidpostprocess_setBypass: (bypass: boolean) => void+postprocess_setMsaaSamples: (samples: number) => voidpostprocess_setOutputTransform: ((transform: number) => void) | undefinedpostprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => voidpostprocess_setPassScale: (name: string, scale: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 8cb12419b..f7fa6ee7f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2329,6 +2329,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefined@@ -5314,6 +5315,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedentryScene: stringhotUpdate: { remoteRoot?: string; persistUpdateKey?: string; } | undefined+msaaSamples: number | undefinedoutputTransform: "none" | "aces" | undefinedphysicsConfig: Physics2DPluginConfig | undefinedphysicsEnabled: boolean | undefined@@ -6052,6 +6054,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setMsaaSamples: (samples: number) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetPresentRequired: (required: boolean) => void@@ -9675,6 +9678,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+msaaSamples: number | undefinedoutputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: 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 @experimentaldiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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.hppindex 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.cppindex 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.cppindex 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::ShaderHandlereturn 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 thediff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 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.mjsindex 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.mjsindex 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. */