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(editor): Settings edits the three quality levels, one at a time, effect by effect, and the device rules Auto chooses by

yhh29b07d70f669
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 25fead0e7..942d90490 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,8 @@ published separately; it ships inside the editor.
### Added
-- **A G-buffer, and reflections that read it.** Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request. A post-process shader that says `#pragma gbuffer` makes the scene target carry a second RGBA8 colour attachment, written in the same pass by the scene's own shaders — octahedral normal in `r`/`g`, roughness in `b`, metalness in `a` (0 where nothing wrote) — and finds it at `u_gbuffer`. A frame whose chain has no such effect makes none and compiles no variant. The render device grew multiple colour attachments for it on both backends: WebGL2 attaches and resolves a second target and sets the draw buffers per pipeline, and WebGPU declares the second target on every pipeline of the pass (written by the ones that write it, an empty write mask for the rest), clears it to zero and resolves it with the colour. Pipelines say whether they write it (`PipelineDesc::gbuffer`), a blended draw never does, and the second output is its own shader variant (`ES_GBUFFER`), so no pass pays for what it did not ask for. The built-in Model shader — what an imported glTF material becomes — writes it from the material's roughness, metalness and normal map. `ssr` reads it: it takes the surface's own normal (normal-map detail that depth cannot see), weighs and blurs the reflection by roughness, reflects a metal at nearly full strength where a dielectric reflects 4%, skips a surface rougher than `maxRoughness` before marching the ray, and takes the Rain effect's `wetness` as a film that smooths the ground. Where nothing wrote a record, it falls back to depth and the dielectric it has always assumed. Verified in the editor on both backends: of two floors that differ only in their material's roughness, the glossy one changes ten times the pixels the rough one does. Quality levels can also leave out expensive effects now: quality levels can now skip expensive post-process effects by name. A level's `skipEffects` lists the effects it leaves out, each named by what its passes' names start with (`ssr`, `taa`, `depthOfField`, `lightShafts`, …); a project's own list in its quality profile replaces the level's. By default low leaves out reflections, temporal anti-aliasing, depth of field and light shafts, and medium leaves out reflections and depth of field; high leaves out nothing. These defaults come from the work each effect does per pixel, not from a weak device: the editor's new `fx-cost` check measured every effect on Bistro at 2560×1600 on a fast desktop GPU, and none added more than about 6 ms (reflections ~5, bloom ~4, the example's whole eight-effect chain ~11, the rest within the ±3 ms the run drifts by), so the levels have not been checked against the hardware they are for.
+- **Quality levels are edited in Settings.** Settings → Project → Rendering edits each quality level, including which effects it runs. **Editing level** picks Low, Medium or High and the groups below — Rendering (render scale, minimum scale, MSAA), Shadows, Reflections and particles, Post-processing — show and change that level, so a level is read the way Unity's Quality page reads: a level, then its settings by subsystem. Post-processing lists every effect the engine has, ticked where the level runs it; an unticked one is skipped at that level wherever a camera's volume asks for it, with all of its passes. Device rules — the model, GPU, memory and core conditions Auto chooses a level by — are a table, shown when the mode is Auto, that says so on a row with no condition instead of dropping it while it is typed. Only what you change is saved to `project.esproject`, as a difference to that level, so an engine default that improves later still reaches a project that never touched it; a row's "changed" mark and reset follow the default of the level it is showing. The old per-level shadow distance rows are the Shadows group's Distance now. The effects a level leaves out had been matched by the prefix of a pass's name, which found none of Auto Exposure's passes; they are now matched by effect type. A new Quality Levels page in the performance docs describes it.
+- **A G-buffer, and reflections that read it.** Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request. A post-process shader that says `#pragma gbuffer` makes the scene target carry a second RGBA8 colour attachment, written in the same pass by the scene's own shaders — octahedral normal in `r`/`g`, roughness in `b`, metalness in `a` (0 where nothing wrote) — and finds it at `u_gbuffer`. A frame whose chain has no such effect makes none and compiles no variant. The render device grew multiple colour attachments for it on both backends: WebGL2 attaches and resolves a second target and sets the draw buffers per pipeline, and WebGPU declares the second target on every pipeline of the pass (written by the ones that write it, an empty write mask for the rest), clears it to zero and resolves it with the colour. Pipelines say whether they write it (`PipelineDesc::gbuffer`), a blended draw never does, and the second output is its own shader variant (`ES_GBUFFER`), so no pass pays for what it did not ask for. The built-in Model shader — what an imported glTF material becomes — writes it from the material's roughness, metalness and normal map. `ssr` reads it: it takes the surface's own normal (normal-map detail that depth cannot see), weighs and blurs the reflection by roughness, reflects a metal at nearly full strength where a dielectric reflects 4%, skips a surface rougher than `maxRoughness` before marching the ray, and takes the Rain effect's `wetness` as a film that smooths the ground. Where nothing wrote a record, it falls back to depth and the dielectric it has always assumed. Verified in the editor on both backends: of two floors that differ only in their material's roughness, the glossy one changes ten times the pixels the rough one does. Quality levels can also leave out expensive effects now: quality levels can now skip expensive post-process effects by name. A level's `skipEffects` lists the effects it leaves out, each named by its effect type (`ssr`, `taa`, `depthOfField`, `lightShafts`, `autoExposure`, …), and an effect leaves with all of its passes however they are named; a project's own list in its quality profile replaces the level's. By default low leaves out reflections, temporal anti-aliasing, depth of field and light shafts, and medium leaves out reflections and depth of field; high leaves out nothing. These defaults come from the work each effect does per pixel, not from a weak device: the editor's new `fx-cost` check measured every effect on Bistro at 2560×1600 on a fast desktop GPU, and none added more than about 6 ms (reflections ~5, bloom ~4, the example's whole eight-effect chain ~11, the rest within the ±3 ms the run drifts by), so the levels have not been checked against the hardware they are for.
- **Rain, wet ground and puddles.** A Rain post-process effect adds falling rain, wet ground, puddles and ripples. `rain` draws three layers of slanted streaks, each at its own distance so a nearer surface hides them and the sky does not; darkens the ground that faces up by `wetness`; lays ripples and splashes where drops land on a grid in the world, so they stay on the ground as the camera moves (ripples need `intensity` above 0: wet ground under no rain is still); and, by `puddles` and `puddleScale`, covers part of the flat ground with standing water that is darker and takes denser, clearer ripples. `ssr` takes the same two numbers and treats those pools as mirrors — flat, far more reflective than dry ground, and sharp — so the pools the rain darkens are the pools that reflect. The clock is `u_time * timeScale + phase`, so a capture can pin it. The rain is a screen-space layer, not particles that collide with the world, and a puddle is flat ground whatever it lies on. Verified in the editor on both backends: streaks light a dark sky and move between two moments, wet ground reads darker, standing water darker still, and puddles change the reflection.
- **Auto Exposure and Depth of Field.** Auto Exposure and Depth of Field post-process effects are available. `autoExposure` measures the average log luminance of the picture (leaving out pixels darker than 2^-8, so a black backdrop does not open the exposure to its limit), turns it into the exposure that puts it at middle grey, and moves toward that over time from where the last frame left it — brighter faster than darker, per second, within `minEV` and `maxEV`, with a `bias` in stops. To keep the settled value between frames a post-process shader can now declare a `u_feedback` texture: the engine keeps that pass's last output, at the pass's own size, and binds it there, without shifting the picture the way `u_history` does. `depthOfField` blurs by distance from `focusDistance`, with a sharp slab of `focusRange`, a blur radius that grows with how far a surface is from focus up to `maxBlur`, and a gather that counts a neighbour only where its own blur reaches back, so a sharp object does not bleed into a blurred background. Verified in the editor on both backends: a dim scene brightens (mean 6.9 to 16.5) and a bright one darkens (30.7 to 20.4), a drop in light is first dark and then recovered over real time (5.2 then 15.8), and focusing close takes the squared edge energy down to 21% of the sharp frame.
- **Height Fog and Light Shafts.** Height Fog and Light Shafts post-process effects add atmosphere. `heightFog` is exponential height fog with a closed-form integral — no marching — so a valley fills and a hilltop clears, the horizon turns hazy while the zenith stays clear, and looking toward the sun the haze takes the sun's colour; sky pixels run through the same formula with a very long ray, and `skyFog` sets how much haze the sky keeps. `lightShafts` marches each pixel toward the sun's place on screen and counts how much of the way is open sky, leaving rays through whatever stands in front of the sun. The sun's direction is set on the effects (azimuth and elevation), not read from a light. Neither is a shadowed volume: fog is lit evenly. Both run on WebGL2 and WebGPU; with an output transform of None, a floor fully taken by the fog reads exactly the authored colour on both.
diff --git a/desktop b/desktop
index 205561b42..32ad74459 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 205561b42bcb6cb49f0b50527e8a37cb6f84cc7e
+Subproject commit 32ad7445902c57140fd8b39b7e1bc1e5d89a484f
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 9f851ca0e..2bb181164 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -327,6 +327,7 @@ export default defineConfig({
items: [
{ label: 'Profiling & Diagnostics', translations: { 'zh-CN': '性能剖析与诊断' }, slug: 'performance/profiling' },
{ label: 'Level of Detail', translations: { 'zh-CN': '细节层次(LOD)' }, slug: 'performance/level-of-detail' },
+ { label: 'Quality Levels', translations: { 'zh-CN': '画质档位' }, slug: 'performance/quality-levels' },
{ label: 'Occlusion Culling', translations: { 'zh-CN': '遮挡剔除' }, slug: 'performance/occlusion-culling' },
{ label: 'Static Batching', translations: { 'zh-CN': '静态合并' }, slug: 'performance/static-batching' },
{ label: 'Frame Debugger', translations: { 'zh-CN': '帧调试器' }, slug: 'performance/frame-debugger' },
diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdx
new file mode 100644
index 000000000..24f76f2c3
--- /dev/null
+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx
@@ -0,0 +1,70 @@
+---
+title: Quality Levels
+description: Three levels of what the renderer spends — resolution, shadows, reflections, particles and which post-process effects run — edited one level at a time in Project Settings, chosen by hand or by device rules.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+A project can ship one picture and run it on a flagship phone and on a six-year-old one. **Quality levels** are how:
+three profiles — **Low, Medium, High** — each saying what the renderer spends at that level. The project picks one
+(or lets the device pick), and a game that is too slow for its level steps its resolution down on its own.
+
+## Choosing the level
+
+**Settings → Project → Rendering → Device Quality → Quality level:**
+
+| Mode | Meaning |
+|---|---|
+| Off | No quality management. The project renders as authored. (The default.) |
+| 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. |
+
+**Dynamic resolution** lowers the scene's resolution under GPU pressure, down to the level's *Min render scale*, and
+brings it back when there is room; the UI stays at display resolution. **Target frame rate** is the frame time it works
+to.
+
+## What a level holds
+
+**Quality Levels → Editing level** picks which level the rows below show and change. They are grouped by what they spend:
+
+| Group | Settings |
+|---|---|
+| Rendering | Render scale, Min render scale, MSAA |
+| Shadows | Atlas size, Cell size, Cascades, Distance |
+| Reflections and particles | Planar reflection scale, max size and updates per second, Particle limit |
+| Post-processing | A master switch, and a tick for each effect that runs at this level |
+
+Each level starts from the engine's own values for it, and **only what you change is saved** in `project.esproject`
+under `features.rendering.quality.profiles.<level>`. A default the engine improves later reaches a project that never
+touched it, and a row set back to its level's default is not a difference.
+
+<Aside type="note">
+A row's "default" is the default of the level it is showing, so the same number can be a change at Low and the default
+at Medium.
+</Aside>
+
+## Leaving effects out
+
+Every post-process effect the engine has is in the list, ticked where the level runs it. An unticked effect is skipped
+at that level wherever a camera's volume asks for it — and all of it: an effect with several passes, such as Ambient
+Occlusion or Auto Exposure, is removed whole. The manifest holds the effects left out by type:
+
+```json
+"quality": { "mode": "auto", "profiles": { "low": { "skipEffects": ["ssr", "taa", "depthOfField"] } } }
+```
+
+By default Low leaves out reflections, temporal anti-aliasing, depth of field and light shafts; Medium leaves out
+reflections and depth of field; High leaves out nothing. These defaults follow the work each effect does per pixel; they
+are **not** measured on weak devices. The editor's `fx-cost` check measures each effect's cost on the machine it runs on,
+which is a way to find out what yours costs before choosing what a level skips.
+
+## Device rules
+
+Shown when the mode is Auto. Each row names a level and the conditions a device must meet: **Model contains**,
+**GPU contains**, **Max RAM** and **Max cores**, all of which must hold. The first row that matches decides the level. A
+row with no condition would match every device, so it must have one.
+
+## In code
+
+The same settings are `QualityConfig` — `QualityController`, `parseQualityConfig`, `resolveQualityProfile` and
+`defaultQualityProfile` build and read them — and the running level is the `Quality` resource.
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
new file mode 100644
index 000000000..7a228003c
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx
@@ -0,0 +1,62 @@
+---
+title: 画质档位
+description: 渲染器花多少的三个档位——分辨率、阴影、反射、粒子,以及运行哪些后处理效果——在项目设置里一次编辑一个档位,手动选择或按设备规则选择。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+同一个项目要能在旗舰手机和六年前的手机上都跑起来。**画质档位**就是做这件事的办法:**低、中、高**三份配置,每份说明渲染器在
+该档位下花多少。项目选一个(或交给设备选),而对档位来说太慢的游戏会自己把分辨率降下来。
+
+## 选择档位
+
+**设置 → 项目 → 渲染 → 设备画质 → 画质档位:**
+
+| 模式 | 含义 |
+|---|---|
+| 关闭 | 不做画质管理,项目按原样渲染(默认)。 |
+| 低 / 中 / 高 | 所有设备都用该档位。 |
+| 自动 | 档位由设备决定:第一条匹配的[设备规则](#设备规则),否则看内存和核心数。 |
+
+**动态分辨率**在 GPU 吃紧时降低场景分辨率,最低降到该档位的*最小渲染比例*,有余量时再升回来;UI 保持显示分辨率。
+**目标帧率**是它要维持的帧时间。
+
+## 一个档位里有什么
+
+**画质档位设置 → 正在编辑的档位**决定下面各行显示并修改哪个档位。它们按花在哪里分组:
+
+| 分组 | 设置 |
+|---|---|
+| 渲染 | 渲染比例、最小渲染比例、MSAA |
+| 阴影 | 图集尺寸、单元尺寸、级联数、距离 |
+| 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 |
+| 后处理 | 总开关,以及在这个档位运行的每个效果的勾选框 |
+
+每个档位从引擎自己的值起步,**只有你改过的才会保存**到 `project.esproject` 的
+`features.rendering.quality.profiles.<档位>` 下。引擎以后改进的默认值会传给从没碰过它的项目;改回该档位默认值的行也不再算差异。
+
+<Aside type="note">
+一行的"默认值"是它正显示的那个档位的默认值,所以同一个数字在低档可能是改动,在中档却是默认。
+</Aside>
+
+## 去掉一些效果
+
+引擎有的每个后处理效果都在列表里,该档位运行的打勾。没勾选的效果在这个档位被跳过,不管相机的体积是否要求它——而且是整个跳过:
+有多个 pass 的效果,比如环境光遮蔽或自动曝光,会被整体移除。清单里按类型保存被去掉的效果:
+
+```json
+"quality": { "mode": "auto", "profiles": { "low": { "skipEffects": ["ssr", "taa", "depthOfField"] } } }
+```
+
+默认情况下,低档去掉反射、时间性抗锯齿、景深和光束;中档去掉反射和景深;高档什么都不去掉。这些默认值依据每个效果每像素的工作量,
+**不是**在弱设备上量出来的。编辑器的 `fx-cost` 检查能量出每个效果在当前机器上的开销,可以在决定某个档位跳过什么之前先看看你的机器上它们要多少。
+
+## 设备规则
+
+模式为自动时显示。每行写一个档位和设备必须满足的条件:**型号包含**、**GPU 包含**、**内存上限**、**核心上限**,全部成立才算。
+第一条匹配的规则决定档位。没有任何条件的规则会匹配所有设备,所以必须至少有一个条件。
+
+## 在代码里
+
+同样的设置就是 `QualityConfig`——`QualityController`、`parseQualityConfig`、`resolveQualityProfile` 和 `defaultQualityProfile`
+构建并读取它——运行中的档位是 `Quality` 资源。
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 83fd13947..ab179d3ea 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 · 152 beta · 1651 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1653 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6983,6 +6983,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+skipEffects: readonly string[]
ssao: boolean
```
@@ -11962,6 +11963,11 @@ Plugin
PluralSelector
```
+## defaultQualityProfile — function @experimental
+```
+(level: QualityLevel): QualityProfile
+```
+
## defineBehavior — function @experimental
```
<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S>
@@ -13642,6 +13648,11 @@ PrefabsPlugin
(scene: SceneData, read: (ref: string) => Promise<unknown | null>): Promise<(ref: string) => PrefabRoot | null>
```
+## resolveQualityProfile — function @experimental
+```
+(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile
+```
+
## resolveShot — function @experimental
```
(clips: readonly CameraClip[], time: number): ShotState | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 1f6ace824..ce321ef82 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 · 157 beta · 1670 experimental · 3 deprecated
+Symbols: 115 public · 157 beta · 1672 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7186,6 +7186,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+skipEffects: readonly string[]
ssao: boolean
```
@@ -12215,6 +12216,11 @@ Plugin
PluralSelector
```
+## defaultQualityProfile — function @experimental
+```
+(level: QualityLevel): QualityProfile
+```
+
## defineBehavior — function @experimental
```
<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S>
@@ -13905,6 +13911,11 @@ PrefabsPlugin
(scene: SceneData, read: (ref: string) => Promise<unknown | null>): Promise<(ref: string) => PrefabRoot | null>
```
+## resolveQualityProfile — function @experimental
+```
+(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile
+```
+
## resolveShot — function @experimental
```
(clips: readonly CameraClip[], time: number): ShotState | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d50e85487..e704d1118 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 · 154 beta · 1650 experimental · 3 deprecated
+Symbols: 115 public · 154 beta · 1652 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6978,6 +6978,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+skipEffects: readonly string[]
ssao: boolean
```
@@ -11957,6 +11958,11 @@ Plugin
PluralSelector
```
+## defaultQualityProfile — function @experimental
+```
+(level: QualityLevel): QualityProfile
+```
+
## defineBehavior — function @experimental
```
<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S>
@@ -13647,6 +13653,11 @@ PrefabsPlugin
(scene: SceneData, read: (ref: string) => Promise<unknown | null>): Promise<(ref: string) => PrefabRoot | null>
```
+## resolveQualityProfile — function @experimental
+```
+(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile
+```
+
## resolveShot — function @experimental
```
(clips: readonly CameraClip[], time: number): ShotState | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5388d9c5a..168f6b109 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 · 152 beta · 1672 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1674 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7271,6 +7271,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+skipEffects: readonly string[]
ssao: boolean
```
@@ -12261,6 +12262,11 @@ Plugin
PluralSelector
```
+## defaultQualityProfile — function @experimental
+```
+(level: QualityLevel): QualityProfile
+```
+
## defineBehavior — function @experimental
```
<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S>
@@ -13951,6 +13957,11 @@ PrefabsPlugin
(scene: SceneData, read: (ref: string) => Promise<unknown | null>): Promise<(ref: string) => PrefabRoot | null>
```
+## resolveQualityProfile — function @experimental
+```
+(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile
+```
+
## resolveShot — function @experimental
```
(clips: readonly CameraClip[], time: number): ShotState | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e42667837..4ccca183e 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 · 152 beta · 1663 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1665 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6985,6 +6985,7 @@ shadowAtlasSize: number
shadowCascades: number
shadowCellSize: number
shadowDistance: number
+skipEffects: readonly string[]
ssao: boolean
```
@@ -11988,6 +11989,11 @@ Plugin
PluralSelector
```
+## defaultQualityProfile — function @experimental
+```
+(level: QualityLevel): QualityProfile
+```
+
## defineBehavior — function @experimental
```
<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S>
@@ -13678,6 +13684,11 @@ PrefabsPlugin
(scene: SceneData, read: (ref: string) => Promise<unknown | null>): Promise<(ref: string) => PrefabRoot | null>
```
+## resolveQualityProfile — function @experimental
+```
+(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile
+```
+
## resolveShot — function @experimental
```
(clips: readonly CameraClip[], time: number): ShotState | null
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 003007cdb..3cfc471db 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -313,7 +313,7 @@ export {
type PreSceneDrawCallback,
type PreSceneDrawInfo,
} from './render/customDraw';
-export { QualityController, parseQualityConfig } from './render/quality';
+export { QualityController, parseQualityConfig, resolveQualityProfile, defaultQualityProfile } from './render/quality';
export type {
QualityConfig, QualityProfile, QualityLevel, QualityMode,
QualityReport, DeviceQualityInfo, DeviceQualityRule,
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index 3c9acb4f3..354d1a948 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -8,6 +8,7 @@ import { handleWasmError } from '../wasm/wasmError';
import { WasmBridge } from '../wasm/WasmBridge';
import { PostProcessStack, PostProcessState } from './PostProcessStack';
import type { QualityProfile } from '../render/quality';
+import { qualityPassAllowed } from './qualityFilter';
/**
* The post-process entry points as a core that HAS them answers them. Named, not
@@ -207,12 +208,7 @@ export class PostProcessAPI {
}
private allowQualityPass_ = (name: string): boolean => {
- const q = this.qualityFilter_;
- if (q === null) return true;
- if (!q.postProcess) return false;
- const lower = name.toLowerCase();
- if (!q.ssao && lower.startsWith('ssao')) return false;
- return !q.skipEffects.some((skipped) => lower.startsWith(skipped.toLowerCase()));
+ return qualityPassAllowed(this.qualityFilter_, name);
};
// -- per-App state (stacks / bindings / screen stack) --------------------
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index b126772b0..6aa745565 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -65,6 +65,21 @@ export function getEffectDef(type: string): EffectDef | undefined {
return effectRegistry.get(type);
}
+/**
+ * The names of every pass an effect puts in the chain, in order: its sub-passes' for a multi-pass effect
+ * (`ssao` is four, named `ssao_ao`, `ssao_blur_x` …; `autoExposure` is `ae_measure`, `ae_adapt`,
+ * `ae_apply`), its own type otherwise. Empty for a type nobody registered. What a quality level that leaves an
+ * effect out has to remove, and what no guess from the effect's name would find.
+ */
+export function effectPassNames(type: string): string[] {
+ const wanted = type.toLowerCase();
+ for (const def of effectRegistry.values()) {
+ if (def.type.toLowerCase() !== wanted) continue;
+ return def.multiPass ? def.multiPass.map((pass) => pass.name) : [def.type];
+ }
+ return [];
+}
+
export function getEffectTypes(): string[] {
return Array.from(effectRegistry.keys());
}
diff --git a/sdk/src/postprocess/qualityFilter.ts b/sdk/src/postprocess/qualityFilter.ts
new file mode 100644
index 000000000..ab729cf06
--- /dev/null
+++ b/sdk/src/postprocess/qualityFilter.ts
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { QualityProfile } from '../render/quality';
+import { effectPassNames } from './effects';
+
+/**
+ * Whether a quality level lets a pass of the chain run.
+ *
+ * A level names the effects it leaves out by TYPE; a pass is named by the effect's definition (its type, or the
+ * names of its sub-passes), so this asks the registry which passes an effect is rather than guessing from the
+ * name — a guess that reads `autoExposure` as a prefix finds none of `ae_measure`, `ae_adapt`, `ae_apply`.
+ * An entry no effect answers to is kept as a prefix of the pass name, which is what the list meant before
+ * effects were named by type.
+ */
+export function qualityPassAllowed(profile: Readonly<QualityProfile> | null, passName: string): boolean {
+ if (profile === null) return true;
+ if (!profile.postProcess) return false;
+ const name = passName.toLowerCase();
+ if (!profile.ssao && effectPassNames('ssao').some((pass) => pass.toLowerCase() === name)) return false;
+ for (const skipped of profile.skipEffects) {
+ const passes = effectPassNames(skipped);
+ if (passes.length > 0) {
+ if (passes.some((pass) => pass.toLowerCase() === name)) return false;
+ } else if (name.startsWith(skipped.toLowerCase())) {
+ return false;
+ }
+ }
+ return true;
+}
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index c7e0d7c89..30708dd13 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -27,10 +27,11 @@ export interface QualityProfile {
postProcess: boolean;
ssao: boolean;
/**
- * Post-process effects this level leaves out, each named by what its passes' names start with
- * (`ssr`, `taa`, `depthOfField`, `lightShafts` …), compared without regard to case. The expensive ones are
- * the ones a weak device has no use for: they are measured per effect (`fx-cost` in the editor checks), and
- * what a level skips follows from what a frame on that device can afford.
+ * Post-process effects this level leaves out, each named by its effect type (`ssr`, `taa`, `depthOfField`,
+ * `lightShafts`, `autoExposure` …), compared without regard to case. An effect is all of its passes: a
+ * multi-pass effect is skipped whole, however its passes are named. The expensive ones are the ones a weak
+ * device has no use for — they are measured per effect (`fx-cost` in the editor checks) — so what a level
+ * skips follows from what a frame on that device can afford.
*/
skipEffects: readonly string[];
}
@@ -153,6 +154,16 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
};
}
+/** A level's profile as the engine will use it: the level's own defaults with a project's overrides on top. */
+export function resolveQualityProfile(level: QualityLevel, overrides?: Partial<QualityProfile>): QualityProfile {
+ return resolveProfile(level, overrides);
+}
+
+/** What a level is before a project says anything about it. */
+export function defaultQualityProfile(level: QualityLevel): QualityProfile {
+ return PROFILES[level];
+}
+
function matches(rule: DeviceQualityRule, info: DeviceQualityInfo): boolean {
const includes = (text: string | undefined, part: string): boolean =>
text?.toLowerCase().includes(part.toLowerCase()) ?? false;
diff --git a/sdk/tests/quality.test.ts b/sdk/tests/quality.test.ts
index 278d1f34e..025fc8f36 100644
--- a/sdk/tests/quality.test.ts
+++ b/sdk/tests/quality.test.ts
@@ -114,3 +114,32 @@ describe('dynamic resolution', () => {
expect(staticQ.renderScale).toBe(0.75);
});
});
+
+describe('what a quality level lets the chain run', () => {
+ const level = (skipEffects: string[], extra: object = {}) => new QualityController({
+ mode: 'low', profiles: { low: { skipEffects, ...extra } },
+ }).profile;
+
+ it('removes every pass of a multi-pass effect, however its passes are named', async () => {
+ const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
+ const profile = level(['autoExposure', 'ssao']);
+ for (const pass of ['ae_measure', 'ae_adapt', 'ae_apply', 'ssao_ao', 'ssao_blur_x', 'ssao_composite']) {
+ expect(qualityPassAllowed(profile, pass), pass).toBe(false);
+ }
+ expect(qualityPassAllowed(profile, 'bloom'), 'bloom').toBe(true);
+ expect(qualityPassAllowed(profile, 'ssr'), 'ssr').toBe(true);
+ });
+
+ it('keeps the old prefix reading for a name no effect answers to, and the ssao and post-process switches', async () => {
+ const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
+ expect(qualityPassAllowed(level(['custom']), 'custom_pass')).toBe(false);
+ expect(qualityPassAllowed(level([], { ssao: false }), 'ssao_blur_y')).toBe(false);
+ expect(qualityPassAllowed(level([], { postProcess: false }), 'bloom')).toBe(false);
+ expect(qualityPassAllowed(null, 'anything')).toBe(true);
+ });
+
+ it('names the effects a level leaves out by type, ignoring case', async () => {
+ const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
+ expect(qualityPassAllowed(level(['DepthOfField']), 'depthOfField')).toBe(false);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6a52c736b..913e11219 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2483,6 +2483,8 @@ export const NOTED = {
{"note":"Auto Exposure and Depth of Field post-process effects are available."},
"feat(render): a Rain effect with wet ground, puddles, ripples and splashes, and reflections that treat puddles as mirrors":
{"note":"A Rain post-process effect adds falling rain, wet ground, puddles and ripples."},
+ "feat(editor): Settings edits the three quality levels, one at a time, effect by effect, and the device rules Auto chooses by":
+ {"note":"Settings → Project → Rendering edits each quality level, including which effects it runs."},
"feat(render): the scene can draw a G-buffer beside its colour, and reflections read each surface's normal, roughness and metalness from it":
{"note":"Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request."},
};