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.

perf(chunks): the chunk and plant growth steps are measured as scopes, and the plan to move generation to worker threads

yhh3261d44490ef
diff --git a/docs/ASYNC_WORLDGEN_PLAN.md b/docs/ASYNC_WORLDGEN_PLAN.md
new file mode 100644
index 000000000..d712966dc
--- /dev/null
+++ b/docs/ASYNC_WORLDGEN_PLAN.md
@@ -0,0 +1,39 @@
+# 流式生成放到后台线程:工作计划
+
+2026-10-25 建立。起因:在编辑器里停止运行、或第一次进入大场景后,主线程会被世界生成占满,视口掉到个位数帧。本文记录测量、结论和做法。
+
+## 测量
+
+星邻球面世界和 `examples/terrain-water` 都一样:每帧 `ProceduralChunkSystem`(`chunks.step`)占主线程 44 ms(均值),最差一帧 250 ms;停止运行后重新铺设的 5 秒里 105 帧中有 74 帧超过 16.7 ms,p95 为 150 ms。成本几乎全在 `WorldPlan.placementsIn`:规则里的群落、配方、候选点、邻居冲突。`cover` 层一个 32 米的块约 43 ms(328 个放置,约 130 µs 一个),四层合计约 70 ms 一个块;绘制距离内有几百个块,总计是十几秒的纯计算。
+
+## 结论:分帧是止痛,不是做法
+
+现在的做法是把工作切成块、每帧只做预算内的几块(`bakes.hasTime()`),而每个块本身要 40–250 ms,且脚下的块不受预算限制。这是单线程里的协作式调度:总工作量不变,每帧仍然要付一整块的钱,所以卡顿只能靠"块更小"来缓解,不能消除。
+
+主流引擎(Unreal 的 World Partition、PCG,Unity 的 Jobs)的做法是:纯计算放到后台线程,游戏线程只做"提交"——创建实体、上传 GPU、挂到场景。游戏线程每帧的成本因此与世界多大无关。
+
+## 做法
+
+1. **作业池**:`runtime/jobs.ts`,一个 Web Worker 池(原生宿主用工作线程),按作业类型派发,作业入参和结果都是可转移的类型化数组或可结构化克隆的数据;取消用 AbortSignal;池大小随硬件并发数,留一个核给主线程和渲染。`ProceduralChunks` 的 `make` 已经可以返回 Promise,所以块层直接接入。
+2. **放置规划上 worker**:`WorldPlan` 是纯函数(种子、规则、环境场),不碰引擎状态,只需要把 `Environment` 的输入换成能在 worker 里重建的"数据":
+ - 规则、区域、差异:JSON,直接发。
+ - 噪声场:引擎自己的纯函数,worker 里同一份代码。
+ - 地面高度、法线、涂色、生态场:由 **提供器** 给出。提供器本来就是"版本化的纯函数"(`registerTerrainProvider` / `registerPlanetProvider`),所以约定提供器可以作为独立模块在 worker 里加载(`provider.module`),主线程不再替 worker 采样。
+ - 水深、岸距:水体的烘焙场(CPU 数组)作为可转移缓冲发给 worker,版本号变了才重发。
+3. **星球页面上 worker**:页面的高度、法线、涂色(含群落上色)都是提供器加规划的纯函数,同样走作业池,返回 `Uint8Array` 页面,主线程只做图集上传。
+4. **碰撞三角网上 worker**:同理,返回位置和索引数组。
+5. **主线程只剩提交**:每帧预算内最多提交 N 个结果(创建实体、`meshInstances_set`、上传纹理),提交本身按结果大小摊平。
+6. **可观测**:作业池的排队数、在途数、每类作业耗时进性能分析器;`chunks.step` 这一帧成本应当接近 0。
+
+## 先后
+
+1. 作业池 + 星球页面(最大头,且提供器是纯的,没有水体问题)。
+2. 放置规划(星球先,平面地形随后:需要水体烘焙场可转移)。
+3. 碰撞三角网。
+4. 验收:同一场景停止运行后 p95 帧时间 < 20 ms,`chunks.step` < 2 ms;结果与主线程版本逐字节相同(同一份规划代码,测试覆盖)。
+
+## 约束与取舍
+
+- 提供器模块要能在 worker 里加载:项目脚本的打包要多出一个 worker 入口;这是管线改动(编辑器、导出、网页运行时都要认)。
+- 规则里自定义的 `fields` 函数(代码注册的规则)不能跨线程;`.esworld` 文件里的规则没有函数,不受影响。代码注册的规则要么提供 worker 模块,要么留在主线程。
+- 小程序等没有 Worker 的宿主退回主线程分帧(现在的做法),行为一致、只是慢。
diff --git a/sdk/src/foliage/plantGrowth.ts b/sdk/src/foliage/plantGrowth.ts
index 55f288362..d8a494ddf 100644
--- a/sdk/src/foliage/plantGrowth.ts
+++ b/sdk/src/foliage/plantGrowth.ts
@@ -203,7 +203,7 @@ export function plantGrowthOf(app: App): PlantGrowth {
const growth = new PlantGrowth();
growth.app_ = app;
app.insertResource(PlantGrowthRes, growth);
- app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { if (app.hasResource(Assets)) growth.step(app); }, { name: 'PlantGrowthSystem' }));
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => { if (app.hasResource(Assets)) app.measureFrameScope('plants.grow', () => growth.step(app)); }, { name: 'PlantGrowthSystem' }));
}
return app.getResource(PlantGrowthRes);
}
diff --git a/sdk/src/residency/chunks.ts b/sdk/src/residency/chunks.ts
index c41bf6032..02058d639 100644
--- a/sdk/src/residency/chunks.ts
+++ b/sdk/src/residency/chunks.ts
@@ -370,7 +370,7 @@ export function chunksOf(app: App): ProceduralChunks {
const bakes = bakesOf(app);
const shown = new Set<object>();
app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => {
- chunks.step(() => bakes.hasTime());
+ app.measureFrameScope('chunks.step', () => chunks.step(() => bakes.hasTime()));
const now = new Set<object>();
for (const p of chunks.progress_()) { bakes.mark(p.owner, p.label, p.progress); now.add(p.owner); }
for (const owner of shown) if (!now.has(owner)) bakes.clear(owner);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 932da4764..ec6a83bc7 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2916,6 +2916,8 @@ export const NOTED = {
{"note":"The editor's own eye shows the scene's post-processing."},
"feat(terrain): the maths of ground on a cube sphere and the nodes drawn round an eye":
{"internal":"The first layer of spherical terrain: pure maths and node selection, not yet drawn."},
+ "perf(chunks): the chunk and plant growth steps are measured as scopes, and the plan to move generation to worker threads":
+ {"internal":"Profiler scopes and a design note."},
"feat(terrain): a planet has a sea and a sky that follows the ground the camera stands on":
{"note":"A planet's sea and sky."},
"feat(worldgen): a generated world lays out over a planet's six faces":