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(worldgen): a planet's world and pages are worked out on worker threads

yhh6f61bb2ba716
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9405749f0..fd3a0b5b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A generated world on worker threads.** A planet provider can give the engine its generator as `workerSource` (the text of a self-contained module), and the world's placements and the planet's pages (heights, normals, and the paint by the biomes) are then worked out by a pool of workers (`runtime/jobs.ts`), byte for byte what the main thread works out, while the main thread only puts the answers in the world, a few a frame. Laying out a planet's world no longer costs the frame: 2 to 8 frames a second while it was laid out became 60.
- **A planet's sea and sky.** `Planet.sea` draws a translucent, lit sphere at `seaLevel` in which the ground that dips below it stands, and `skyAtmosphere` takes the planet's radius and centre (`u_planetRadius`, `u_planetX/Y/Z`, as `heightFog` does) to work the sky out in the frame of the ground the camera stands on, so the horizon, the sun and the haze follow it round.
- **A generated world on a planet.** A `WorldGen` with `surface` Planet, on a `Planet`'s entity, lays the world out over the cube's six faces, each as a plane of metres, by the same rules a flat world has: biomes over fields, recipes and layers. A direction is planned by the face it falls on; what is placed is taken to the planet and stands along its up. The fields are the planet's own (height, slope, noise in three dimensions with no seam between faces, `paint.<layer>`, and the fields a planet provider names with `fields`), the biomes paint the ground too, and `seaLevel` and `WorldZone`s work over a planet.
- **A planet pulls and answers.** `Planet.gravity` pulls every dynamic 3D body toward the centre of the nearest planet that pulls (the world's gravity is taken off the body and the planet's put on, as a force each fixed step), and the `PlanetRegistryRes` resource answers `up`, `altitude`, `groundHeight`, `groundPoint` and `nearest` for what stands, aims or falls on a round world.
diff --git a/docs/ASYNC_WORLDGEN_PLAN.md b/docs/ASYNC_WORLDGEN_PLAN.md
index d712966dc..d58d64bff 100644
--- a/docs/ASYNC_WORLDGEN_PLAN.md
+++ b/docs/ASYNC_WORLDGEN_PLAN.md
@@ -25,6 +25,12 @@
5. **主线程只剩提交**:每帧预算内最多提交 N 个结果(创建实体、`meshInstances_set`、上传纹理),提交本身按结果大小摊平。
6. **可观测**:作业池的排队数、在途数、每类作业耗时进性能分析器;`chunks.step` 这一帧成本应当接近 0。
+## 进展(2026-10-25)
+
+已完成第 1、2 步在星球上的部分:`runtime/jobs.ts`(作业池)、`worldgen/planWorker.ts`(放置规划与星球页面,打包成文本 `runtime/planWorkerBundle.generated.ts`,由 `sdk/scripts/build-worker.mjs` 生成并有测试守新鲜度)、`PlanetProvider.workerSource`(提供器的自包含模块文本,星邻由 `tools/build-provider-worker.mjs` 生成)。提交一侧:`ProceduralChunks` 的答案和星球页面都进队列、每帧限量放入世界。实测星邻球面世界铺设期间:此前 2–8 帧,现在 60 帧(p95 33 ms,最差 33 ms);`chunks.step` 44 ms → 2.3 ms,`PlanetSystem` 133 ms → 1.7 ms。worker 的结果与主线程逐字节一致(`tests/worldgen-worker.test.ts`)。
+
+未做:平面地形(`Terrain`)上的 `WorldGen`(需要水体烘焙场可转移)、碰撞三角网、没有 Worker 时的主线程路径仍是分帧。
+
## 先后
1. 作业池 + 星球页面(最大头,且提供器是纯的,没有水体问题)。
diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdx
index 75e38c1cc..1d5d7a8ff 100644
--- a/docs/astro/src/content/docs/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/graphics/terrain.mdx
@@ -286,7 +286,9 @@ A planet answers the questions a round world puts to everything standing on it,
A generated world can be laid out over a planet: put a `WorldGen` with `surface` set to Planet on the `Planet`'s entity. Each of the cube's six faces is laid out as a plane of metres by the same rules a flat world has (biomes over fields, recipes, layers), a direction is planned by the face it falls on, and what is placed is taken to the planet and stands along its up. The fields are the planet's own: the ground's height, its slope, noise read in three dimensions (so a field wanders over an edge between two faces with no seam), `paint.<layer>` for each of the planet's layers, and the fields the provider names with `fields` (an ecology). The biomes also paint the ground (`paintGround`), so what is drawn and what grows are one map. `seaLevel` is the height of the sea: lower ground is under water. Zones (`WorldZone`) stand at a position in the world and are kept on the face they fall on.
-The ground collides: the finest nodes within `collisionDistance` of every moving 3D body and character are built as collision geometry from the same samples the ground is drawn from (`collision`, `collisionDistance`, `collisionLayer`, `friction`, as on a flat terrain). A planet's transform is a position only: a turned or scaled planet's collision stands where it would be unturned. `layers` names up to four `.esterrainlayer` files, as on a flat terrain; each is read on the planes of the world's axes by how much the ground faces them, with a wider read mixed in far off so the repeat is lost. Without layers the ground is the four colours. Set `sea` and the planet has a sea: a translucent, lit sphere at `seaLevel` above the radius, in which the ground that dips below it stands (waves and shore foam are the flat water's and come to the sphere later). The sky follows the horizon round: give `skyAtmosphere` and `heightFog` the planet's radius and centre and they work out the sky and the haze for the ground the camera stands on, with the sun a fixed direction, so a place's day and night are where it is on the planet.
+The ground collides: the finest nodes within `collisionDistance` of every moving 3D body and character are built as collision geometry from the same samples the ground is drawn from (`collision`, `collisionDistance`, `collisionLayer`, `friction`, as on a flat terrain). A planet's transform is a position only: a turned or scaled planet's collision stands where it would be unturned. `layers` names up to four `.esterrainlayer` files, as on a flat terrain; each is read on the planes of the world's axes by how much the ground faces them, with a wider read mixed in far off so the repeat is lost. Without layers the ground is the four colours. A planet's provider can hand the engine its generator as a module a worker can load (`workerSource`: the text of a self-contained module of plain JavaScript whose default export answers `sample`, `fields`, `versions` and `id`). The world is then laid out and the ground painted on worker threads, and the main thread only puts the answers in the world, a few a frame; without it everything is done on the main thread as before.
+
+Set `sea` and the planet has a sea: a translucent, lit sphere at `seaLevel` above the radius, in which the ground that dips below it stands (waves and shore foam are the flat water's and come to the sphere later). The sky follows the horizon round: give `skyAtmosphere` and `heightFog` the planet's radius and centre and they work out the sky and the haze for the ground the camera stands on, with the sun a fixed direction, so a place's day and night are where it is on the planet.
## Limits
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
index eda2ad9a3..e5aad8523 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
@@ -197,7 +197,9 @@ registerTerrainProvider(planet);
生成的世界可以铺在星球上:在 `Planet` 所在的实体上放一个 `surface` 设为 Planet 的 `WorldGen`。立方体的六个面各按米制平面,用和平面世界一样的规则(字段之上的群落、配方、图层)铺设;一个方向由它落在的那个面来规划,放出来的东西被带到星球上,沿着当地的"上"站立。字段是星球自己的:地面高度、坡度、在三维里读的噪声(所以字段越过两个面之间的边没有接缝)、星球每个图层的 `paint.<层名>`,以及提供器用 `fields` 命名的字段(比如生态)。群落同时给地面上色(`paintGround`),画出来的和长出来的是同一张图。`seaLevel` 是海平面高度,比它低的地面在水下。区域(`WorldZone`)站在世界里的一个位置上,归它落在的那个面。
-地面有碰撞:每个运动的 3D 刚体和角色在 `collisionDistance` 内的最细节点,会用画地面的同一批采样建成碰撞几何(`collision`、`collisionDistance`、`collisionLayer`、`friction`,和平面地形一样)。星球的变换只有位置:旋转或缩放过的星球,碰撞仍站在没旋转时的位置。`layers` 可以写最多四个 `.esterrainlayer` 文件,和平面地形一样;每层按地面朝向世界坐标轴的程度,在三个投影面上取样,远处混入更宽的一次取样,看不出重复。不写图层时地面就是四种颜色。设置 `sea` 星球就有海:一个半透明、受光的球面,高出半径 `seaLevel`,低于它的地面站在水里(波浪和岸边泡沫是平面水体的,之后会来到球面)。天空跟着地平线转:给 `skyAtmosphere` 和 `heightFog` 填上星球的半径和中心,它们就按相机站着的那片地面算天空和雾,太阳是固定方向,所以一个地方的昼夜取决于它在星球上的位置。
+地面有碰撞:每个运动的 3D 刚体和角色在 `collisionDistance` 内的最细节点,会用画地面的同一批采样建成碰撞几何(`collision`、`collisionDistance`、`collisionLayer`、`friction`,和平面地形一样)。星球的变换只有位置:旋转或缩放过的星球,碰撞仍站在没旋转时的位置。`layers` 可以写最多四个 `.esterrainlayer` 文件,和平面地形一样;每层按地面朝向世界坐标轴的程度,在三个投影面上取样,远处混入更宽的一次取样,看不出重复。不写图层时地面就是四种颜色。星球的提供器可以把自己的生成器交给引擎,作为 worker 能加载的模块(`workerSource`:一段自包含的纯 JavaScript 模块文本,默认导出实现 `sample`、`fields`、`versions` 和 `id`)。这样世界的铺设和地面上色都在 worker 线程里完成,主线程只负责把结果放进世界,每帧放几个;不提供时一切仍在主线程上做。
+
+设置 `sea` 星球就有海:一个半透明、受光的球面,高出半径 `seaLevel`,低于它的地面站在水里(波浪和岸边泡沫是平面水体的,之后会来到球面)。天空跟着地平线转:给 `skyAtmosphere` 和 `heightFog` 填上星球的半径和中心,它们就按相机站着的那片地面算天空和雾,太阳是固定方向,所以一个地方的昼夜取决于它在星球上的位置。
## 限制
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3fefb96b2..b79be3640 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -6784,6 +6784,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f12c1c6f9..0dfa93277 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -6987,6 +6987,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 66c4dc6dc..db1f9bf5d 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -6779,6 +6779,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 595f46a68..982eee545 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7072,6 +7072,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
diff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.md
index 7b3cd2b55..283c83b1c 100644
--- a/sdk/etc/terrain.api.md
+++ b/sdk/etc/terrain.api.md
@@ -213,6 +213,7 @@ layers: readonly string[]
paint: ((dx: number, dy: number, dz: number) => readonly number[] | null) | null
radius: number
sampleMany: ((directions: Float32Array, count: number) => PlanetSamples | null) | null
+worker: { source: string; seed: number; version: number; world: string; } | null | undefined
```
## PlanetPageSource — interface @experimental
@@ -244,6 +245,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
@@ -265,7 +267,8 @@ nearest: (x: number, y: number, z: number) => Entity | null
paintOf: (entity: Entity) => PlanetPainter | null
paintRevision: number
planets: Map<number, PlanetFacts>
-setPaint: (entity: Entity, painter: PlanetPainter | null) => void
+remotePaintOf: (entity: Entity) => RemotePaint | null
+setPaint: (entity: Entity, painter: PlanetPainter | null, remote?: RemotePaint | null) => void
up: (entity: Entity, x: number, y: number, z: number) => [number, number, number] | null
static new (): PlanetRegistry
static prototype: PlanetRegistry
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 7815c3a96..7b540f873 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -6786,6 +6786,7 @@ id: string
range: (seed: number, version: number, radius: number) => [number, number]
sample: (region: PlanetRegion) => PlanetSamples | Promise<PlanetSamples>
versions: readonly number[]
+workerSource: string | undefined
```
## PlanetRegion — interface @experimental
diff --git a/sdk/package.json b/sdk/package.json
index 1ae605d3d..5b23f9a8e 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -183,7 +183,7 @@
"dist"
],
"scripts": {
- "build": "pnpm clean && rolldown -c && rollup -c",
+ "build": "pnpm clean && node scripts/build-worker.mjs && rolldown -c && rollup -c",
"watch": "rolldown -c -w",
"clean": "rimraf dist",
"api:check": "node ../tools/api-surface.mjs --check",
diff --git a/sdk/scripts/build-worker.mjs b/sdk/scripts/build-worker.mjs
new file mode 100644
index 000000000..fa2644119
--- /dev/null
+++ b/sdk/scripts/build-worker.mjs
@@ -0,0 +1,14 @@
+// Bundles the worlds' planning worker (src/worldgen/planWorker.ts) into the text the engine starts its workers from, and writes it as a module:
+// node scripts/build-worker.mjs [--check]
+// `--check` writes nothing and exits 1 when the committed text is not what the source makes now.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { workerModule } from './worker-source.mjs';
+
+const { path, source, bytes } = await workerModule();
+if (process.argv.includes('--check')) {
+ if ((existsSync(path) ? readFileSync(path, 'utf8') : '') !== source) { console.error('planWorkerBundle.generated.ts is not what src/worldgen/planWorker.ts makes now: run node scripts/build-worker.mjs'); process.exit(1); }
+ console.log('planWorkerBundle.generated.ts is current');
+} else {
+ writeFileSync(path, source);
+ console.log(`planWorkerBundle.generated.ts: ${bytes} bytes of worker`);
+}
diff --git a/sdk/scripts/worker-source.mjs b/sdk/scripts/worker-source.mjs
new file mode 100644
index 000000000..c195aca63
--- /dev/null
+++ b/sdk/scripts/worker-source.mjs
@@ -0,0 +1,24 @@
+// The planning worker (src/worldgen/planWorker.ts) bundled into one script, and the module that carries its text.
+import { rolldown } from 'rolldown';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const root = `${resolve(dirname(fileURLToPath(import.meta.url)), '..')}/`;
+
+/** The path of the generated module, and its source for the script the bundler makes now. */
+export async function workerModule() {
+ const bundle = await rolldown({ input: `${root}src/worldgen/planWorker.ts`, platform: 'browser', treeshake: { moduleSideEffects: () => true }, logLevel: 'silent' });
+ const { output } = await bundle.generate({ format: 'iife', minify: true, codeSplitting: false });
+ await bundle.close();
+ const text = output.find((c) => c.type === 'chunk').code;
+ return {
+ path: `${root}src/runtime/planWorkerBundle.generated.ts`,
+ bytes: text.length,
+ source: `// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+// Generated by sdk/scripts/build-worker.mjs from src/worldgen/planWorker.ts: do not edit.
+/** The planning worker's script: what a pool of planning workers is started from. */
+export const PLAN_WORKER_SOURCE = ${JSON.stringify(text)};
+`,
+ };
+}
diff --git a/sdk/src/residency/chunks.ts b/sdk/src/residency/chunks.ts
index 02058d639..273c5a626 100644
--- a/sdk/src/residency/chunks.ts
+++ b/sdk/src/residency/chunks.ts
@@ -94,7 +94,9 @@ interface Layer<T> {
}
/** At most this many chunks of a layer are answered later at once. */
-const MAX_IN_FLIGHT = 8;
+const MAX_IN_FLIGHT = 16;
+/** The most answers put in the world in one frame, however much time it has. */
+const MAX_COMMITS = 16;
const keyOf = (cx: number, cz: number): string => `${cx},${cz}`;
@@ -186,6 +188,7 @@ export class ProceduralChunks {
* stands in at once and the rest while `hasTime` says so.
*/
step(hasTime: () => boolean): void {
+ this.commit(hasTime);
const world = this.suspended ? [] : this.sources_();
const wanted: { layer: Layer<unknown>; cx: number; cz: number; dist: number }[] = [];
for (const layer of this.layers_.values()) {
@@ -238,6 +241,15 @@ export class ProceduralChunks {
}
/** Makes one chunk; true when it is now being answered later. */
+ /** The answers that came back and have not been put in the world yet. */
+ private readonly commits_: (() => void)[] = [];
+
+ /** Puts answers in the world: a couple a frame at least, and more while the frame has time. */
+ private commit(hasTime: () => boolean): void {
+ let n = 0;
+ while (this.commits_.length > 0 && (n < 2 || (n < MAX_COMMITS && hasTime()))) { this.commits_.shift()!(); n++; }
+ }
+
private make(layer: Layer<unknown>, cx: number, cz: number): boolean {
const key = keyOf(cx, cz);
let c = layer.chunks.get(key);
@@ -262,11 +274,14 @@ export class ProceduralChunks {
}
chunk.making = { generation, abort };
made.then((value) => {
- // Thrown away if the chunk was let go, made again, or the layer moved on while this was being made.
- if (chunk.making?.abort !== abort || abort.signal.aborted) return;
- chunk.making = null;
- if (layer.chunks.get(key) !== chunk || generation !== layer.def.generation) return;
- if (value !== null) this.publish(layer, chunk, value, generation);
+ // What was made off the main thread waits its turn to be put in the world: a burst of answers is not one frame's work.
+ this.commits_.push(() => {
+ // Thrown away if the chunk was let go, made again, or the layer moved on while this was being made.
+ if (chunk.making?.abort !== abort || abort.signal.aborted) return;
+ chunk.making = null;
+ if (layer.chunks.get(key) !== chunk || generation !== layer.def.generation) return;
+ if (value !== null) this.publish(layer, chunk, value, generation);
+ });
}, (e: unknown) => {
if (chunk.making?.abort !== abort || abort.signal.aborted) return;
chunk.making = null;
diff --git a/sdk/src/runtime/jobs.ts b/sdk/src/runtime/jobs.ts
new file mode 100644
index 000000000..5a991c74e
--- /dev/null
+++ b/sdk/src/runtime/jobs.ts
@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file jobs.ts
+ * @brief Work done off the main thread: a pool of workers that answer questions, and nothing else.
+ *
+ * @details Generating a world is computation, and computation on the main thread is a frame that is not drawn however it is sliced. A pool starts workers from
+ * the text of a script (so nothing depends on where a file is served from), sends each job to one of them and answers with a Promise. The main thread's
+ * part is only to take the answer and put it in the world.
+ *
+ * A job names the worker it wants by `affinity` (a number, taken modulo the pool's size), so the jobs that share what a worker keeps (a plan that has
+ * already worked out a layer) go to the same one. A host with no Worker has no pool: `createJobPool` answers null and the caller does its work in place.
+ */
+
+/** A pool of workers. */
+export interface JobPool {
+ /** How many workers there are. */
+ readonly size: number;
+ /** How many jobs are out, and how many have been answered. */
+ readonly inFlight: number;
+ readonly done: number;
+ /** Sends `message` to the worker `affinity` names and answers with what it sends back; rejects with its error. */
+ run<T>(affinity: number, message: Record<string, unknown>, transfer?: Transferable[]): Promise<T>;
+ /** Stops the workers; jobs still out are rejected. */
+ dispose(): void;
+}
+
+/** How many workers to start: the cores beside the main thread's, and the render's, at most four. */
+export function defaultWorkerCount(): number {
+ const cores = typeof navigator !== 'undefined' ? navigator.hardwareConcurrency ?? 2 : 2;
+ return Math.max(1, Math.min(4, cores - 2));
+}
+
+/** Starts a pool from the text of a worker script, or answers null where this realm has no Worker. */
+export function createJobPool(script: string, size = defaultWorkerCount()): JobPool | null {
+ if (typeof Worker === 'undefined' || typeof Blob === 'undefined' || typeof URL?.createObjectURL !== 'function') return null;
+ const url = URL.createObjectURL(new Blob([script], { type: 'text/javascript' }));
+ const workers: Worker[] = [];
+ const pending = new Map<number, { resolve(v: unknown): void; reject(e: Error): void }>();
+ let nextId = 1, inFlight = 0, done = 0, dead = false;
+ const fail = (e: Error): void => {
+ for (const p of pending.values()) p.reject(e);
+ pending.clear();
+ inFlight = 0;
+ };
+ try {
+ for (let i = 0; i < Math.max(1, size); i++) {
+ const w = new Worker(url);
+ w.onmessage = (e: MessageEvent<{ id: number; result?: unknown; error?: string }>) => {
+ const p = pending.get(e.data.id);
+ if (!p) return;
+ pending.delete(e.data.id);
+ inFlight--; done++;
+ if (e.data.error !== undefined) p.reject(new Error(e.data.error)); else p.resolve(e.data.result);
+ };
+ w.onerror = (e) => { dead = true; fail(new Error(`a job worker failed: ${e.message}`)); };
+ workers.push(w);
+ }
+ } finally {
+ URL.revokeObjectURL(url);
+ }
+ return {
+ size: workers.length,
+ get inFlight() { return inFlight; },
+ get done() { return done; },
+ run<T>(affinity: number, message: Record<string, unknown>, transfer: Transferable[] = []): Promise<T> {
+ if (dead) return Promise.reject(new Error('the job workers have stopped'));
+ const id = nextId++;
+ return new Promise<T>((resolve, reject) => {
+ pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+ inFlight++;
+ workers[((affinity % workers.length) + workers.length) % workers.length]!.postMessage({ ...message, id }, transfer);
+ });
+ },
+ dispose() {
+ for (const w of workers) w.terminate();
+ dead = true;
+ fail(new Error('the job pool was disposed'));
+ },
+ };
+}
diff --git a/sdk/src/runtime/planPool.ts b/sdk/src/runtime/planPool.ts
new file mode 100644
index 000000000..e1b54dc0a
--- /dev/null
+++ b/sdk/src/runtime/planPool.ts
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planPool.ts
+ * @brief The one pool of workers the engine's world planning runs on (placements, planet pages), started the first time something asks for it.
+ */
+import { createJobPool, type JobPool } from './jobs';
+import { PLAN_WORKER_SOURCE } from './planWorkerBundle.generated';
+
+let pool: JobPool | null | undefined;
+
+/** The planning pool, or null where this host has no workers (the caller then plans in place). */
+export function planPool(): JobPool | null {
+ if (pool === undefined) pool = createJobPool(PLAN_WORKER_SOURCE);
+ return pool;
+}
+
+/** The plans each worker has been sent, as `worker:key`: a plan is sent to a worker once, with the first question that needs it. */
+const sent = new Set<string>();
+
+/** True the first time `key` is asked of `worker` (and remembers it): that question carries the plan. */
+export function firstSend(worker: number, key: string): boolean {
+ const id = `${worker}:${key}`;
+ if (sent.has(id)) return false;
+ sent.add(id);
+ return true;
+}
+
+/** Forgets that a worker was sent `key`, so the next question sends it again. */
+export function forgetSent(worker: number, key: string): void {
+ sent.delete(`${worker}:${key}`);
+}
+
+/** Stops the pool (a test, an app's end); the next ask starts a new one. */
+export function disposePlanPool(): void {
+ pool?.dispose();
+ pool = undefined;
+ sent.clear();
+}
diff --git a/sdk/src/runtime/planWorkerBundle.generated.ts b/sdk/src/runtime/planWorkerBundle.generated.ts
new file mode 100644
index 000000000..ca5c1aefe
--- /dev/null
+++ b/sdk/src/runtime/planWorkerBundle.generated.ts
@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+// Generated by sdk/scripts/build-worker.mjs from src/worldgen/planWorker.ts: do not edit.
+/** The planning worker's script: what a pool of planning workers is started from. */
+export const PLAN_WORKER_SOURCE = "(function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`}),Math.sqrt(1.0036)-.06;function t(e,t,n){let r=Math.imul(e,374761393)+Math.imul(t,668265263)+Math.imul(n|0,2147483647)|0;return r=Math.imul(r^r>>>13,1274126177),r=(r^r>>>16)>>>0,r/4294967295}function n(e,n,r){let i=Math.floor(e),a=Math.floor(n),o=e-i,s=n-a,c=o*o*(3-2*o),l=s*s*(3-2*s),u=6*o*(1-o),d=6*s*(1-s),f=t(i,a,r),p=t(i+1,a,r),m=t(i,a+1,r),h=t(i+1,a+1,r),g=p-f,_=m-f,v=f-p-m+h;return[f+g*c+_*l+v*c*l,(g+v*l)*u,(_+v*c)*d]}let r={moisture:{scale:900,octaves:4},temperature:{scale:2400,octaves:3},rock:{scale:500,octaves:4}};function i(...e){let t=-1640531527;for(let n of e)t=Math.imul(t^(n|0),2246822507),t=t^t>>>13|0,t=Math.imul(t,3266489909),t=t^t>>>16|0;return(t>>>0)/4294967296}function a(e){let t=-2128831035;for(let n=0;n<e.length;n++)t=Math.imul(t^e.charCodeAt(n),16777619);return t|0}function o(e,t,n,r,i){let a=0,o=0,s=1,l=1;for(let u=0;u<i;u++)a+=c(e*l,t*l,n*l,r+u*131)*s,o+=s,s*=.5,l*=2;return a/o}function s(e,t,n,r){return i(e,t,n,r)}function c(e,t,n,r){let i=Math.floor(e),a=Math.floor(t),o=Math.floor(n),c=e-i,l=t-a,u=n-o,d=c*c*(3-2*c),f=l*l*(3-2*l),p=u*u*(3-2*u),m=(e,t,n)=>s(i+e,a+t,o+n,r),h=m(0,0,0)+(m(1,0,0)-m(0,0,0))*d,g=m(0,1,0)+(m(1,1,0)-m(0,1,0))*d,_=m(0,0,1)+(m(1,0,1)-m(0,0,1))*d,v=m(0,1,1)+(m(1,1,1)-m(0,1,1))*d,y=h+(g-h)*f;return y+(_+(v-_)*f-y)*p}function l(e,t,r,i){let a=0,o=0,s=1,c=1;for(let l=0;l<i;l++)a+=n(e*c,t*c,r+l*131)[0]*s,o+=s,s*=.5,c*=2;return a/o}var u=class{constructor(e){this.inputs=e,this.seeds_={},this.noise_={...r};for(let[t,n]of Object.entries(e.noise??{}))n&&(this.noise_[t]=n);for(let t of Object.keys(this.noise_))this.seeds_[t]=e.seed*7919^a(t)}sample(e,t){let n={},r=(e,t)=>{let r=!1,i=0;Object.defineProperty(n,e,{enumerable:!0,configurable:!0,get:()=>(r||=(i=t(),!0),i),set:e=>{i=e,r=!0}})},i,a=()=>i===void 0?i=this.inputs.ground(e,t):i;r(`height`,()=>a()?.y??NaN),r(`up`,()=>a()?.up??1),r(`slope`,()=>1-(a()?.up??1)),r(`waterDepth`,()=>{let n=a();return n&&this.inputs.waterDepth?this.inputs.waterDepth(e,t,n.y)??-1/0:-1/0}),r(`shoreDistance`,()=>this.inputs.shoreDistance?.(e,t)??1/0);for(let[n,i]of Object.entries(this.noise_)){let a=Math.max(i.scale,1e-6),s=Math.max(1,i.octaves??3);this.inputs.space?r(n,()=>{let r=this.inputs.space(e,t);return o(r[0]/a,r[1]/a,r[2]/a,this.seeds_[n],s)}):r(n,()=>l(e/a,t/a,this.seeds_[n],s))}for(let[i,a]of Object.entries(this.inputs.fields??{}))r(i,()=>a(e,t,n));for(let r of this.inputs.overrides?.(e,t)??[]){let e=n[r.field]??r.value;n[r.field]=e+(r.value-e)*Math.min(Math.max(r.weight,0),1)}return n}};function d(e,t,n){if(e.type===`circle`)return Math.hypot(t-e.x,n-e.z)-e.radius;let r=Math.cos(-(e.yaw??0)),i=Math.sin(-(e.yaw??0)),a=t-e.x,o=n-e.z,s=Math.abs(a*r-o*i)-e.halfX,c=Math.abs(a*i+o*r)-e.halfZ;return Math.hypot(Math.max(s,0),Math.max(c,0))+Math.min(Math.max(s,c),0)}function f(e,t){if(t<=0)return 1;if(e.falloff<=0||t>=e.falloff)return 0;let n=1-t/e.falloff;return n*n*(3-2*n)}function p(e){let t=e.shape,n=(t.type===`circle`?t.radius:Math.hypot(t.halfX,t.halfZ))+Math.max(e.falloff,0);return[t.x-n,t.z-n,t.x+n,t.z+n]}var m=class{constructor(){this.zones_=new Map,this.revision=0,this.onChange=null}set(e){let t=this.zones_.get(e.id);t&&JSON.stringify(t)===JSON.stringify(e)||(this.zones_.set(e.id,e),this.revision++,t&&this.onChange?.(p(t),t),this.onChange?.(p(e),e))}delete(e){let t=this.zones_.get(e);t&&(this.zones_.delete(e),this.revision++,this.onChange?.(p(t),t))}get(e){return this.zones_.get(e)}all(){return this.zones_.values()}at(e,t,n=0){let r=[];for(let i of this.zones_.values()){let a=f(i,d(i.shape,e,t)-n);a>0&&r.push({zone:i,weight:a})}return r.sort((e,t)=>t.zone.priority-e.zone.priority||(e.zone.id<t.zone.id?-1:1))}excluding(e,t,n,r,o){for(let{zone:s,weight:c}of this.at(e,t,n))if(s.excludes.some(e=>e===`*`||r.includes(e))&&(c>=1||i(o,a(s.id),Math.floor(e*16),Math.floor(t*16))<c))return s;return null}};let h=[{normal:[1,0,0],a:[0,0,-1],b:[0,1,0]},{normal:[-1,0,0],a:[0,0,1],b:[0,1,0]},{normal:[0,1,0],a:[1,0,0],b:[0,0,-1]},{normal:[0,-1,0],a:[1,0,0],b:[0,0,1]},{normal:[0,0,1],a:[1,0,0],b:[0,1,0]},{normal:[0,0,-1],a:[-1,0,0],b:[0,1,0]}],g=Math.PI/4;function _(e,t,n,r=[0,0,0]){let i=h[e],a=Math.tan(t*g),o=Math.tan(n*g),s=i.normal[0]+a*i.a[0]+o*i.b[0],c=i.normal[1]+a*i.a[1]+o*i.b[1],l=i.normal[2]+a*i.a[2]+o*i.b[2],u=Math.hypot(s,c,l);return r[0]=s/u,r[1]=c/u,r[2]=l/u,r}function v(e,t,n){let r=Math.abs(e),i=Math.abs(t),a=Math.abs(n),o;o=r>=i&&r>=a?e>=0?0:1:i>=a?t>=0?2:3:n>=0?4:5;let s=h[o],c=e*s.normal[0]+t*s.normal[1]+n*s.normal[2],l=e*s.a[0]+t*s.a[1]+n*s.a[2],u=e*s.b[0]+t*s.b[1]+n*s.b[2];return{face:o,u:Math.atan(l/c)/g,v:Math.atan(u/c)/g}}function y(e,t,n,r){let i=h[e],a=t*i.normal[0]+n*i.normal[1]+r*i.normal[2];if(a<=1e-6)return null;let o=t*i.a[0]+n*i.a[1]+r*i.a[2],s=t*i.b[0]+n*i.b[1]+r*i.b[2];return{u:Math.atan(o/a)/g,v:Math.atan(s/a)/g}}let b=(e,t)=>2/2**(e-1-t);function x(e,t){let n=b(e,t.level);return{u0:-1+t.ix*n,v0:-1+t.iz*n,span:n}}function S(e,t,n,r){let i=h[e];for(let[e,a]of[[i.a,n],[i.b,r]]){let n=e[0]*t[0]+e[1]*t[1]+e[2]*t[2],r=e[0]-t[0]*n,i=e[1]-t[1]*n,o=e[2]-t[2]*n,s=Math.hypot(r,i,o)||1;a[0]=r/s,a[1]=i/s,a[2]=o/s}}function C(e,t){let{u0:n,v0:r,span:i}=x(e.levels,t),a=i/64,o=new Float32Array(13467),s=[0,0,0];for(let e=0;e<67;e++)for(let i=0;i<67;i++){_(t.face,n+(i-1)*a,r+(e-1)*a,s);let c=(e*67+i)*3;o[c]=s[0],o[c+1]=s[1],o[c+2]=s[2]}let c=e.provider.sample({world:e.world,seed:e.seed,version:e.version,radius:e.radius,directions:o,count:4489});return c instanceof Promise?c.then(n=>w(e,t,o,n.heights,n.paint)):w(e,t,o,c.heights,c.paint)}function w(e,t,n,r,i){let a=1/0,o=-1/0;for(let e=1;e<=65;e++)for(let t=1;t<=65;t++){let n=r[e*67+t];a=Math.min(a,n),o=Math.max(o,n)}let s=Math.max(e.maxHeight-e.minHeight,1e-6),c=new Uint8Array(17956),l=new Uint8Array(17956),u=new Uint8Array(17956),d=(t,i,a)=>{let o=Math.min(Math.max(t,0),66),s=Math.min(Math.max(i,0),66)*67+o,c=e.radius+r[s];a[0]=n[s*3]*c,a[1]=n[s*3+1]*c,a[2]=n[s*3+2]*c},f=[0,0,0],p=[0,0,0],m=[0,0,0],h=[0,0,0],g=[0,0,0],_=[0,0,0],v=e.paint?.()??null,y=v?T(v,n,i):null;for(let a=0;a<67;a++)for(let o=0;o<67;o++){let u=a*67+o,v=Math.round(Math.min(Math.max((r[u]-e.minHeight)/s,0),1)*65535);d(o-1,a,f),d(o+1,a,p),d(o,a-1,m),d(o,a+1,h);let b=[p[0]-f[0],p[1]-f[1],p[2]-f[2]],x=[h[0]-m[0],h[1]-m[1],h[2]-m[2]],C=b[1]*x[2]-b[2]*x[1],w=b[2]*x[0]-b[0]*x[2],T=b[0]*x[1]-b[1]*x[0],E=[n[u*3],n[u*3+1],n[u*3+2]],D=Math.hypot(C,w,T)||1;C/=D,w/=D,T/=D,C*E[0]+w*E[1]+T*E[2]<0&&(C=-C,w=-w,T=-T),S(t.face,E,g,_);let O=C*g[0]+w*g[1]+T*g[2],k=C*_[0]+w*_[1]+T*_[2],A=C*E[0]+w*E[1]+T*E[2];D=Math.hypot(O,A,k)||1,c[u*4]=v>>8,c[u*4+1]=v&255,c[u*4+2]=Math.round((O/D*.5+.5)*255),c[u*4+3]=Math.round((k/D*.5+.5)*255);let j=0,M=0,N=0,P=0;if(y){let e=y(o,a);j=e[0],M=e[1],N=e[2],P=e[3]}else if(i)j=i[u*4],M=i[u*4+1],N=i[u*4+2],P=i[u*4+3];else{let e=Math.min(Math.max((.9-A/D)*6,0),1);j=1-e,P=e}l[u*4]=Math.round(Math.min(Math.max(j,0),1)*255),l[u*4+1]=Math.round(Math.min(Math.max(M,0),1)*255),l[u*4+2]=Math.round(Math.min(Math.max(N,0),1)*255),l[u*4+3]=Math.round(Math.min(Math.max(P,0),1)*255)}return{heights:c,paint:l,paint2:u,min:Number.isFinite(a)?a:e.minHeight,max:Number.isFinite(o)?o:e.maxHeight}}function T(e,t,n){let r=Array(81);for(let i=0;i<9;i++)for(let a=0;a<9;a++){let o=1+a*8,s=(1+i*8)*67+o,c=n?[n[s*4],n[s*4+1],n[s*4+2],n[s*4+3]]:[1,0,0,0],l=e(t[s*3],t[s*3+1],t[s*3+2],c);r[i*9+a]=[l[0]??0,l[1]??0,l[2]??0,l[3]??0]}return(e,t)=>{let n=Math.min(Math.max((e-1)/8,0),8),i=Math.min(Math.max((t-1)/8,0),8),a=Math.min(Math.floor(n),7),o=Math.min(Math.floor(i),7),s=n-a,c=i-o,l=r[o*9+a],u=r[o*9+a+1],d=r[(o+1)*9+a],f=r[(o+1)*9+a+1],p=[0,0,0,0];for(let e=0;e<4;e++)p[e]=(l[e]*(1-s)+u[e]*s)*(1-c)+(d[e]*(1-s)+f[e]*s)*c;return p}}let E=e=>e*Math.PI/4,D=e=>E(e),O=1.5;var k=class{constructor(e,t){this.face=e,this.planet=t,this.tiles_=new Map}facts(){return this.planet()}directionAt(e,t){let n=this.facts(),r=E(n?.radius??1);return _(this.face,e/r,t/r)}planeOf(e,t,n){let r=this.facts(),i=y(this.face,e,t,n);if(!r||!i)return null;let a=E(r.radius);return{x:i.u*a,z:i.v*a}}frameAt(e,t){let n=this.directionAt(e,t),r=[0,0,0],i=[0,0,0];return S(this.face,n,r,i),{dir:n,eu:r,ev:i}}world(e,t,n){let r=this.facts(),i=this.directionAt(e,n),a=r.radius+t;return[r.centre[0]+i[0]*a,r.centre[1]+i[1]*a,r.centre[2]+i[2]*a]}tile(e,t){let n=Math.floor(e/48),r=Math.floor(t/48),i=`${n},${r}`,a=this.tiles_.get(i);if(a)return this.tiles_.delete(i),this.tiles_.set(i,a),a;let o=this.facts();if(!o?.sampleMany)return null;let s=new Float32Array(3675);for(let e=0;e<35;e++)for(let t=0;t<35;t++){let i=this.directionAt(n*48+(t-1)*O,r*48+(e-1)*O);s[(e*35+t)*3]=i[0],s[(e*35+t)*3+1]=i[1],s[(e*35+t)*3+2]=i[2]}let c=o.sampleMany(s,1225);if(!c)return null;let l={x0:n*48-O,z0:r*48-O,n:35,heights:c.heights,paint:c.paint,fields:c.fields,fieldCount:o.fieldNames.length};return this.tiles_.set(i,l),this.tiles_.size>6e3&&this.tiles_.delete(this.tiles_.keys().next().value),l}cellOf(e,t,n){let r=(t-e.x0)/O,i=(n-e.z0)/O,a=Math.min(Math.max(Math.floor(r),0),e.n-2),o=Math.min(Math.max(Math.floor(i),0),e.n-2);return{i:a,j:o,fx:Math.min(Math.max(r-a,0),1),fz:Math.min(Math.max(i-o,0),1)}}heightAt(e,t){let n=this.tile(e,t);if(!n)return null;let{i:r,j:i,fx:a,fz:o}=this.cellOf(n,e,t),s=n.n,c=n.heights,l=c[i*s+r],u=c[i*s+r+1],d=c[(i+1)*s+r],f=c[(i+1)*s+r+1];return(l+(u-l)*a)*(1-o)+(d+(f-d)*a)*o}paintAt(e,t){let n=this.tile(e,t);if(!n?.paint)return null;let{i:r,j:i,fx:a,fz:o}=this.cellOf(n,e,t),s=(i+ +(o>.5))*n.n+r+ +(a>.5);return[n.paint[s*4],n.paint[s*4+1],n.paint[s*4+2],n.paint[s*4+3]]}fieldsAt(e,t){let n=this.tile(e,t);if(!n?.fields||n.fieldCount===0)return null;let{i:r,j:i,fx:a,fz:o}=this.cellOf(n,e,t),s=n.fieldCount,c=n.n,l=[];for(let e=0;e<s;e++){let t=n.fields[(i*c+r)*s+e],u=n.fields[(i*c+r+1)*s+e],d=n.fields[((i+1)*c+r)*s+e],f=n.fields[((i+1)*c+r+1)*s+e];l.push((t+(u-t)*a)*(1-o)+(d+(f-d)*a)*o)}return l}ground(e,t){let n=this.heightAt(e,t);if(n===null)return null;let r=O,i=this.heightAt(e-r,t),a=this.heightAt(e+r,t),o=this.heightAt(e,t-r),s=this.heightAt(e,t+r);if(i===null||a===null||o===null||s===null)return{y:n,up:1,normal:[0,1,0]};let c=-(a-i)/3,l=-(s-o)/3,u=Math.hypot(c,1,l);return{y:n,up:1/u,normal:[c/u,1/u,l/u]}}worldNormal(e,t,n){let r=this.frameAt(t,n);return[e[0]*r.eu[0]+e[1]*r.dir[0]+e[2]*r.ev[0],e[0]*r.eu[1]+e[1]*r.dir[1]+e[2]*r.ev[1],e[0]*r.eu[2]+e[1]*r.dir[2]+e[2]*r.ev[2]]}environment(){return{ground:(e,t)=>this.ground(e,t),space:(e,t)=>{let n=this.facts(),r=this.directionAt(e,t);return[r[0]*n.radius,r[1]*n.radius,r[2]*n.radius]}}}zoneOnFace(e){let t=this.facts(),n=e.shape;if(!t||n.y===void 0)return null;let r=n.x-t.centre[0],i=n.y-t.centre[1],a=n.z-t.centre[2],o=Math.hypot(r,i,a);if(o<1e-9)return null;let s=this.planeOf(r/o,i/o,a/o),c=D(t.radius),l=(n.type===`circle`?n.radius:Math.hypot(n.halfX,n.halfZ))+e.falloff;if(!s||Math.abs(s.x)>c+l||Math.abs(s.z)>c+l)return null;if(n.type===`circle`)return{...e,shape:{type:`circle`,x:s.x,z:s.z,radius:n.radius}};let u=this.frameAt(s.x,s.z),d=n.facing??[Math.cos(n.yaw??0),0,Math.sin(n.yaw??0)],f=Math.atan2(d[0]*u.ev[0]+d[1]*u.ev[1]+d[2]*u.ev[2],d[0]*u.eu[0]+d[1]*u.eu[1]+d[2]*u.eu[2]);return{...e,shape:{type:`rect`,x:s.x,z:s.z,halfX:n.halfX,halfZ:n.halfZ,yaw:f}}}sourcesOnFace(e,t){let n=this.facts(),r=[];if(!n)return r;let i=D(n.radius);for(let a of e){let e=a.x-n.centre[0],o=(a.y??0)-n.centre[1],s=a.z-n.centre[2],c=Math.hypot(e,o,s);if(c<1e-9)continue;let l=this.planeOf(e/c,o/c,s/c);l&&Math.abs(l.x)<=i+t&&Math.abs(l.z)<=i+t&&r.push(l)}return r}};function A(e,t){if(!Number.isFinite(t))return 0;let n=Math.max(e.blend??0,1e-9),r=e=>{if(e<=0)return 1;if(e>=n)return 0;let t=1-e/n;return t*t*(3-2*t)};return r(e.min===void 0?-1:e.min-t)*r(e.max===void 0?-1:t-e.max)}let j=4e4;function M(e){let t=e.anchor.footprint;for(let n of e.members??[])t=Math.max(t,(n.ring?.[1]??0)+n.footprint);return t}let N=(e,t,n)=>e?e[0]+(e[1]-e[0])*t:n;var P=class{constructor(e,t,n,r,i){this.rules=e,this.env=t,this.zones=n,this.seed=r,this.world=i,this.recipes_=new Map,this.layers_=[],this.viable_=new Map,this.groups_=new Map,this.worldHash_=a(i)^r;for(let t of e.recipes)this.recipes_.set(t.id,t);for(let t of e.layers){let n=new Set;for(let r of e.biomes)for(let e of r.recipes)e.layer===t.id&&n.add(e.recipe);let r=0;for(let e of n){let t=this.recipes_.get(e);t&&(r=Math.max(r,M(t)))}this.layers_.push({def:t,hash:a(t.id),maxRadius:r,recipes:n})}}invalidate(){this.viable_.clear(),this.groups_.clear()}layerIndex(e){return this.layers_.findIndex(t=>t.def.id===e)}biomeWeights(e,t){let n=[],r=0;for(let i of this.rules.biomes){let a=this.biomeWeight(i,e,t);a>0&&(n.push({biome:i.id,weight:a}),r+=a)}for(let{zone:i,weight:a}of this.zones.at(e,t)){if(!i.biome)continue;for(let e of n)e.weight*=1-a;r=r*(1-a)+a;let e=n.find(e=>e.biome===i.biome);e?e.weight+=a:n.push({biome:i.biome,weight:a});break}if(r<=0)return[];for(let e of n)e.weight/=r;return n.filter(e=>e.weight>0).sort((e,t)=>t.weight-e.weight||(e.biome<t.biome?-1:1))}biomeAt(e,t){return this.biomeWeights(e,t)[0]?.biome??null}paint(e,t,n){let r=n.length,i=this.biomeWeights(e,t);for(let{biome:e}of i)r=Math.max(r,this.rules.biomes.find(t=>t.id===e)?.paint?.length??0);let a=Array.from({length:r},(e,t)=>n[t]??0);for(let{biome:e,weight:t}of i){let i=this.rules.biomes.find(t=>t.id===e);if(!i?.paint)continue;let o=t*Math.min(Math.max(i.paintStrength??1,0),1);for(let e=0;e<r;e++)a[e]=a[e]+((i.paint[e]??0)-(n[e]??0))*o}let o=a.reduce((e,t)=>e+t,0)||1;return a.map(e=>e/o)}groupsIn(e,t,n,r,i){let a=this.layerIndex(e);if(a<0)return[];let o=this.layers_[a].def.spacing,s=[];for(let e=Math.floor(n/o);e<=Math.floor(i/o);e++)for(let c=Math.floor(t/o);c<=Math.floor(r/o);c++){let o=this.group(a,c,e);typeof o!=`string`&&o.x>=t&&o.x<r&&o.z>=n&&o.z<i&&s.push(o)}return s}placementsIn(e,t,n,r,i){let a=[];for(let o of this.layers_)if(!(i&&!i.includes(o.def.id)))for(let i of this.groupsIn(o.def.id,e,t,n,r))a.push(i.anchor,...i.members);return a}stats(e,t,n,r,i){let a={placed:0,noBiome:0,density:0,noGround:0,slope:0,water:0,zone:0,occupied:0,conflict:0},o=this.layerIndex(e);if(o<0)return a;let s=this.layers_[o].def.spacing;for(let e=Math.floor(n/s);e<Math.ceil(i/s);e++)for(let n=Math.floor(t/s);n<Math.ceil(r/s);n++){let t=this.group(o,n,e);typeof t==`string`?a[t]++:a.placed++}return a}explain(e,t){let n=this.layers_.map((n,r)=>{let i=Math.floor(e/n.def.spacing),a=Math.floor(t/n.def.spacing),o=this.group(r,i,a),s=this.viable(r,i,a);return{layer:n.def.id,cell:[i,a],group:typeof o==`string`?null:o.id,rejected:typeof o==`string`?o:null,detail:s.ok?void 0:s.detail}});return{fields:this.env.sample(e,t),biomes:this.biomeWeights(e,t),zones:this.zones.at(e,t).map(({zone:e,weight:t})=>({id:e.id,kind:e.kind,weight:t})),layers:n}}group(e,t,n){let r=`${e}:${t},${n}`,i=this.groups_.get(r);if(i!==void 0)return i;this.groups_.size>j&&this.groups_.clear();let a=this.makeGroup(e,t,n);return this.groups_.set(r,a),a}makeGroup(e,t,n){let r=this.viable(e,t,n);if(!r.ok)return r.reason;let a=r.candidate,o=this.layers_[e],s=o.def.spacing,c=Math.ceil((a.radius+o.maxRadius)/s);for(let r=-c;r<=c;r++)for(let i=-c;i<=c;i++){if(i===0&&r===0)continue;let o=this.viable(e,t+i,n+r);if(!o.ok)continue;let s=o.candidate;if((s.priority>a.priority||s.priority===a.priority&&(s.gz<n||s.gz===n&&s.gx<t))&&Math.hypot(s.x-a.x,s.z-a.z)<a.radius+s.radius)return`conflict`}let l=`${o.def.id}@${o.def.version??1}:${t},${n}`,u=a.recipe,d=this.place(l,o.def,u,u.anchor,0,a.x,a.z,a.biome,a.fields,0),f=[],p=[d];for(let[r,s]of(u.members??[]).entries()){let c=(e,a)=>i(this.worldHash_,o.hash,t,n,1e3+r*37+e,a),d=s.count?s.count[0]+Math.floor(c(0,0)*(s.count[1]-s.count[0]+1)):1;for(let t=0;t<d;t++){if(s.chance!==void 0&&c(1,t)>=s.chance)continue;let n=N(s.arc,c(2,t),c(2,t)*360)*Math.PI/180,r=N(s.ring,c(3,t),0),i=a.x+Math.cos(n)*r,d=a.z+Math.sin(n)*r,m=this.env.sample(i,d);if(this.standing(m,s)!==null||this.zones.excluding(i,d,s.footprint,this.tagsOf(o.def,u,s),this.seed)!==null||this.occupied(e,i,d,s.footprint)!==null||p.some(e=>Math.hypot(e.x-i,e.z-d)<e.footprint+s.footprint))continue;let h=this.place(l,o.def,u,s,t,i,d,a.biome,m,c(4,t));h&&(f.push(h),p.push(h))}}return{id:l,layer:o.def.id,x:a.x,z:a.z,radius:a.radius,priority:a.priority,anchor:d,members:f}}place(e,t,n,r,o,s,c,l,u,d){if(!Number.isFinite(u.height))return null;let f=i(this.worldHash_,a(e),a(r.id),o,7),p=this.env.inputs.ground(s,c),m=p?.up??1,h=p?.normal??[0,m,Math.sqrt(Math.max(0,1-m*m))];return{id:`${e}/${n.id}@${n.version}/${r.id}.${o}`,group:e,layer:t.id,recipe:n.id,recipeVersion:n.version,member:r.id,biome:l,zone:this.zones.at(s,c)[0]?.zone.id??null,x:s,y:u.height,z:c,yaw:(d||f)*Math.PI*2,scale:N(r.scale,i(this.worldHash_,a(e),o,11),1),normal:h,attach:r.attach??`upright`,mesh:typeof r.mesh==`number`?r.mesh:0,material:typeof r.material==`number`?r.material:0,plant:r.plant??null,interactive:r.interactive??null,footprint:r.footprint,canopy:r.canopy??r.footprint,far:r.far??null}}standing(e,t){return Number.isFinite(e.height)?e.up<(t.minUp??0)?`slope`:e.waterDepth>(t.waterDepth??0)?`water`:null:`noGround`}tagsOf(e,t,n){return[e.id,t.id,n.interactive?`interactive`:`decor`,...t.tags??[],...n.tags??[]]}viable(e,t,n){let r=`${e}:${t},${n}`,i=this.viable_.get(r);if(i)return i;this.viable_.size>j&&this.viable_.clear();let a=this.makeViable(e,t,n);return this.viable_.set(r,a),a}makeViable(e,t,n){let r=this.layers_[e],a=r.def.spacing,o=e=>i(this.worldHash_,r.hash,t,n,e),s=(t+o(1))*a,c=(n+o(2))*a,l=this.biomeWeights(s,c);if(l.length===0)return{ok:!1,reason:`noBiome`};let u=o(3),d=l[l.length-1].biome;for(let e of l){if(u<e.weight){d=e.biome;break}u-=e.weight}let f=(this.rules.biomes.find(e=>e.id===d)?.recipes??[]).filter(e=>e.layer===r.def.id&&this.recipes_.has(e.recipe)),p=o(4),m=null;for(let e of f){if(p<e.density){m=this.recipes_.get(e.recipe);break}p-=e.density}if(!m)return{ok:!1,reason:`density`};let h=this.env.sample(s,c),g=this.standing(h,m.anchor);if(g)return{ok:!1,reason:g};let _=this.zones.excluding(s,c,m.anchor.footprint,this.tagsOf(r.def,m,m.anchor),this.seed);if(_)return{ok:!1,reason:`zone`,detail:_.id};let v=this.occupied(e,s,c,m.anchor.footprint);return v?{ok:!1,reason:`occupied`,detail:v}:{ok:!0,candidate:{gx:t,gz:n,x:s,z:c,priority:o(5),biome:d,recipe:m,radius:M(m),fields:h}}}occupied(e,t,n,r){for(let i=0;i<e;i++){let e=this.layers_[i];if(e.def.occupies===!1)continue;let a=e.def.spacing,o=r+e.maxRadius;for(let e=Math.floor((n-o)/a);e<=Math.floor((n+o)/a);e++)for(let s=Math.floor((t-o)/a);s<=Math.floor((t+o)/a);s++){let a=this.group(i,s,e);if(typeof a!=`string`){for(let e of[a.anchor,...a.members])if(Math.hypot(e.x-t,e.z-n)<e.footprint+r)return e.id}}}return null}biomeWeight(e,t,n){let r=e.transition??0,i=t,o=n;if(r>0){let s=a(e.id)^this.worldHash_;i+=(l(t/r,n/r,s,2)-.5)*2*r,o+=(l(t/r,n/r,s+1,2)-.5)*2*r}let s=this.env.sample(i,o),c=e.weight??1;for(let t of e.conditions)if(c*=A(t,s[t.field]??NaN),c<=0)return 0;return c}};function F(e){return e.layers.some(e=>(e.farSpacing??1)>1)?{...e,layers:e.layers.map(e=>(e.farSpacing??1)>1?{...e,spacing:e.spacing*e.farSpacing}:e)}:null}function I(e,t){let n={};t.layers.forEach((t,r)=>{n[`paint.${t}`]=(t,n)=>e.paintAt(t,n)?.[r]??0}),t.fieldNames.forEach((t,r)=>{n[t]=(t,n)=>e.fieldsAt(t,n)?.[r]??0});let r=new u({seed:t.seed,noise:t.rules.noise,fields:{...n,...t.rules.fields},...e.environment(),waterDepth:(e,n,r)=>t.seaLevel-r,overrides:(e,n)=>{let r=[];for(let{zone:i,weight:a}of t.zones.at(e,n))for(let[e,t]of Object.entries(i.fields??{}))r.push({field:e,value:t,weight:a});return r}}),i=`${t.world}#${e.face}`;return{plan:new P(t.rules,r,t.zones,t.seed,i),farPlan:t.farRules?new P(t.farRules,r,t.zones,t.seed,i):null}}let L=new Map,R=new Map,z=e=>{let t=URL.createObjectURL(new Blob([e],{type:`text/javascript`}));return import(t).then(e=>e.default).finally(()=>URL.revokeObjectURL(t))};function B(e,t){let n=R.get(e);return n||(n=t(e),R.set(e,n)),n}async function V(e,t){let n=await B(e.provider.source,t),r={centre:e.centre,radius:e.radius,gravity:0,height:null,paint:null,layers:e.layers,fieldNames:e.fieldNames,fieldsAt:null,sampleMany:(t,r)=>{let i=n.sample({world:e.provider.world,seed:e.provider.seed,version:e.provider.version,radius:e.radius,directions:t,count:r});if(i instanceof Promise)throw Error(`a provider used in a worker must answer at once`);return i}},i=new k(e.face,()=>r),a=new m;for(let t of e.zones)a.set(t);return{face:i,...I(i,{rules:e.rules,farRules:F(e.rules),seed:e.seed,world:e.world,seaLevel:e.seaLevel,layers:e.layers,fieldNames:e.fieldNames,zones:a})}}async function H(e,t,n){let r=L.get(e);if(!r){if(!t)throw Error(`the plan ${e} is not known to this worker`);r=await V(t,n),L.set(e,r),L.size>24&&L.delete(L.keys().next().value)}return r}async function U(e,t=z){let n=await H(e.key,e.spec,t);return(e.far&&n.farPlan?n.farPlan:n.plan).placementsIn(e.x0,e.z0,e.x1,e.z1,[e.layer])}async function W(e,t=z){let n=await B(e.provider.source,t),r=null;if(e.paintKeys){let n=e.paintKeys,i=await Promise.all(n.map((n,r)=>H(n,e.specs[r],t)));r=(e,t,n,r)=>{let a=i[v(e,t,n).face],o=a.face.planeOf(e,t,n);return o?a.plan.paint(o.x,o.z,r):r}}let i=await C({provider:n,world:e.provider.world,seed:e.provider.seed,version:e.provider.version,radius:e.radius,levels:e.levels,minHeight:e.minHeight,maxHeight:e.maxHeight,...r?{paint:()=>r}:{}},e.node);return{result:i,transfer:[i.heights.buffer,i.paint.buffer,i.paint2.buffer]}}return typeof self<`u`&&typeof self.importScripts==`function`&&(self.onmessage=e=>{let t=e.data,n=e=>self.postMessage({id:t.id,error:e instanceof Error?e.message:String(e)});t.type===`page`?W(t).then(e=>self.postMessage({id:t.id,result:e.result},e.transfer),n):U(t).then(e=>self.postMessage({id:t.id,result:e}),n)}),e.page=W,e.placements=U,e})({});";
diff --git a/sdk/src/terrain/planetPlugin.ts b/sdk/src/terrain/planetPlugin.ts
index b2262880e..b6a5912ca 100644
--- a/sdk/src/terrain/planetPlugin.ts
+++ b/sdk/src/terrain/planetPlugin.ts
@@ -38,6 +38,8 @@ import { buildSphereMesh } from './planetSea';
import { removePlanetCollision, updatePlanetCollision } from './planetCollision';
import { planetProvider, planetProvidersRevision, type PlanetProvider } from './planetProvider';
import { makePlanetPage, type PlanetPageSource } from './planetPages';
+import { firstSend, forgetSent, planPool } from '../runtime/planPool';
+import type { PageRequest } from '../worldgen/planWorker';
import type { PlanetSamples } from './planetProvider';
import { levelsFor, nodePoint, selectSphereNodes, sphereNodeKey, type SphereNode, type SphereTreeParams } from './sphere';
@@ -153,6 +155,8 @@ interface Built {
providers: number;
/** The painters' revision the pages were last painted at. */
painted: number;
+ /** Pages that came back from a worker and are not in the atlas yet. */
+ ready: { key: string; image: PageImage }[];
/** The sea's entity, mesh and material instance, when the planet has one. */
sea: { entity: Entity; mesh: number; material: number; base: number } | null;
}
@@ -217,6 +221,7 @@ export class PlanetPlugin implements Plugin {
const got = source.provider.sample({ world: source.world, seed: source.seed, version: source.version, radius: source.radius, directions, count });
return got instanceof Promise ? null : got;
},
+ worker: source.provider.workerSource ? { source: source.provider.workerSource, seed: source.seed, version: source.version, world: source.world } : null,
fieldNames: source.provider.fields ?? [],
fieldsAt: source.provider.fields ? (dx, dy, dz) => { const got = sampleAt(source, dx, dy, dz); return got?.fields ? Array.from(got.fields) : null; } : null,
layers: built.data.layers.map((ref, i) => (ref.split('/').pop() ?? '').replace(/\.[^.]*$/, '') || `layer${i}`),
@@ -245,7 +250,7 @@ export class PlanetPlugin implements Plugin {
const built: Built = {
signature, data: { ...data }, provider: null, source: null, tree: null, epoch, table: new PageTable(ATLAS_SIZE),
heights: 0, paint: 0, mesh: 0, instance: 0, nodes: new Map(), spare: [], wanted: new Map(), asked: new Set(), pending: false, failure: null, arrays: [], packed: '', packing: false,
- providers: planetProvidersRevision(), painted: 0, sea: null,
+ providers: planetProvidersRevision(), painted: 0, sea: null, ready: [],
};
const provider = planetProvider(data.provider);
if (!provider) {
@@ -371,7 +376,7 @@ export class PlanetPlugin implements Plugin {
if (covered.has(sphereNodeKey(up))) { drawn.delete(key); break; }
}
}
- this.makePages(app, built, eye);
+ this.makePages(app, entity, built, eye);
this.pack(app, built);
const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
@@ -481,7 +486,29 @@ export class PlanetPlugin implements Plugin {
}
/** Makes the wanted pages, coarse and near first, for as long as the frame can spare. */
- private makePages(app: App, built: Built, eye: [number, number, number]): void {
+ /** One node's page: made by a worker when the planet's provider can be loaded in one, here when it cannot. */
+ private pageOf(app: App, entity: Entity, src: PlanetPageSource, node: SphereNode): PageImage | Promise<PageImage> {
+ const pool = planPool();
+ const provider = src.provider;
+ if (!pool || !provider.workerSource) return makePlanetPage(src, node);
+ const registry = app.hasResource(PlanetRegistryRes) ? app.getResource(PlanetRegistryRes) : null;
+ const remote = registry?.remotePaintOf(entity) ?? null;
+ // A painter that only the main thread can run (a world with no plan a worker could make) keeps its pages here.
+ if (registry?.paintOf(entity) && !remote) return makePlanetPage(src, node);
+ const worker = node.face % pool.size;
+ const keys = remote ? [...remote.keys] : null;
+ const request: PageRequest = {
+ id: 0, type: 'page', node, levels: src.levels, radius: src.radius, minHeight: src.minHeight, maxHeight: src.maxHeight,
+ provider: { source: provider.workerSource, seed: src.seed, version: src.version, world: src.world },
+ paintKeys: keys, specs: keys ? keys.map((k, f) => (firstSend(worker, k) ? remote!.spec(f) as PageRequest['specs'][number] : null)) : [],
+ };
+ return pool.run<PageImage>(node.face, request as unknown as Record<string, unknown>).catch((e: unknown) => {
+ if (keys) for (const k of keys) forgetSent(worker, k);
+ throw e;
+ });
+ }
+
+ private makePages(app: App, entity: Entity, built: Built, eye: [number, number, number]): void {
const bakes = bakesOf(app);
if (built.wanted.size === 0) { bakes.mark(built, 'Building the planet', 1); return; }
const src = built.source!;
@@ -500,16 +527,24 @@ export class PlanetPlugin implements Plugin {
return true;
};
const epoch = built.epoch;
+ // The pages a worker made, in the atlas: two a frame at least, and more while the frame has time.
+ let stored = 0;
+ while (built.ready.length > 0 && (stored < 2 || (stored < 12 && bakes.hasTime()))) {
+ const r = built.ready.shift()!;
+ if (built.epoch === epoch && built.heights) store(r.key, r.image);
+ stored++;
+ }
for (const node of order) {
const key = sphereNodeKey(node);
if (built.asked.has(key)) continue;
- const image = makePlanetPage(src, node);
+ const image = this.pageOf(app, entity, src, node);
if (image instanceof Promise) {
if (built.asked.size >= PAGES_IN_FLIGHT) break;
built.asked.add(key);
void image.then((img) => {
built.asked.delete(key);
- if (built.epoch === epoch && built.heights) store(key, img);
+ // Put in the atlas in a later frame's turn, a few at a time: a burst of answers is not one frame's work.
+ if (built.epoch === epoch && built.heights) built.ready.push({ key, image: img });
}, (e) => {
built.asked.delete(key);
log.warn('planet', `the provider failed a page (${key})`, e);
diff --git a/sdk/src/terrain/planetProvider.ts b/sdk/src/terrain/planetProvider.ts
index 4b5184319..bce2c77b3 100644
--- a/sdk/src/terrain/planetProvider.ts
+++ b/sdk/src/terrain/planetProvider.ts
@@ -44,6 +44,11 @@ export interface PlanetProvider {
* a place is a wetland). A game's own generator decides them, so the ground that is drawn and what grows on it come from one function.
*/
readonly fields?: readonly string[];
+ /**
+ * The text of a self-contained module (plain JavaScript, no imports) whose default export is this provider's `id`, `versions`, `fields` and `sample`, so that
+ * a worker can load the generator and a generated world can be laid out off the main thread. Absent, the world is laid out on the main thread.
+ */
+ readonly workerSource?: string;
/** The ground in the directions asked: heights in metres above the radius, the layer weights if it paints, and its fields if it has any. May answer later. */
sample(region: PlanetRegion): PlanetSamples | Promise<PlanetSamples>;
}
diff --git a/sdk/src/terrain/planetQuery.ts b/sdk/src/terrain/planetQuery.ts
index 6f890e8c4..fd2dfc9ea 100644
--- a/sdk/src/terrain/planetQuery.ts
+++ b/sdk/src/terrain/planetQuery.ts
@@ -31,6 +31,8 @@ export interface PlanetFacts {
fieldsAt: ((dx: number, dy: number, dz: number) => readonly number[] | null) | null;
/** The provider's answer for many directions at once (heights, paint, fields), or null while it answers later: a world is laid out from tiles of it, not a call a point. */
sampleMany: ((directions: Float32Array, count: number) => PlanetSamples | null) | null;
+ /** What a worker needs to read this planet's ground itself: its provider's module text, and what it is asked with. Null where the provider has none. */
+ worker?: { source: string; seed: number; version: number; world: string } | null;
}
/**
@@ -39,19 +41,34 @@ export interface PlanetFacts {
*/
export type PlanetPainter = (dx: number, dy: number, dz: number, base: readonly number[]) => readonly number[];
+/** How a worker is made to paint a planet as the main thread's painter does: the plan of each face by a key, and what a worker makes it from. */
+export interface RemotePaint {
+ /** The six faces' plans' keys. */
+ readonly keys: readonly string[];
+ /** What a worker makes face `face`'s plan from (plain data). */
+ spec(face: number): unknown;
+}
+
/** The planets of the app. @experimental */
export class PlanetRegistry {
readonly planets = new Map<Entity, PlanetFacts>();
private readonly painters_ = new Map<Entity, PlanetPainter>();
+ private readonly remote_ = new Map<Entity, RemotePaint>();
/** Bumped when a painter is set, changed or taken away, so the planet's pages are painted again. */
paintRevision = 0;
/** Sets what paints the planet `entity`'s ground (null takes it away); a planet paints with its provider's paint until then. */
- setPaint(entity: Entity, painter: PlanetPainter | null): void {
+ setPaint(entity: Entity, painter: PlanetPainter | null, remote: RemotePaint | null = null): void {
if (painter) this.painters_.set(entity, painter); else this.painters_.delete(entity);
+ if (remote) this.remote_.set(entity, remote); else this.remote_.delete(entity);
this.paintRevision++;
}
+ /** How a worker paints the planet `entity`'s ground as its painter does, when it can. */
+ remotePaintOf(entity: Entity): RemotePaint | null {
+ return this.remote_.get(entity) ?? null;
+ }
+
/** What paints the planet `entity`'s ground, if anything does. */
paintOf(entity: Entity): PlanetPainter | null {
return this.painters_.get(entity) ?? null;
diff --git a/sdk/src/worldgen/facePlan.ts b/sdk/src/worldgen/facePlan.ts
new file mode 100644
index 000000000..6c1c64d13
--- /dev/null
+++ b/sdk/src/worldgen/facePlan.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file facePlan.ts
+ * @brief The plan of one face of a planet's world, made the same way on the main thread and on a worker.
+ *
+ * @details A face's plan is a function of the rules, the seed, the world's name, the sea, the face's zones and what the planet's provider says. Where it is made
+ * is not part of that: the main thread makes it for painting the ground, a worker makes it to place what grows, and the two must agree, so there is
+ * one place that makes it.
+ */
+import { Environment } from './fields';
+import { WorldPlan } from './plan';
+import type { WorldRules } from './rules';
+import type { Zones } from './zones';
+import type { PlanetFace } from './planetSurface';
+
+/** What a face's plan is made from, besides the face itself. */
+export interface FacePlanInputs {
+ rules: WorldRules;
+ /** The rules with the layers that have a `farSpacing` planned sparser, for the far versions of their plants; null when none has one. */
+ farRules: WorldRules | null;
+ seed: number;
+ world: string;
+ /** The height of the sea above the planet's radius. */
+ seaLevel: number;
+ /** The names of the planet's layers, whose paint is a field each (`paint.<name>`), and of the provider's own fields. */
+ layers: readonly string[];
+ fieldNames: readonly string[];
+ /** The zones over this face, in its plane. */
+ zones: Zones;
+}
+
+/** The far rules for `rules`: each layer with a `farSpacing` spaced that many times further; null when none has one. */
+export function farRulesOf(rules: WorldRules): WorldRules | null {
+ if (!rules.layers.some((l) => (l.farSpacing ?? 1) > 1)) return null;
+ return { ...rules, layers: rules.layers.map((l) => ((l.farSpacing ?? 1) > 1 ? { ...l, spacing: l.spacing * l.farSpacing! } : l)) };
+}
+
+/** A face's plan, and the far one. */
+export function makeFacePlan(face: PlanetFace, i: FacePlanInputs): { plan: WorldPlan; farPlan: WorldPlan | null } {
+ // The planet's layers, as the provider paints them, are fields (`paint.grass` for a layer file grass.esterrainlayer), as a terrain's are, and the
+ // provider's own fields (an ecology) are fields by the names it gives them.
+ const fields: Record<string, (x: number, z: number) => number> = {};
+ i.layers.forEach((name, k) => { fields[`paint.${name}`] = (x, z) => face.paintAt(x, z)?.[k] ?? 0; });
+ i.fieldNames.forEach((name, k) => { fields[name] = (x, z) => face.fieldsAt(x, z)?.[k] ?? 0; });
+ const env = new Environment({
+ seed: i.seed, noise: i.rules.noise, fields: { ...fields, ...i.rules.fields },
+ ...face.environment(),
+ // The sea stands at a height, so the water over a point is how far it is below it (negative on land, by how far above).
+ waterDepth: (_x, _z, y) => i.seaLevel - y,
+ overrides: (x, z) => {
+ const out: { field: string; value: number; weight: number }[] = [];
+ for (const { zone, weight } of i.zones.at(x, z)) for (const [field, value] of Object.entries(zone.fields ?? {})) out.push({ field, value, weight });
+ return out;
+ },
+ });
+ const name = `${i.world}#${face.face}`;
+ return {
+ plan: new WorldPlan(i.rules, env, i.zones, i.seed, name),
+ farPlan: i.farRules ? new WorldPlan(i.farRules, env, i.zones, i.seed, name) : null,
+ };
+}
diff --git a/sdk/src/worldgen/planWorker.ts b/sdk/src/worldgen/planWorker.ts
new file mode 100644
index 000000000..6d73cb741
--- /dev/null
+++ b/sdk/src/worldgen/planWorker.ts
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planWorker.ts
+ * @brief The script a planning worker runs: what a planet's world places in a square of one of its faces, worked out off the main thread.
+ *
+ * @details This file is bundled on its own (sdk/scripts/build-worker.mjs) into text the engine starts workers from, so it imports only what planning
+ * needs, none of the engine's runtime. It speaks the pool's protocol (runtime/jobs.ts): a message `{ id, spec?, key, ... }` is answered with
+ * `{ id, result }` or `{ id, error }`.
+ *
+ * A plan is made once for a key and kept, so what it works out (the groups of a layer, the viability of a candidate) is shared by every square asked
+ * of it. The planet's provider is the game's own generator, handed over as the text of a self-contained module and loaded here, which is what lets
+ * the ground be read in the worker with no help from the main thread.
+ */
+import type { Placement } from './plan';
+import type { WorldPlan } from './plan';
+import type { WorldRules } from './rules';
+import type { ZoneDef } from './zones';
+import { Zones } from './zones';
+import { PlanetFace } from './planetSurface';
+import { farRulesOf, makeFacePlan } from './facePlan';
+import type { PlanetFacts } from '../terrain/planetQuery';
+import type { PlanetProvider } from '../terrain/planetProvider';
+import type { PlanetPainter } from '../terrain/planetQuery';
+import { faceOf, type SphereNode } from '../terrain/sphere';
+import { makePlanetPage, type PlanetPageSource } from '../terrain/planetPages';
+import type { PageImage } from '../terrain/pages';
+
+/** What a plan is made from: everything the main thread knew when it made its own. */
+export interface PlanSpec {
+ rules: WorldRules;
+ seed: number;
+ world: string;
+ seaLevel: number;
+ face: number;
+ radius: number;
+ centre: [number, number, number];
+ layers: string[];
+ fieldNames: string[];
+ /** The zones over the face, in its plane. */
+ zones: ZoneDef[];
+ /** The planet's provider: the text of a module whose default export is it, and what it is asked with. */
+ provider: { source: string; seed: number; version: number; world: string };
+}
+
+/** A question: the square of the face's plane, and whether it is the far plan's. */
+export interface PlacementsRequest {
+ id: number;
+ /** Names the plan; a worker that has not seen it is sent `spec` with it. */
+ key: string;
+ spec?: PlanSpec;
+ layer: string;
+ far: boolean;
+ x0: number;
+ z0: number;
+ x1: number;
+ z1: number;
+}
+
+interface Made { plan: WorldPlan; farPlan: WorldPlan | null; face: PlanetFace }
+
+/** The plans kept, newest last, and the providers loaded (by the text of their source). */
+const plans = new Map<string, Made>();
+const providers = new Map<string, Promise<PlanetProvider>>();
+const PLANS_KEPT = 24;
+
+/** How the text of a provider's module becomes the provider: a blob the worker imports. A test, which has no blob to import, gives its own. */
+export type ProviderLoader = (source: string) => Promise<PlanetProvider>;
+
+const blobLoader: ProviderLoader = (source) => {
+ const url = URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
+ return import(/* @vite-ignore */ url).then((m: { default: PlanetProvider }) => m.default).finally(() => URL.revokeObjectURL(url));
+};
+
+function providerOf(source: string, load: ProviderLoader): Promise<PlanetProvider> {
+ let p = providers.get(source);
+ if (!p) { p = load(source); providers.set(source, p); }
+ return p;
+}
+
+async function makeFor(spec: PlanSpec, load: ProviderLoader): Promise<Made> {
+ const provider = await providerOf(spec.provider.source, load);
+ const facts: PlanetFacts = {
+ centre: spec.centre, radius: spec.radius, gravity: 0, height: null, paint: null, layers: spec.layers, fieldNames: spec.fieldNames, fieldsAt: null,
+ sampleMany: (directions, count) => {
+ const got = provider.sample({ world: spec.provider.world, seed: spec.provider.seed, version: spec.provider.version, radius: spec.radius, directions, count });
+ if (got instanceof Promise) throw new Error('a provider used in a worker must answer at once');
+ return got;
+ },
+ };
+ const face = new PlanetFace(spec.face, () => facts);
+ const zones = new Zones();
+ for (const z of spec.zones) zones.set(z);
+ return { face, ...makeFacePlan(face, {
+ rules: spec.rules, farRules: farRulesOf(spec.rules), seed: spec.seed, world: spec.world, seaLevel: spec.seaLevel,
+ layers: spec.layers, fieldNames: spec.fieldNames, zones,
+ }) };
+}
+
+/** The plan for `key`: the one this worker kept, or one made from `spec`. */
+async function planFor(key: string, spec: PlanSpec | null | undefined, load: ProviderLoader): Promise<Made> {
+ let made = plans.get(key);
+ if (!made) {
+ if (!spec) throw new Error(`the plan ${key} is not known to this worker`);
+ made = await makeFor(spec, load);
+ plans.set(key, made);
+ if (plans.size > PLANS_KEPT) plans.delete(plans.keys().next().value!);
+ }
+ return made;
+}
+
+/** The placements of a layer in a square, as the plan for `key` has them. @internal */
+export async function placements(r: PlacementsRequest, load: ProviderLoader = blobLoader): Promise<Placement[]> {
+ const made = await planFor(r.key, r.spec, load);
+ const plan = r.far && made.farPlan ? made.farPlan : made.plan;
+ return plan.placementsIn(r.x0, r.z0, r.x1, r.z1, [r.layer]);
+}
+
+
+/** A planet's page to make: its node, the planet's numbers, and (when a world paints the ground) the six faces' plans by key, each with its spec when this worker has none. */
+export interface PageRequest {
+ id: number;
+ type: 'page';
+ node: SphereNode;
+ levels: number;
+ radius: number;
+ minHeight: number;
+ maxHeight: number;
+ provider: { source: string; seed: number; version: number; world: string };
+ paintKeys: string[] | null;
+ specs: (PlanSpec | null)[];
+}
+
+/** The page of a planet's node: heights, normals and paint, the paint by the biomes of the world when it is painted by one. @internal */
+export async function page(r: PageRequest, load: ProviderLoader = blobLoader): Promise<{ result: PageImage; transfer: ArrayBuffer[] }> {
+ const provider = await providerOf(r.provider.source, load);
+ let painter: PlanetPainter | null = null;
+ if (r.paintKeys) {
+ const keys = r.paintKeys;
+ const made = await Promise.all(keys.map((k, f) => planFor(k, r.specs[f], load)));
+ painter = (dx, dy, dz, base) => {
+ const m = made[faceOf(dx, dy, dz).face]!;
+ const at = m.face.planeOf(dx, dy, dz);
+ return at ? m.plan.paint(at.x, at.z, base) : base;
+ };
+ }
+ const src: PlanetPageSource = { provider, world: r.provider.world, seed: r.provider.seed, version: r.provider.version, radius: r.radius, levels: r.levels, minHeight: r.minHeight, maxHeight: r.maxHeight, ...(painter ? { paint: () => painter } : {}) };
+ const image = await makePlanetPage(src, r.node);
+ return { result: image, transfer: [image.heights.buffer as ArrayBuffer, image.paint.buffer as ArrayBuffer, image.paint2.buffer as ArrayBuffer] };
+}
+
+// The worker's loop. Absent where this file is imported as a module (a test), where `self` is not a worker's scope.
+declare const self: { onmessage: ((e: { data: PlacementsRequest | PageRequest }) => void) | null; postMessage(m: unknown, transfer?: ArrayBuffer[]): void } | undefined;
+if (typeof self !== 'undefined' && typeof (self as { importScripts?: unknown }).importScripts === 'function') {
+ self.onmessage = (e) => {
+ const m = e.data;
+ const fail = (err: unknown): void => self!.postMessage({ id: m.id, error: err instanceof Error ? err.message : String(err) });
+ if ((m as { type?: string }).type === 'page') page(m as PageRequest).then((r) => self!.postMessage({ id: m.id, result: r.result }, r.transfer), fail);
+ else placements(m as PlacementsRequest).then((result) => self!.postMessage({ id: m.id, result }), fail);
+ };
+}
diff --git a/sdk/src/worldgen/worldgenPlugin.ts b/sdk/src/worldgen/worldgenPlugin.ts
index d94269247..9289c0615 100644
--- a/sdk/src/worldgen/worldgenPlugin.ts
+++ b/sdk/src/worldgen/worldgenPlugin.ts
@@ -36,6 +36,10 @@ import { plantGrowthOf, prepareKinds, type GrownCell, type ReadyKinds } from '..
import { PlanetRegistryRes, type PlanetFacts } from '../terrain/planetQuery';
import { faceOf } from '../terrain/sphere';
import { Environment } from './fields';
+import { farRulesOf, makeFacePlan } from './facePlan';
+import type { JobPool } from '../runtime/jobs';
+import { firstSend, forgetSent, planPool } from '../runtime/planPool';
+import type { PlacementsRequest, PlanSpec } from './planWorker';
import { FaceZones, faceHalf, planetFaces, type PlanetFace } from './planetSurface';
import { expandPlants, type PlantSet } from './plants';
import { WorldPlan, type Placement } from './plan';
@@ -179,6 +183,8 @@ interface FaceUnit { face: PlanetFace; plan: WorldPlan; farPlan: WorldPlan | nul
interface Unit {
/** Names its layers' chunks: empty for a plane, `f0` to `f5` for a face. */
key: string;
+ /** What lays this unit out off the main thread, when something can: asked for the square of a layer, it answers with what is placed there. */
+ away?: (layer: string, far: boolean, x0: number, z0: number, x1: number, z1: number) => Promise<Placement[]> | null;
plan: WorldPlan;
farPlan: WorldPlan | null;
face: PlanetFace | null;
@@ -514,33 +520,13 @@ export class WorldGenPlugin implements Plugin {
const registry = app.getResource(PlanetRegistryRes);
const facts = (): PlanetFacts | null => registry.planets.get(entity) ?? null;
if (!facts()) { built.waitingForPlanet = true; return; }
- const sparse = rules.layers.some((l) => (l.farSpacing ?? 1) > 1);
- const farRules: WorldRules | null = sparse
- ? { ...rules, layers: rules.layers.map((l) => (l.farSpacing ?? 1) > 1 ? { ...l, spacing: l.spacing * l.farSpacing! } : l) } : null;
+ const farRules = farRulesOf(rules);
built.faces = planetFaces(facts).map((face) => {
const zones = new FaceZones(face);
- // The planet's layers, as the provider paints them, are fields (`paint.grass` for a layer file grass.esterrainlayer), as a terrain's are.
- const paintFields: Record<string, (x: number, z: number) => number> = {};
- (facts()?.layers ?? []).forEach((name, i) => {
- paintFields[`paint.${name}`] = (x, z) => face.paintAt(x, z)?.[i] ?? 0;
- });
- // And the provider's own fields (an ecology) by the names it gives them.
- (facts()?.fieldNames ?? []).forEach((name, i) => {
- paintFields[name] = (x, z) => face.fieldsAt(x, z)?.[i] ?? 0;
+ const { plan, farPlan } = makeFacePlan(face, {
+ rules, farRules, seed: data.seed, world: data.world, seaLevel: data.seaLevel,
+ layers: facts()?.layers ?? [], fieldNames: facts()?.fieldNames ?? [], zones: zones.zones,
});
- const env = new Environment({
- seed: data.seed, noise: rules.noise, fields: { ...paintFields, ...rules.fields },
- ...face.environment(),
- // The sea stands at a height, so the water over a point is how far it is below it (negative on land, by how far above).
- waterDepth: (_x, _z, y) => data.seaLevel - y,
- overrides: (x, z) => {
- const out: { field: string; value: number; weight: number }[] = [];
- for (const { zone, weight } of zones.zones.at(x, z)) for (const [field, value] of Object.entries(zone.fields ?? {})) out.push({ field, value, weight });
- return out;
- },
- });
- const plan = new WorldPlan(rules, env, zones.zones, data.seed, `${data.world}#${face.face}`);
- const farPlan = farRules ? new WorldPlan(farRules, env, zones.zones, data.seed, `${data.world}#${face.face}`) : null;
// A zone that changes makes again only the chunks of this face it reaches, and paints the ground under it again.
zones.zones.onChange = (bounds, zone) => {
plan.invalidate();
@@ -550,19 +536,21 @@ export class WorldGenPlugin implements Plugin {
const reach = l.spacing * 3;
chunks.invalidate(layerIdOf(entity, l.id, FACE_KEYS[face.face]), bounds[0] - reach, bounds[1] - reach, bounds[2] + reach, bounds[3] + reach);
}
- if (data.paintGround && (zone.biome || zone.fields)) registry.setPaint(entity, registry.paintOf(entity));
+ if (data.paintGround && (zone.biome || zone.fields)) registry.setPaint(entity, registry.paintOf(entity), registry.remotePaintOf(entity));
};
return { face, plan, farPlan, zones };
});
built.plan = built.faces[2]!.plan;
const faces = built.faces;
- // The ground is painted where the direction falls: by the plan of the face it is on.
+ const plugin = this;
+ // The ground is painted where the direction falls: by the plan of the face it is on. A worker paints it the same way from the same plans.
if (data.paintGround) {
+ const remote = facts()?.worker ? { get keys() { return faces.map((u) => plugin.planKey(built, u)); }, spec: (face: number) => plugin.planSpec(built, faces[face]!, facts()!) } : null;
registry.setPaint(entity, (dx, dy, dz, base) => {
const unit = faces[faceOf(dx, dy, dz).face]!;
const at = unit.face.planeOf(dx, dy, dz);
return at ? unit.plan.paint(at.x, at.z, base) : base;
- });
+ }, remote);
}
}
@@ -629,10 +617,12 @@ export class WorldGenPlugin implements Plugin {
const world = [...gens.zones(built.data.world).all()];
for (const unit of built.faces) unit.zones.sync(world);
const half = faceHalf(facts.radius);
+ const pool = planPool();
for (const unit of built.faces) {
this.publishUnit(app, gens, entity, built, {
key: FACE_KEYS[unit.face.face]!, plan: unit.plan, farPlan: unit.farPlan, face: unit.face,
bounds: [-half, -half, half, half], known: (x, z) => unit.face.ground(x, z) !== null,
+ away: pool && facts.worker ? this.awayOf(pool, built, unit, facts) : undefined,
}, `planet:${facts.radius}`, false);
}
return;
@@ -654,6 +644,36 @@ export class WorldGenPlugin implements Plugin {
}, ground, waiting);
}
+ /** The name of a face's plan for workers: what it was made from, so a plan made from other rules, zones or sea is a new one. */
+ private planKey(built: BuiltWorld, unit: FaceUnit): string {
+ return `${built.signature}:f${unit.face.face}:z${unit.zones.zones.revision}`;
+ }
+
+ /** What a worker makes a face's plan from: plain data, the rules without what is code (the fields a game registered) or what only the main thread reads (the plants' kinds). */
+ private planSpec(built: BuiltWorld, unit: FaceUnit, facts: PlanetFacts): PlanSpec {
+ const data = built.data;
+ return {
+ rules: { ...built.rules!, fields: undefined, plants: undefined } as WorldRules, seed: data.seed, world: data.world, seaLevel: data.seaLevel,
+ face: unit.face.face, radius: facts.radius, centre: facts.centre, layers: [...facts.layers], fieldNames: [...facts.fieldNames],
+ zones: [...unit.zones.zones.all()], provider: facts.worker!,
+ };
+ }
+
+ /** Asks the pool for a square of a face's plan: the plan is sent with the first question a worker is asked of it, and named after that. */
+ private awayOf(pool: JobPool, built: BuiltWorld, unit: FaceUnit, facts: PlanetFacts): NonNullable<Unit['away']> {
+ const worker = unit.face.face % pool.size;
+ return (layer, far, x0, z0, x1, z1) => {
+ const key = this.planKey(built, unit);
+ const first = firstSend(worker, key);
+ const request: PlacementsRequest = { id: 0, key, layer, far, x0, z0, x1, z1, ...(first ? { spec: this.planSpec(built, unit, facts) } : {}) };
+ return pool.run<Placement[]>(unit.face.face, request as unknown as Record<string, unknown>).catch((e: unknown) => {
+ // A worker that does not know the plan (it was restarted) is sent it again with the next question.
+ forgetSent(worker, key);
+ throw e;
+ });
+ };
+ }
+
/** One unit's layers as chunks: nearest first within the frame's budget, with the far versions of its plants a layer of their own. */
private publishUnit(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld, unit: Unit, ground: string, waiting: boolean): void {
const rules = built.rules!;
@@ -676,9 +696,11 @@ export class WorldGenPlugin implements Plugin {
...(sourcesFor ? { sources: sourcesFor(layer.drawDistance + size) } : {}),
make: (cx, cz) => {
const x0 = cx * size, z0 = cz * size;
- if (waiting || !known(x0, z0, size)) return null;
// The plants' parts are read before any chunk: a chunk made without them would leave the plants out until it is made again.
if (rendering && built.plants && !built.plantsReady) return null;
+ const away = unit.away?.(layer.id, false, x0, z0, x0 + size, z0 + size);
+ if (away) return away.then((placed) => this.chunk(app, null, diffs, layer, x0, z0, size, rendering, built.plants, face, false, 1, placed));
+ if (waiting || !known(x0, z0, size)) return null;
return this.chunk(app, plan, diffs, layer, x0, z0, size, rendering, built.plants, face);
},
publish: (_cx, _cz, value) => this.place(app, gens, entity, value),
@@ -702,9 +724,11 @@ export class WorldGenPlugin implements Plugin {
...(sourcesFor ? { sources: sourcesFor(built.plants.reach + fsize) } : {}),
make: (cx, cz) => {
const x0 = cx * fsize, z0 = cz * fsize;
- if (waiting || !known(x0, z0, fsize)) return null;
if (!built.plantsReady) return null;
const sparse = (layer.farSpacing ?? 1) > 1 && unit.farPlan;
+ const away = unit.away?.(layer.id, true, x0, z0, x0 + fsize, z0 + fsize);
+ if (away) return away.then((placed) => this.chunk(app, null, diffs, layer, x0, z0, fsize, rendering, built.plants, face, true, sparse ? layer.farSpacing! ** 2 : 1, placed));
+ if (waiting || !known(x0, z0, fsize)) return null;
return this.chunk(app, sparse ? unit.farPlan! : plan, diffs, layer, x0, z0, fsize, rendering, built.plants, face, true, sparse ? layer.farSpacing! ** 2 : 1);
},
publish: (_cx, _cz, value) => this.place(app, gens, entity, value),
@@ -714,10 +738,11 @@ export class WorldGenPlugin implements Plugin {
}
/** What one chunk of a layer places: its decoration merged by mesh, and its interactive placements, with the changes laid over. */
- private chunk(app: App, plan: WorldPlan, diffs: PlacementDiffs, layer: PlacementLayer, x0: number, z0: number, size: number,
- rendering: boolean, plants: PlantSet | null, face: PlanetFace | null, far = false, thinnedBy = 1): PlacedChunk | Promise<PlacedChunk> {
+ private chunk(app: App, plan: WorldPlan | null, diffs: PlacementDiffs, layer: PlacementLayer, x0: number, z0: number, size: number,
+ rendering: boolean, plants: PlantSet | null, face: PlanetFace | null, far = false, thinnedBy = 1, given?: readonly Placement[]): PlacedChunk | Promise<PlacedChunk> {
const placements: Placement[] = [];
- for (const planned of plan.placementsIn(x0, z0, x0 + size, z0 + size, [layer.id])) {
+ // What is placed in the square: asked of the plan here, or already worked out (by a worker).
+ for (const planned of given ?? plan!.placementsIn(x0, z0, x0 + size, z0 + size, [layer.id])) {
// On a planet a placement is taken from its face's plane to the planet, and named for its face: the same cell of two faces is two places.
const p = face ? onPlanet(planned, face) : planned;
if (diffs.isRemoved(p.id)) continue;
diff --git a/sdk/tests/procedural-chunks.test.ts b/sdk/tests/procedural-chunks.test.ts
index cc1885d96..43a0c552c 100644
--- a/sdk/tests/procedural-chunks.test.ts
+++ b/sdk/tests/procedural-chunks.test.ts
@@ -110,6 +110,9 @@ describe('procedural chunks', () => {
expect(answers).toHaveLength(2);
answers[1]!.resolve('new');
await Promise.resolve();
+ // An answer that came back waits for the next frame's turn to be put in the world.
+ expect(live.size).toBe(0);
+ chunks.step(always);
expect([...live.values()]).toEqual(['new']);
expect(chunks.stateAt('l', 1005, 5)).toBe('ready');
});
diff --git a/sdk/tests/worker-bundle-fresh.test.ts b/sdk/tests/worker-bundle-fresh.test.ts
new file mode 100644
index 000000000..62aaa4397
--- /dev/null
+++ b/sdk/tests/worker-bundle-fresh.test.ts
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+// @ts-expect-error a build script, plain JavaScript
+import { workerModule } from '../scripts/worker-source.mjs';
+
+describe('the planning worker\'s script', () => {
+ it('is what src/worldgen/planWorker.ts makes now (run node scripts/build-worker.mjs after changing it)', async () => {
+ const made = await workerModule() as { path: string; source: string };
+ expect(readFileSync(made.path, 'utf8')).toBe(made.source);
+ });
+});
diff --git a/sdk/tests/worldgen-worker.test.ts b/sdk/tests/worldgen-worker.test.ts
new file mode 100644
index 000000000..77f1bbafc
--- /dev/null
+++ b/sdk/tests/worldgen-worker.test.ts
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import type { PlanetFacts } from '../src/terrain/planetQuery';
+import { PlanetFace, FaceZones } from '../src/worldgen/planetSurface';
+import { farRulesOf, makeFacePlan } from '../src/worldgen/facePlan';
+import { page, placements, type PageRequest, type PlacementsRequest, type PlanSpec } from '../src/worldgen/planWorker';
+import { makePlanetPage } from '../src/terrain/planetPages';
+import { faceOf } from '../src/terrain/sphere';
+import { PLAN_WORKER_SOURCE } from '../src/runtime/planWorkerBundle.generated';
+import type { WorldRules } from '../src/worldgen/rules';
+import { createJobPool } from '../src/runtime/jobs';
+
+const radius = 4000;
+/** A provider as a game writes it for a worker: a module of plain JavaScript whose default export answers. */
+const providerSource = `
+const fields = ['ecology.island', 'ecology.wild'];
+export default {
+ id: 'test', versions: [1], range: () => [-10, 40], fields,
+ sample({ radius, directions, count }) {
+ const heights = new Float32Array(count), paint = new Float32Array(count * 4), f = new Float32Array(count * 2);
+ for (let i = 0; i < count; i++) {
+ const x = directions[i * 3], y = directions[i * 3 + 1], z = directions[i * 3 + 2];
+ heights[i] = 6 + 5 * Math.sin(x * 40) * Math.cos(z * 33) + 3 * y;
+ paint[i * 4] = 0.7; paint[i * 4 + 1] = 0.3;
+ f[i * 2] = 0.5 + 0.5 * Math.sin(x * 20); f[i * 2 + 1] = 1 - f[i * 2];
+ }
+ return { heights, paint, fields: f };
+ },
+};`;
+
+const loader = async (source: string) => (await import(/* @vite-ignore */ `data:text/javascript;base64,${Buffer.from(source).toString('base64')}`)).default;
+
+const rules: WorldRules = {
+ id: 't', versions: [1],
+ biomes: [{ id: 'meadow', transition: 3, conditions: [{ field: 'height', min: -100, max: 100 }, { field: 'ecology.island', min: 0.3, blend: 0.2 }, { field: 'paint.grass', min: 0.2, blend: 0.2 }], recipes: [{ recipe: 'tuft', layer: 'cover', density: 1 }] }],
+ recipes: [{ id: 'tuft', version: 1, anchor: { id: 'a', mesh: 1, material: 1, footprint: 0.4 }, members: [{ id: 'b', mesh: 1, material: 1, footprint: 0.2, ring: [0.5, 1.5], count: [1, 3] }] }],
+ layers: [{ id: 'cover', spacing: 6, drawDistance: 100, farSpacing: 2 }],
+ noise: { moisture: { scale: 40, octaves: 2 } },
+};
+
+const spec = (face: number): PlanSpec => ({
+ rules, seed: 9, world: 'w', seaLevel: 0, face, radius, centre: [0, -radius, 0], layers: ['grass', 'dirt', 'snow', 'rock'], fieldNames: ['ecology.island', 'ecology.wild'],
+ zones: [], provider: { source: providerSource, seed: 9, version: 1, world: 'w' },
+});
+
+/** What the main thread makes for the same face, with the same provider. */
+async function onMain(face: number, layer: string, far: boolean, sq: [number, number, number, number]) {
+ const provider = await loader(providerSource);
+ const facts: PlanetFacts = {
+ centre: [0, -radius, 0], radius, gravity: 0, height: null, paint: null, layers: ['grass', 'dirt', 'snow', 'rock'], fieldNames: ['ecology.island', 'ecology.wild'], fieldsAt: null,
+ sampleMany: (directions, count) => provider.sample({ world: 'w', seed: 9, version: 1, radius, directions, count }),
+ };
+ const f = new PlanetFace(face, () => facts);
+ const zones = new FaceZones(f);
+ const { plan, farPlan } = makeFacePlan(f, { rules, farRules: farRulesOf(rules), seed: 9, world: 'w', seaLevel: 0, layers: facts.layers, fieldNames: facts.fieldNames, zones: zones.zones });
+ return (far && farPlan ? farPlan : plan).placementsIn(sq[0], sq[1], sq[2], sq[3], [layer]);
+}
+
+describe('a planet\'s pages made in a worker', () => {
+ it('are the pages the main thread makes, with the world\'s biomes painting the ground', async () => {
+ const provider = await loader(providerSource);
+ const facts: PlanetFacts = {
+ centre: [0, -radius, 0], radius, gravity: 0, height: null, paint: null, layers: ['grass', 'dirt', 'snow', 'rock'], fieldNames: ['ecology.island', 'ecology.wild'], fieldsAt: null,
+ sampleMany: (directions, count) => provider.sample({ world: 'w', seed: 9, version: 1, radius, directions, count }),
+ };
+ const faces = [0, 1, 2, 3, 4, 5].map((f) => {
+ const face = new PlanetFace(f, () => facts);
+ const zones = new FaceZones(face);
+ return { face, ...makeFacePlan(face, { rules, farRules: null, seed: 9, world: 'w', seaLevel: 0, layers: facts.layers, fieldNames: facts.fieldNames, zones: zones.zones }) };
+ });
+ const painter = (dx: number, dy: number, dz: number, base: readonly number[]) => {
+ const u = faces[faceOf(dx, dy, dz).face]!;
+ const at = u.face.planeOf(dx, dy, dz);
+ return at ? u.plan.paint(at.x, at.z, base) : base;
+ };
+ const node = { face: 2, level: 3, ix: 5, iz: 6 };
+ const common = { levels: 8, radius, minHeight: -10, maxHeight: 40 };
+ const here = await makePlanetPage({ provider, world: 'w', seed: 9, version: 1, ...common, paint: () => painter }, node);
+ const keys = [0, 1, 2, 3, 4, 5].map((f) => `pk${f}`);
+ const request: PageRequest = {
+ id: 1, type: 'page', node, ...common, provider: { source: providerSource, seed: 9, version: 1, world: 'w' },
+ paintKeys: keys, specs: keys.map((_k, f) => spec(f)),
+ };
+ const away = (await page(request, loader)).result;
+ expect(Buffer.from(away.heights)).toEqual(Buffer.from(here.heights));
+ expect(Buffer.from(away.paint)).toEqual(Buffer.from(here.paint));
+ expect(away.min).toBe(here.min);
+ expect(away.max).toBe(here.max);
+ // And without a painter, the provider's own paint.
+ const plainHere = await makePlanetPage({ provider, world: 'w', seed: 9, version: 1, ...common }, node);
+ const plainAway = (await page({ ...request, id: 2, paintKeys: null, specs: [] }, loader)).result;
+ expect(Buffer.from(plainAway.paint)).toEqual(Buffer.from(plainHere.paint));
+ });
+});
+
+describe('a planet\'s world planned in a worker', () => {
+ it('places exactly what the main thread places, near and far, on any face', async () => {
+ for (const face of [0, 2, 5]) {
+ for (const far of [false, true]) {
+ const sq: [number, number, number, number] = [-40, 10, 56, 106];
+ const request: PlacementsRequest = { id: 1, key: `k${face}`, spec: spec(face), layer: 'cover', far, x0: sq[0], z0: sq[1], x1: sq[2], z1: sq[3] };
+ const away = await placements(request, loader);
+ const here = await onMain(face, 'cover', far, sq);
+ expect(away.length).toBeGreaterThan(5);
+ expect(JSON.parse(JSON.stringify(away))).toEqual(JSON.parse(JSON.stringify(here)));
+ }
+ }
+ });
+
+ it('keeps a plan it was sent and answers later questions from it', async () => {
+ const first: PlacementsRequest = { id: 1, key: 'kept', spec: spec(2), layer: 'cover', far: false, x0: 0, z0: 0, x1: 48, z1: 48 };
+ await placements(first, loader);
+ const second = await placements({ id: 2, key: 'kept', layer: 'cover', far: false, x0: 48, z0: 0, x1: 96, z1: 48 }, loader);
+ expect(second.length).toBeGreaterThan(0);
+ await expect(placements({ id: 3, key: 'unknown', layer: 'cover', far: false, x0: 0, z0: 0, x1: 8, z1: 8 }, loader)).rejects.toThrow(/not known/);
+ });
+
+ it('is a script a worker can start from: valid, and answering on the message loop', () => {
+ expect(PLAN_WORKER_SOURCE.length).toBeGreaterThan(1000);
+ expect(() => new Function(PLAN_WORKER_SOURCE)).not.toThrow();
+ expect(PLAN_WORKER_SOURCE).toContain('onmessage');
+ });
+
+ it('has no pool where there is no Worker, so the caller plans in place', () => {
+ expect(createJobPool(PLAN_WORKER_SOURCE)).toBeNull();
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index ec6a83bc7..db5c48d26 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."},
+ "feat(worldgen): a planet's world and pages are worked out on worker threads":
+ {"note":"A generated world on worker threads."},
"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":