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(quality): a phone or tablet takes Medium when a project names no level, and an orthographic camera is left out of its temporal smoothing
yhhd6e59bd42558
diff --git a/desktop b/desktopindex 804dd12a6..b4c4e4055 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 804dd12a6c3cbf594c9127c56f4cb7ad73d07326+Subproject commit b4c4e4055dce5eb1dbe2532845777c83ba3e6085diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdxindex ffee4bb96..b28514ebf 100644--- a/docs/astro/src/content/docs/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx@@ -15,7 +15,8 @@ three profiles — **Low, Medium, High** — each saying what the renderer spend| Mode | Meaning ||---|---|-| Off | No quality management. The project renders as authored. (The default.) |+| Default | Nothing chosen: **Medium on phones and tablets**, Off everywhere else. A mini game keeps its own defaults. |+| Off | No quality management, on every device. The project renders as authored. || Low / Medium / High | That level, on every device. || Auto | The level comes from the device: the first [device rule](#device-rules) that matches, otherwise memory and core count. |diff --git a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdxindex e9c81cdf2..6f1eb5f70 100644--- a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx@@ -14,7 +14,8 @@ import { Aside } from '@astrojs/starlight/components';| 模式 | 含义 ||---|---|-| 关闭 | 不做画质管理,项目按原样渲染(默认)。 |+| 默认 | 未选择:**手机和平板上为中档**,其他设备为关闭。小游戏保留自己的默认值。 |+| 关闭 | 在所有设备上都不做画质管理,项目按原样渲染。 || 低 / 中 / 高 | 所有设备都用该档位。 || 自动 | 档位由设备决定:第一条匹配的[设备规则](#设备规则),否则看内存和核心数。 |diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 04b5a9d7e..4448d79e1 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 176,- "experimental": 2840,+ "experimental": 2841,"deprecated": 3},- "total": 3131,+ "total": 3132,"subsystems": [{"id": "mobile-controls",diff --git a/native/host/bindings/DeviceBindings.cpp b/native/host/bindings/DeviceBindings.cppindex ca3930f6f..450c909a8 100644--- a/native/host/bindings/DeviceBindings.cpp+++ b/native/host/bindings/DeviceBindings.cpp@@ -57,6 +57,14 @@ esjs::Val js_deviceName(const esjs::Args& a) {return esjs::string(deviceName().c_str());}+esjs::Val js_isHandheld(const esjs::Args& a) {+#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IPHONE)+ return esjs::boolean(true);+#else+ return esjs::boolean(false);+#endif+}+esjs::Val js_deviceCapabilities(const esjs::Args& a) {return esjs::int32(hostAlive() && host().platform ? host().platform->deviceCapabilities() : 0);}@@ -108,6 +116,7 @@ esjs::Val js_setTargetFrameRate(const esjs::Args& a) {void registerDeviceBindings(HostState& h, esjs::Val global) {bindGlobal(global, "es_deviceName", js_deviceName, 0);+ bindGlobal(global, "es_isHandheld", js_isHandheld, 0);bindGlobal(global, "es_deviceCapabilities", js_deviceCapabilities, 0);bindGlobal(global, "es_startMotion", js_startMotion, 3);bindGlobal(global, "es_stopMotion", js_stopMotion, 0);diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.tsindex 615b7657f..0d88d7f18 100644--- a/pipeline/src/project/runtimeConfig.ts+++ b/pipeline/src/project/runtimeConfig.ts@@ -82,6 +82,8 @@ export interface RuntimeProjectConfig {* device clamps it — this is the policy half, never the capability. */msaaSamples: number;quality: QualityConfig;+ /** Whether the project names a level, `off` among them. One that names none takes the device's default (see `defaultQualityMode`). */+ qualityModeNamed: boolean;/** 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';@@ -168,6 +170,7 @@ export function runtimeConfigOf(: f?.rendering?.outputTransform === 'neutral' ? 'neutral' : 'none',msaaSamples: msaaOf(f?.rendering?.msaa),quality: parseQualityConfig(f?.rendering?.quality),+ qualityModeNamed: parseQualityConfig(f?.rendering?.quality).mode === (f?.rendering?.quality as { mode?: unknown } | undefined)?.mode,renderBackend: f?.rendering?.backend === 'webgpu' ? 'webgpu' : 'webgl2',screenFit: resolveScreenFit(manifest),};@@ -211,7 +214,8 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime...(rc.msaaSamples !== 4 ? { msaaSamples: rc.msaaSamples } : {}),// The block also carries three delivery choices that have nothing to do with a quality level (compile shaders in the background, warm them up// behind the splash, draw only changing frames); with the level off they must still ship, or the switch is read from a project and never reaches a game.- ...(qualityShips(rc.quality) ? { quality: rc.quality } : {}),+ // A named level ships, `off` too: left out, it would read as no level and a phone would take medium over the author's word.+ ...(rc.qualityModeNamed ? { quality: rc.quality } : qualityShips(rc.quality) ? { quality: withoutMode(rc.quality) } : {}),...(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@@ -235,6 +239,11 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime};}+function withoutMode(quality: QualityConfig): QualityConfig {+ const { mode: _unnamed, ...rest } = quality;+ return rest;+}+/** Whether a build has anything to be told about quality: a level, or one of the delivery choices that hold whatever the level. */export function qualityShips(quality: QualityConfig): boolean {return quality.mode !== 'off' || quality.asyncShaderCompile === truediff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.tsindex 0f14eaf58..e2e463d35 100644--- a/pipeline/tests/runtime-config.test.ts+++ b/pipeline/tests/runtime-config.test.ts@@ -197,9 +197,18 @@ describe('the quality block that ships with the level off', () => {expect(packagedRuntimeFields(rc).quality?.mode).toBe('off');}});- it('still leaves the block out when nothing in it is on', () => {+ it('ships a level named off, or a phone would read it as none named and take medium', () => {const rc = runtimeConfigOf({ features: { rendering: { quality: { mode: 'off', targetFps: 30 } } } });- expect(packagedRuntimeFields(rc)).not.toHaveProperty('quality');+ expect(packagedRuntimeFields(rc).quality?.mode).toBe('off');+ });+ it('leaves the block out when the project says nothing in it', () => {+ expect(packagedRuntimeFields(runtimeConfigOf({ features: { rendering: {} } }))).not.toHaveProperty('quality');+ expect(packagedRuntimeFields(runtimeConfigOf({ features: { rendering: { quality: { targetFps: 30 } } } }))).not.toHaveProperty('quality');+ });+ it('ships delivery choices with no level when none is named', () => {+ const fields = packagedRuntimeFields(runtimeConfigOf({ features: { rendering: { quality: { renderOnDemand: true } } } }));+ expect(fields.quality?.renderOnDemand).toBe(true);+ expect(fields.quality).not.toHaveProperty('mode');});});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex a6422d78b..26c4c2ae5 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 164 beta · 2049 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2050 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -7354,6 +7354,7 @@ getStorageItem: (key: string) => string | nullhasCacheStorage: (() => boolean) | undefinedhasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedlistCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -14590,6 +14591,11 @@ PluginPluralSelector```+## defaultQualityMode — function @experimental+```+(handheld: boolean): QualityMode+```+## defaultQualityProfile — function @experimental```(level: QualityLevel): QualityProfilediff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 62bc4dd01..08eed4d0e 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 169 beta · 2068 experimental · 3 deprecated+Symbols: 115 public · 169 beta · 2069 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -6370,6 +6370,7 @@ devicePixelRatio: () => numberfetch: (url: string, options?: PlatformRequestOptions) => Promise<NativeFetchResult>fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | null+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>now: (() => number) | undefined@@ -6445,6 +6446,7 @@ es_deviceName: (() => string) | undefinedes_devicePixelRatio: (() => number) | undefinedes_fetch: ((request: { url: string; method?: string; headers?: Record<string, string>; body?: string | ArrayBuffer; responseType?: string; }, callback: (result: { ok: boolean; status: number; statusText: string; headers: Record<string, string>; arrayBuffer?: ArrayBuffer; text?: string; error?: string; }) => void) => void) | undefinedes_getStorageItem: ((key: string) => string | null) | undefined+es_isHandheld: (() => boolean) | undefinedes_keepScreenOn: ((enabled: boolean) => boolean) | undefinedes_loadImagePixels: (pathOrBytes: string | ArrayBuffer) => { width: number; height: number; pixels: ArrayBuffer; } | nulles_pollGamepads: (() => { index: number; connected: boolean; buttons: number[]; axes: number[]; }[]) | undefined@@ -6519,6 +6521,7 @@ fileExists: (path: string) => Promise<boolean>getStorageItem: (key: string) => string | nullhasCacheStorage: () => booleaninstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: () => booleanlanguage: () => stringloadImagePixels: (path: string) => Promise<ImageLoadResult>name: "native"@@ -7557,6 +7560,7 @@ getStorageItem: (key: string) => string | nullhasCacheStorage: (() => boolean) | undefinedhasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedlistCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -14843,6 +14847,11 @@ PluginPluralSelector```+## defaultQualityMode — function @experimental+```+(handheld: boolean): QualityMode+```+## defaultQualityProfile — function @experimental```(level: QualityLevel): QualityProfilediff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 9feabcdcb..2ca93774a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2048 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2049 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7349,6 +7349,7 @@ getStorageItem: (key: string) => string | nullhasCacheStorage: (() => boolean) | undefinedhasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedlistCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -14585,6 +14586,11 @@ PluginPluralSelector```+## defaultQualityMode — function @experimental+```+(handheld: boolean): QualityMode+```+## defaultQualityProfile — function @experimental```(level: QualityLevel): QualityProfilediff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 97cab51c8..a62812b30 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 164 beta · 2070 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2071 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7645,6 +7645,7 @@ getStorageItem: (key: string) => string | nullhasCacheStorage: (() => boolean) | undefinedhasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedlistCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -14892,6 +14893,11 @@ PluginPluralSelector```+## defaultQualityMode — function @experimental+```+(handheld: boolean): QualityMode+```+## defaultQualityProfile — function @experimental```(level: QualityLevel): QualityProfilediff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 314fe76d3..d8d9d5bd8 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 164 beta · 2061 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 2062 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -7356,6 +7356,7 @@ getStorageItem: (key: string) => string | nullhasCacheStorage: (() => boolean) | undefinedhasTouch: (() => boolean) | undefinedinstantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>+isHandheld: (() => boolean) | undefinedlanguage: (() => string) | undefinedlistCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefinedloadImagePixels: (path: string) => Promise<ImageLoadResult>@@ -14618,6 +14619,11 @@ PluginPluralSelector```+## defaultQualityMode — function @experimental+```+(handheld: boolean): QualityMode+```+## defaultQualityProfile — function @experimental```(level: QualityLevel): QualityProfilediff --git a/sdk/src/app/renderOptions.ts b/sdk/src/app/renderOptions.tsindex 4eae28a07..82c480073 100644--- a/sdk/src/app/renderOptions.ts+++ b/sdk/src/app/renderOptions.ts@@ -13,7 +13,8 @@ import { outputTransformCode, type OutputTransform } from '../postprocess';import { installQuality } from '../render/qualityRuntime';import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from '../camera/ScreenScaling';import { RenderResolution } from '../camera/presentPlan';-import type { QualityConfig } from '../render/quality';+import { defaultQualityMode, type QualityConfig } from '../render/quality';+import { getPlatform } from '../platform';import type { App } from './app';/** The engine entry points these reach, by the names the wasm module and the native host's API share. */@@ -65,5 +66,7 @@ export function applyAppOptions(app: App, options: RenderOptions | undefined): v|| (options.screenFit.renderPolicy ?? RenderResolution.Surface) !== RenderResolution.Surface)) {app.insertResource(ScreenScaling, { ...options.screenFit });}- if (options?.quality) installQuality(app, options.quality, options.msaaSamples ?? 4);+ // A block with no level in it (a build carrying only its delivery choices) has named none either.+ const mode = options?.quality?.mode ?? defaultQualityMode(getPlatform().isHandheld?.() ?? false);+ if (options?.quality || mode !== 'off') installQuality(app, { ...options?.quality, mode }, options?.msaaSamples ?? 4);}diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 321f9e655..c935122af 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -350,7 +350,7 @@ export {type PreSceneDrawCallback,type PreSceneDrawInfo,} from './render/customDraw';-export { QualityController, parseQualityConfig, resolveQualityProfile, defaultQualityProfile } from './render/quality';+export { QualityController, parseQualityConfig, resolveQualityProfile, defaultQualityProfile, defaultQualityMode } from './render/quality';export type {QualityConfig, QualityProfile, QualityLevel, QualityMode,QualityReport, DeviceQualityInfo, DeviceQualityRule,diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex f9e7d7d4b..a16e5df90 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -304,6 +304,10 @@ export class NativePlatformAdapter implements PlatformAdapter {return () => { live = false; };}+ isHandheld(): boolean {+ return this.bridge_.isHandheld?.() ?? false;+ }+deviceName(): string {return this.bridge_.deviceName?.() ?? '';}diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex 1da279413..600306681 100644--- a/sdk/src/platform/native/bridge.ts+++ b/sdk/src/platform/native/bridge.ts@@ -233,6 +233,9 @@ export interface NativeBridge {/** What the device is called in a list (system and model), when the host says. */deviceName?(): string;+ /** Whether the host is a phone or a tablet, when it says. */+ isHandheld?(): boolean;+/** `ws://` sockets, on a host that carries the client. Absent → `createSocket`* is unavailable, as it is on a host with no network. */socket?: NativeSocketBridge;diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.tsindex 5735b1838..9830b3268 100644--- a/sdk/src/platform/native/hostBridge.ts+++ b/sdk/src/platform/native/hostBridge.ts@@ -112,6 +112,9 @@ export interface NativeHostBindings extends NativeDeviceHost {/** What the device is called in a list: its system and model. */es_deviceName?(): string;+ /** Whether this host is a phone or a tablet. */+ es_isHandheld?(): boolean;+/** The host's `ws://` client: events arrive on the JS thread, `close` last. */es_wsOpen?(url: string, onEvent: (event: NativeSocketEvent) => void): number;es_wsSend?(id: number, data: string | ArrayBuffer): boolean;@@ -204,6 +207,7 @@ export function createHostBridge(fileExists: (path) => Promise.resolve(bindings.es_readAsset(path) != null),fetch: (url, options) => hostFetch(bindings, url, options),...(bindings.es_deviceName ? { deviceName: () => bindings.es_deviceName!() } : {}),+ ...(bindings.es_isHandheld ? { isHandheld: () => bindings.es_isHandheld!() } : {}),...(bindings.es_wsOpen && bindings.es_wsSend && bindings.es_wsClose ? {socket: {open: (url, onEvent) => {diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 61003a956..8537b75c6 100644--- a/sdk/src/platform/types.ts+++ b/sdk/src/platform/types.ts@@ -597,6 +597,9 @@ export interface PlatformAdapter {/** What a person would call this device when picking it from a list: a* phone's model, or a browser and its system. Optional. */deviceName?(): string;+ /** Whether this is a phone or a tablet: a small GPU, on a battery, behind a very dense screen. Optional; absent is no. A mini-game host does not+ * answer: it already draws within its own defaults (see `waterQualityOf`). */+ isHandheld?(): boolean;/** One rewarded ad unit. Mini-game hosts implement it over their* RewardedVideoAd; platforms without an ad system (web, native until adiff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.tsindex 88cc76fa4..b4ded3a2b 100644--- a/sdk/src/platform/web.ts+++ b/sdk/src/platform/web.ts@@ -361,6 +361,10 @@ class WebPlatformAdapter implements PlatformAdapter {return typeof navigator !== 'undefined' ? browserDeviceName(navigator.userAgent) : '';}+ isHandheld(): boolean {+ return typeof navigator !== 'undefined' && browserIsHandheld(navigator.userAgent, navigator.maxTouchPoints ?? 0);+ }+deviceQualityInfo(): { memoryGB?: number; cores?: number } {if (typeof navigator === 'undefined') return {};return { memoryGB: (navigator as Navigator & { deviceMemory?: number }).deviceMemory,@@ -432,6 +436,11 @@ export const webAdapter = new WebPlatformAdapter();/** A browser and the system it runs on, from its user agent. Chrome on Android* no longer names the phone's model there, so this is as close as a page gets. */+/** A phone or a tablet, by its browser. An iPad's Safari says it is a Mac by default; only its touch screen tells them apart. */+export function browserIsHandheld(ua: string, touchPoints: number): boolean {+ return /Android|iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && touchPoints > 1);+}+export function browserDeviceName(ua: string): string {const system = /Android/.test(ua) ? 'Android': /iPhone/.test(ua) ? 'iPhone'diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.tsindex ddec3862c..b1ec3e580 100644--- a/sdk/src/postprocess/volumeSystem.ts+++ b/sdk/src/postprocess/volumeSystem.ts@@ -7,7 +7,7 @@ import { EDITOR_VIEW_ENTITY } from '../camera/uiLayoutRect';import { defineResource, Res } from '../ecs/resource';import { Query } from '../ecs/query';import type { Entity } from '../types';-import { PostProcessVolume, Transform, Camera, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';+import { PostProcessVolume, Transform, Camera, ProjectionType, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';import { PostProcess, deviceHasCompute, type PostProcessAPI } from './PostProcessAPI';import { getEffectDef } from './effects';import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type BlendedEffect, type VolumeTransform } from './volumeBlending';@@ -175,10 +175,11 @@ function effectsSignature(effects: ResolvedEffects): string {/*** The effects with the temporal anti-aliasing pass in them, where the quality level asks for it and the scene has not listed it: before the exposure* and the grading, after the lighting and the fog, which is where the harness measured it and where an author puts it. A level that does not ask- * leaves the effects as they are.+ * leaves the effects as they are, and so does an orthographic camera: jittered, sprites and text go soft, and a 2D game would pay a full-screen chain+ * for it. An author who lists `taa` on one still gets it.*/-function withTemporalAntialiasing(api: PostProcessAPI, effects: ResolvedEffects): ResolvedEffects {- if (api.antialiasing !== 'temporal' || effects.has('taa')) return effects;+export function withTemporalAntialiasing(api: PostProcessAPI, effects: ResolvedEffects, perspective: boolean): ResolvedEffects {+ if (!perspective || api.antialiasing !== 'temporal' || effects.has('taa')) return effects;const taa: BlendedEffect = { enabled: true, uniforms: new Map([['u_blend', 0.1], ['u_objectMotion', 1]]), textures: new Map(), colors: new Map() };const out: ResolvedEffects = new Map();let placed = false;@@ -197,8 +198,9 @@ function applyBlendedEffects(api: PostProcessAPI,camera: Entity,blended: ResolvedEffects,+ perspective: boolean,): void {- const effects = withTemporalAntialiasing(api, blended);+ const effects = withTemporalAntialiasing(api, blended, perspective);if (effects.size === 0) {const existing = api.volumeStacks.get(camera);if (existing) {@@ -333,7 +335,7 @@ export const postProcessVolumeSystem = defineSystem(for (const [cameraEntity, cameraData, cameraTransform] of cameraQuery) {if (!cameraData.isActive) continue;const p = cameraTransform.position;- applyBlendedEffects(api, cameraEntity, effectsAt(volumes, p.x, p.y, p.z));+ applyBlendedEffects(api, cameraEntity, effectsAt(volumes, p.x, p.y, p.z), cameraData.projectionType !== ProjectionType.Orthographic);}},{ name: 'PostProcessVolumeSystem' }@@ -350,7 +352,7 @@ export function editorViewVolumeSystem(app: App) {const view = app.hasResource(EditorView) ? app.getResource(EditorView) : null;const eye = EDITOR_VIEW_ENTITY as Entity;if (!view || !view.active || !app.getResource(PostProcessVolumeConfigResource).enabled) {- if (api.volumeStacks.has(eye)) applyBlendedEffects(api, eye, new Map() as ResolvedEffects);+ if (api.volumeStacks.has(eye)) applyBlendedEffects(api, eye, new Map() as ResolvedEffects, false);return;}const volumes: { data: PostProcessVolumeData; tx: VolumeTransform }[] = [];@@ -358,7 +360,7 @@ export function editorViewVolumeSystem(app: App) {volumes.push({ data: volumeData, tx: { x: transform.position.x, y: transform.position.y, z: transform.position.z } });}const at = view.perspective ? editorViewEye(view) : { x: view.x, y: view.y, z: view.z };- applyBlendedEffects(api, eye, effectsAt(volumes, at.x, at.y, at.z));+ applyBlendedEffects(api, eye, effectsAt(volumes, at.x, at.y, at.z), view.perspective);},{ name: 'EditorViewVolumeSystem' },);diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.tsindex a42a424e3..4e8e986f8 100644--- a/sdk/src/render/quality.ts+++ b/sdk/src/render/quality.ts@@ -182,6 +182,15 @@ function finite(value: unknown, fallback: number, min: number, max: number): num? Math.min(max, Math.max(min, value)) : fallback;}+/**+ * The level a project gets that names none. A phone or tablet takes medium: all of a level's picture at a fraction of the cost (a full-screen sea on a+ * Snapdragon 8 Elite is 25.7 ms a frame as authored and 9.0 at medium, mostly by leaving four samples behind). Elsewhere nothing is managed. Naming a+ * level, `off` among them, always wins.+ */+export function defaultQualityMode(handheld: boolean): QualityMode {+ return handheld ? 'medium' : 'off';+}+/** @experimental */export function parseQualityConfig(value: unknown): QualityConfig {const raw = record(value);diff --git a/sdk/tests/quality-default.test.ts b/sdk/tests/quality-default.test.tsnew file mode 100644index 000000000..28bffe6a4--- /dev/null+++ b/sdk/tests/quality-default.test.ts@@ -0,0 +1,42 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { QualityController, defaultQualityMode, defaultQualityProfile } from '../src/render/quality';+import { browserIsHandheld } from '../src/platform/web';+import { withTemporalAntialiasing } from '../src/postprocess/volumeSystem';+import type { PostProcessAPI } from '../src/postprocess/PostProcessAPI';++describe('the level a project gets that names none', () => {+ it('is medium on a phone or tablet and nothing managed elsewhere', () => {+ expect(defaultQualityMode(true)).toBe('medium');+ expect(defaultQualityMode(false)).toBe('off');+ expect(new QualityController({ mode: defaultQualityMode(true) }).report().level).toBe('medium');+ expect(new QualityController({ mode: defaultQualityMode(false) }).enabled).toBe(false);+ });++ it('tells a handheld browser, an iPad that says it is a Mac among them', () => {+ const mac = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/17.0 Safari/605.1.15';+ expect(browserIsHandheld('Mozilla/5.0 (Linux; Android 15; 24129PN74C) Chrome/120.0 Mobile', 5)).toBe(true);+ expect(browserIsHandheld('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) Safari/604.1', 5)).toBe(true);+ expect(browserIsHandheld(mac, 5)).toBe(true);+ expect(browserIsHandheld(mac, 0)).toBe(false);+ expect(browserIsHandheld('Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0', 10)).toBe(false);+ });+});++describe('the temporal smoothing a level asks for', () => {+ const asking = { antialiasing: defaultQualityProfile('medium').antialiasing } as unknown as PostProcessAPI;++ it('goes on a camera with depth', () => {+ expect(withTemporalAntialiasing(asking, new Map(), true).has('taa')).toBe(true);+ });++ it('leaves an orthographic camera as authored: jittered, sprites and text go soft', () => {+ expect(withTemporalAntialiasing(asking, new Map(), false).size).toBe(0);+ });++ it('still gives an orthographic camera the pass its author listed', () => {+ const listed = new Map([['taa', { enabled: true, uniforms: new Map(), textures: new Map(), colors: new Map() }]]);+ expect(withTemporalAntialiasing(asking, listed, false).has('taa')).toBe(true);+ });+});diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjsindex b653cac00..d1a754879 100644--- a/tools/check-project-settings.mjs+++ b/tools/check-project-settings.mjs@@ -64,6 +64,10 @@ const SETTINGS_FILES = [SETTINGS, 'desktop/src/settings/qualitySettings.ts', 'de* printed by `--list` so the gaps stay visible rather than becoming folklore.*/const DECLARED_GAPS = {+ qualityModeNamed: {+ parse: 'read off the quality block in place, whether its mode is one parseQualityConfig keeps; it is no manifest key of its own',+ editor: 'the settings row reads the block as written (rawQuality), which says the same thing',+ },achievements: {editor: 'nothing unlocks one while a scene is being authored — edit mode runs no '+ 'gameplay, so the set is checked in Play and in a shipped build',@@ -110,6 +114,7 @@ const DECLARED_GAPS = {/** The feature branch in the manifest parser each field is read from. */const PARSE_KEY = {+ qualityModeNamed: 'r.quality',achievements: 'p.achievements',steamAppId: 'dt.steam',physicsEnabled: 'p.enabled',@@ -134,6 +139,7 @@ const PARSE_KEY = {* a claim of "there is a UI" that nobody checked is the same as no UI.*/const AUTHORING = {+ qualityModeNamed: { internal: 'derived from the quality block; the setting an author touches is `quality`' },achievements: { ui: 'project.packaging.achievements' },steamAppId: { ui: 'project.packaging.desktop.steam.appId' },physicsEnabled: { ui: 'project.physics.enabled' },