@woosh/meep-engine 3.15.0 → 3.16.0

package/src/engine/graphics3/TerrainSystem.js

@@ -1,566 +1,565 @@
-import { assert } from "../../core/assert.js";
-import {
-    bvh_query_user_data_intersects_frustum
-} from "../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_frustum.js";
-import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
-import { noop } from "../../core/function/noop.js";
-import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
-import { GameAssetType } from "../asset/GameAssetType.js";
-import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { System } from "../ecs/System.js";
-import Terrain from "../ecs/terrain/ecs/Terrain.js";
-import { TerrainFlags } from "../ecs/terrain/ecs/TerrainFlags.js";
-import { tile_geometry_to_meshlets } from "../ecs/terrain/tiles/tile_geometry_to_meshlets.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { t64_copy_from_transform } from "../ecs/transform/t64_copy_from_transform.js";
-import { t64_equals_transform } from "../ecs/transform/t64_equals_transform.js";
-import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
-import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
-import { WHITE_PIXEL_DATA_URL } from "../graphics/WHITE_PIXEL_DATA_URL.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { StandardShadeMaterial } from "../../shade/renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../../shade/renderer/scene/Mesh.js";
-import { GPUTerrainSplatRenderer } from "./terrain/GPUTerrainSplatRenderer.js";
-import { pack_terrain_row_table } from "./terrain/pack_terrain_row_table.js";
-
-/**
- * Tile indices a frustum query answers with. Module-static because the query runs every frame and
- * every terrain shares one shape of answer.
- *
- * @type {number[]}
- */
-const SCRATCH_TILE_INDICES = [];
-
-/**
- * What the overlay's sprite is until an authored one loads — the same white pixel the component's
- * own default URL names, held as pixels so nothing has to decode a data URL to draw a grid.
- *
- * @type {Sampler2D}
- */
-const WHITE_SPRITE = Sampler2D.uint8(4, 1, 1);
-WHITE_SPRITE.data.fill(255);
-
-/**
- * Draws terrain under Shade: each built tile becomes one meshlet-encoded mesh in the scene, and a
- * pass after the opaque geometry textures the lot.
- *
- * **The tile is the unit, not the terrain.** Tiles are built on demand as the camera sees them and
- * destroyed as it leaves, which is the streaming the tile manager already does; this system follows
- * that with scene membership rather than deciding anything about it.
- *
- * **Tile vertices are already in terrain space** — the height-field builder positions each tile
- * within the whole grid rather than at its own origin — so every tile mesh carries the terrain
- * entity's transform and nothing else. That is also why the tile's own raycast inverts the same
- * matrix.
- *
- * **Texturing is a full-screen pass, not a material** (U3b, D40): the tiles draw with one flat
- * material, and at {@link FramePhase.AfterGBuffer} the splat mix and grid overlay are painted over
- * every pixel the visibility buffer attributes to a tile — the architecture decals built (D23),
- * keyed on mesh rows rather than froxels. Registered before `DecalSystem` in the profile, which
- * is what puts scorch marks on top of the textured ground rather than under it.
- *
- * **It does not call `Terrain.link`.** That method binds a three `ShaderMaterial` through
- * `graphics.getMaterialManager()`, which `GraphicsEngine` does not have and will not; the parts of
- * linking that are not about three — starting the tile build service — are done here directly.
- */
-export class TerrainSystem extends System {
-    dependencies = [Terrain];
-
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * The scene this system writes into, received rather than created so terrain, meshes and lights
-     * all land in the one the facade draws.
-     *
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * @type {AssetManager}
-     */
-    #assetManager;
-
-    /**
-     * What each terrain entity has in the scene.
-     *
-     * @type {Map<number, {terrain: Terrain, material: StandardShadeMaterial, meshes: Map<TerrainTile, Mesh>, bindings: SignalBinding[]}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {Scene} scene
-     * @param {AssetManager} assetManager
-     */
-    constructor(graphics, scene, assetManager) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene, 'scene');
-        assert.defined(assetManager, 'assetManager');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
-        this.#assetManager = assetManager;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new TerrainExtension(this));
-
-        // the terrain's own layer loading decodes images; the decoder is renderer-neutral and the
-        // legacy system registers the same one
-        await this.#assetManager.tryRegisterLoader(GameAssetType.Image, new ImageRGBADataLoader());
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-    }
-
-    /**
-     * @param {Terrain} terrain
-     * @param {number} entity
-     */
-    link(terrain, entity) {
-        if (!terrain.getFlag(TerrainFlags.Built)) {
-            terrain.build(this.#assetManager);
-        }
-
-        const entry = {
-            terrain,
-            /*
-             One material for the whole terrain, and a flat one on purpose: the splat pass rewrites
-             the albedo after the G-buffer is drawn (U3b), so what the material contributes is the
-             other three channels — roughness 1 and metalness 0, which is exactly what the legacy
-             splat shader forced.
-             */
-            material: new StandardShadeMaterial(),
-            meshes: new Map(),
-            bindings: [],
-            renderer: new GPUTerrainSplatRenderer(),
-            /**
-             * The pass's per-frame tables and settings, reused between frames.
-             */
-            rows: new Uint32Array(0),
-            scales: new Float32Array(0),
-            world_to_terrain: new Float32Array(16),
-            inv_world_size: new Float32Array(2),
-            grid_transform: new Float32Array(4),
-            grid_resolution: new Float32Array(2),
-            sprite: WHITE_SPRITE
-        };
-
-        entry.material.name = 'terrain';
-        entry.material.roughness_factor = 1;
-        entry.material.metallic_factor = 0;
-
-        this.#entries.set(entity, entry);
-
-        const manager = terrain.tiles;
-
-        const built = new SignalBinding(manager.on.tileBuilt, tile => this.#add_tile(entity, tile));
-        const destroyed = new SignalBinding(manager.on.tileDestroyed, tile => this.#remove_tile(entity, tile));
-        const sprite = new SignalBinding(terrain.overlay.tileImage.onChanged, () => this.#load_sprite(entity, terrain));
-
-        built.link();
-        destroyed.link();
-        sprite.link();
-
-        entry.bindings.push(built, destroyed, sprite);
-
-        this.#load_sprite(entity, terrain);
-
-        terrain.startBuildService();
-
-        // tiles that were already standing before this system saw the entity
-        for (const tile of manager.tiles) {
-            if (tile.isBuilt) {
-                this.#add_tile(entity, tile);
-            }
-        }
-    }
-
-    /**
-     * @param {Terrain} terrain
-     * @param {number} entity
-     */
-    unlink(terrain, entity) {
-        terrain.stopBuildService();
-
-        this.#drop(entity);
-    }
-
-    update(timeDelta) {
-        const em = this.entityManager;
-
-        if (em === null) {
-            return;
-        }
-
-        const ecd = em.dataset;
-
-        if (ecd === null) {
-            return;
-        }
-
-        ecd.traverseComponents(Terrain, (terrain, entity) => {
-            const transform = ecd.getComponent(entity, Transform);
-
-            if (transform !== undefined) {
-                // the raycast inverts this to bring a ray into terrain space, so it has to track
-                // the entity whether or not anything is drawn
-                terrain.transform = transform.matrix;
-            }
-
-            this.#place(entity, transform);
-
-            this.#build_visible_tiles(terrain);
-        });
-    }
-
-    /**
-     * Ask for the tiles the camera can see. The manager owns what that costs — a tile already built
-     * or already building is not requested again.
-     *
-     * @param {Terrain} terrain
-     */
-    #build_visible_tiles(terrain) {
-        const camera = this.#graphics.camera.camera;
-
-        const manager = terrain.tiles;
-
-        const hit_count = bvh_query_user_data_intersects_frustum(
-            SCRATCH_TILE_INDICES, 0,
-            manager.bvh, camera.frustum
-        );
-
-        for (let i = 0; i < hit_count; i++) {
-            const tile = manager.tiles[SCRATCH_TILE_INDICES[i]];
-
-            if (tile.isBuilt || tile.isBuildInProgress) {
-                continue;
-            }
-
-            const position = tile.gridPosition;
-
-            manager.build(position.x, position.y, noop, noop);
-        }
-    }
-
-    /**
-     * @param {number} entity
-     * @param {TerrainTile} tile
-     */
-    #add_tile(entity, tile) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        if (entry.meshes.has(tile)) {
-            // a rebuilt tile replaces what it had rather than accumulating
-            this.#remove_tile(entity, tile);
-        }
-
-        const geometry = tile_geometry_to_meshlets({
-            vertices: tile.vertices,
-            normals: tile.normals,
-            uvs: tile.uvs,
-            indices: tile.indices
-        }, `terrain tile ${tile.gridPosition.x},${tile.gridPosition.y}`);
-
-        const mesh = Mesh.from(geometry, entry.material);
-
-        entry.meshes.set(tile, mesh);
-
-        this.#scene.add(mesh);
-
-        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
-
-        if (ecd !== null) {
-            this.#place(entity, ecd.getComponent(entity, Transform));
-        }
-    }
-
-    /**
-     * @param {number} entity
-     * @param {TerrainTile} tile
-     */
-    #remove_tile(entity, tile) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        const mesh = entry.meshes.get(tile);
-
-        if (mesh === undefined) {
-            return;
-        }
-
-        this.#scene.remove(mesh);
-
-        entry.meshes.delete(tile);
-    }
-
-    /**
-     * @param {number} entity
-     * @param {Transform|undefined} transform
-     */
-    #place(entity, transform) {
-        if (transform === undefined) {
-            return;
-        }
-
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        for (const mesh of entry.meshes.values()) {
-            /*
-             A tile already standing where it belongs is left alone, and it is the common case:
-             {@link update} places on a poll rather than on the entity's transform signals, because a
-             terrain may be linked before it has a `Transform` at all. `updateMatrices` bumps a
-             version whether or not anything moved, and downstream that version is what makes the
-             scene database upload a row and the top-level acceleration structure rebuild itself —
-             a whole-tree treelet optimisation and a fresh GPU buffer, once a frame, for a ground
-             that has not moved since the level loaded (E19).
-            */
-            if (t64_equals_transform(mesh.transform_local, transform)) {
-                continue;
-            }
-
-            t64_copy_from_transform(mesh.transform_local, transform);
-
-            mesh.updateMatrices();
-        }
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        for (let i = 0; i < entry.bindings.length; i++) {
-            entry.bindings[i].unlink();
-        }
-
-        for (const mesh of entry.meshes.values()) {
-            this.#scene.remove(mesh);
-        }
-
-        entry.renderer.destroy();
-
-        this.#entries.delete(entity);
-    }
-
-    /**
-     * Fetch the overlay's cell sprite. The default is the white pixel the component names by data
-     * URL, held here as pixels — a grid with no authored sprite is the cell colours themselves,
-     * and nothing decodes a data URL to get there.
-     *
-     * @param {number} entity
-     * @param {Terrain} terrain
-     */
-    #load_sprite(entity, terrain) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        const url = terrain.overlay.baseTileImage;
-
-        if (url === WHITE_PIXEL_DATA_URL) {
-            entry.sprite = WHITE_SPRITE;
-
-            return;
-        }
-
-        this.#assetManager.promise(url, GameAssetType.Image).then(asset => {
-            if (this.#entries.get(entity) !== entry || terrain.overlay.baseTileImage !== url) {
-                // unlinked, or re-authored while the image was in flight
-                return;
-            }
-
-            entry.sprite = sampler2d_ensure_uint8_RGBA(asset.create());
-        });
-    }
-
-    /**
-     * Everything the splat pass draws one terrain from, assembled against the scene that will be
-     * asked for the rows. What the pass consumes and what a gate inspects are deliberately the
-     * same object — the same reason `DecalSystem` exposes its packed records.
-     *
-     * @param {number} entity
-     * @param {GPUSceneContext} scene
-     * @returns {object|null} `null` when this terrain has nothing on screen to texture — no tiles
-     * built, or none of them in the scene database yet
-     */
-    splat_frame(entity, scene) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined || entry.meshes.size === 0) {
-            return null;
-        }
-
-        const packed = pack_terrain_row_table({ meshes: entry.meshes, scene, table: entry.rows });
-
-        entry.rows = packed.table;
-
-        if (packed.size === 0) {
-            return null;
-        }
-
-        const terrain = entry.terrain;
-
-        const invertible = m4_invert(entry.world_to_terrain, terrain.transform);
-
-        assert.equal(invertible, true, 'terrain transform is not invertible');
-
-        const world_x = terrain.size.x * terrain.gridScale;
-        const world_y = terrain.size.y * terrain.gridScale;
-
-        entry.inv_world_size[0] = 1 / world_x;
-        entry.inv_world_size[1] = 1 / world_y;
-
-        const grid_transform = terrain.gridTransform;
-
-        entry.grid_transform[0] = grid_transform.scale_x;
-        entry.grid_transform[1] = grid_transform.scale_y;
-        entry.grid_transform[2] = grid_transform.offset_x;
-        entry.grid_transform[3] = grid_transform.offset_y;
-
-        entry.grid_resolution[0] = terrain.size.x;
-        entry.grid_resolution[1] = terrain.size.y;
-
-        const layers = terrain.layers;
-        const layer_count = layers.count();
-
-        if (entry.scales.length < layer_count * 2) {
-            entry.scales = new Float32Array(layer_count * 2);
-        }
-
-        // the legacy `updateLayerScales`, computed at the source instead of read off a texture
-        for (let i = 0; i < layer_count; i++) {
-            const layer = layers.get(i);
-
-            entry.scales[i * 2] = world_x / layer.size.x;
-            entry.scales[i * 2 + 1] = world_y / layer.size.y;
-        }
-
-        const splat = terrain.splat;
-        const layer_image = layers.sampler;
-
-        if (layer_count > 0) {
-            // `Terrain.build` and `addLayer` keep all three in step; a mismatch is an upstream bug
-            // that would draw the wrong layer, silently
-            assert.equal(splat.depth, layer_count, 'splat weight layers disagree with the layer list');
-            assert.equal(layer_image.depth, layer_count, 'layer texture depth disagrees with the layer list');
-        }
-
-        return {
-            rows: entry.rows,
-            row_count: packed.size,
-            scales: entry.scales,
-            layer_count,
-            world_to_terrain: entry.world_to_terrain,
-            inv_world_size: entry.inv_world_size,
-            grid_transform: entry.grid_transform,
-            grid_resolution: entry.grid_resolution,
-            weights: {
-                data: splat.weightData,
-                width: splat.size.x,
-                height: splat.size.y,
-                depth: splat.depth,
-                version: splat.weights.version
-            },
-            layer_image: {
-                data: layer_image.data,
-                width: layer_image.width,
-                height: layer_image.height,
-                depth: layer_image.depth,
-                version: layer_image.version
-            },
-            overlay: terrain.overlay.sampler,
-            sprite: entry.sprite
-        };
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        for (const entity of this.#entries.keys()) {
-            const splat = this.splat_frame(entity, frame.view.scene);
-
-            if (splat === null) {
-                // nothing of this terrain on screen; the frame keeps the albedo it already had
-                continue;
-            }
-
-            splat.frame = frame;
-
-            this.#entries.get(entity).renderer.graph_draw(splat);
-        }
-    }
-}
-
-/**
- * The splat and the grid overlay are a full-screen pass writing a replacement albedo, so this is
- * {@link FramePhase.AfterGBuffer} — the one phase where the G-buffer may be published into.
- *
- * Everything that paints on top of the ground declares itself after this rather than being
- * registered after it; {@link DecalExtension} is the one that does.
- */
-export class TerrainExtension extends RenderExtension {
-    name = "terrain";
-
-    phase = FramePhase.AfterGBuffer;
-
-    /**
-     * @type {TerrainSystem}
-     */
-    #system;
-
-    /**
-     * @param {TerrainSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+import { assert } from "../../core/assert.js";
+import {
+    bvh_query_user_data_intersects_frustum
+} from "../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_frustum.js";
+import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
+import { noop } from "../../core/function/noop.js";
+import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
+import { GameAssetType } from "../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { System } from "../ecs/System.js";
+import Terrain from "../ecs/terrain/ecs/Terrain.js";
+import { TerrainFlags } from "../ecs/terrain/ecs/TerrainFlags.js";
+import { tile_geometry_to_meshlets } from "../ecs/terrain/tiles/tile_geometry_to_meshlets.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { t64_equals_components } from "../ecs/transform/t64_equals_components.js";
+import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
+import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
+import { WHITE_PIXEL_DATA_URL } from "../graphics/WHITE_PIXEL_DATA_URL.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { StandardShadeMaterial } from "../../shade/renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../../shade/renderer/scene/Mesh.js";
+import { GPUTerrainSplatRenderer } from "./terrain/GPUTerrainSplatRenderer.js";
+import { pack_terrain_row_table } from "./terrain/pack_terrain_row_table.js";
+
+/**
+ * Tile indices a frustum query answers with. Module-static because the query runs every frame and
+ * every terrain shares one shape of answer.
+ *
+ * @type {number[]}
+ */
+const SCRATCH_TILE_INDICES = [];
+
+/**
+ * What the overlay's sprite is until an authored one loads — the same white pixel the component's
+ * own default URL names, held as pixels so nothing has to decode a data URL to draw a grid.
+ *
+ * @type {Sampler2D}
+ */
+const WHITE_SPRITE = Sampler2D.uint8(4, 1, 1);
+WHITE_SPRITE.data.fill(255);
+
+/**
+ * Draws terrain under Shade: each built tile becomes one meshlet-encoded mesh in the scene, and a
+ * pass after the opaque geometry textures the lot.
+ *
+ * **The tile is the unit, not the terrain.** Tiles are built on demand as the camera sees them and
+ * destroyed as it leaves, which is the streaming the tile manager already does; this system follows
+ * that with scene membership rather than deciding anything about it.
+ *
+ * **Tile vertices are already in terrain space** — the height-field builder positions each tile
+ * within the whole grid rather than at its own origin — so every tile mesh carries the terrain
+ * entity's transform and nothing else. That is also why the tile's own raycast inverts the same
+ * matrix.
+ *
+ * **Texturing is a full-screen pass, not a material** (U3b, D40): the tiles draw with one flat
+ * material, and at {@link FramePhase.AfterGBuffer} the splat mix and grid overlay are painted over
+ * every pixel the visibility buffer attributes to a tile — the architecture decals built (D23),
+ * keyed on mesh rows rather than froxels. Registered before `DecalSystem` in the profile, which
+ * is what puts scorch marks on top of the textured ground rather than under it.
+ *
+ * **It does not call `Terrain.link`.** That method binds a three `ShaderMaterial` through
+ * `graphics.getMaterialManager()`, which `GraphicsEngine` does not have and will not; the parts of
+ * linking that are not about three — starting the tile build service — are done here directly.
+ */
+export class TerrainSystem extends System {
+    dependencies = [Terrain];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * The scene this system writes into, received rather than created so terrain, meshes and lights
+     * all land in the one the facade draws.
+     *
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {AssetManager}
+     */
+    #assetManager;
+
+    /**
+     * What each terrain entity has in the scene.
+     *
+     * @type {Map<number, {terrain: Terrain, material: StandardShadeMaterial, meshes: Map<TerrainTile, Mesh>, bindings: SignalBinding[]}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     * @param {AssetManager} assetManager
+     */
+    constructor(graphics, scene, assetManager) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+        assert.defined(assetManager, 'assetManager');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+        this.#assetManager = assetManager;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new TerrainExtension(this));
+
+        // the terrain's own layer loading decodes images; the decoder is renderer-neutral and the
+        // legacy system registers the same one
+        await this.#assetManager.tryRegisterLoader(GameAssetType.Image, new ImageRGBADataLoader());
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    link(terrain, entity) {
+        if (!terrain.getFlag(TerrainFlags.Built)) {
+            terrain.build(this.#assetManager);
+        }
+
+        const entry = {
+            terrain,
+            /*
+             One material for the whole terrain, and a flat one on purpose: the splat pass rewrites
+             the albedo after the G-buffer is drawn (U3b), so what the material contributes is the
+             other three channels — roughness 1 and metalness 0, which is exactly what the legacy
+             splat shader forced.
+             */
+            material: new StandardShadeMaterial(),
+            meshes: new Map(),
+            bindings: [],
+            renderer: new GPUTerrainSplatRenderer(),
+            /**
+             * The pass's per-frame tables and settings, reused between frames.
+             */
+            rows: new Uint32Array(0),
+            scales: new Float32Array(0),
+            world_to_terrain: new Float32Array(16),
+            inv_world_size: new Float32Array(2),
+            grid_transform: new Float32Array(4),
+            grid_resolution: new Float32Array(2),
+            sprite: WHITE_SPRITE
+        };
+
+        entry.material.name = 'terrain';
+        entry.material.roughness_factor = 1;
+        entry.material.metallic_factor = 0;
+
+        this.#entries.set(entity, entry);
+
+        const manager = terrain.tiles;
+
+        const built = new SignalBinding(manager.on.tileBuilt, tile => this.#add_tile(entity, tile));
+        const destroyed = new SignalBinding(manager.on.tileDestroyed, tile => this.#remove_tile(entity, tile));
+        const sprite = new SignalBinding(terrain.overlay.tileImage.onChanged, () => this.#load_sprite(entity, terrain));
+
+        built.link();
+        destroyed.link();
+        sprite.link();
+
+        entry.bindings.push(built, destroyed, sprite);
+
+        this.#load_sprite(entity, terrain);
+
+        terrain.startBuildService();
+
+        // tiles that were already standing before this system saw the entity
+        for (const tile of manager.tiles) {
+            if (tile.isBuilt) {
+                this.#add_tile(entity, tile);
+            }
+        }
+    }
+
+    /**
+     * @param {Terrain} terrain
+     * @param {number} entity
+     */
+    unlink(terrain, entity) {
+        terrain.stopBuildService();
+
+        this.#drop(entity);
+    }
+
+    update(timeDelta) {
+        const em = this.entityManager;
+
+        if (em === null) {
+            return;
+        }
+
+        const ecd = em.dataset;
+
+        if (ecd === null) {
+            return;
+        }
+
+        ecd.traverseComponents(Terrain, (terrain, entity) => {
+            const transform = ecd.getComponent(entity, Transform64);
+
+            if (transform !== undefined) {
+                // the raycast inverts this to bring a ray into terrain space, so it has to track
+                // the entity whether or not anything is drawn
+                terrain.transform = transform.matrix;
+            }
+
+            this.#place(entity, transform);
+
+            this.#build_visible_tiles(terrain);
+        });
+    }
+
+    /**
+     * Ask for the tiles the camera can see. The manager owns what that costs — a tile already built
+     * or already building is not requested again.
+     *
+     * @param {Terrain} terrain
+     */
+    #build_visible_tiles(terrain) {
+        const camera = this.#graphics.camera.camera;
+
+        const manager = terrain.tiles;
+
+        const hit_count = bvh_query_user_data_intersects_frustum(
+            SCRATCH_TILE_INDICES, 0,
+            manager.bvh, camera.frustum
+        );
+
+        for (let i = 0; i < hit_count; i++) {
+            const tile = manager.tiles[SCRATCH_TILE_INDICES[i]];
+
+            if (tile.isBuilt || tile.isBuildInProgress) {
+                continue;
+            }
+
+            const position = tile.gridPosition;
+
+            manager.build(position.x, position.y, noop, noop);
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @param {TerrainTile} tile
+     */
+    #add_tile(entity, tile) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        if (entry.meshes.has(tile)) {
+            // a rebuilt tile replaces what it had rather than accumulating
+            this.#remove_tile(entity, tile);
+        }
+
+        const geometry = tile_geometry_to_meshlets({
+            vertices: tile.vertices,
+            normals: tile.normals,
+            uvs: tile.uvs,
+            indices: tile.indices
+        }, `terrain tile ${tile.gridPosition.x},${tile.gridPosition.y}`);
+
+        const mesh = Mesh.from(geometry, entry.material);
+
+        entry.meshes.set(tile, mesh);
+
+        this.#scene.add(mesh);
+
+        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
+
+        if (ecd !== null) {
+            this.#place(entity, ecd.getComponent(entity, Transform64));
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @param {TerrainTile} tile
+     */
+    #remove_tile(entity, tile) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        const mesh = entry.meshes.get(tile);
+
+        if (mesh === undefined) {
+            return;
+        }
+
+        this.#scene.remove(mesh);
+
+        entry.meshes.delete(tile);
+    }
+
+    /**
+     * @param {number} entity
+     * @param {Transform64|undefined} transform
+     */
+    #place(entity, transform) {
+        if (transform === undefined) {
+            return;
+        }
+
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        for (const mesh of entry.meshes.values()) {
+            /*
+             A tile already standing where it belongs is left alone, and it is the common case:
+             {@link update} places on a poll rather than on the entity's transform signals, because a
+             terrain may be linked before it has a `Transform` at all. `updateMatrices` bumps a
+             version whether or not anything moved, and downstream that version is what makes the
+             scene database upload a row and the top-level acceleration structure rebuild itself —
+             a whole-tree treelet optimisation and a fresh GPU buffer, once a frame, for a ground
+             that has not moved since the level loaded (E19).
+            */
+            if (t64_equals_components(mesh.transform_local, transform)) {
+                continue;
+            }
+
+            mesh.transform_local.copy(transform);
+
+            mesh.updateMatrices();
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        for (let i = 0; i < entry.bindings.length; i++) {
+            entry.bindings[i].unlink();
+        }
+
+        for (const mesh of entry.meshes.values()) {
+            this.#scene.remove(mesh);
+        }
+
+        entry.renderer.destroy();
+
+        this.#entries.delete(entity);
+    }
+
+    /**
+     * Fetch the overlay's cell sprite. The default is the white pixel the component names by data
+     * URL, held here as pixels — a grid with no authored sprite is the cell colours themselves,
+     * and nothing decodes a data URL to get there.
+     *
+     * @param {number} entity
+     * @param {Terrain} terrain
+     */
+    #load_sprite(entity, terrain) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        const url = terrain.overlay.baseTileImage;
+
+        if (url === WHITE_PIXEL_DATA_URL) {
+            entry.sprite = WHITE_SPRITE;
+
+            return;
+        }
+
+        this.#assetManager.promise(url, GameAssetType.Image).then(asset => {
+            if (this.#entries.get(entity) !== entry || terrain.overlay.baseTileImage !== url) {
+                // unlinked, or re-authored while the image was in flight
+                return;
+            }
+
+            entry.sprite = sampler2d_ensure_uint8_RGBA(asset.create());
+        });
+    }
+
+    /**
+     * Everything the splat pass draws one terrain from, assembled against the scene that will be
+     * asked for the rows. What the pass consumes and what a gate inspects are deliberately the
+     * same object — the same reason `DecalSystem` exposes its packed records.
+     *
+     * @param {number} entity
+     * @param {GPUSceneContext} scene
+     * @returns {object|null} `null` when this terrain has nothing on screen to texture — no tiles
+     * built, or none of them in the scene database yet
+     */
+    splat_frame(entity, scene) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined || entry.meshes.size === 0) {
+            return null;
+        }
+
+        const packed = pack_terrain_row_table({ meshes: entry.meshes, scene, table: entry.rows });
+
+        entry.rows = packed.table;
+
+        if (packed.size === 0) {
+            return null;
+        }
+
+        const terrain = entry.terrain;
+
+        const invertible = m4_invert(entry.world_to_terrain, terrain.transform);
+
+        assert.equal(invertible, true, 'terrain transform is not invertible');
+
+        const world_x = terrain.size.x * terrain.gridScale;
+        const world_y = terrain.size.y * terrain.gridScale;
+
+        entry.inv_world_size[0] = 1 / world_x;
+        entry.inv_world_size[1] = 1 / world_y;
+
+        const grid_transform = terrain.gridTransform;
+
+        entry.grid_transform[0] = grid_transform.scale_x;
+        entry.grid_transform[1] = grid_transform.scale_y;
+        entry.grid_transform[2] = grid_transform.offset_x;
+        entry.grid_transform[3] = grid_transform.offset_y;
+
+        entry.grid_resolution[0] = terrain.size.x;
+        entry.grid_resolution[1] = terrain.size.y;
+
+        const layers = terrain.layers;
+        const layer_count = layers.count();
+
+        if (entry.scales.length < layer_count * 2) {
+            entry.scales = new Float32Array(layer_count * 2);
+        }
+
+        // the legacy `updateLayerScales`, computed at the source instead of read off a texture
+        for (let i = 0; i < layer_count; i++) {
+            const layer = layers.get(i);
+
+            entry.scales[i * 2] = world_x / layer.size.x;
+            entry.scales[i * 2 + 1] = world_y / layer.size.y;
+        }
+
+        const splat = terrain.splat;
+        const layer_image = layers.sampler;
+
+        if (layer_count > 0) {
+            // `Terrain.build` and `addLayer` keep all three in step; a mismatch is an upstream bug
+            // that would draw the wrong layer, silently
+            assert.equal(splat.depth, layer_count, 'splat weight layers disagree with the layer list');
+            assert.equal(layer_image.depth, layer_count, 'layer texture depth disagrees with the layer list');
+        }
+
+        return {
+            rows: entry.rows,
+            row_count: packed.size,
+            scales: entry.scales,
+            layer_count,
+            world_to_terrain: entry.world_to_terrain,
+            inv_world_size: entry.inv_world_size,
+            grid_transform: entry.grid_transform,
+            grid_resolution: entry.grid_resolution,
+            weights: {
+                data: splat.weightData,
+                width: splat.size.x,
+                height: splat.size.y,
+                depth: splat.depth,
+                version: splat.weights.version
+            },
+            layer_image: {
+                data: layer_image.data,
+                width: layer_image.width,
+                height: layer_image.height,
+                depth: layer_image.depth,
+                version: layer_image.version
+            },
+            overlay: terrain.overlay.sampler,
+            sprite: entry.sprite
+        };
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        for (const entity of this.#entries.keys()) {
+            const splat = this.splat_frame(entity, frame.view.scene);
+
+            if (splat === null) {
+                // nothing of this terrain on screen; the frame keeps the albedo it already had
+                continue;
+            }
+
+            splat.frame = frame;
+
+            this.#entries.get(entity).renderer.graph_draw(splat);
+        }
+    }
+}
+
+/**
+ * The splat and the grid overlay are a full-screen pass writing a replacement albedo, so this is
+ * {@link FramePhase.AfterGBuffer} — the one phase where the G-buffer may be published into.
+ *
+ * Everything that paints on top of the ground declares itself after this rather than being
+ * registered after it; {@link DecalExtension} is the one that does.
+ */
+export class TerrainExtension extends RenderExtension {
+    name = "terrain";
+
+    phase = FramePhase.AfterGBuffer;
+
+    /**
+     * @type {TerrainSystem}
+     */
+    #system;
+
+    /**
+     * @param {TerrainSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}