Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(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/desktop
index 804dd12a6..b4c4e4055 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 804dd12a6c3cbf594c9127c56f4cb7ad73d07326
+Subproject commit b4c4e4055dce5eb1dbe2532845777c83ba3e6085
diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdx
index 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.mdx
index 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.json
index 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.cpp
index 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.ts
index 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 === true
diff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.ts
index 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.md
index 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 | null
hasCacheStorage: (() => boolean) | undefined
hasTouch: (() => boolean) | undefined
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
listCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
@@ -14590,6 +14591,11 @@ Plugin
PluralSelector
```
+## defaultQualityMode — function @experimental
+```
+(handheld: boolean): QualityMode
+```
+
## defaultQualityProfile — function @experimental
```
(level: QualityLevel): QualityProfile
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: () => number
fetch: (url: string, options?: PlatformRequestOptions) => Promise<NativeFetchResult>
fileExists: (path: string) => Promise<boolean>
getStorageItem: (key: string) => string | null
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
now: (() => number) | undefined
@@ -6445,6 +6446,7 @@ es_deviceName: (() => string) | undefined
es_devicePixelRatio: (() => number) | undefined
es_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) | undefined
es_getStorageItem: ((key: string) => string | null) | undefined
+es_isHandheld: (() => boolean) | undefined
es_keepScreenOn: ((enabled: boolean) => boolean) | undefined
es_loadImagePixels: (pathOrBytes: string | ArrayBuffer) => { width: number; height: number; pixels: ArrayBuffer; } | null
es_pollGamepads: (() => { index: number; connected: boolean; buttons: number[]; axes: number[]; }[]) | undefined
@@ -6519,6 +6521,7 @@ fileExists: (path: string) => Promise<boolean>
getStorageItem: (key: string) => string | null
hasCacheStorage: () => boolean
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: () => boolean
language: () => string
loadImagePixels: (path: string) => Promise<ImageLoadResult>
name: "native"
@@ -7557,6 +7560,7 @@ getStorageItem: (key: string) => string | null
hasCacheStorage: (() => boolean) | undefined
hasTouch: (() => boolean) | undefined
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
listCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
@@ -14843,6 +14847,11 @@ Plugin
PluralSelector
```
+## defaultQualityMode — function @experimental
+```
+(handheld: boolean): QualityMode
+```
+
## defaultQualityProfile — function @experimental
```
(level: QualityLevel): QualityProfile
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | null
hasCacheStorage: (() => boolean) | undefined
hasTouch: (() => boolean) | undefined
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
listCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
@@ -14585,6 +14586,11 @@ Plugin
PluralSelector
```
+## defaultQualityMode — function @experimental
+```
+(handheld: boolean): QualityMode
+```
+
## defaultQualityProfile — function @experimental
```
(level: QualityLevel): QualityProfile
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | null
hasCacheStorage: (() => boolean) | undefined
hasTouch: (() => boolean) | undefined
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
listCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
@@ -14892,6 +14893,11 @@ Plugin
PluralSelector
```
+## defaultQualityMode — function @experimental
+```
+(handheld: boolean): QualityMode
+```
+
## defaultQualityProfile — function @experimental
```
(level: QualityLevel): QualityProfile
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | null
hasCacheStorage: (() => boolean) | undefined
hasTouch: (() => boolean) | undefined
instantiateWasm: (pathOrBuffer: string | ArrayBuffer, imports: WebAssembly.Imports) => Promise<WasmInstantiateResult>
+isHandheld: (() => boolean) | undefined
language: (() => string) | undefined
listCacheFiles: (() => Promise<{ name: string; size: number; lastAccess: number; }[]>) | undefined
loadImagePixels: (path: string) => Promise<ImageLoadResult>
@@ -14618,6 +14619,11 @@ Plugin
PluralSelector
```
+## defaultQualityMode — function @experimental
+```
+(handheld: boolean): QualityMode
+```
+
## defaultQualityProfile — function @experimental
```
(level: QualityLevel): QualityProfile
diff --git a/sdk/src/app/renderOptions.ts b/sdk/src/app/renderOptions.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 a
diff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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' },