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.

65.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    worldgenPlugin.ts
 * @brief   A generated world in the scene: a `WorldGen` names the game's rules, `WorldZone`s plan it, and what the rules place is
 *          published in chunks round the streaming sources.
 *
 * @details One plan (plan.ts) a WorldGen, read from the terrain's surface and the water, and laid over by the world's changes
 *          (diffs.ts) before anything is shown. Each of the rules' layers is a layer of procedural chunks (residency/chunks.ts), so
 *          it is made nearest first within the frame's budget, let go past its `drawDistance`, and made again with its old chunk kept
 *          until then when the ground or the water changes; a zone or a change touches only the chunks it reaches.
 *
 *            - Plant parts use shared geometry and per-instance LOD; other decoration is merged per mesh and material in a chunk.
 *            - What a game interacts with is an entity of its own, carrying a `PlacedObject` with its placement id and kind, so the
 *              game can find it, act on it and record what it did (`diffs.remove(id)` when it is felled).
 *            - The ground is painted by the biomes, when the WorldGen says so.
 *
 *          A server without a renderer makes the plan and the interactive entities, and nothing that is only drawn.
 */
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { defineResource } from '../ecs/resource';
import {
    defineComponent, getComponent, MeshRenderer, RuntimeOnly, SceneOwner, Transform,
    type ComponentDef, type MeshRendererData, type TransformData,
} from '../ecs/component';
import { Assets } from '../asset/AssetPlugin';
import { AssetScope, ownedAssetLease, type AssetLease } from '../asset/AssetLease';
import type { MeshData } from '../asset/meshFormat';
import { log } from '../util/logger';
import type { Entity } from '../types';
import { Terrains, TerrainsRes } from '../terrain/terrainPlugin';
import { flattenModifier } from '../terrain/source';
import { buildBillboardMesh, buildInstancedMesh, type Plant } from '../foliage/builder';
import { chunksOf, ProceduralChunksRes, streamingSourcesOf, type ChunkLayerStatus, type ChunkSource } from '../residency/chunks';
import { plantGrowthOf, prepareKinds, type GrownCell, type ReadyKinds } from '../foliage/plantGrowth';
import { plantInteractionOf } from '../foliage/plantInteraction';
import { PlanetRegistryRes, type PlanetFacts } from '../terrain/planetQuery';
import { faceOf } from '../terrain/sphere';
import { Environment } from './fields';
import { farRulesOf, makeFacePlan } from './facePlan';
import { makePlanePlan } from './planePlan';
import type { WaterQueryData } from '../water/waterQuery';
import type { JobPool } from '../runtime/jobs';
import { firstSend, forgetSent, planPool } from '../runtime/planPool';
import type { GroundPageRequest, PlacementsRequest, PlanSpec, PlaneSpec } from './planWorker';
import type { PageImage } from '../terrain/pages';
import { FaceZones, faceHalf, planetFaces, type PlanetFace } from './planetSurface';
import { expandPlants, type PlantSet } from './plants';
import { WorldPlan, type Placement } from './plan';
import { worldRules, worldRulesRevision, type PlacementLayer, type RecipeMember, type WorldRules } from './rules';
import { Zones, type ZoneDef } from './zones';
import { PlacementDiffs } from './diffs';
import { isRulesFile } from './rulesAsset';
import { lodCullSizeWithin, lodSizeAtDistance, lodSphereRadius } from '../render/lodDistance';
import { enableSceneOrigins, sceneOriginOf } from '../scene/sceneOrigins';

/** The fields of the `WorldGen` component. @experimental */
export interface WorldGenData {
    /** The rules the world is laid out by, as the game registered them, and the version of them the world was made with. */
    rules: string;
    version: number;
    /** The world (a planet, a level) as the game names it, and its seed. */
    world: string;
    seed: number;
    /** Whether the biomes paint the terrain. */
    paintGround: boolean;
    /** {@link WorldSurface}: a plane (a Terrain of x and z), or a planet (the entity is also a `Planet`, and the world is laid out over its six faces). */
    surface: number;
    /** The height of the sea above a planet's radius: a point lower than this is under water. */
    seaLevel: number;
}

/** What a world is laid out on. */
export const WorldSurface = { Plane: 0, Planet: 1 } as const;

/**
 * A generated world: the rules it is laid out by. Presence is the opt-in; what the rules place is published as its children.
 *
 * @experimental
 */
export const WorldGen: ComponentDef<WorldGenData> = defineComponent<WorldGenData>('WorldGen', {
    rules: '', version: 1, world: '', seed: 1, paintGround: true, surface: WorldSurface.Plane, seaLevel: 0,
}, {
    fields: {
        rules: { tooltip: 'The rules the world is laid out by: a .esworld file, or the id of rules the game registered with registerWorldRules.' },
        version: { min: 1, step: 1, tooltip: 'The version of the rules the world was made with. A version the rules no longer have fails the world rather than laying out another one.' },
        world: { tooltip: 'The world (a planet, a level) as the game names it.' },
        seed: { step: 1, tooltip: 'Another seed lays out another world by the same rules.' },
        paintGround: { tooltip: 'Whether the biomes paint the terrain.' },
        surface: { enum: [{ label: 'Plane', value: WorldSurface.Plane }, { label: 'Planet', value: WorldSurface.Planet }], tooltip: 'Plane: laid out over a Terrain. Planet: this entity is also a Planet, and the world is laid out over its six faces.' },
        seaLevel: { shownWhen: { field: 'surface', values: [WorldSurface.Planet] }, tooltip: 'The height of the sea above the planet\'s radius: ground lower than this is under water.' },
    },
});

/** How a `WorldZone` is shaped. */
export const ZoneShapeKind = { Circle: 0, Box: 1 } as const;

/** The fields of the `WorldZone` component. @experimental */
export interface WorldZoneData {
    /** What the zone is for (home, road, landing, building, resource, view): the game's own words. */
    kind: string;
    shape: number;
    radius: number;
    sizeX: number;
    sizeZ: number;
    /** Over how many world units past its outline it fades out. */
    falloff: number;
    priority: number;
    /** The tags of what it keeps out, separated by commas; `*` keeps out everything. */
    excludes: string;
    /** A biome it holds over its area; empty holds none. */
    biome: string;
    /** Whether it levels the terrain under it to the ground's height at its centre. */
    flatten: boolean;
}

/**
 * An area of a generated world planned by hand: kept clear, held to a biome, or both. It follows its entity's position and its turn
 * about the vertical.
 *
 * @experimental
 */
export const WorldZone: ComponentDef<WorldZoneData> = defineComponent<WorldZoneData>('WorldZone', {
    kind: 'reserve', shape: ZoneShapeKind.Circle, radius: 10, sizeX: 20, sizeZ: 20, falloff: 4, priority: 0, excludes: '*', biome: '', flatten: false,
}, {
    fields: {
        kind: { tooltip: 'What the zone is for (home, road, landing, building, resource, view): the game\'s own words.' },
        shape: { enum: [{ label: 'Circle', value: ZoneShapeKind.Circle }, { label: 'Box', value: ZoneShapeKind.Box }] },
        radius: { min: 0, shownWhen: { field: 'shape', values: [ZoneShapeKind.Circle] }, tooltip: 'The circle\'s radius, in world units.' },
        sizeX: { min: 0, shownWhen: { field: 'shape', values: [ZoneShapeKind.Box] }, tooltip: 'The box\'s size along its own x.' },
        sizeZ: { min: 0, shownWhen: { field: 'shape', values: [ZoneShapeKind.Box] }, tooltip: 'The box\'s size along its own z.' },
        falloff: { min: 0, tooltip: 'Over how many world units past the outline the zone fades out: what it keeps out thins there.' },
        priority: { step: 1, tooltip: 'Where zones overlap, the higher priority holds the biome.' },
        excludes: { tooltip: 'The tags of what the zone keeps out, separated by commas (a layer, a recipe, its tags, decor, interactive); * keeps out everything; empty keeps nothing out.' },
        biome: { tooltip: 'A biome the zone holds over its area; empty holds none.' },
        flatten: { tooltip: 'Level the terrain under the zone to the ground\'s height at its centre, blending back over its falloff: a plot to build on.' },
    },
});

/** The fields of the `PlacedObject` component. @experimental */
export interface PlacedObjectData {
    /** The placement's id: what a save records when the game changes it. */
    id: string;
    /** What the game interacts with it as. */
    kind: string;
}

/**
 * Marks an entity a generated world placed for the game to interact with. Written by the engine; a scene does not author it.
 *
 * @experimental
 */
export const PlacedObject: ComponentDef<PlacedObjectData> = defineComponent<PlacedObjectData>('PlacedObject', { id: '', kind: '' });

/** Where a WorldGen stands: being made, ready, or failed (with why); and each of its layers' chunks. */
export interface WorldGenStatus {
    state: 'loading' | 'ready' | 'failed';
    reason?: string;
    layers: Record<string, ChunkLayerStatus>;
}

interface BuiltWorld {
    assets: AssetLease<AssetScope>;
    retired: boolean;
    meshData: Map<number, MeshData | null | Promise<MeshData | null>>;
    signature: string;
    data: WorldGenData;
    rules: WorldRules | null;
    plan: WorldPlan | null;
    /** The same plan with the sparser spacing the layers that have a `farSpacing` are planned at for their far versions; null when none has one. */
    farPlan: WorldPlan | null;
    failure: string | null;
    /** The terrain's and the water's revisions the plan was read from. */
    ground: string;
    /** Subscriptions and terrain effects owned by this generation, not by its retained chunks. */
    listeners: (() => void)[];
    levelled: Set<string>;
    paint: Terrains['paint_'];
    /** The maker of the ground's pages this world handed its terrain, and the plan it was made for. */
    pager?: Terrains['pager_'];
    pagerKey?: string;
    /** Zones that level their ground and wait for it to be known. */
    levelling: Set<string>;
    /** The rules' plants as kinds, and their parts once the assets are in hand (null while they are being loaded, or when the rules have no plants). */
    plants: PlantSet | null;
    plantsReady: ReadyKinds | null;
    /** A planet's six faces, each laid out as a plane (null for a world on a plane). */
    faces: FaceUnit[] | null;
    /** A world on a planet whose plan waits for the planet to say what it is (its ground and layers), which it does a frame after it is made. */
    waitingForPlanet: boolean;
}

/** One face of a planet's world: its plane, its plan (and the sparser one for far versions) and the zones over it. */
interface FaceUnit { face: PlanetFace; plan: WorldPlan; farPlan: WorldPlan | null; zones: FaceZones }

/** One piece of a world laid out and published in chunks: the whole of a plane, or a face of a planet. */
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;
    /** The area in the unit's plane its chunks are counted over, or null for no end. */
    bounds: [number, number, number, number] | null;
    /** Whether the ground at a point of the plane is known (a chunk waits for the corners of its square). */
    known(x: number, z: number): boolean;
}

/** A chunk of a layer: what it places (its decoration merged by mesh, its interactive placements), and what it put in the world. */
interface PlacedChunk {
    assets?: AssetLease<AssetScope>;
    /** A kind of decoration: its near mesh and, when it has one, its far cards; drawn near out to `lodDistance`, out to `drawDistance`. */
    decor: { mesh: number; material: number; data: MeshData; far: MeshData | null; origin: [number, number, number]; lodDistance: number; drawDistance: number }[];
    objects: Placement[];
    /** The plants of the rules' `plants` in it, by kind, standing relative to `at` (the chunk's centre), and what grew them once published. */
    planted: Map<number, Plant[]> | null;
    at: [number, number, number];
    /** The chunk's side. */
    side: number;
    grown: GrownCell | null;
    /** Made for the far layer: only the far versions of its plants, which are shown from past what their kinds draw as themselves. */
    far: boolean;
    /** How many times thinner than the layer's own spacing the plants were planned (its `farSpacing` squared): the far version does not thin them again. */
    thinnedBy: number;
    entities: Entity[];
    meshes: number[];
}

/** The water, as worldgen asks it (the water module is optional: read by name, not imported). */
interface WaterQuery { depthAt(x: number, z: number, y: number): number | null; shoreAt?(x: number, z: number): number | null; queryData?(): WaterQueryData | null; readonly empty?: boolean; revision_: number; baking: boolean }

function waterOf(app: App): WaterQuery | null {
    const w = (app as unknown as { getResourceByName?: (name: string) => unknown }).getResourceByName?.('Waters') as Partial<WaterQuery> | undefined;
    return w && typeof w.depthAt === 'function' ? w as WaterQuery : null;
}

const layerIdOf = (entity: Entity, layer: string, key = ''): string => `worldgen:${entity}:${key ? `${key}:` : ''}${layer}`;
function zoneIdOf(app: App, entity: Entity): string {
    const origin = sceneOriginOf(app, entity);
    const scene = app.world.tryGet(entity, SceneOwner)?.scene;
    return origin !== undefined && scene !== undefined
        ? `zone:scene:${JSON.stringify([scene, origin])}`
        : `zone:${entity}`;
}
const FACE_KEYS = ['f0', 'f1', 'f2', 'f3', 'f4', 'f5'] as const;

/** Lets go of a layer's chunks, near and far, on a plane and on every face of a planet. */
function dropLayer(app: App, entity: Entity, layer: string): void {
    const chunks = chunksOf(app);
    for (const key of ['', ...FACE_KEYS]) { chunks.remove(layerIdOf(entity, layer, key)); chunks.remove(layerIdOf(entity, `${layer}:far`, key)); }
}

/** Run-time access to the generated worlds. */
export class WorldGens {
    /** @internal */ readonly built_ = new Map<Entity, BuiltWorld>();
    /** @internal */ app_: App | null = null;
    private readonly zones_ = new Map<string, Zones>();
    private readonly diffs_ = new Map<string, PlacementDiffs>();
    /** @internal Authored projections belong to a named world, shared by all of its generators. */
    readonly authored_ = new Map<string, Set<string>>();
    /** @internal A flatten modifier remains until its last live plan lets it go. */
    readonly levelled_ = new Map<string, { signature: string; owners: Set<BuiltWorld> }>();
    /** @internal The interactive entity of each placement id published now. */
    readonly objects_ = new Map<string, Entity>();

    /** The zones of a world (by its name), which a game adds to as it plans and builds. Shared by every WorldGen of that world. */
    zones(world = this.first_()?.data.world ?? ''): Zones {
        let z = this.zones_.get(world);
        if (!z) { z = new Zones(); this.zones_.set(world, z); }
        return z;
    }

    /** The changes made to a world (by its name), which a save stores and reads back. */
    diffs(world = this.first_()?.data.world ?? ''): PlacementDiffs {
        let d = this.diffs_.get(world);
        if (!d) { d = new PlacementDiffs(); this.diffs_.set(world, d); }
        return d;
    }

    /** A WorldGen's plan, or the first one's: what stands where, asked of anywhere, loaded or not. Null until it is made or if it failed. */
    plan(entity?: Entity): WorldPlan | null {
        return (entity !== undefined ? this.built_.get(entity) : this.first_())?.plan ?? null;
    }

    /** The interactive entity standing for placement `id`, or null where its chunk is not published or the placement is removed. */
    objectOf(id: string): Entity | null {
        return this.objects_.get(id) ?? null;
    }

    status(entity: Entity): WorldGenStatus | null {
        const built = this.built_.get(entity);
        if (!built) return null;
        const layers: Record<string, ChunkLayerStatus> = {};
        const chunks = this.app_?.hasResource(ProceduralChunksRes) ? this.app_.getResource(ProceduralChunksRes) : null;
        for (const l of built.rules?.layers ?? []) {
            // A planet's layer is one of chunks on each of its six faces: counted together.
            for (const key of built.faces ? FACE_KEYS : ['']) {
                const s = chunks?.status(layerIdOf(entity, l.id, key));
                if (!s) continue;
                const had = layers[l.id];
                layers[l.id] = had
                    ? { ready: had.ready + s.ready, stale: had.stale + s.stale, pending: had.pending + s.pending, making: had.making + s.making, failed: had.failed + s.failed, reason: had.reason ?? s.reason }
                    : s;
            }
        }
        if (built.failure) return { state: 'failed', reason: built.failure, layers };
        return { state: built.plan ? 'ready' : 'loading', layers };
    }

    private first_(): BuiltWorld | undefined {
        return this.built_.values().next().value;
    }
}

/** The resource the plugin installs. @experimental */
export const WorldGenRes = defineResource<WorldGens>(new WorldGens(), 'WorldGens');

/**
 * Runs an asset load again when it fails, a few times and a little later each time. Reading a project's files is slowest while the project is still being
 * opened (the asset database is scanned and cooked against it), and a load that waited out its timeout then is not a world that cannot be shown.
 */
async function retried<T>(load: () => Promise<T>, attempts = 5): Promise<T> {
    for (let n = 1; ; n++) {
        try { return await load(); } catch (error) {
            if (n >= attempts) throw error;
            log.warn('worldgen', `loading the world's assets failed (${error instanceof Error ? error.message : String(error)}); trying again`);
            await new Promise<void>((resolve) => setTimeout(resolve, 2000 * n));
        }
    }
}

export class WorldGenPlugin implements Plugin {
    name = 'worldgen';

    /** Stops listening for edited rules files. */
    private watching_: (() => void) | null = null;

    build(app: App): void {
        enableSceneOrigins(app);
        const gens = new WorldGens();
        gens.app_ = app;
        app.insertResource(WorldGenRes, gens);
        app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
            this.sweep(app, gens);
            for (const entity of app.world.getEntitiesWithComponents([WorldGen, Transform])) {
                const data = app.world.get(entity, WorldGen) as WorldGenData;
                const signature = `${JSON.stringify(data)}#${worldRulesRevision()}`;
                let built = gens.built_.get(entity);
                if (!built || built.signature !== signature) {
                    built = this.make(app, gens, entity, data, built);
                    gens.built_.set(entity, built);
                }
                if (built.waitingForPlanet && built.rules && app.hasResource(PlanetRegistryRes) && app.getResource(PlanetRegistryRes).planets.has(entity)) {
                    built.waitingForPlanet = false;
                    this.plan(app, gens, entity, built, built.rules);
                }
            }
            this.syncZones(app, gens);
            for (const [entity, built] of gens.built_) this.publish(app, gens, entity, built);
        }, { name: 'WorldGenSystem' }));
    }

    cleanup(app?: App): void {
        this.watching_?.();
        this.watching_ = null;
        if (!app?.hasResource(WorldGenRes)) return;
        const gens = app.getResource(WorldGenRes);
        for (const entity of [...gens.built_.keys()]) this.drop(app, gens, entity);
        this.syncZones(app, gens);
    }

    /** A WorldGen's rules and plan, or why it has none. */
    private make(app: App, gens: WorldGens, entity: Entity, data: WorldGenData, had: BuiltWorld | undefined): BuiltWorld {
        if (had) this.retire(app, gens, had);
        const meshData: BuiltWorld['meshData'] = new Map();
        const assets = ownedAssetLease(`worldgen:${entity}`, (had?.assets.generation ?? 0) + 1, new AssetScope(), scope => {
            try { scope.releaseAll(); } finally { meshData.clear(); }
        });
        const built: BuiltWorld = { assets, retired: false, meshData, signature: `${JSON.stringify(data)}#${worldRulesRevision()}`, data: { ...data }, rules: null, plan: null, farPlan: null, failure: null, ground: '', listeners: [], levelled: new Set(), paint: null, levelling: new Set(), plants: null, plantsReady: null, faces: null, waitingForPlanet: false };
        // Rules in a project file are read first, then made like rules registered by code.
        if (isRulesFile(data.rules)) {
            if (!app.hasResource(Assets)) {
                built.failure = `the world rules file ${data.rules} cannot be read without an asset system: register its rules in code instead`;
                log.error('worldgen', built.failure);
                return built;
            }
            const assets = app.getResource(Assets);
            // A rules file edited and saved is read again, and the world laid out by it again (its old chunks kept until then).
            if (!this.watching_) {
                this.watching_ = assets.onInvalidate(({ ref }) => {
                    const changed = assets.resolveLoadPath(ref);
                    for (const b of gens.built_.values()) if (isRulesFile(b.data.rules) && assets.resolveLoadPath(b.data.rules) === changed) b.signature = '';
                });
            }
            void assets.acquireTyped<WorldRules>('world-rules', data.rules).then((receipt) => {
                if (built.retired || gens.built_.get(entity) !== built) { receipt.release(); return; }
                built.assets.value.add(receipt);
                this.adopt(app, gens, entity, built, receipt.value, had);
            }, (e: unknown) => {
                if (gens.built_.get(entity) !== built) return;
                built.failure = `the world rules file ${data.rules} could not be read: ${e instanceof Error ? e.message : String(e)}`;
                log.error('worldgen', built.failure);
            });
            return built;
        }
        const rules = worldRules(data.rules);
        if (!rules) {
            built.failure = `no world rules ${data.rules || '(none named)'} are registered`;
            log.error('worldgen', `the world ${data.world} cannot be laid out: ${built.failure}`);
            for (const l of had?.rules?.layers ?? []) dropLayer(app, entity, l.id);
            return built;
        }
        this.adopt(app, gens, entity, built, rules, had);
        return built;
    }

    /** Takes a WorldGen's rules, once they are known: checks the version, and makes the plan (loading what the recipes name first). */
    private adopt(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld, rules: WorldRules, had: BuiltWorld | undefined): void {
        const data = built.data;
        if (!rules.versions.includes(data.version)) built.failure = `the world rules ${rules.id} have no version ${data.version} (they have ${rules.versions.join(', ')})`;
        else built.rules = rules;
        if (built.failure) {
            log.error('worldgen', `the world ${data.world} cannot be laid out: ${built.failure}`);
            // A world that cannot be laid out shows nothing of the one before it.
            for (const l of had?.rules?.layers ?? []) dropLayer(app, entity, l.id);
            return;
        }
        // Layers the new rules no longer have are let go; the ones they keep keep their chunks until they are made again.
        for (const l of had?.rules?.layers ?? []) if (!rules.layers.some((n) => n.id === l.id)) dropLayer(app, entity, l.id);
        // The plants the recipes name: as kinds, and their parts read once there is a renderer to grow them with. A chunk waits for them.
        if (rules.plants && Object.keys(rules.plants).length > 0 && app.hasResource(Assets)) {
            const set = expandPlants(rules.plants);
            built.plants = set;
            void retried(() => prepareKinds(app.getResource(Assets), set.kinds)).then((ready) => {
                if (built.retired || gens.built_.get(entity) !== built) { ready.lease.release(); return; }
                built.assets.value.add(ready.lease);
                built.plantsReady = ready;
            }, (e: unknown) => {
                if (built.retired) return;
                built.failure = `the plants' assets could not be loaded: ${e instanceof Error ? e.message : String(e)}`;
                log.error('worldgen', built.failure);
            });
        }
        // Recipes name their meshes and materials by path: with a renderer they are loaded first, and the plan is made with them.
        const refs = assetRefsOf(rules);
        if (refs.length > 0 && app.hasResource(Assets)) {
            void retried(() => this.resolve(app, rules, refs)).then((resolved) => {
                if (built.retired || gens.built_.get(entity) !== built) { resolved.scope.releaseAll(); return; }
                built.assets.value.absorb(resolved.scope);
                built.rules = resolved.rules;
                this.plan(app, gens, entity, built, resolved.rules);
            }, (e: unknown) => {
                if (built.retired) return;
                built.failure = `the recipes' assets could not be loaded: ${e instanceof Error ? e.message : String(e)}`;
                log.error('worldgen', built.failure);
            });
            return;
        }
        this.plan(app, gens, entity, built, rules);
    }

    /** Loads the meshes and materials `refs` name, and gives back the rules with each path replaced by its handle. */
    private async resolve(app: App, rules: WorldRules, refs: { kind: 'mesh' | 'material'; ref: string }[]): Promise<{ rules: WorldRules; scope: AssetScope }> {
        const assets = app.getResource(Assets);
        const scope = new AssetScope();
        const handles = new Map<string, number>();
        const results = await Promise.allSettled(refs.map(async ({ kind, ref }) => {
            const receipt = scope.add(await assets.acquireTyped<{ handle: number }>(kind, ref));
            handles.set(`${kind}:${ref}`, receipt.value.handle);
        }));
        const failed = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
        if (failed) { scope.releaseAll(); throw failed.reason; }
        const member = (m: RecipeMember): RecipeMember => ({
            ...m,
            mesh: typeof m.mesh === 'string' ? handles.get(`mesh:${m.mesh}`) ?? 0 : m.mesh,
            material: typeof m.material === 'string' ? handles.get(`material:${m.material}`) ?? 0 : m.material,
        });
        return { scope, rules: { ...rules, recipes: rules.recipes.map((r) => ({ ...r, anchor: member(r.anchor), members: r.members?.map(member) })) } };
    }

    /** Makes a WorldGen's plan from its rules, and what keeps it current. */
    private plan(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld, rules: WorldRules): void {
        const data = built.data;
        if (data.surface === WorldSurface.Planet) { this.planPlanet(app, gens, entity, built, rules); return; }
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const zones = gens.zones(data.world);
        const t0 = app.world.tryGet(entity, Transform) as TransformData | null;
        const flatY = t0?.worldPosition.y ?? 0;
        const made = makePlanePlan({
            rules, farRules: farRulesOf(rules), seed: data.seed, world: data.world, zones,
            // A terrain can finish loading after the plan was created. Read its current
            // availability rather than capturing a flat fallback for the plan's lifetime.
            ground: terrains ? {
                heightAt: (x, z) => terrains.built_.size > 0 || terrains.loading ? terrains.heightAt(x, z) : flatY,
                normalAt: (x, z) => terrains.normalAt(x, z),
                paintAt: (x, z) => terrains.paintAt(x, z),
            } : null,
            flatY,
            water: { depthAt: (x, z, y) => waterOf(app)?.depthAt(x, z, y) ?? null, shoreAt: (x, z) => waterOf(app)?.shoreAt?.(x, z) ?? null },
            layers: terrains ? terrains.layerNames() : [],
        });
        built.plan = made.plan;
        const plan = built.plan;
        built.farPlan = made.farPlan;
        // A zone that changes, or a placement a player changes, makes again only the chunks it reaches.
        built.listeners.push(zones.subscribe((bounds, zone) => {
            plan.invalidate();
            built.farPlan?.invalidate();
            const chunks = chunksOf(app);
            for (const l of rules.layers) {
                // A group kept out lets a neighbour it had beaten stand, which may beat its own: a few cells round are made again.
                const reach = l.spacing * 3;
                chunks.invalidate(layerIdOf(entity, l.id), bounds[0] - reach, bounds[1] - reach, bounds[2] + reach, bounds[3] + reach);
            }
            // A zone that holds a biome or sets a field changes the ground's paint under it.
            if (terrains && data.paintGround && (zone.biome || zone.fields)) terrains.repaint();
            // One that levels its ground lays a modifier on the terrain, and takes it off when it goes or stops levelling.
            if (terrains) {
                const now = zones.get(zone.id);
                if (now?.flatten !== undefined) this.level(terrains, gens, built, now);
                else this.unlevel(terrains, gens, built, zone.id);
            }
        }));
        built.listeners.push(gens.diffs(data.world).subscribe((id) => {
            const at = this.anchorOf(plan, id);
            if (at) chunksOf(app).invalidate(layerIdOf(entity, at.layer), at.x, at.z, at.x, at.z);
        }));
        if (terrains && data.paintGround) {
            built.paint = this.painter(plan);
            terrains.setPaint(built.paint);
        }
        // Zones that were there before the plan was made level their ground now.
        if (terrains) for (const zone of zones.all()) if (zone.flatten !== undefined) this.level(terrains, gens, built, zone);
    }

    /**
     * Makes a planet's plans: one for each face of the cube, each on the face's plane. The plan of a face is the same plan as a plane's, read from the
     * planet's ground by direction and from noise in three dimensions, so a field wanders over an edge between two faces without a seam; a direction is
     * planned by the face it falls on, and the faces' plans paint the planet's ground by the same biomes that place what stands on it.
     */
    private planPlanet(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld, rules: WorldRules): void {
        const data = built.data;
        if (!app.hasResource(PlanetRegistryRes)) { built.failure = 'a world on a planet needs the Planet plugin'; log.error('worldgen', built.failure); return; }
        const registry = app.getResource(PlanetRegistryRes);
        const facts = (): PlanetFacts | null => registry.planets.get(entity) ?? null;
        if (!facts()) { built.waitingForPlanet = true; return; }
        const farRules = farRulesOf(rules);
        built.faces = planetFaces(facts).map((face) => {
            const zones = new FaceZones(face);
            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,
            });
            // 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();
                farPlan?.invalidate();
                const chunks = chunksOf(app);
                for (const l of rules.layers) {
                    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), registry.remotePaintOf(entity));
            };
            return { face, plan, farPlan, zones };
        });
        built.plan = built.faces[2]!.plan;
        const faces = built.faces;
        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);
        }
    }

    /** Levels a zone's ground, or (the ground under its centre not known yet) keeps it to level once it is. */
    private level(terrains: Terrains, gens: WorldGens, built: BuiltWorld, zone: ZoneDef): void {
        const height = zone.flatten === 'ground' ? terrains.heightBeneathAt(zone.shape.x, zone.shape.z) : zone.flatten;
        if (height === null || height === undefined) { built.levelling.add(zone.id); return; }
        const signature = JSON.stringify([zone.shape, zone.falloff, height]);
        let held = gens.levelled_.get(zone.id);
        if (!held) { held = { signature: '', owners: new Set() }; gens.levelled_.set(zone.id, held); }
        held.owners.add(built);
        built.levelled.add(zone.id);
        if (held.signature !== signature) {
            terrains.setModifier(flattenModifier(`zone:${zone.id}`, zone.shape, height, zone.falloff));
            held.signature = signature;
        }
        built.levelling.delete(zone.id);
    }

    private unlevel(terrains: Terrains | null, gens: WorldGens, built: BuiltWorld, id: string): void {
        built.levelling.delete(id);
        built.levelled.delete(id);
        const held = gens.levelled_.get(id);
        if (!held) return;
        held.owners.delete(built);
        if (held.owners.size === 0) {
            terrains?.deleteModifier(`zone:${id}`);
            gens.levelled_.delete(id);
        }
    }

    /** The ground's paint by a plan's biomes. */
    private painter(plan: WorldPlan) {
        return (x: number, z: number, _h: number, _ny: number, w: readonly number[]) => plan.paint(x, z, w);
    }

    /** Where the group of placement `id` is anchored, from the layer and grid cell its id names. */
    private anchorOf(plan: WorldPlan, id: string): { layer: string; x: number; z: number } | null {
        const m = /^(.+)@\d+:(-?\d+),(-?\d+)\//.exec(id);
        if (!m) return null;
        const li = plan.layerIndex(m[1]!);
        if (li < 0) return null;
        const g = plan.group(li, Number(m[2]), Number(m[3]));
        return typeof g === 'string' ? null : { layer: m[1]!, x: g.x, z: g.z };
    }

    /** Puts the authored `WorldZone`s into their world's zones. */
    private syncZones(app: App, gens: WorldGens): void {
        const worlds = new Map([...gens.built_.values()].map(built => [built.data.world, built]));
        for (const [name, authored] of gens.authored_) {
            if (worlds.has(name)) continue;
            for (const id of authored) gens.zones(name).delete(id);
            gens.authored_.delete(name);
        }
        const entities = app.world.getEntitiesWithComponents([WorldZone, Transform]);
        for (const [name, built] of worlds) this.syncWorldZones(app, gens, name, built, entities);
    }

    private syncWorldZones(app: App, gens: WorldGens, name: string, built: BuiltWorld, entities: readonly Entity[]): void {
        const zones = gens.zones(name);
        const seen = new Set<string>();
        for (const e of entities) {
            const z = app.world.get(e, WorldZone) as WorldZoneData;
            const t = app.world.get(e, Transform) as TransformData;
            const p = t.worldPosition, q = t.worldRotation;
            const yaw = Math.atan2(2 * (q.w * q.y + q.x * q.z), 1 - 2 * (q.y * q.y + q.z * q.z));
            // On a planet a zone stands at a place in the world (its height too), and a box carries where its own x axis points.
            const onPlanet = built.data.surface === WorldSurface.Planet;
            const facing: [number, number, number] = [1 - 2 * (q.y * q.y + q.z * q.z), 2 * (q.x * q.y + q.w * q.z), 2 * (q.x * q.z - q.w * q.y)];
            const def: ZoneDef = {
                id: zoneIdOf(app, e), kind: z.kind, falloff: z.falloff, priority: z.priority,
                shape: z.shape === ZoneShapeKind.Box
                    ? { type: 'rect', x: p.x, z: p.z, halfX: z.sizeX / 2, halfZ: z.sizeZ / 2, yaw: -yaw, ...(onPlanet ? { y: p.y, facing } : {}) }
                    : { type: 'circle', x: p.x, z: p.z, radius: z.radius, ...(onPlanet ? { y: p.y } : {}) },
                excludes: z.excludes.split(',').map((s) => s.trim()).filter(Boolean),
                ...(z.biome ? { biome: z.biome } : {}),
                ...(z.flatten ? { flatten: 'ground' as const } : {}),
            };
            zones.set(def);
            seen.add(def.id);
        }
        for (const id of gens.authored_.get(name) ?? []) if (!seen.has(id)) zones.delete(id);
        gens.authored_.set(name, seen);
    }

    /** Hands each of the rules' layers to the chunks, made from the plan: of the one plane, or of each face of a planet. */
    private publish(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld): void {
        const plan = built.plan, rules = built.rules;
        if (!plan || !rules) return;
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        const water = waterOf(app);
        if (built.faces) {
            const registry = app.getResource(PlanetRegistryRes);
            const facts = registry.planets.get(entity);
            if (!facts) return;
            // The world's zones, over each face: those whose centre falls on it, in its plane.
            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;
        }
        // What the plan read the ground and the water from: when either changes everything is read again.
        const ground = `${terrains?.revision_ ?? 0}:${water?.revision_ ?? 0}`;
        if (ground !== built.ground) { plan.invalidate(); built.farPlan?.invalidate(); built.ground = ground; }
        const waiting = !!terrains?.loading || !!water?.baking;
        if (terrains) {
            for (const id of [...built.levelling]) {
                const zone = gens.zones(built.data.world).get(id);
                if (zone?.flatten !== undefined) this.level(terrains, gens, built, zone); else this.unlevel(terrains, gens, built, id);
            }
        }
        // A world on a terrain of an area ends where the terrain does: its chunks are counted over that, and not over a radius of empty world.
        this.publishUnit(app, gens, entity, built, {
            key: '', plan, farPlan: built.farPlan, face: null, bounds: terrains?.areaBounds() ?? null,
            known: (x, z) => !terrains || terrains.groundKnownAt(x, z),
            away: this.awayOnPlane(app, gens, entity, built, terrains, water, waiting),
        }, ground, waiting);
    }

    /**
     * What lays a plane's world out on workers, when the ground and the water can be handed to them as data (a terrain of a field or of noise, with nothing laid over it;
     * water that is baked): the chunks are spread over the workers, and a worker is sent the plan the first time it is asked a square of it. Null when they cannot, and
     * the world is laid out here.
     */
    private awayOnPlane(app: App, gens: WorldGens, entity: Entity, built: BuiltWorld, terrains: Terrains | null, water: WaterQuery | null, waiting: boolean): Unit['away'] | undefined {
        const pool = planPool();
        // The ground's pages go where the plan is: a world that paints the ground has its biomes read on the workers, or here when they cannot have the plan.
        const mine = built.paint !== null && terrains?.paint_ === built.paint;
        const none = (): undefined => { if (mine && terrains && built.pager && terrains.pager_ === built.pager) terrains.setPager(null); built.pager = null; built.pagerKey = undefined; return undefined; };
        if (!pool || waiting || built.data.surface !== WorldSurface.Plane) return none();
        const ground = terrains && terrains.built_.size > 0 ? terrains.groundData() : null;
        if (terrains && terrains.built_.size > 0 && !ground) return none();
        const waterData = water ? water.queryData?.() ?? null : null;
        // Water that cannot be handed over keeps the plan here; water there is none of is handed over as none.
        if (water && !waterData && water.queryData && !water.empty) return none();
        const zones = gens.zones(built.data.world);
        const key = `${built.signature}:plane:t${terrains?.revision_ ?? 0}:w${water?.revision_ ?? 0}:z${zones.revision}`;
        const flatY = (app.world.tryGet(entity, Transform) as TransformData | null)?.worldPosition.y ?? 0;
        const spec = (): PlaneSpec => ({
            plane: true, rules: { ...built.rules!, fields: undefined, plants: undefined } as WorldRules, seed: built.data.seed, world: built.data.world,
            ground, flatY, water: waterData, layers: terrains ? terrains.layerNames() : [], zones: [...zones.all()],
        });
        // The same key and the same workers as the placements: a worker that has laid a square out has the plan a page of it is painted from.
        const workerAt = (x: number, z: number): number => Math.abs((Math.floor(x / 256) * 73856093) ^ (Math.floor(z / 256) * 19349663)) % pool.size;
        if (mine && terrains && ground && built.pagerKey !== key) {
            const origin = ground.origin;
            built.pagerKey = key;
            built.pager = (x0, z0, size) => {
                // Asked for a ground that has changed since (a modifier laid on it, another terrain): not this plan's to make.
                if (built.pagerKey !== key || terrains.groundData() === null) return null;
                const worker = workerAt(x0 + origin.x, z0 + origin.z);
                const first = firstSend(worker, key);
                const request: GroundPageRequest = { id: 0, type: 'groundPage', key, x0, z0, size, paint: true, ...(first ? { spec: spec() } : {}) };
                return pool.run<PageImage>(worker, request as unknown as Record<string, unknown>).catch((e: unknown) => {
                    forgetSent(worker, key);
                    throw e;
                });
            };
            terrains.setPager(built.pager);
        }
        return (layer, far, x0, z0, x1, z1) => {
            // Squares are spread over the workers by where they are, so neighbours share a worker and what it has worked out.
            const worker = workerAt(x0, z0);
            const first = firstSend(worker, key);
            const request: PlacementsRequest = { id: 0, key, layer, far, x0, z0, x1, z1, ...(first ? { spec: spec() } : {}) };
            return pool.run<Placement[]>(worker, request as unknown as Record<string, unknown>).catch((e: unknown) => {
                forgetSent(worker, key);
                throw e;
            });
        };
    }

    /** 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!;
        const diffs = gens.diffs(built.data.world);
        const rendering = app.hasResource(Assets);
        const chunks = chunksOf(app);
        const { plan, bounds, face } = unit;
        const known = (x0: number, z0: number, side: number): boolean => [[x0, z0], [x0 + side, z0], [x0, z0 + side], [x0 + side, z0 + side]].every(([x, z]) => unit.known(x!, z!));
        // Where the layer is wanted round: the world's streaming sources, put in the face's plane on a planet.
        const sourcesFor = face ? (reach: number) => (): Iterable<ChunkSource> => face.sourcesOnFace(streamingSourcesOf(app), reach) : null;
        for (const layer of rules.layers) {
            const size = layer.chunkSize ?? 64;
            const extent: [number, number, number, number] | null = bounds
                ? [Math.floor(bounds[0] / size), Math.floor(bounds[1] / size), Math.ceil(bounds[2] / size), Math.ceil(bounds[3] / size)] : null;
            chunks.set<PlacedChunk>(layerIdOf(entity, layer.id, unit.key), {
                label: 'Laying out the world',
                async: !!unit.away,
                originX: 0, originZ: 0, sizeX: size, sizeZ: size, extent,
                loadRadius: layer.drawDistance, unloadRadius: layer.drawDistance + size,
                generation: `${built.signature}:${ground}`,
                ...(sourcesFor ? { sources: sourcesFor(layer.drawDistance + size) } : {}),
                make: (cx, cz) => {
                    const x0 = cx * size, z0 = cz * size;
                    // 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 this.ownChunk(built, () => away.then((placed) => this.chunk(app, built.meshData, null, diffs, layer, x0, z0, size, rendering, built.plants, face, false, 1, placed)));
                    if (waiting || !known(x0, z0, size)) return null;
                    return this.ownChunk(built, () => this.chunk(app, built.meshData, plan, diffs, layer, x0, z0, size, rendering, built.plants, face));
                },
                publish: (_cx, _cz, value) => this.place(app, gens, entity, value),
                release: (_cx, _cz, value) => this.unplace(app, gens, value),
            });
            // The plants' far versions are a layer of their own, wanted as far as the furthest of them goes: they are cheap, so the whole world stands at once,
            // where the plants themselves are only grown near the eye. They are shown from past what their kinds draw as themselves.
            const farId = layerIdOf(entity, `${layer.id}:far`, unit.key);
            if (!rendering || !built.plants || built.plants.reach <= layer.drawDistance) { chunks.remove(farId); continue; }
            // A far cell is as many chunks wide as the shortest span a far version is shown over allows: the far versions are one draw a kind a cell, and a ring
            // of ground cover a few chunks wide would otherwise be thousands of them.
            const farSide = Math.min(Math.max(Math.floor(built.plants.span / size), 1), 2);
            const fsize = size * farSide;
            const fextent: [number, number, number, number] | null = bounds
                ? [Math.floor(bounds[0] / fsize), Math.floor(bounds[1] / fsize), Math.ceil(bounds[2] / fsize), Math.ceil(bounds[3] / fsize)] : null;
            chunks.set<PlacedChunk>(farId, {
                label: 'Laying out the far plants',
                async: !!unit.away,
                originX: 0, originZ: 0, sizeX: fsize, sizeZ: fsize, extent: fextent,
                loadRadius: built.plants.reach, unloadRadius: built.plants.reach + fsize,
                generation: `${built.signature}:${ground}`,
                ...(sourcesFor ? { sources: sourcesFor(built.plants.reach + fsize) } : {}),
                make: (cx, cz) => {
                    const x0 = cx * fsize, z0 = cz * fsize;
                    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 this.ownChunk(built, () => away.then((placed) => this.chunk(app, built.meshData, 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.ownChunk(built, () => this.chunk(app, built.meshData, 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),
                release: (_cx, _cz, value) => this.unplace(app, gens, value),
            });
        }
    }

    /** Pending and published chunks both borrow the generation they were built from. */
    private ownChunk(built: BuiltWorld, make: () => PlacedChunk | Promise<PlacedChunk>): PlacedChunk | Promise<PlacedChunk> | null {
        const assets = built.assets.retain();
        if (!assets) return null;
        const hold = (chunk: PlacedChunk): PlacedChunk => { chunk.assets = assets; return chunk; };
        try {
            const value = make();
            return value instanceof Promise ? value.then(hold, error => { assets.release(); throw error; }) : hold(value);
        } catch (error) { assets.release(); throw error; }
    }

    /** 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, meshData: BuiltWorld['meshData'], 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[] = [];
        // 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;
            const c = diffs.changeOf(p.id);
            placements.push(c ? { ...p, ...c } : p);
        }
        // Where the chunk stands: the middle of its square, on the plane's zero height (a planet: that point of the ground's sphere).
        const centre: [number, number, number] = face ? face.world(x0 + size / 2, 0, z0 + size / 2) : [x0 + size / 2, 0, z0 + size / 2];
        const objects = far ? [] : placements.filter((p) => p.interactive !== null);
        const decor = rendering && !far ? placements.filter((p) => p.interactive === null && p.mesh) : [];
        const meshes = [...new Set(decor.map((p) => p.mesh))];
        const finish = (): PlacedChunk => {
            const out: PlacedChunk = { decor: [], objects, planted: null, at: centre, side: size, grown: null, far, thinnedBy, entities: [], meshes: [] };
            // The plants: each at its kind (its colouring there), relative to the chunk's centre, sunk by what its kind says.
            if (plants && rendering) {
                const by = new Map<number, Plant[]>();
                for (const p of placements) {
                    if (p.interactive !== null || p.plant === null) continue;
                    const k = plants.kindAt(p.plant, p.x, p.z);
                    if (k < 0) continue;
                    let list = by.get(k);
                    if (!list) by.set(k, list = []);
                    list.push({ ...(plants.kinds[k]?.interaction ? { key: p.id } : {}), x: p.x - out.at[0], y: p.y - out.at[1] - plants.sinkOf(p.plant), z: p.z - out.at[2], yaw: p.yaw, scale: p.scale * plants.unitOf(p.plant), phase: 0, shade: 1,
                        ...(leanOf(p) ? { up: leanOf(p)! } : {}) });
                }
                if (by.size > 0) out.planted = by;
            }
            const byKind = new Map<string, Placement[]>();
            for (const p of decor) {
                const k = `${p.mesh}:${p.material}`;
                let list = byKind.get(k);
                if (!list) byKind.set(k, list = []);
                list.push(p);
            }
            const origin = out.at;
            for (const list of byKind.values()) {
                const source = meshData.get(list[0]!.mesh);
                if (!source || source instanceof Promise) continue;
                const plants: Plant[] = list.map((p, i) => ({
                    x: p.x - origin[0], y: p.y - origin[1], z: p.z - origin[2], yaw: p.yaw, scale: p.scale, phase: (i * 0.618) % 1, shade: 1,
                    ...(leanOf(p) ? { up: leanOf(p)! } : {}),
                }));
                const far = list[0]!.far;
                const width = Math.max(source.aabbMax[0] - source.aabbMin[0], source.aabbMax[2] - source.aabbMin[2]);
                out.decor.push({
                    mesh: list[0]!.mesh, material: list[0]!.material, data: buildInstancedMesh(source, plants), origin,
                    far: far ? buildBillboardMesh(plants, width, source.aabbMax[1] - source.aabbMin[1], far, undefined, far.tent === true) : null,
                    lodDistance: layer.lodDistance ?? layer.drawDistance, drawDistance: layer.drawDistance,
                });
            }
            return out;
        };
        const missing = meshes.filter((m) => !meshData.has(m) || meshData.get(m) instanceof Promise);
        if (missing.length === 0) return finish();
        const assets = app.getResource(Assets);
        return Promise.all(missing.map((m) => {
            let got = meshData.get(m);
            if (got === undefined) {
                const read = assets.readMeshData(m).catch(() => null).then((d) => {
                    if (!d) log.warn('worldgen', `the geometry of mesh ${m} cannot be read, so what it draws is left out`);
                    meshData.set(m, d);
                    return d;
                });
                meshData.set(m, read);
                got = read;
            }
            return got;
        })).then(finish);
    }

    /** Puts a chunk in the world: a mesh a kind of decoration, an entity an interactive placement. */
    private place(app: App, gens: WorldGens, parent: Entity, chunk: PlacedChunk): void {
        const world = app.world;
        if (!world.valid(parent)) return;
        const base = (world.get(parent, Transform) as TransformData).worldPosition;
        const assets = app.hasResource(Assets) ? app.getResource(Assets) : null;
        const built = gens.built_.get(parent);
        if (chunk.planted && built?.plants && built.plantsReady) {
            // The plants of the chunk: its entity stands at once, and they grow in it over the frames, as a placed foliage's do.
            const e = world.spawn('WorldGenPlants');
            world.insert(e, RuntimeOnly);
            world.insert(e, Transform, { position: { x: chunk.at[0] - base.x, y: chunk.at[1] - base.y, z: chunk.at[2] - base.z } });
            world.setParent(e, parent);
            chunk.entities.push(e);
            chunk.grown = { entity: e, handles: [], dead: false };
            const growth = plantGrowthOf(app);
            const interactive = built.plants.kinds.some((k) => k.interaction);
            if (interactive) chunk.grown.sets = [];
            if (chunk.far) growth.growFar(app, chunk.grown, built.plants.kinds, built.plantsReady, chunk.planted, { x: chunk.at[0], z: chunk.at[2], half: chunk.side / 2 }, chunk.thinnedBy);
            else growth.growCell(app, chunk.grown, built.plants.kinds, built.plantsReady, chunk.planted);
            if (interactive) {
                const source = `world:${built.data.world}`;
                if (chunk.far) plantInteractionOf(app).addFarCell(chunk.grown, source, built.plants.kinds, built.plantsReady);
                else plantInteractionOf(app).addCell(chunk.grown, source, built.plants.kinds, built.plantsReady, chunk.planted, chunk.side / 2);
            }
        }
        for (const d of chunk.decor) {
            const handle = assets?.createMesh(d.data) ?? 0;
            if (!handle) continue;
            chunk.meshes.push(handle);
            const farHandle = d.far ? assets?.createMesh(d.far) ?? 0 : 0;
            if (farHandle) chunk.meshes.push(farHandle);
            const e = world.spawn('WorldGenDecor');
            // Made again from the rules whenever its chunk is: a scene or a save never holds it.
            world.insert(e, RuntimeOnly);
            world.insert(e, Transform, { position: { x: d.origin[0] - base.x, y: d.origin[1] - base.y, z: d.origin[2] - base.z } });
            world.insert(e, MeshRenderer, {
                mesh: handle, material: d.material, lit: true, opaque: true, cullBackfaces: false, color: { r: 1, g: 1, b: 1, a: 1 },
            } as Partial<MeshRendererData>);
            const lodDef = getComponent('LODGroup');
            if (lodDef) {
                // The layer's distances as the screen sizes the engine compares, on the sphere it will measure: the one round
                // what this chunk actually holds, which for a chunk with one group of rocks in it is a small part of the chunk.
                const radius = lodSphereRadius([d.data, farHandle ? d.far : null]);
                world.insert(e, lodDef, {
                    lod1: farHandle, lod2: 0, lod3: 0, lod1Size: farHandle ? lodSizeAtDistance(radius, d.lodDistance) : 0, lod2Size: 0, lod3Size: 0,
                    cullSize: lodCullSizeWithin(radius, d.drawDistance), hysteresis: 0.1, enabled: true,
                });
            }
            world.setParent(e, parent);
            chunk.entities.push(e);
        }
        for (const p of chunk.objects) {
            const e = world.spawn(`${p.interactive} ${p.id}`);
            world.insert(e, RuntimeOnly);
            world.insert(e, Transform, {
                position: { x: p.x - base.x, y: p.y - base.y, z: p.z - base.z },
                rotation: orientation(p),
                scale: { x: p.scale, y: p.scale, z: p.scale },
            });
            if (assets && p.mesh) {
                world.insert(e, MeshRenderer, {
                    mesh: p.mesh, material: p.material, lit: true, opaque: true, color: { r: 1, g: 1, b: 1, a: 1 },
                } as Partial<MeshRendererData>);
            }
            world.insert(e, PlacedObject, { id: p.id, kind: p.interactive! });
            world.setParent(e, parent);
            chunk.entities.push(e);
            gens.objects_.set(p.id, e);
        }
    }

    private unplace(app: App, gens: WorldGens, chunk: PlacedChunk): void {
        if (chunk.grown) { plantGrowthOf(app).release(app, chunk.grown); chunk.grown = null; }
        const mine = new Set(chunk.entities);
        for (const p of chunk.objects) if (mine.has(gens.objects_.get(p.id)!)) gens.objects_.delete(p.id);
        for (const e of chunk.entities) if (app.world.valid(e)) app.world.despawn(e);
        const assets = app.hasResource(Assets) ? app.getResource(Assets) : null;
        for (const h of chunk.meshes) assets?.releaseBuiltMesh(h);
        chunk.entities.length = 0;
        chunk.meshes.length = 0;
        chunk.assets?.release();
        chunk.assets = undefined;
    }

    private retire(app: App, gens: WorldGens, built: BuiltWorld): void {
        built.retired = true;
        for (const stop of built.listeners.splice(0)) stop();
        const terrains = app.hasResource(TerrainsRes) ? app.getResource(TerrainsRes) : null;
        for (const id of built.levelled) this.unlevel(terrains, gens, built, id);
        built.levelling.clear();
        if (terrains && built.paint && terrains.paint_ === built.paint) {
            const remaining = [...gens.built_.values()].reverse().find(other => !other.retired && other.paint);
            terrains.setPaint(remaining?.paint ?? null);
        }
        if (terrains && built.pager && terrains.pager_ === built.pager) terrains.setPager(null);
        built.pager = null;
        built.paint = null;
        built.assets.release();
    }

    private drop(app: App, gens: WorldGens, entity: Entity): void {
        const built = gens.built_.get(entity);
        if (app.hasResource(ProceduralChunksRes)) {
            for (const l of built?.rules?.layers ?? []) dropLayer(app, entity, l.id);
            if (built?.faces && app.hasResource(PlanetRegistryRes)) app.getResource(PlanetRegistryRes).setPaint(entity, null);
        }
        if (built) this.retire(app, gens, built);
        gens.built_.delete(entity);
    }

    private sweep(app: App, gens: WorldGens): void {
        for (const entity of [...gens.built_.keys()]) {
            if (app.world.valid(entity) && app.world.has(entity, WorldGen) && app.world.has(entity, Transform)) continue;
            this.drop(app, gens, entity);
        }
    }
}

/** The meshes and materials a rule set's recipes name by path. */
function assetRefsOf(rules: WorldRules): { kind: 'mesh' | 'material'; ref: string }[] {
    const seen = new Map<string, { kind: 'mesh' | 'material'; ref: string }>();
    for (const r of rules.recipes) for (const m of [r.anchor, ...(r.members ?? [])]) {
        if (typeof m.mesh === 'string' && m.mesh) seen.set(`mesh:${m.mesh}`, { kind: 'mesh', ref: m.mesh });
        if (typeof m.material === 'string' && m.material) seen.set(`material:${m.material}`, { kind: 'material', ref: m.material });
    }
    return [...seen.values()];
}

/** What a placement leans toward: the ground's normal when it is aligned, else which way is up where it stands on a round world; null when it stands along +Y. */
function leanOf(p: Placement): [number, number, number] | null {
    return p.attach === 'align' ? p.normal : (p.up ?? null);
}

/** A placement of a face's plane as it stands on the planet: its place in the world, its normal and up in the world, and its face in its names. */
function onPlanet(p: Placement, face: PlanetFace): Placement {
    const at = face.world(p.x, p.y, p.z);
    return {
        ...p, id: `f${face.face}:${p.id}`, group: `f${face.face}:${p.group}`, x: at[0], y: at[1], z: at[2],
        normal: face.worldNormal(p.normal, p.x, p.z), up: face.frameAt(p.x, p.z).dir,
    };
}

/** A placement's turn: about the vertical, and leaning with the ground when it is aligned (or with up, on a round world). */
function orientation(p: Placement): { x: number; y: number; z: number; w: number } {
    const half = p.yaw / 2;
    const yawQ = { x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) };
    const lean = leanOf(p);
    if (!lean) return yawQ;
    // The turn that takes up to the normal, after the yaw.
    const [nx, ny, nz] = lean;
    const ax = nz, az = -nx, s = Math.hypot(ax, az);
    if (s < 1e-6) return yawQ;
    const angle = Math.acos(Math.min(Math.max(ny, -1), 1)) / 2;
    const tilt = { x: (ax / s) * Math.sin(angle), y: 0, z: (az / s) * Math.sin(angle), w: Math.cos(angle) };
    return {
        x: tilt.w * yawQ.x + tilt.x * yawQ.w + tilt.y * yawQ.z - tilt.z * yawQ.y,
        y: tilt.w * yawQ.y - tilt.x * yawQ.z + tilt.y * yawQ.w + tilt.z * yawQ.x,
        z: tilt.w * yawQ.z + tilt.x * yawQ.y - tilt.y * yawQ.x + tilt.z * yawQ.w,
        w: tilt.w * yawQ.w - tilt.x * yawQ.x - tilt.y * yawQ.y - tilt.z * yawQ.z,
    };
}

export const worldGenPlugin: Plugin = new WorldGenPlugin();