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
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.mjsindex 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":