@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/TerrainSystem.js

@@ -0,0 +1,566 @@
+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);
+    }
+}

package/src/engine/graphics3/TerrainSystem3.d.ts

@@ -1,80 +1,10 @@
 /**
- * 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.
+ * @deprecated Renamed to {@link TerrainSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **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 `DecalSystem3` 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 `GraphicsEngine3` 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 TerrainSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     * @param {AssetManager} assetManager
-     */
-    constructor(graphics: GraphicsEngine3, scene: Scene, assetManager: AssetManager);
-    dependencies: (typeof Terrain)[];
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {Terrain} terrain
-     * @param {number} entity
-     */
-    link(terrain: Terrain, entity: number): void;
-    /**
-     * @param {Terrain} terrain
-     * @param {number} entity
-     */
-    unlink(terrain: Terrain, entity: number): void;
-    update(timeDelta: any): void;
-    /**
-     * 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 `DecalSystem3` 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: number, scene: GPUSceneContext): object | null;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * 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.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class TerrainExtension extends RenderExtension {
-    /**
-     * @param {TerrainSystem3} system
-     */
-    constructor(system: TerrainSystem3);
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import Terrain from "../ecs/terrain/ecs/Terrain.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+export const TerrainSystem3: typeof TerrainSystem;
+import { TerrainSystem } from "./TerrainSystem.js";
 //# sourceMappingURL=TerrainSystem3.d.ts.map

package/src/engine/graphics3/TerrainSystem3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TerrainSystem3.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAiCI;;;;OAIG;IACH,iFAUC;IA/CD,iCAAyB;IAiDzB,2CAQC;IAED,4CAUC;IAED;;;OAGG;IACH,cAHW,OAAO,UACP,MAAM,QA2DhB;IAED;;;OAGG;IACH,gBAHW,OAAO,UACP,MAAM,QAMhB;IAED,6BA0BC;IAoLD;;;;;;;;;OASG;IACH,oBALW,MAAM,2BAEJ,MAAM,GAAC,IAAI,CA2FvB;IAED;;OAEG;IACH,kCAaC;;CACJ;AAED;;;;;;GAMG;AACH;IAUI;;OAEG;IACH,oBAFW,cAAc,EAMxB;IAED,yBAEC;;CACJ;uBA5iBsB,kBAAkB;oBACrB,+BAA+B;gCAUnB,mDAAmD"}
+{"version":3,"file":"TerrainSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TerrainSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,kDAA4C;8BATd,oBAAoB"}