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.

81.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    terrainPlugin.ts
 * @brief   Ground: a source of heights drawn as a CDLOD quadtree of one shared patch, its heights read from pages on the GPU.
 *
 * @details The `Terrain` component says what the ground is: an area (a heightmap, or noise worn by rain) or ground without end (noise
 *          read anywhere). Its source (source.ts) answers the CPU, and the GPU draws it in pages (pages.ts): each quadtree node
 *          (quadtree.ts) round the eye is the same small patch, placed and sized by its instance, whose vertices the Terrain shader
 *          lifts from the node's page and slides onto the coarser grid toward the end of their level's range, so neighbouring levels
 *          meet without a crack. The nodes are ordinary MeshRenderers of one mesh and one material, which the renderer draws as instanced
 *          runs; pages are made a few a frame, coarse first, and a node whose page is not ready is drawn by an ancestor's.
 *
 *          What is collided with and what `heightAt` answers is the surface (surface.ts): the finest level's triangles, the same
 *          wherever the eye is. Collision is built in tiles round what moves on the ground (a moving 3D body, a character) and handed
 *          to the physics world as collision geometry.
 */
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { defineResource } from '../ecs/resource';
import {
    defineComponent, getComponent, Camera, MeshRenderer, Transform,
    type ComponentDef, type CameraData, type MeshRendererData, type TransformData,
} from '../ecs/component';
import { Assets } from '../asset/AssetPlugin';
import type { MaterialShaderSource } from '../asset/loaders/MaterialShaderAssetLoader';
import { platformLoadImagePixels } from '../platform/base';
import { decodeImagePixels } from '../asset/imageDecode';
import { decodePngData } from '../asset/pngData';
import { Material, MATERIAL_FORMAT_VERSION } from '../render/material';
import { BlendMode } from '../render/blend';
import { holdShaderWarmup } from '../render/shaderWarmup';
import { createTextureArrayFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';
import { getResourceManager, withdrawTextureContent } from '../wasm/resourceManager';
import { TextureContent } from '../wasm';
import { EditorView, editorViewpoint } from '../camera/EditorView';
import { log } from '../util/logger';
import { bakesOf } from '../runtime/bakes';
import type { Color, Entity } from '../types';
import { erosionJob, heightfieldFromPixels, HeightmapFormat, type Heightfield } from './heightfield';
import { findGroundPath, type ReachOptions, type ReachResult } from './reach';
import { paintWeights } from './paint';

export { paintWeights };
import { GroundEdit } from './groundEdit';
import { FieldSource, ModifiedSource, NoiseSource, type NoiseParams, type TerrainModifier, type TerrainSource } from './source';
import { fitRange, levelRange, nodeKey, parentOf, type QuadtreeParams, type TerrainNode } from './quadtree';
import { makePage, makePageJob, PageTable, PAGE_SIDE, PAGE_TEXELS, PATCH_CELLS, type PageImage, type Repaint } from './pages';
import { noiseProvider, ProviderSource, terrainProvider, terrainProvidersRevision, TerrainUnavailable, type TerrainProvider } from './provider';
import { buildPatchMesh } from './patch';
import { TerrainSurface, TILE_CELLS, type SurfaceTile } from './surface';
import { groundHeightAt, groundNormalAt, groundPaintAt, type GroundData } from './groundQuery';
import { collisionGeometryOf } from '../runtime/collisionGeometry';
import { chunksOf, ProceduralChunksRes } from '../residency/chunks';
import { movers } from './movers';
import { imagePixelsAt, loadLayersInto, releaseLayerArrays } from './layerArrays';
import { SurfaceCache, type SurfaceRequest } from './surfaceCache';
import { isMiniGame } from '../platform';
import { createPageAtlases } from './atlases';
import { parseTerrainTiles, TiledSource } from './tiles';
import { TiledGroundEdit } from './tiledGroundEdit';

/** The engine's own provider of ground without end: seeded noise of the world's position. */
export const NOISE_PROVIDER = 'estella:noise';

/** How far the ground goes: an area of its own size, or for ever. */
export const TerrainExtent = { Area: 0, Infinite: 1 } as const;

/** The fields of the `Terrain` component. @experimental */
export interface TerrainData {
    /** {@link TerrainExtent}: an area `sizeX` by `sizeZ`, or ground that goes on for ever (from a provider, read anywhere). */
    extent: number;
    /**
     * Ground read from a provider (without end, or an area with no heightmap, a window on it where the area stands): the provider
     * (`estella:noise`, the engine's noise, or one a game registers with registerTerrainProvider), the world it belongs to as the game
     * names it, and the generator version that world was made with.
     */
    provider: string;
    world: string;
    generatorVersion: number;
    /** A heightmap image, read as {@link heightmapFormat} says. Empty makes the ground from noise. */
    heightmap: number;
    /** A `.esterrain` (project path): the area's ground as tiles read where they are looked at, and an overview for the rest. Takes the heightmap's place. */
    tiles: string;
    /** How the heightmap holds its heights: a {@link HeightmapFormat}. */
    heightmapFormat: number;
    /** An image whose four channels are the weights of layers 1 to 4; empty paints by height and slope. */
    splatmap: number;
    /** An image whose four channels are the weights of layers 5 to 8, read with the first. */
    splatmap2: number;
    /** A picture laid over the whole of an area and mixed into the ground's colour by its alpha: a meadow's flowers, a map's regions, scorched ground. */
    colorMap: number;
    /** How much of the colour map is mixed in where its alpha is whole. */
    colorMapStrength: number;
    /** An image over the whole of an area whose red says how much of the sky reaches the ground there: a baked occlusion, for the folds no screen-space pass can see across. */
    occlusionMap: number;
    /** How much of the occlusion map is applied. */
    occlusionStrength: number;
    /**
     * The terrain layers (`.esterrainlayer` files, up to eight) the ground is drawn with, in the order the paint weighs them. With any,
     * the ground is drawn on the Terrain Layers shader (its material, if one is named, must be on it); with none, by the four colours.
     */
    layers: string[];
    /** A material on the Terrain shader. Empty draws the layer colours onto the ground. */
    material: number;
    /** An area's size along x and z, centred on its entity; for ground without end, the span `frequency` hills are spread over. */
    sizeX: number;
    sizeZ: number;
    /** World height of the highest ground. */
    height: number;
    /** The finest cell of the ground's mesh, in world units: what it is drawn at near the eye. */
    cellSize: number;
    /** Above 1 the finest cells reach further out before the ground coarsens. */
    detail: number;
    /** How far ground without end is drawn. */
    drawDistance: number;
    /**
     * Whether the ground's surface is baked into pages (a runtime virtual texture): from level {@link virtualTextureFrom} out, each node
     * of ground is drawn from its page of colour, roughness, normal and occlusion, made once, instead of reading every layer at every
     * pixel. Ground with layers only; steep ground and ground whose page is not made yet are drawn from the layers.
     */
    virtualTexture: boolean;
    /** The first level of the quadtree drawn from its baked surface: 0 the nearest ground too, 1 (the default) all but it. */
    virtualTextureFrom: number;
    /** Whether bodies collide with the ground; how far round each thing that moves on it the ground is built for collision; its layer and friction. */
    collision: boolean;
    collisionDistance: number;
    collisionLayer: number;
    friction: number;
    /** Noise ground: the seed, how many hills across, how many octaves, how rough, how ridged, and (an area's) how many samples. */
    seed: number;
    frequency: number;
    octaves: number;
    persistence: number;
    ridged: number;
    resolution: number;
    /** How far the noise is bent by noise of its own, 0 to 1: winding valleys and bent ridges instead of round hills. */
    warp: number;
    /** How much rain wears the ground, 0 to 4: an area is worn drop by drop (dirt where the water ran), ground without end by its noise. */
    erosion: number;
    /** Painting: how steep ground must be to turn to rock (0 flat, 1 sheer), and the heights, 0 to 1, where dirt and snow start. */
    rockSlope: number;
    dirtHeight: number;
    snowHeight: number;
    /** The four layers: grass, dirt, snow, rock. With no material these are the colours the ground is drawn in; a material has its own layers and tints. */
    layerColor0: Color;
    layerColor1: Color;
    layerColor2: Color;
    layerColor3: Color;
}

const rgb = (r: number, g: number, b: number): Color => ({ r, g, b, a: 1 });

/**
 * The ground. Presence is the opt-in; its children are the quadtree's nodes, drawn as instances of one patch.
 *
 * @experimental
 */
export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponent<TerrainData>('Terrain', {
    extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, tiles: '', heightmapFormat: HeightmapFormat.Grey, splatmap: 0, splatmap2: 0, colorMap: 0, colorMapStrength: 1, occlusionMap: 0, occlusionStrength: 1, layers: [] as string[], material: 0,
    // Lengths at the engine's reference of 100 units a metre (ecs/worldUnits.ts): a kilometre of ground 150 m high on 2 m cells in any project.
    sizeX: 100000, sizeZ: 100000, height: 15000, cellSize: 200, detail: 1, drawDistance: 400000, virtualTexture: false, virtualTextureFrom: 1,
    collision: true, collisionDistance: 6400, collisionLayer: 0, friction: 0.6,
    seed: 1, frequency: 3, octaves: 5, persistence: 0.5, ridged: 0.35, resolution: 257, warp: 0, erosion: 0,
    rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88,
    layerColor0: rgb(0.28, 0.46, 0.2), layerColor1: rgb(0.45, 0.36, 0.24), layerColor2: rgb(0.93, 0.95, 0.98), layerColor3: rgb(0.4, 0.38, 0.36),
}, {
    assetFields: [{ field: 'heightmap', type: 'texture' }, { field: 'splatmap', type: 'texture' }, { field: 'splatmap2', type: 'texture' }, { field: 'colorMap', type: 'texture' }, { field: 'occlusionMap', type: 'texture' }, { field: 'material', type: 'material' }],
    worldUnitFields: ['sizeX', 'sizeZ', 'height', 'cellSize', 'drawDistance', 'collisionDistance'],
    fields: {
        extent: { enum: [{ label: 'Area', value: TerrainExtent.Area }, { label: 'Infinite', value: TerrainExtent.Infinite }], category: 'Shape', tooltip: 'An area of its own size, from a heightmap or noise; or ground that goes on for ever, from noise read anywhere (the same seed is the same ground).' },
        provider: { category: 'Shape', tooltip: 'The generator the ground is made by, without end or (with no heightmap) in an area: estella:noise, or one the game registers. The same provider, world, seed and version are the same ground on every machine, and two areas side by side join.' },
        world: { category: 'Shape', tooltip: 'The world (a planet, a level) the ground belongs to, as the game names it; handed to the provider.' },
        generatorVersion: { min: 1, step: 1, category: 'Shape', tooltip: 'The generator version the world was made with. A version the provider no longer has fails the terrain rather than growing other ground under what was built.' },
        heightmap: { tooltip: 'A heightmap image, read as data (shipped as the PNG it is). Empty makes the ground from noise; a heightmap that cannot be read fails the terrain instead.', category: 'Shape', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        tiles: { category: 'Shape', tooltip: 'A .esterrain: the ground as tiles, read near where it is looked at and let go far from it, with a coarse overview for the rest. Takes the heightmap\'s place.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        heightmapFormat: { enum: [{ label: 'Grey (8 or 16 bit)', value: HeightmapFormat.Grey }, { label: 'Red + green (16 bit)', value: HeightmapFormat.RedGreen16 }], category: 'Shape', tooltip: 'How the heightmap holds its heights: grey (or red) at the depth of the file, 16 bits from a 16-bit PNG; or sixteen bits across red (high byte) and green (low byte) of an 8-bit image.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        splatmap: { tooltip: 'An image whose red, green, blue and alpha are the weights of grass, dirt, snow and rock.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        splatmap2: { tooltip: 'An image whose red, green, blue and alpha are the weights of layers 5 to 8.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        colorMap: { tooltip: 'A picture laid over the whole area and mixed into the ground\'s colour by its alpha. Its Use is Colour.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        colorMapStrength: { min: 0, max: 1, step: 0.01, slider: true, category: 'Layers', tooltip: 'How much of the colour map is mixed in where its alpha is whole.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        occlusionMap: { tooltip: 'An image over the whole area whose red says how much of the sky reaches the ground: white all of it, black none. It dims the light from all round, not the sun\'s. Its Use is Data.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        occlusionStrength: { min: 0, max: 1, step: 0.01, slider: true, category: 'Layers', tooltip: 'How much of the occlusion map is applied.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        layers: { tooltip: 'The terrain layers (.esterrainlayer, up to eight) the ground is drawn with, in the order the paint weighs them. Empty draws the four layer colours.', category: 'Layers' },
        material: { tooltip: 'A material on the Terrain shader (on Terrain Layers when the ground has layers). Empty uses the stock one.', category: 'Layers' },
        sizeX: { min: 1, category: 'Shape', tooltip: 'An area\'s size along x; for ground without end, the span its hills are spread over.' },
        sizeZ: { min: 1, category: 'Shape', tooltip: 'An area\'s size along z.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        height: { min: 0, category: 'Shape', tooltip: 'World height of the highest ground.' },
        cellSize: { min: 0.01, category: 'Detail', tooltip: 'The finest cell of the ground\'s mesh, in world units: what it is drawn at near the eye. Further off the cells double, level by level.' },
        detail: { min: 0.25, max: 8, step: 0.05, category: 'Detail', tooltip: 'Above 1 the finest cells reach further out before the ground coarsens.' },
        drawDistance: { min: 1, category: 'Detail', tooltip: 'How far ground without end is drawn.', shownWhen: { field: 'extent', values: [TerrainExtent.Infinite] } },
        virtualTexture: { label: 'Virtual Texture', category: 'Detail', tooltip: "Bake the ground's surface into pages, as Unreal's Runtime Virtual Texture does: from Virtual Texture From out, each node is drawn from its page (two texture reads) instead of every layer at every pixel. Ground with layers only; steep ground, and a node whose page is still being made, is drawn from the layers." },
        virtualTextureFrom: { min: 0, max: 15, step: 1, category: 'Detail', tooltip: "The first level of the ground drawn from its baked surface: 0 the nearest ground too, 1 all but it. The nearest is where the layers' own detail shows most." },
        collision: { category: 'Collision', tooltip: 'Whether 3D bodies and characters collide with the ground: the finest level\'s triangles, wherever the camera is.' },
        collisionDistance: { min: 1, category: 'Collision', tooltip: 'How far round each moving body and character the ground is built for collision, in world units.' },
        collisionLayer: { min: 0, max: 15, step: 1, category: 'Collision', advanced: true, tooltip: 'The collision layer the ground is in (0 to 15).' },
        friction: { min: 0, category: 'Collision', advanced: true, tooltip: 'How much the ground holds what slides on it.' },
        seed: { step: 1, category: 'Noise', tooltip: 'Another seed is another ground.' },
        frequency: { min: 0.1, max: 32, step: 0.1, category: 'Noise', tooltip: 'How many hills across the terrain (or across sizeX, for ground without end).' },
        octaves: { min: 1, max: 8, step: 1, category: 'Noise', tooltip: 'Layers of detail in the noise.' },
        persistence: { min: 0, max: 1, step: 0.01, category: 'Noise', tooltip: 'How much of its height each finer layer keeps. Lower is smoother.' },
        ridged: { min: 0, max: 1, step: 0.01, category: 'Noise', tooltip: '0 is rolling hills; 1 is sharp ridges.' },
        resolution: { min: 17, max: 2049, step: 1, category: 'Noise', tooltip: 'Samples along each side of an area\'s noise ground.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },
        warp: { min: 0, max: 1, step: 0.01, category: 'Noise', tooltip: 'How far the noise is bent by noise of its own: winding valleys and bent ridges instead of round hills.' },
        erosion: { min: 0, max: 4, step: 0.05, category: 'Shape', tooltip: 'How much rain wears the ground: an area (a heightmap\'s too) drop by drop, with dirt where the water ran; ground without end by its noise. 0 leaves it as made.' },
        rockSlope: { min: 0, max: 1, step: 0.01, category: 'Layers', tooltip: 'How steep ground must be to turn to rock. 0 is flat, 1 is sheer.' },
        dirtHeight: { min: 0, max: 1, step: 0.01, category: 'Layers', tooltip: 'The height, as a share of the terrain, where grass gives way to dirt.' },
        snowHeight: { min: 0, max: 1, step: 0.01, category: 'Layers', tooltip: 'The height, as a share of the terrain, where snow begins.' },
        layerColor0: { label: 'Grass', category: 'Layers' },
        layerColor1: { label: 'Dirt', category: 'Layers' },
        layerColor2: { label: 'Snow', category: 'Layers' },
        layerColor3: { label: 'Rock', category: 'Layers' },
    },
});

/** The side of the atlases the pages are kept in, in texels: 900 pages of 67 by 67. */
const ATLAS_SIZE = 2048;
/** The share of the atlas the nodes drawn may fill: the rest is for the coarser pages that stand in while a finer one is made. */
const PAGE_SHARE = 0.85;
/** The most layers a terrain draws: two paint atlases of four weights. */
const MAX_LAYERS = 8;
/** The chunk layer a terrain's collision is, and the key of one tile's piece of collision geometry. */
const collisionLayerOf = (entity: Entity): string => `terrain-collision:${entity}`;
const tileKey = (entity: Entity, tx: number, tz: number): string => `terrain:${entity}:${tx}:${tz}`;

/**
 * Makes the page of the square (x0, z0) to (x0 + size, z0 + size) of a terrain's own space somewhere else, painted as the terrain would
 * paint it; null when it cannot make this one.
 */
export type TerrainPager = (x0: number, z0: number, size: number) => Promise<PageImage> | null;

/** Pages asked at once of a provider that answers later. */
const PAGES_IN_FLIGHT = 16;
/** A baked surface page's side in texels (half on a minigame), and how the surface atlas holds its pages: 7 to a row, 9 rows. */
const SURFACE_TEXELS = 256;
const SURFACE_PER_ROW = 7;
const SURFACE_ROWS = 9;
/** Surface pages drawn a frame: each is two squares of the layers' whole shading, so a ground comes in over some frames, nearest first. */
const SURFACES_PER_FRAME = 2;
const NO_SURFACES: ReadonlyMap<string, number> = new Map();

/** What the plugin knows about one terrain it has built. */
interface Built {
    signature: string;
    data: TerrainData;
    source: TerrainSource | null;
    /** The triangles of the finest level, which queries and collision read. */
    surface: TerrainSurface | null;
    /** Bumped on every rebuild so an answer that arrives for an older one is thrown away. */
    epoch: number;
    loading: boolean;
    /** The erosion in hand, to stop if the terrain is rebuilt. */
    cancel: (() => void) | null;
    table: PageTable;
    heights: number;
    paint: number;
    mesh: number;
    instance: number;
    /** The nodes drawn now, by key, and spare ones to place again. */
    nodes: Map<string, Entity>;
    spare: Entity[];
    /** Pages wanted and not made yet, by key. */
    wanted: Map<string, TerrainNode>;
    /** The share of its detail's range the ground is drawn at, so its nodes fit the pages there are (see fitRange). */
    fit: number;
    fitSaid?: boolean;
    /** Pages asked of a provider that answers later, by key: the frame's budget is not spent waiting for them. */
    asked: Set<string>;
    /** The workers failed one of this terrain's pages: it makes its own. */
    pagerFailed?: boolean;
    /** A synchronous source's page paused inside sampling/painting, rather than blocking a whole frame. */
    pageWork?: { key: string; epoch: number; edits: number; job: Generator<number, PageImage, void>; image?: PageImage };
    pending: boolean;
    /** Why the ground could not be made, once it could not: nothing is drawn or answered for it. */
    failure: string | null;
    /** Bumped whenever modifiers change the ground under it: a page asked for before is thrown away when it lands. */
    edits: number;
    /** The atlas of layers 5 to 8's paint, with layers. */
    paint2: number;
    /** The layers packed (albedo, normal and mask arrays), what they were packed from, and whether a packing is in hand. */
    arrays: number[];
    packed: string;
    packing: boolean;
    /** Whether the colour map is on the material: so taking it off is written once, and ground without one is written nothing. */
    washed: boolean;
    /** The same of the occlusion map. */
    shaded: boolean;
    /** The baked surface (virtualTexture), whether the material reads it, and what makes its pages stale: a serial for each page of
     *  heights and paint made, by node, and a count bumped whenever the layers are packed again. */
    baked: SurfaceCache | null;
    surfaceOn: boolean;
    pageMade: Map<string, number>;
    pageSerial: number;
    surfaceGen: number;
}

/** Where a terrain's ground stands: still being made, ready, or failed (with why). */
export interface TerrainStatus { state: 'loading' | 'ready' | 'failed'; reason?: string }

export interface TerrainLoad { loading: number; cpuBytes: number; tiles: number; unsaved: number }

/** Run-time access to the ground: how high it is anywhere, for putting things on it. */
export class Terrains {
    /** @internal */ readonly built_ = new Map<Entity, Built>();
    /** @internal */ app_: App | null = null;

    /**
     * The world height of the ground at (x, z), or null where no terrain is. The terrain's own position is taken into account; its
     * rotation and scale are not (a terrain is laid flat at its own size).
     */
    heightAt(x: number, z: number): number | null {
        const world = this.app_?.world;
        if (!world) return null;
        for (const [entity, built] of this.built_) {
            if (!built.surface || !world.valid(entity)) continue;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const h = groundHeightAt(built.surface, t.worldPosition, x, z);
            if (h !== null) return h;
        }
        return null;
    }

    /**
     * The weights of the terrain's layers at (x, z), as the ground is painted there (four, or as many as it has layers), or null where no terrain is:
     * what a world's rules read as the fields `paint.<layer>`.
     */
    paintAt(x: number, z: number): readonly number[] | null {
        const world = this.app_?.world;
        if (!world) return null;
        for (const [entity, built] of this.built_) {
            const source = built.source, surface = built.surface;
            if (!source || !surface || !world.valid(entity)) continue;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const w = groundPaintAt(source, surface, t.worldPosition, x, z);
            if (w) return w;
        }
        return null;
    }

    /**
     * The world rectangle the terrains cover, `[minX, minZ, maxX, maxZ]`, or null where it has no end (a terrain of infinite extent) or there is none:
     * what a layer of chunks laid over the ground is held to, so it does not count a radius of empty world.
     */
    areaBounds(): [number, number, number, number] | null {
        const world = this.app_?.world;
        if (!world) return null;
        let out: [number, number, number, number] | null = null;
        for (const [entity, built] of this.built_) {
            if (!world.valid(entity)) continue;
            if (built.data.extent !== TerrainExtent.Area) return null;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const r: [number, number, number, number] = [
                t.worldPosition.x - built.data.sizeX / 2, t.worldPosition.z - built.data.sizeZ / 2,
                t.worldPosition.x + built.data.sizeX / 2, t.worldPosition.z + built.data.sizeZ / 2,
            ];
            out = out ? [Math.min(out[0], r[0]), Math.min(out[1], r[1]), Math.max(out[2], r[2]), Math.max(out[3], r[3])] : r;
        }
        return out;
    }

    /**
     * The ground as data a worker can rebuild it from, when it can be: one terrain, made, of a field or of noise (the engine's own noise provider
     * included, whose ground is its parameters), with nothing laid over it. Null otherwise (a game's provider, a modified ground, several terrains,
     * one still being made), when what is laid out over it must ask here.
     */
    groundData(): GroundData | null {
        const world = this.app_?.world;
        if (!world || this.built_.size !== 1 || this.modifiers_.size > 0) return null;
        const [entity, built] = [...this.built_][0]!;
        if (built.failure || built.loading || !built.surface || !built.source || !world.valid(entity)) return null;
        const t = world.tryGet(entity, Transform) as TransformData | null;
        if (!t) return null;
        const base = built.source instanceof ModifiedSource ? built.source.base : built.source;
        const origin = { x: t.worldPosition.x, y: t.worldPosition.y, z: t.worldPosition.z };
        if (base instanceof FieldSource) return { origin, cell: built.surface.cell, source: { kind: 'field', data: base.toData() } };
        if (base instanceof NoiseSource) return { origin, cell: built.surface.cell, source: { kind: 'noise', data: base.toData() } };
        // The engine's noise as a provider: the same function, read at the world's position and not the terrain's own.
        if (base instanceof ProviderSource && base.provider.id === NOISE_PROVIDER) {
            const d = built.data;
            const params: NoiseParams = {
                seed: d.seed, frequency: d.frequency, octaves: d.octaves, persistence: d.persistence, ridged: d.ridged, warp: d.warp, erosion: d.erosion,
                sizeX: d.sizeX, height: d.height, rockSlope: d.rockSlope, dirtHeight: d.dirtHeight, snowHeight: d.snowHeight,
            };
            return { origin, cell: built.surface.cell, source: { kind: 'noise', data: params }, shift: { x: origin.x, z: origin.z } };
        }
        return null;
    }

    /** The names of the terrain's layers, in the order `paintAt` weighs them: the layer files' names, or grass, dirt, snow and rock without any. */
    layerNames(): string[] {
        for (const built of this.built_.values()) {
            const layers = built.data.layers ?? [];
            if (layers.length > 0) return layers.map((ref, i) => (ref.split('/').pop() ?? '').replace(/\.[^.]*$/, '') || `layer${i}`);
        }
        return ['grass', 'dirt', 'snow', 'rock'];
    }

    /** The world height of the ground at (x, z) as it was made, under every modifier laid over it: what a plot is levelled from. */
    heightBeneathAt(x: number, z: number): number | null {
        const world = this.app_?.world;
        if (!world) return null;
        for (const [entity, built] of this.built_) {
            const source = built.source;
            if (!source || !world.valid(entity)) continue;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const base = source instanceof ModifiedSource ? source.base : source;
            const h = base.height(x - t.worldPosition.x, z - t.worldPosition.z);
            if (h !== null) return t.worldPosition.y + h;
        }
        return null;
    }

    /** Where the ground faces at (x, z) (a unit normal), or null where no terrain is. */
    normalAt(x: number, z: number): [number, number, number] | null {
        const world = this.app_?.world;
        if (!world) return null;
        for (const [entity, built] of this.built_) {
            const surface = built.surface;
            if (!surface || !world.valid(entity)) continue;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const n = groundNormalAt(surface, t.worldPosition, x, z);
            if (n) return n;
        }
        return null;
    }

    /**
     * Whether the ground at (x, z) is known: false while a terrain that covers it is still being made, or its provider has not answered
     * there yet; true where it is known, and where no terrain is (there is no ground to wait for).
     */
    groundKnownAt(x: number, z: number): boolean {
        const world = this.app_?.world;
        if (!world) return true;
        for (const [entity, built] of this.built_) {
            if (built.failure || !world.valid(entity)) continue;
            if (built.loading || !built.surface) return false;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const lx = x - t.worldPosition.x, lz = z - t.worldPosition.z;
            if (built.surface.covers(lx, lz)) return built.surface.height(lx, lz) !== null;
        }
        return true;
    }

    /**
     * Where a ray meets the ground, anywhere and whether or not anything collides there: exact against the same triangles collision and
     * `heightAt` use. `maxDistance` is along the direction. Null where it meets no terrain within it.
     */
    raycast(origin: { x: number; y: number; z: number }, direction: { x: number; y: number; z: number }, maxDistance: number):
        { distance: number; point: { x: number; y: number; z: number }; normal: { x: number; y: number; z: number }; entity: Entity } | null {
        const world = this.app_?.world;
        if (!world) return null;
        let best: { distance: number; point: { x: number; y: number; z: number }; normal: { x: number; y: number; z: number }; entity: Entity } | null = null;
        for (const [entity, built] of this.built_) {
            if (!built.surface || !world.valid(entity)) continue;
            const t = world.tryGet(entity, Transform) as TransformData | null;
            if (!t) continue;
            const at = t.worldPosition;
            const hit = built.surface.raycast(origin.x - at.x, origin.y - at.y, origin.z - at.z, direction.x, direction.y, direction.z,
                best ? best.distance : maxDistance);
            if (!hit) continue;
            best = {
                distance: hit.distance, entity,
                point: { x: hit.point[0] + at.x, y: hit.point[1] + at.y, z: hit.point[2] + at.z },
                normal: { x: hit.normal[0], y: hit.normal[1], z: hit.normal[2] },
            };
        }
        return best;
    }

    /**
     * A way across the ground from one place to another that a walker held to `maxSlope` can take, or why there is none: what a game
     * checks a spawn, a quest's goal or a village against. The ground is read where the search goes, modifiers and all, so nothing is
     * baked first; ground still being made is no ground yet (see `groundKnownAt`).
     */
    findPath(from: { x: number; z: number }, to: { x: number; z: number }, options?: ReachOptions): ReachResult {
        return findGroundPath(this, from.x, from.z, to.x, to.z, options);
    }

    /** Whether the ground under (x, z) is built for collision: what a game waits on before it drops something there. */
    collisionReadyAt(x: number, z: number): boolean {
        const app = this.app_;
        if (!app?.hasResource(ProceduralChunksRes)) return false;
        const chunks = app.getResource(ProceduralChunksRes);
        for (const [entity, built] of this.built_) {
            const t = app.world.valid(entity) ? app.world.tryGet(entity, Transform) as TransformData | null : null;
            if (!t || !built.surface?.covers(x - t.worldPosition.x, z - t.worldPosition.z)) continue;
            const state = chunks.stateAt(collisionLayerOf(entity), x, z);
            return state === 'ready' || state === 'stale';
        }
        return false;
    }

    /** Where a terrain's ground stands. A failed one draws and answers nothing, and says why. */
    status(entity: Entity): TerrainStatus | null {
        const built = this.built_.get(entity);
        if (!built) return null;
        if (built.failure) return { state: 'failed', reason: built.failure };
        return { state: built.loading || !built.source ? 'loading' : 'ready' };
    }

    load(): TerrainLoad {
        let loading = 0, cpuBytes = 0, tiles = 0, unsaved = 0;
        for (const built of this.built_.values()) {
            if (built.loading) loading++;
            const source = built.source instanceof ModifiedSource ? built.source.base : built.source;
            if (source instanceof TiledSource) {
                const s = source.stats();
                loading += s.reading;
                cpuBytes += s.bytes + source.overviewBytes;
                tiles += s.resident;
                unsaved += source.dirtyTiles().length;
                continue;
            }
            if (!(source instanceof FieldSource)) continue;
            const { a, b } = source.splats();
            cpuBytes += source.field.data.byteLength + (a?.pixels.byteLength ?? 0) + (b?.pixels.byteLength ?? 0);
        }
        return { loading, cpuBytes, tiles, unsaved };
    }

    /** @internal The modifiers laid over every terrain's ground, by id, in the order they were set. */
    readonly modifiers_ = new Map<string, TerrainModifier>();

    /**
     * Lays `modifier` over the ground (or replaces the one with its id): the drawn ground, its queries and its collision all follow it,
     * and only what it reaches is made again.
     */
    setModifier(modifier: TerrainModifier): void {
        const had = this.modifiers_.get(modifier.id);
        this.modifiers_.set(modifier.id, modifier);
        if (had) this.remake_(had.bounds);
        this.remake_(modifier.bounds);
    }

    /** Takes a modifier off the ground. */
    deleteModifier(id: string): void {
        const had = this.modifiers_.get(id);
        if (!had) return;
        this.modifiers_.delete(id);
        this.remake_(had.bounds);
    }

    /**
     * A handle to change the ground of the area terrain on `entity` with brushes (sculpt.ts), or null while it is being made, when it
     * is not an area of its own heights (infinite ground, a provider's) or when it is not a terrain.
     */
    groundEdit(entity: Entity): GroundEdit | TiledGroundEdit | null {
        const built = this.built_.get(entity), source = built?.source;
        if (built && source instanceof ModifiedSource && source.base instanceof TiledSource) {
            return new TiledGroundEdit({ remake: (b) => this.remake_(b) }, source.base, source, built.data.sizeX, built.data.sizeZ);
        }
        if (!built || !(source instanceof ModifiedSource) || !(source.base instanceof FieldSource)) return null;
        return new GroundEdit({ remake: (b) => this.remake_(b) }, source.base, source, built.data.sizeX, built.data.sizeZ);
    }

    /** @internal Makes again what the world square `b` reaches: its pages and its collision, and what stands on the ground. */
    remake_(b: readonly [number, number, number, number]): void {
        const app = this.app_;
        for (const [entity, built] of this.built_) {
            const source = built.source;
            if (!(source instanceof ModifiedSource)) continue;
            const o = source.origin, leaf = PATCH_CELLS * Math.max(built.data.cellSize, 1e-3);
            built.table.markStale((key) => {
                const [level, ix, iz] = key.split(':').map(Number) as [number, number, number];
                const size = leaf * 2 ** level, x0 = ix * size + o.x, z0 = iz * size + o.z;
                return x0 <= b[2] && x0 + size >= b[0] && z0 <= b[3] && z0 + size >= b[1];
            });
            built.edits++;
            if (app?.hasResource(ProceduralChunksRes)) app.getResource(ProceduralChunksRes).invalidate(collisionLayerOf(entity), b[0], b[1], b[2], b[3]);
        }
        this.revision_++;
    }

    /** @internal What has the last word on the ground's paint, in world space (a world's biomes), if anything does. */
    paint_: Repaint | null = null;

    /**
     * Gives the ground's paint to `paint` (or back to the terrains, with null): at each sample, in world space, it is handed the paint
     * the terrain made and returns the paint to draw. The pages already made are made again.
     */
    setPaint(paint: Repaint | null): void {
        if (paint === this.paint_) return;
        this.paint_ = paint;
        this.repaint();
    }

    /** @internal Who makes the ground's pages off the main thread, if anyone does. */
    pager_: TerrainPager | null = null;

    /**
     * Hands the making of pages to `pager` (or back to the terrain, with null). A world that paints the ground has the plan the paint is
     * read from on its workers already, and a page painted there costs the frame nothing; painted here it is tens of milliseconds a page.
     * The pager answers null for a page it cannot make (its plan is no longer the ground's), and the terrain makes that one itself.
     */
    setPager(pager: TerrainPager | null): void {
        this.pager_ = pager;
    }

    /** Makes every page again, for a paint that changed what it answers. */
    repaint(): void {
        for (const built of this.built_.values()) {
            built.edits++;
            built.pageWork = undefined;
            built.table.markStale(() => true);
        }
    }

    /** @internal Bumped whenever a terrain's ground changes, so what stands on it knows to stand again. */
    revision_ = 0;

    /** Whether any terrain is still reading its images or wearing its ground: its heights are not known yet. */
    get loading(): boolean {
        for (const b of this.built_.values()) if (b.loading) return true;
        return false;
    }

    /** A ground is not drawn yet, or its layers are still being packed: what it draws with has not all been asked for. */
    get preparing(): boolean { return this.toPrepare > 0; }

    /** How much of that is left: the pages still wanted, and one for each ground not yet drawn or still packing its layers. */
    get toPrepare(): number {
        let n = 0;
        for (const b of this.built_.values()) {
            if (b.failure) continue;
            n += b.wanted.size + (b.loading || !b.instance || b.packing ? 1 : 0);
        }
        return n;
    }

    /** How many pages every terrain still wants made for what is in view. */
    get pending(): number {
        let n = 0;
        for (const b of this.built_.values()) n += b.wanted.size + (b.loading ? 1 : 0);
        return n;
    }
}

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

/** What, changed, rebuilds the ground: everything but the colours, the colour map, the detail and the collision, which are read each frame. */
function signatureOf(data: TerrainData, at: { x: number; z: number }): string {
    const { layerColor0: _a, layerColor1: _b, layerColor2: _c, layerColor3: _d, detail: _e, drawDistance: _f, virtualTexture: _vt, virtualTextureFrom: _vtf,
        collision: _g, collisionDistance: _h, collisionLayer: _i, friction: _j, colorMap: _k, colorMapStrength: _l, occlusionMap: _m, occlusionStrength: _n, layers, ...rest } = data;
    // Which layers are only what the arrays are packed from; whether there are any is which shader the ground is drawn with.
    const shape = { ...rest, layered: (layers?.length ?? 0) > 0 };
    // Ground read from a provider is the world's where the terrain stands: moved, it is read again; and a game's own provider is read
    // again when one is registered under its name.
    const fromProvider = data.extent === TerrainExtent.Infinite || (!data.heightmap && !data.tiles);
    const where = fromProvider ? `@${at.x},${at.z}` : '';
    const late = fromProvider && data.provider !== NOISE_PROVIDER ? `#${terrainProvidersRevision()}` : '';
    return `${JSON.stringify(shape)}${where}${late}`;
}

async function tiledSourceOf(app: App, data: TerrainData): Promise<TiledSource> {
    const assets = app.getResource(Assets);
    const doc = parseTerrainTiles(JSON.parse(await assets.fetchText(data.tiles)), data.tiles);
    const read = (path: string) => imagePixelsAt(app, path);
    const [overview, s1, s2] = await Promise.all([read(doc.overview), doc.overviewSplat ? read(doc.overviewSplat) : null, doc.overviewSplat2 ? read(doc.overviewSplat2) : null]);
    if (!overview) throw new TerrainUnavailable(`the overview of ${data.tiles} (${doc.overview}) could not be read`);
    const field = heightfieldFromPixels(overview.width, overview.height, overview.pixels, doc.format, overview.wide);
    const splat = (s: typeof s1) => s && { width: s.width, height: s.height, pixels: s.pixels };
    return new TiledSource(doc, data, field, splat(s1), splat(s2), read);
}

/** The provider a terrain names, or why it cannot have it. */
function providerOf(data: TerrainData): TerrainProvider {
    const provider = data.provider === NOISE_PROVIDER ? noiseProvider(() => data) : terrainProvider(data.provider);
    if (!provider) throw new TerrainUnavailable(`no terrain provider ${data.provider} is registered`);
    return provider;
}

/** The ground's paint by height (over the provider's range) and slope, for a provider that does not paint. */
function paintBy(provider: TerrainProvider, data: TerrainData): (h: number, ny: number) => [number, number, number, number] {
    const [lo, hi] = provider.range(data.seed, data.generatorVersion);
    return (h, ny) => paintWeights((h - lo) / Math.max(hi - lo, 1e-6), ny, data);
}

/** An area's window on its provider's ground: `resolution` samples along its longer side, over the provider's range. */
async function windowOf(provider: TerrainProvider, data: TerrainData, cx: number, cz: number, range: [number, number]): Promise<Heightfield> {
    const res = Math.min(2049, Math.max(17, Math.floor(data.resolution)));
    const spacing = Math.max(data.sizeX, data.sizeZ) / (res - 1);
    const nx = Math.max(2, Math.round(data.sizeX / spacing) + 1), nz = Math.max(2, Math.round(data.sizeZ / spacing) + 1);
    const count = Math.max(nx, nz);
    const got = await provider.sample({
        world: data.world, seed: data.seed, version: data.generatorVersion, x0: cx - data.sizeX / 2, z0: cz - data.sizeZ / 2, spacing, count,
    });
    const span = Math.max(range[1] - range[0], 1e-6);
    const out = new Float32Array(nx * nz);
    for (let j = 0; j < nz; j++) for (let i = 0; i < nx; i++) out[j * nx + i] = (got.heights[j * count + i]! - range[0]) / span;
    return { width: nx, height: nz, data: out };
}

export class TerrainPlugin implements Plugin {
    name = 'terrain';
    /** No terrain, no work; the frame after the last one goes still runs its sweep. */
    readonly activeWhen = [Terrain];

    /** The stock materials a terrain with none of its own is an instance of: without layers, and with. */
    private stock_ = 0;
    private stockLayers_ = 0;
    /** The Terrain Surface Bake shader (a virtual texture's pages are drawn through it), compiled once, and whether it is being loaded. */
    private bakeShader_ = 0;
    private bakeShaderAsked_ = false;
    /** Bumped when an asset is edited and saved, so layers are packed again; and the listener that bumps it. */
    private layerEdits_ = 0;
    private watching_: (() => void) | null = null;

    build(app: App): void {
        const terrains = new Terrains();
        terrains.app_ = app;
        app.insertResource(TerrainsRes, terrains);
        holdShaderWarmup(app, () => (app.hasResource(Assets) ? terrains.toPrepare : 0));

        app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
            // What the ground IS needs no renderer: a server or a test without one still makes the source and answers from it.
            const rendering = app.hasResource(Assets);
            this.sweep(app, terrains);
            for (const entity of app.world.getEntitiesWithComponents([Terrain, Transform])) {
                const data = app.world.get(entity, Terrain) as TerrainData;
                const signature = signatureOf(data, (app.world.get(entity, Transform) as TransformData).worldPosition);
                let built = terrains.built_.get(entity);
                if (!built || built.signature !== signature) {
                    if (built) this.destroy(app, built);
                    built = {
                        signature, data: { ...data }, source: null, surface: null, epoch: (built?.epoch ?? 0) + 1, loading: true, cancel: null,
                        table: new PageTable(ATLAS_SIZE), heights: 0, paint: 0, mesh: 0, instance: 0,
                        nodes: new Map(), spare: [], wanted: new Map(), fit: 1, asked: new Set(), pending: false, failure: null, edits: 0,
                        paint2: 0, arrays: [], packed: '', packing: false, washed: false, shaded: false,
                        baked: null, surfaceOn: false, pageMade: new Map(), pageSerial: 0, surfaceGen: 0,
                    };
                    terrains.built_.set(entity, built);
                    void this.load(app, entity, built);
                    continue;
                }
                built.data = { ...data };
                // Modifiers are the world's: a terrain moved stands under them somewhere else, so what they reached is made again.
                if (built.source instanceof ModifiedSource) {
                    const at = (app.world.get(entity, Transform) as TransformData).worldPosition, o = built.source.origin;
                    if (at.x !== o.x || at.y !== o.y || at.z !== o.z) {
                        built.source.origin = { x: at.x, y: at.y, z: at.z };
                        for (const m of terrains.modifiers_.values()) terrains.remake_(m.bounds);
                    }
                }
                this.collide(app, entity, built);
                if (built.loading || !built.source || !rendering) continue;
                if (!built.instance) {
                    if (!built.pending) void this.prepare(app, built);
                    continue;
                }
                this.pack(app, built);
                this.draw(app, entity, built);
            }
        }, { name: 'TerrainSystem' }));
    }

    cleanup(app?: App): void {
        if (!app?.hasResource(TerrainsRes)) return;
        const terrains = app.getResource(TerrainsRes);
        for (const [entity, built] of terrains.built_) {
            if (app.hasResource(ProceduralChunksRes)) app.getResource(ProceduralChunksRes).remove(collisionLayerOf(entity));
            this.destroy(app, built);
        }
        terrains.built_.clear();
        if (this.stock_) Material.release(this.stock_);
        this.stock_ = 0;
        if (this.stockLayers_) Material.release(this.stockLayers_);
        this.stockLayers_ = 0;
        this.watching_?.();
        this.watching_ = null;
    }

    /** Reads the images the terrain names (or makes its noise, and wears it), and makes its source. */
    private async load(app: App, entity: Entity, built: Built): Promise<void> {
        const epoch = built.epoch;
        const data = built.data;
        try {
            const t = app.world.get(entity, Transform) as TransformData;
            if (data.extent === TerrainExtent.Infinite) {
                const provider = providerOf(data);
                built.source = new ProviderSource(provider, data.world, data.seed, data.generatorVersion, t.worldPosition.x, t.worldPosition.z,
                    Math.max(data.cellSize, 1e-3), paintBy(provider, data));
            } else if (data.tiles) {
                built.source = await tiledSourceOf(app, data);
                if (built.epoch !== epoch || !app.world.valid(entity)) return;
            } else {
                // A heightmap named and not read is a failure: a world built on that ground must not quietly get other ground.
                const height = await this.pixelsOf(app, data.heightmap);
                if (data.heightmap && !height) throw new TerrainUnavailable(`the heightmap (texture ${data.heightmap}) could not be read: it is read as data, so it must ship as the PNG it is (not compressed)`);
                const splat = await this.pixelsOf(app, data.splatmap);
                const splat2 = await this.pixelsOf(app, data.splatmap2);
                if (built.epoch !== epoch || !app.world.valid(entity)) return;
                // Without a heightmap an area is a window on its provider's ground, read where it stands in the world: two areas side by
                // side are one ground, and the area is the same ground the provider gives without end.
                let range: [number, number] = [0, data.height];
                let made: Heightfield;
                if (height) {
                    made = heightfieldFromPixels(height.width, height.height, height.pixels, data.heightmapFormat, height.wide);
                } else {
                    const provider = providerOf({ ...data, erosion: 0 });
                    const checked = new ProviderSource(provider, data.world, data.seed, data.generatorVersion, 0, 0, 1, paintBy(provider, data));
                    range = [checked.minHeight, checked.maxHeight];
                    made = await windowOf(provider, data, t.worldPosition.x, t.worldPosition.z, range);
                    if (built.epoch !== epoch || !app.world.valid(entity)) return;
                }
                let field = made, flow: Float32Array | null = null;
                if (data.erosion > 0) {
                    // Rain over a big field is seconds of work: it is spread over frames, and shown while it runs.
                    const job = bakesOf(app).run('Eroding the terrain',
                        erosionJob(made, { amount: data.erosion, seed: data.seed, sizeX: data.sizeX, sizeZ: data.sizeZ, height: range[1] - range[0] }));
                    built.cancel = job.cancel;
                    const worn = await job.done;
                    built.cancel = null;
                    if (built.epoch !== epoch || !app.world.valid(entity)) return;
                    field = worn.field;
                    flow = worn.flow;
                }
                built.source = new FieldSource(field, data, splat, flow, range, splat2);
            }
            // The modifiers set on the ground (a plot levelled, a bed cut) are laid over it, for the pages, the queries and collision alike.
            const terrains = app.getResource(TerrainsRes);
            built.source = new ModifiedSource(built.source, () => terrains.modifiers_.values(), t.worldPosition, Math.max(data.cellSize, 1e-3));
            built.surface = new TerrainSurface(built.source, Math.max(data.cellSize, 1e-3));
            app.getResource(TerrainsRes).revision_++;
        } catch (e) {
            if (built.epoch === epoch) built.failure = e instanceof Error ? e.message : String(e);
            log.error('terrain', 'building the terrain failed', e);
        } finally {
            if (built.epoch === epoch) built.loading = false;
        }
    }

    private async pixelsOf(app: App, handle: number): Promise<{ width: number; height: number; pixels: Uint8Array; wide?: Uint16Array } | null> {
        if (!handle || !app.hasResource(Assets)) return null;
        const path = app.getResource(Assets).pathForHandle('texture', handle);
        if (!path) { log.warn('terrain', `no source image is known for texture ${handle}`); return null; }
        return this.pixelsAt(app, path);
    }

    /** An image file's pixels exactly as stored (no premultiply, no colour conversion), by its project path or reference. */
    private pixelsAt(app: App, path: string): ReturnType<typeof imagePixelsAt> {
        return imagePixelsAt(app, path);
    }

    /** The stock material: the Terrain shader, compiled once. */
    private async stock(app: App): Promise<number> {
        if (this.stock_) return this.stock_;
        const source = await app.getResource(Assets).load<MaterialShaderSource>('material-shader', 'builtin:terrain');
        const shader = source.compile([]);
        if (this.stock_) return this.stock_;
        this.stock_ = Material.createFromAsset({
            version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:terrain', blendMode: BlendMode.None,
            depthTest: true, depthWrite: true, cull: 0, properties: {},
        }, shader);
        return this.stock_;
    }

    /** The stock material for ground with layers: the Terrain Layers shader, compiled once. */
    private async stockLayers(app: App): Promise<number> {
        if (this.stockLayers_) return this.stockLayers_;
        const source = await app.getResource(Assets).load<MaterialShaderSource>('material-shader', 'builtin:terrain-layers');
        const shader = source.compile([]);
        if (this.stockLayers_) return this.stockLayers_;
        this.stockLayers_ = Material.createFromAsset({
            version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:terrain-layers', blendMode: BlendMode.None,
            depthTest: true, depthWrite: true, cull: 0, properties: {},
        }, shader);
        return this.stockLayers_;
    }

    /**
     * Packs the terrain's layers into the arrays its material reads, when what they name changed (or a layer file was saved): the
     * ground keeps the arrays it has until the new ones are made.
     */
    private pack(app: App, built: Built): void {
        const refs = built.data.layers ?? [];
        if (refs.length === 0 || built.packing) return;
        const assets = app.getResource(Assets);
        const wanted = `${JSON.stringify(refs)}#${this.layerEdits_}`;
        if (wanted === built.packed) return;
        built.packing = true;
        const epoch = built.epoch;
        if (!this.watching_) {
            // A layer file edited and saved, or a texture it names, is packed again.
            this.watching_ = assets.onInvalidate(() => { this.layerEdits_++; });
        }
        void (async () => {
            try {
                const still = (): boolean => built.epoch === epoch && !!built.instance;
                const arrays = await loadLayersInto(app, built.instance, refs, MAX_LAYERS, still);
                if (!still()) { if (arrays) releaseLayerArrays(arrays); return; }
                if (!arrays) {
                    log.warn('terrain', 'the engine refused the terrain layers\' texture arrays');
                    return;
                }
                releaseLayerArrays(built.arrays);
                built.arrays = arrays;
                built.surfaceGen++;
            } catch (e) {
                log.error('terrain', 'packing the terrain layers failed', e);
            } finally {
                built.packed = wanted;
                built.packing = false;
            }
        })();
    }

    /** Makes what the ground is drawn with: the patch, the atlases and an instance of its material. */
    private async prepare(app: App, built: Built): Promise<void> {
        built.pending = true;
        const epoch = built.epoch;
        try {
            const layered = (built.data.layers?.length ?? 0) > 0;
            const material = built.data.material || (layered ? await this.stockLayers(app) : await this.stock(app));
            if (built.epoch !== epoch) return;
            const assets = app.getResource(Assets);
            built.mesh = assets.createMesh(buildPatchMesh(PATCH_CELLS));
            [built.heights = 0, built.paint = 0, built.paint2 = 0] = createPageAtlases(app, layered ? 3 : 2, ATLAS_SIZE, () => built.table.clear());
            built.instance = Material.createInstance(material);
            if (!built.mesh || !built.heights || !built.paint || !built.instance) {
                log.warn('terrain', 'the engine refused the terrain\'s mesh, atlases or material');
                return;
            }
            const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
            set('u_heightPages', Material.tex(built.heights));
            set('u_paintPages', Material.tex(built.paint));
            if (built.paint2) {
                set('u_paintPages2', Material.tex(built.paint2));
                // Until the layers are packed the ground is one plain layer: an array left unset reads black on some devices.
                const one = (rgba: number[], srgb: boolean): number => createTextureArrayFromPixels(app.wasmModule,
                    { width: 1, height: 1, layers: [new Uint8Array(rgba)] }, TextureContent.Retained, { filterMode: 'linear', wrapMode: 'repeat', srgb });
                built.arrays = [one([150, 150, 140, 255], true), one([128, 128, 255, 255], false), one([255, 230, 128, 255], false)];
                set('u_albedoLayers', Material.tex(built.arrays[0]!));
                set('u_normalLayers', Material.tex(built.arrays[1]!));
                set('u_maskLayers', Material.tex(built.arrays[2]!));
                set('u_layerCount', 1);
            }
            set('u_terrainPages', 1);
            set('u_atlasTexels', ATLAS_SIZE);
            set('u_pageTexels', PAGE_TEXELS);
            set('u_patchCells', PATCH_CELLS);
        } catch (e) {
            log.error('terrain', 'preparing the terrain failed', e);
        } finally {
            built.pending = false;
        }
    }

    /**
     * The terrain's collision as a layer of procedural chunks: a tile within `collisionDistance` of every moving 3D body and character,
     * made when one comes near, let go when none is, and made again (the old tile kept till then) when the ground changes.
     */
    private collide(app: App, entity: Entity, built: Built): void {
        const id = collisionLayerOf(entity);
        const d = built.data;
        if (!d.collision || built.failure) {
            if (app.hasResource(ProceduralChunksRes)) app.getResource(ProceduralChunksRes).remove(id);
            return;
        }
        const chunks = chunksOf(app);
        const at = (app.world.get(entity, Transform) as TransformData).worldPosition;
        const cell = Math.max(d.cellSize, 1e-3), span = TILE_CELLS * cell;
        const bounds = built.source?.bounds ?? (d.extent === TerrainExtent.Area ? [-d.sizeX / 2, -d.sizeZ / 2, d.sizeX / 2, d.sizeZ / 2] : null);
        const geometry = collisionGeometryOf(app);
        chunks.set<{ key: string; tile: SurfaceTile }>(id, {
            label: 'Building the ground\'s collision',
            originX: at.x, originZ: at.z, sizeX: span, sizeZ: span,
            extent: bounds && [Math.floor(bounds[0] / span), Math.floor(bounds[1] / span), Math.ceil(bounds[2] / span), Math.ceil(bounds[3] / span)],
            loadRadius: Math.max(d.collisionDistance, 0),
            unloadRadius: Math.max(d.collisionDistance, 0) + span,
            // The ground (rebuilt under a new epoch), where it stands, and the layer and friction its tiles were made with.
            generation: `${built.epoch}:${at.x}:${at.y}:${at.z}:${d.collisionLayer}:${d.friction}`,
            sources: () => movers(app),
            make: (tx, tz) => {
                // The ground is not known yet (still loading, or a provider still answering): asked again next frame.
                const tile = built.surface?.tile(tx, tz);
                return tile ? { key: tileKey(entity, tx, tz), tile } : null;
            },
            publish: (_tx, _tz, { key, tile }) => {
                geometry.set(key, {
                    owner: entity, origin: [at.x + tile.x0, at.y, at.z + tile.z0], positions: tile.positions, indices: tile.indices,
                    friction: d.friction, restitution: 0, layer: d.collisionLayer,
                });
            },
            release: (_tx, _tz, { key }) => geometry.delete(key),
        });
    }

    private eye(app: App, t: TransformData): [number, number, number] | null {
        if (app.hasResource(EditorView)) {
            const e = editorViewpoint(app.getResource(EditorView));
            if (e) return [e.x - t.worldPosition.x, e.y - t.worldPosition.y, e.z - t.worldPosition.z];
        }
        for (const entity of app.world.getEntitiesWithComponents([Camera, Transform])) {
            if (!(app.world.get(entity, Camera) as CameraData).isActive) continue;
            const c = app.world.get(entity, Transform) as TransformData;
            return [c.worldPosition.x - t.worldPosition.x, c.worldPosition.y - t.worldPosition.y, c.worldPosition.z - t.worldPosition.z];
        }
        return null;
    }

    /** The quadtree's cut for this terrain: leaf nodes a patch of the finest cells, ranges doubling, enough levels to cover it. */
    private treeOf(built: Built, source: TerrainSource, share = 1): QuadtreeParams {
        const d = built.data;
        const leafSize = PATCH_CELLS * Math.max(d.cellSize, 1e-3);
        const range0 = leafSize * 2.5 * Math.max(d.detail, 0.25) * share;
        const reach = source.bounds ? Math.max(source.bounds[2] - source.bounds[0], source.bounds[3] - source.bounds[1]) : Math.max(d.drawDistance, leafSize);
        let levels = 1;
        while (levels < 16 && (source.bounds ? leafSize * 2 ** (levels - 1) < reach : levelRange({ range0 }, levels - 1) < reach)) levels++;
        return { leafSize, levels, range0, bounds: source.bounds, minHeight: source.minHeight, maxHeight: source.maxHeight };
    }

    /** Chooses the nodes for the eye, makes the pages they want within the budget, and places the nodes. */
    private draw(app: App, entity: Entity, built: Built): void {
        const source = built.source!;
        const t = app.world.get(entity, Transform) as TransformData;
        const eye = this.eye(app, t);
        const eyeAt = eye ?? [0, source.maxHeight, 0];
        const table = built.table;
        // The pages are a budget (see fitRange): a `detail` that asks for more than the atlas holds is drawn at the share of it that fits.
        const fitted = fitRange((share) => this.treeOf(built, source, share), eyeAt[0], eyeAt[1], eyeAt[2], Math.floor(table.capacity * PAGE_SHARE), built.fit);
        if (fitted.share < 1 && !built.fitSaid) {
            built.fitSaid = true;
            log.warn('terrain', `detail ${built.data.detail} asks for more pages than the ${table.capacity} there are; the ground is drawn at ${(built.data.detail * fitted.share).toFixed(2)}`);
        }
        built.fit = fitted.share;
        const tree = this.treeOf(built, source, fitted.share);
        const chosen = fitted.nodes;
        table.tick();

        // Each node is drawn by its own page, or by its nearest ancestor that has one; a node under an ancestor drawn instead is not.
        built.wanted.clear();
        const drawn = new Map<string, TerrainNode>();
        const covered = new Set<string>();
        for (const node of chosen) {
            let n: TerrainNode | null = node;
            const own = nodeKey(node.level, node.ix, node.iz);
            if (!table.get(own) || table.isStale(own)) built.wanted.set(own, node);
            while (n && !table.get(nodeKey(n.level, n.ix, n.iz))) {
                n = n.level + 1 < tree.levels ? parentOf(n, tree.leafSize) : null;
                if (n && !table.get(nodeKey(n.level, n.ix, n.iz))) built.wanted.set(nodeKey(n.level, n.ix, n.iz), n);
            }
            if (!n) continue;
            const key = nodeKey(n.level, n.ix, n.iz);
            // An ancestor drawn in place of a missing page and out of date is made again too.
            if (n !== node && table.isStale(key)) built.wanted.set(key, n);
            if (n !== node) covered.add(key);
            drawn.set(key, n);
        }
        for (const [key, n] of drawn) {
            // A node whose ancestor is drawn in its place is left out: the ancestor covers it.
            for (let up = n; up.level + 1 < tree.levels;) {
                up = parentOf(up, tree.leafSize);
                if (covered.has(nodeKey(up.level, up.ix, up.iz))) { drawn.delete(key); break; }
            }
        }
        // What is drawn this frame is in use before any page is made: a page made now takes the slot of the least recently drawn,
        // and a page chosen above and not yet marked was that one, gone by the time its node was placed.
        for (const key of drawn.keys()) table.touch(key);
        this.makePages(app, built, source, eyeAt, t.worldPosition);

        const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
        set('u_heightRange', { x: source.minHeight, y: Math.max(source.maxHeight - source.minHeight, 1e-6) });
        set('u_lodRange0', tree.range0);
        set('u_terrainOrigin', { x: t.worldPosition.x, y: t.worldPosition.y, z: t.worldPosition.z, w: 0 });
        // Not the pass's camera: a shadow is drawn from the light, and its ground must be the one the eye sees.
        set('u_terrainEye', { x: eyeAt[0] + t.worldPosition.x, y: eyeAt[1] + t.worldPosition.y, z: eyeAt[2] + t.worldPosition.z, w: 1 });
        const b = source.bounds;
        set('u_terrainBounds', b ? { x: b[0], y: b[1], z: b[2], w: b[3] } : { x: -1e9, y: -1e9, z: 1e9, w: 1e9 });
        const wash = b && built.data.colorMap ? built.data.colorMapStrength : 0;
        const shade = b && built.data.occlusionMap ? built.data.occlusionStrength : 0;
        // Both maps lie over the whole area.
        if ((wash > 0 || shade > 0) && b) set('u_colorMapArea', { x: b[0], y: b[1], z: b[2] - b[0], w: b[3] - b[1] });
        if (wash > 0) set('u_colorMap', Material.tex(built.data.colorMap));
        if (shade > 0) set('u_occlusionMap', Material.tex(built.data.occlusionMap));
        if (shade > 0 || built.shaded) set('u_occlusionStrength', shade);
        built.shaded = shade > 0;
        if (wash > 0 || built.washed) set('u_colorMapStrength', wash);
        built.washed = wash > 0;
        // The four layer colours are the Terrain shader's; ground with layers is drawn by another, which has no such params.
        if (!built.data.material && (built.data.layers?.length ?? 0) === 0) {
            const d = built.data;
            for (const [i, c] of [d.layerColor0, d.layerColor1, d.layerColor2, d.layerColor3].entries()) set(`u_tint${i}`, { x: c.r, y: c.g, z: c.b, w: c.a });
        }
        this.place(app, entity, built, drawn, this.surfaces(app, built, drawn, eyeAt, wash, shade));
    }

    /** The Terrain Surface Bake shader's handle, once it is compiled; 0 until then. */
    private bakeShader(app: App): number {
        if (this.bakeShader_ || this.bakeShaderAsked_) return this.bakeShader_;
        this.bakeShaderAsked_ = true;
        void app.getResource(Assets).load<MaterialShaderSource>('material-shader', 'builtin:terrain-surface-bake')
            .then((source) => { this.bakeShader_ = source.compile([]); })
            .catch((e) => log.warn('terrain', 'the Terrain Surface Bake shader could not be loaded; virtual textures are drawn from their layers', e));
        return 0;
    }

    /**
     * The baked surface (virtualTexture): asks for the pages of the nodes drawn from its first level out, nearest first, and hands back
     * the slot of each whose page is ready. Ground without layers, or with the setting off, reads none.
     */
    private surfaces(app: App, built: Built, drawn: Map<string, TerrainNode>, eye: [number, number, number], wash: number, shade: number): ReadonlyMap<string, number> {
        const d = built.data;
        const on = d.virtualTexture && (d.layers?.length ?? 0) > 0 && built.packed !== '' && !built.baked?.failed;
        const shader = on ? this.bakeShader(app) : 0;
        if (!on || !shader) {
            if (!on && built.baked) { bakesOf(app).clear(built.baked); built.baked.release(); built.baked = null; }
            if (built.surfaceOn) Material.setUniform(built.instance, 'u_surfaceOn', 0);
            built.surfaceOn = false;
            return NO_SURFACES;
        }
        if (!built.baked) {
            const texels = isMiniGame() ? SURFACE_TEXELS / 2 : SURFACE_TEXELS;
            built.baked = new SurfaceCache(texels, SURFACE_PER_ROW, SURFACE_ROWS);
        }
        const cache = built.baked;
        const texture = cache.texture();
        if (!texture) return NO_SURFACES;
        if (!built.surfaceOn) {
            const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
            set('u_surfacePages', Material.tex(texture));
            set('u_surfaceTexels', cache.texels);
            set('u_surfacePerRow', cache.perRow);
            set('u_surfaceAtlas', { x: cache.width, y: cache.height, z: (cache.texels + 2) / cache.width, w: 0 });
            set('u_surfaceOn', 1);
            built.surfaceOn = true;
        }
        const from = Math.max(0, Math.floor(d.virtualTextureFrom));
        const requests: SurfaceRequest[] = [];
        // What a page is made from besides its own page of heights and paint: the layers (as packed), and the maps over the whole area.
        const common = `${built.surfaceGen}:${wash}:${shade}:${d.colorMap}:${d.occlusionMap}`;
        for (const [key, n] of drawn) {
            if (n.level < from) continue;
            const page = built.table.get(key);
            if (!page) continue;
            const [pageX, pageY] = built.table.origin(page.slot);
            requests.push({ key, source: `${common}:${built.pageMade.get(key) ?? 0}`, x0: n.x0, z0: n.z0, size: n.size, level: n.level, pageX, pageY });
        }
        const far = (r: SurfaceRequest): number => Math.hypot(r.x0 + r.size / 2 - eye[0], r.z0 + r.size / 2 - eye[2]);
        requests.sort((a, b) => far(a) - far(b));
        const ready = cache.update(requests, built.instance, shader, SURFACES_PER_FRAME);
        // Shown with the rest of the ground's making while pages are being baked: of the nodes there are pages for, how many are drawn
        // from theirs.
        const wanted = Math.min(requests.length, cache.perRow * cache.rows);
        bakesOf(app).mark(cache, "Baking the ground's surface", wanted > 0 && !cache.failed ? ready.size / wanted : 1);
        return ready;
    }

    /** Makes the wanted pages, coarse and near first: asked of the workers where a pager can make them, else made here for as long as the frame can spare. */
    private makePages(app: App, built: Built, source: TerrainSource, eye: [number, number, number], at: { x: number; y: number; z: number }): void {
        const terrains = app.getResource(TerrainsRes);
        const paint = terrains.paint_;
        const repaint: Repaint | undefined = paint ? (x, z, h, ny, w) => paint(x + at.x, z + at.z, h + at.y, ny, w) : undefined;
        const bakes = bakesOf(app);
        if (built.wanted.size === 0) { built.pageWork = undefined; bakes.mark(built, 'Building the terrain', 1); bakes.urge(built, false); return; }
        // How far along: the pages there are, of those and the ones still wanted. (It was the pages made THIS frame, which read 0% for half a minute.)
        const progress = (): number => built.table.size / (built.table.size + built.wanted.size);
        // The page under the eye is the ground the player is standing on drawn too coarse: the frame gives more until it is made.
        bakes.urge(built, [...built.wanted.values()].some((n) => n.level === 0
            && eye[0] >= n.x0 && eye[0] < n.x0 + n.size && eye[2] >= n.z0 && eye[2] < n.z0 + n.size));
        const pager = built.pagerFailed ? null : terrains.pager_;
        if (pager) {
            const sorted = [...built.wanted.values()].sort((a, b) => b.level - a.level
                || Math.hypot(a.x0 + a.size / 2 - eye[0], a.z0 + a.size / 2 - eye[2]) - Math.hypot(b.x0 + b.size / 2 - eye[0], b.z0 + b.size / 2 - eye[2]));
            const epoch = built.epoch, edits = built.edits;
            let refused = false;
            for (const node of sorted) {
                const key = nodeKey(node.level, node.ix, node.iz);
                if (built.asked.has(key)) continue;
                if (built.asked.size >= PAGES_IN_FLIGHT) break;
                const image = pager(node.x0, node.z0, node.size);
                if (!image) { refused = true; break; }
                built.asked.add(key);
                void image.then((img) => {
                    built.asked.delete(key);
                    // Thrown away if the ground or its paint changed while it was being made: the page is wanted again, and asked again.
                    if (built.epoch !== epoch || built.edits !== edits || !built.heights) return;
                    const page = built.table.claim(key, img.min, img.max);
                    if (!page) return;
                    built.pageMade.set(key, ++built.pageSerial);
                    const [ox, oy] = built.table.origin(page.slot);
                    updateTextureSubregion(app.wasmModule, built.heights, ox, oy, PAGE_SIDE, PAGE_SIDE, img.heights);
                    updateTextureSubregion(app.wasmModule, built.paint, ox, oy, PAGE_SIDE, PAGE_SIDE, img.paint);
                    if (built.paint2) updateTextureSubregion(app.wasmModule, built.paint2, ox, oy, PAGE_SIDE, PAGE_SIDE, img.paint2);
                }, (e) => {
                    built.asked.delete(key);
                    // A worker that cannot make this ground's pages will not make the next one either: the terrain makes its own from here.
                    if (!built.pagerFailed) log.warn('terrain', 'the workers failed a page; the terrain makes its pages on the main thread from here', e);
                    built.pagerFailed = true;
                });
            }
            if (!refused) {
                built.pageWork = undefined;
                bakes.mark(built, 'Building the terrain', progress());
                return;
            }
        }
        if (built.pageWork && (built.pageWork.epoch !== built.epoch || built.pageWork.edits !== built.edits || !built.wanted.has(built.pageWork.key))) built.pageWork = undefined;
        const order = [...built.wanted.values()].sort((a, b) => b.level - a.level
            || Math.hypot(a.x0 + a.size / 2 - eye[0], a.z0 + a.size / 2 - eye[2]) - Math.hypot(b.x0 + b.size / 2 - eye[0], b.z0 + b.size / 2 - eye[2]));
        let made = 0;
        const store = (key: string, image: PageImage): boolean => {
            const page = built.table.claim(key, image.min, image.max);
            if (!page) return false;
            built.pageMade.set(key, ++built.pageSerial);
            const [ox, oy] = built.table.origin(page.slot);
            updateTextureSubregion(app.wasmModule, built.heights, ox, oy, PAGE_SIDE, PAGE_SIDE, image.heights);
            updateTextureSubregion(app.wasmModule, built.paint, ox, oy, PAGE_SIDE, PAGE_SIDE, image.paint);
            if (built.paint2) updateTextureSubregion(app.wasmModule, built.paint2, ox, oy, PAGE_SIDE, PAGE_SIDE, image.paint2);
            return true;
        };
        const epoch = built.epoch, edits = built.edits;
        const base = source instanceof ModifiedSource ? source.base : source;
        // The built-in noise provider has ready point samples identical to its region samples. External region providers may not.
        const incremental = !source.region || (base instanceof ProviderSource && base.provider.id === NOISE_PROVIDER);
        if (incremental) {
            do {
                if (!built.pageWork) {
                    const node = order.find((n) => built.wanted.has(nodeKey(n.level, n.ix, n.iz)));
                    if (!node) break;
                    built.pageWork = { key: nodeKey(node.level, node.ix, node.iz), epoch, edits, job: makePageJob(source, node.x0, node.z0, node.size, repaint) };
                }
                const work = built.pageWork;
                if (!work.image) {
                    const next = work.job.next();
                    if (next.done) work.image = next.value;
                }
                if (work.image) {
                    if (!store(work.key, work.image)) break;
                    built.wanted.delete(work.key); built.pageWork = undefined; made++;
                }
            } while (bakes.hasTime(built));
            bakes.mark(built, 'Building the terrain', progress());
            return;
        }
        for (const node of order) {
            const key = nodeKey(node.level, node.ix, node.iz);
            if (built.asked.has(key)) continue;
            if (source.region && built.asked.size >= PAGES_IN_FLIGHT) break;
            const image = makePage(source, node.x0, node.z0, node.size, repaint);
            if (image instanceof Promise) {
                // A provider answering later: its page is stored when it lands, if the terrain is still the one that asked.
                built.asked.add(key);
                void image.then((img) => {
                    built.asked.delete(key);
                    if (built.epoch === epoch && built.edits === edits && built.heights) store(key, img);
                }, (e) => {
                    built.asked.delete(key);
                    log.warn('terrain', `the provider failed a page (${key})`, e);
                });
                continue;
            }
            if (!store(key, image)) break;
            built.wanted.delete(key);
            made++;
            // The frame's one budget, shared with the bakes and the chunks of the world; at least one page a frame.
            if (!bakes.hasTime(built)) break;
        }
        bakes.mark(built, 'Building the terrain', progress());
    }

    /** Puts a node entity on each node drawn (reusing the ones it had), and takes the rest away. */
    private place(app: App, entity: Entity, built: Built, drawn: Map<string, TerrainNode>, surfaces: ReadonlyMap<string, number>): void {
        const world = app.world;
        for (const [key, e] of built.nodes) {
            if (drawn.has(key)) continue;
            built.nodes.delete(key);
            if (!world.valid(e)) continue;
            const mr = world.get(e, MeshRenderer) as MeshRendererData;
            if (mr.enabled) world.insert(e, MeshRenderer, { ...mr, enabled: false });
            built.spare.push(e);
        }
        for (const [key, n] of drawn) {
            const page = built.table.get(key)!;
            built.table.touch(key);
            let e = built.nodes.get(key);
            if (e === undefined || !world.valid(e)) {
                e = built.spare.pop();
                if (e === undefined || !world.valid(e)) {
                    e = world.spawn('TerrainNode');
                    world.insert(e, Transform, {});
                    world.setParent(e, entity);
                }
                built.nodes.set(key, e);
            }
            const [ox, oy] = built.table.origin(page.slot);
            // The tint names the page and the level (see the Terrain shader's hook), and the baked surface's page (2 + its slot; 1 none): every
            // channel above zero, as the hook divides by it.
            const surface = surfaces.get(key);
            const color = { r: (ox + 0.5) / ATLAS_SIZE, g: (oy + 0.5) / ATLAS_SIZE, b: (n.level + 1) / 64, a: surface === undefined ? 1 : 2 + surface };
            const position = { x: n.x0, y: page.min, z: n.z0 };
            const scale = { x: n.size, y: Math.max(page.max - page.min, 1e-3), z: n.size };
            const t = world.get(e, Transform) as TransformData;
            if (t.position.x !== position.x || t.position.y !== position.y || t.position.z !== position.z || t.scale.x !== scale.x || t.scale.y !== scale.y) {
                world.insert(e, Transform, { ...t, position, scale });
            }
            const mr = world.tryGet(e, MeshRenderer) as MeshRendererData | null;
            if (!mr || !mr.enabled || mr.color.r !== color.r || mr.color.g !== color.g || mr.color.b !== color.b || mr.color.a !== color.a || mr.material !== built.instance) {
                world.insert(e, MeshRenderer, {
                    ...(mr ?? {}), mesh: built.mesh, material: built.instance, lit: true, opaque: true, cullBackfaces: true, color, enabled: true,
                } as Partial<MeshRendererData>);
            }
        }
    }

    private destroy(app: App, built: Built): void {
        built.epoch++;
        built.cancel?.();
        built.cancel = null;
        bakesOf(app).clear(built);
        for (const e of [...built.nodes.values(), ...built.spare]) if (app.world.valid(e)) app.world.despawn(e);
        built.nodes.clear();
        built.spare.length = 0;
        built.wanted.clear();
        built.pageWork = undefined;
        const rm = getResourceManager();
        for (const handle of [built.heights, built.paint, built.paint2]) {
            if (!handle) continue;
            withdrawTextureContent(handle);
            rm?.releaseTexture(handle);
        }
        built.heights = built.paint = built.paint2 = 0;
        releaseLayerArrays(built.arrays);
        built.arrays = [];
        built.packed = '';
        if (built.baked) bakesOf(app).clear(built.baked);
        built.baked?.release();
        built.baked = null;
        built.surfaceOn = false;
        if (built.instance) Material.release(built.instance);
        built.instance = 0;
        if (built.mesh && app.hasResource(Assets)) app.getResource(Assets).releaseBuiltMesh(built.mesh);
        built.mesh = 0;
        built.source = null;
    }

    /** Releases the nodes of a terrain whose entity is gone. */
    private sweep(app: App, terrains: Terrains): void {
        for (const [entity, built] of terrains.built_) {
            if (app.world.valid(entity) && app.world.has(entity, Terrain)) continue;
            chunksOf(app).remove(collisionLayerOf(entity));
            this.destroy(app, built);
            terrains.built_.delete(entity);
            terrains.revision_++;
        }
    }
}

export const terrainPlugin: Plugin = /* @__PURE__ */ new TerrainPlugin();