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(render): a quality level sets how far plants keep their detail

yhh0a8fc624237d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 690581c3f..57b40590a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A quality level sets how far plants keep their detail.** A level's profile takes a `detailScale` (0.25 to 1; Low 0.5, Medium 0.8, High 1): a placed plant changes to its cheaper mesh, stops being drawn and stops casting a shadow at that share of its distances, so the same world draws a fraction of the triangles on a phone. It is a row in Project Settings → Rendering → Quality Levels.
- **Placed plants cast shadows only as far as twice their detailed distance.** `MeshInstances` takes a `shadowDistance` (metres from the eye past which an instance casts no shadow); a plant kind with a cheaper mesh sets it to twice that mesh's distance, so a tree far off is drawn into the shadow maps no more than its shadow is worth.
- **The editor lets go of a generated world while the game plays.** The game runs in a realm of its own that builds its own copy of a generated world; the editor's copy is released for as long as it runs and made again on Stop, so the two are not held together.
- **Plants are instances of one mesh.** A generated world's and a `PlacedFoliage`'s plants no longer merge their vertices a cell at a time: a new `MeshInstances` component places one resident mesh at many places (sixty-four bytes a plant), and the engine culls each plant against the view, takes a cheaper mesh past a distance and draws none past another, as one instanced draw that cells sharing a mesh and a material merge into. The geometry exists once however many plants there are, so a planet's plants take a tenth of the memory and a fraction of the draws, and a cell is grown in microseconds instead of a few milliseconds.
diff --git a/desktop b/desktop
index cf048c839..f4d2077af 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit cf048c8394110ae80bf67e30484335cfc60bea97
+Subproject commit f4d2077af858b0459801dc4e7169d3630b0c3487
diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdx
index 16b0739c1..3fa6802e0 100644
--- a/docs/astro/src/content/docs/performance/quality-levels.mdx
+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx
@@ -29,7 +29,7 @@ to.
| Group | Settings |
|---|---|
-| Rendering | Render scale, Min render scale, MSAA |
+| Rendering | Render scale, Min render scale, MSAA, Detail distance |
| 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 |
@@ -43,6 +43,10 @@ A row's "default" is the default of the level it is showing, so the same number
at Medium.
</Aside>
+**Detail distance** is the share of its distances a placed plant keeps at the level: at 0.5, a tree that changes to its
+cheaper mesh at 60 m and is not drawn as itself past 150 m does so at 30 m and 75 m, and its far cards take over sooner.
+Low keeps 0.5, Medium 0.8 and High all of it, so the same world draws a fraction of the triangles on a phone.
+
## 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
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 b6067ee4f..b9aeaf94a 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
@@ -27,7 +27,7 @@ import { Aside } from '@astrojs/starlight/components';
| 分组 | 设置 |
|---|---|
-| 渲染 | 渲染比例、最小渲染比例、MSAA |
+| 渲染 | 渲染比例、最小渲染比例、MSAA、细节距离 |
| 阴影 | 图集尺寸、单元尺寸、级联数、距离 |
| 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 |
| 后处理 | 总开关,以及在这个档位运行的每个效果的勾选框 |
@@ -39,6 +39,8 @@ import { Aside } from '@astrojs/starlight/components';
一行的"默认值"是它正显示的那个档位的默认值,所以同一个数字在低档可能是改动,在中档却是默认。
</Aside>
+**细节距离**是一档里放置的植物保留多少比例的距离:0.5 时,原本 60 米换成更省网格、150 米外不再画本体的树,会在 30 米和 75 米处这样做,远景卡片也更早接手。低档保留 0.5、中档 0.8、高档全部,所以同一个世界在手机上画的三角形只有一小部分。
+
## 去掉一些效果
引擎有的每个后处理效果都在列表里,该档位运行的打勾。没勾选的效果在这个档位被跳过,不管相机的体积是否要求它——而且是整个跳过:
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3dab0b92e..96be3b511 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -7566,6 +7566,7 @@ static prototype: QualityController
## QualityProfile — interface @experimental
```
+detailScale: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 6d485c610..7924ec35e 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -7769,6 +7769,7 @@ static prototype: QualityController
## QualityProfile — interface @experimental
```
+detailScale: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 4524c04cf..0a3b5100a 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7561,6 +7561,7 @@ static prototype: QualityController
## QualityProfile — interface @experimental
```
+detailScale: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7f595c697..d67a220a4 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7854,6 +7854,7 @@ static prototype: QualityController
## QualityProfile — interface @experimental
```
+detailScale: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d891f77c7..86d7ed729 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7568,6 +7568,7 @@ static prototype: QualityController
## QualityProfile — interface @experimental
```
+detailScale: number
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
particleLimit: number
diff --git a/sdk/src/foliage/plantGrowth.ts b/sdk/src/foliage/plantGrowth.ts
index c82e38233..5fe2a440d 100644
--- a/sdk/src/foliage/plantGrowth.ts
+++ b/sdk/src/foliage/plantGrowth.ts
@@ -21,6 +21,7 @@ import { engineApi } from '../ecs/bridge/engineApi';
import type { CppRegistry } from '../wasm';
import { withScratch } from '../wasm/wasmScratch';
import { Assets } from '../asset/AssetPlugin';
+import { Quality } from '../render/qualityRuntime';
import type { Assets as AssetsApi } from '../asset/Assets';
import { log } from '../util/logger';
import { bakesOf } from '../runtime/bakes';
@@ -96,10 +97,16 @@ export class PlantGrowth {
/**
* Makes one entity under `parent` that draws `part`'s mesh at every place in `plants`, relative to `parent`. `from` and `to` are the distances
- * from the eye between which a plant is drawn (0 for no limit); `lod` is the distance past which the part's cheaper mesh stands in, and `shadow` the one past which it casts no shadow.
+ * from the eye between which a plant is drawn (0 for no limit); `lod` is the distance past which the part's cheaper mesh stands in, and `shadow` the one past which it casts no shadow. All of them are scaled by the quality level's `detailScale`.
*/
- private place(app: App, parent: Entity, name: string, part: ReadyPart, plants: readonly Plant[], lod: number, from: number, to: number, shadow = 0): void {
+ private place(app: App, parent: Entity, name: string, part: ReadyPart, plants: readonly Plant[], lod: number, from: number, to: number, shadow = 0, far = false): void {
const world = app.world;
+ // The quality level's share of the kind's distances: a weaker device changes to the cheaper mesh sooner and draws less far.
+ const quality = app.hasResource(Quality) ? app.getResource(Quality) : null;
+ const detail = quality && quality.enabled ? quality.profile.detailScale : 1;
+ lod *= detail; from *= detail; shadow *= detail;
+ // The far version costs the same at any distance, so only where it begins moves, not where it ends.
+ if (to > 0 && !far) to *= detail;
const e = world.spawn(name);
world.insert(e, RuntimeOnly);
world.insert(e, Transform, {});
@@ -158,7 +165,7 @@ export class PlantGrowth {
const parts = ready.far[kindIndex], kind = kinds[kindIndex];
if (!kind || !parts || parts.length === 0) continue;
const kept = thinPlants(plants, kind.farKeep ?? 1);
- for (const r of parts) this.place(app, entity, `far ${kindIndex}`, r, kept, 0, kind.drawDistance, kind.farDistance);
+ for (const r of parts) this.place(app, entity, `far ${kindIndex}`, r, kept, 0, kind.drawDistance, kind.farDistance, 0, true);
}
}
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index 15fe66ff6..77002cb18 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -19,6 +19,11 @@ export interface QualityProfile {
shadowCellSize: number;
shadowCascades: number;
shadowDistance: number;
+ /**
+ * How much of its distances a level lets a plant keep, 0.25 to 1: a kind that changes to its cheaper mesh at 60 m and is not drawn past
+ * 150 m does so at 30 m and 75 m with 0.5. The far version (a tree's cards) is the same cost at any distance, so it takes over sooner.
+ */
+ detailScale: number;
particleLimit: number;
planarReflectionScale: number;
planarReflectionMaxSize: number;
@@ -69,7 +74,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
renderScale: 0.75, minRenderScale: 0.5, msaaSamples: 1,
shadowAtlasSize: 1024, shadowCellSize: 256, shadowCascades: 2,
planarReflectionScale: 0.25, planarReflectionMaxSize: 512, planarReflectionUpdatesPerSecond: 0,
- shadowDistance: 0, particleLimit: 1000, postProcess: true, ssao: false,
+ shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,
waterWaves: 2, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,
skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI'],
},
@@ -77,7 +82,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2,
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 3,
planarReflectionScale: 0.5, planarReflectionMaxSize: 1024, planarReflectionUpdatesPerSecond: 0,
- shadowDistance: 0, particleLimit: 5000, postProcess: true, ssao: true,
+ shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,
waterWaves: 3, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: ['ssr', 'depthOfField'],
},
@@ -87,7 +92,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
// shadow speckles it with dirt. 1024 is the cell that clears it for a character at arm's length.
shadowAtlasSize: 4096, shadowCellSize: 1024, shadowCascades: 4,
planarReflectionScale: 1, planarReflectionMaxSize: 2048, planarReflectionUpdatesPerSecond: 0,
- shadowDistance: 0, particleLimit: 20000, postProcess: true, ssao: true,
+ shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,
waterWaves: 4, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: [],
},
@@ -156,6 +161,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
shadowCellSize: Math.min(cell, atlas / 2),
shadowCascades: Math.round(finite(r.shadowCascades, base.shadowCascades, 1, 4)),
shadowDistance: finite(r.shadowDistance, base.shadowDistance, 0, 10000000),
+ detailScale: finite(r.detailScale, base.detailScale, 0.25, 1),
particleLimit: Math.round(finite(r.particleLimit, base.particleLimit, 0, 1000000)),
planarReflectionScale: finite(r.planarReflectionScale, base.planarReflectionScale, 0.125, 1),
planarReflectionMaxSize: Math.round(finite(r.planarReflectionMaxSize, base.planarReflectionMaxSize, 64, 4096)),
diff --git a/sdk/tests/quality.test.ts b/sdk/tests/quality.test.ts
index 16a0531c4..3aefa087d 100644
--- a/sdk/tests/quality.test.ts
+++ b/sdk/tests/quality.test.ts
@@ -146,3 +146,14 @@ describe('what a quality level lets the chain run', () => {
}
});
});
+
+describe('how far plants keep their detail', () => {
+ it('is a share of a plant\'s distances that falls with the level, and a project may set it', () => {
+ const share = (mode: 'low' | 'medium' | 'high', detailScale?: unknown) =>
+ new QualityController(parseQualityConfig({ mode, profiles: detailScale === undefined ? undefined : { [mode]: { detailScale } } })).profile.detailScale;
+ expect([share('low'), share('medium'), share('high')]).toEqual([0.5, 0.8, 1]);
+ expect(share('low', 0.3)).toBe(0.3);
+ expect(share('low', 0)).toBe(0.25);
+ expect(share('low', 7)).toBe(1);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index bc2498ee2..eeed745e4 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2908,6 +2908,8 @@ export const NOTED = {
{"internal":"Reference snapshot and doc links."},
"feat(render): placed plants cast shadows only as far as twice their detailed distance":
{"note":"Placed plants cast shadows only as far as twice their detailed distance."},
+ "feat(render): a quality level sets how far plants keep their detail":
+ {"note":"A quality level sets how far plants keep their detail."},
"feat(assets): a project names folders its asset database leaves alone":
{"note":"A project can keep folders out of its asset database."},
"feat(worldgen): a plant part may cast no shadow, and far cells are capped at two cells wide":