@woosh/meep-engine 3.11.3 → 3.12.0

package/src/engine/graphics3/TerrainSystem3.js

@@ -1,566 +1,10 @@
-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";
+import { TerrainSystem } from "./TerrainSystem.js";
 
 /**
- * Tile indices a frustum query answers with. Module-static because the query runs every frame and
- * every terrain shares one shape of answer.
+ * @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.
  *
- * @type {number[]}
+ * 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.
  */
-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 `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 {
-    dependencies = [Terrain];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #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 {GraphicsEngine3} 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 `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, 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 {TerrainSystem3}
-     */
-    #system;
-
-    /**
-     * @param {TerrainSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const TerrainSystem3 = TerrainSystem;

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

@@ -0,0 +1,65 @@
+/**
+ * Shows an entity's tooltip when the pointer is over it, under Shade.
+ *
+ * **The target is a promise, and that is the visible difference.** The renderer this replaces
+ * answered "what is under the pointer" inside the call that asked, by walking every visible mesh and
+ * raycasting three's geometry. Picking here is asynchronous and batched by contract (I-9), because
+ * the backend it is built for reads entity ids off the visibility buffer — a frame late, a batch at
+ * a time. So the answer arrives a tick after the question, and a tooltip appears a tick later than
+ * it used to. That is a change to the UI's timing, not to what it points at.
+ *
+ * **One ray, one answer, and it is the nearest thing.** The old path tested only entities that
+ * carried a tooltip, so a chest behind a wall described itself through the wall. This asks what the
+ * pointer is on and takes what comes back: something in front without a tooltip means no tooltip,
+ * which is both what the player can see and the only thing an id read off a pixel could ever say.
+ *
+ * **{@link Pickable} governs what can be found.** An entity with a tooltip and no `Pickable` is not
+ * in the picking index and has no tooltip in practice — the opt-in is authored next to the tooltip
+ * itself.
+ *
+ * The delay is a delay before a tooltip *appears*. Once one is up the pointer is asked about on
+ * every tick, so moving off an entity takes the tooltip away without waiting again.
+ */
+export class TooltipComponentSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {TooltipManager} tooltips
+     * @param {PointerDevice} pointer
+     * @param {Localization} localization
+     * @param {PickingSystem} picking
+     */
+    constructor({ graphics, tooltips, pointer, localization, picking }: GraphicsEngine);
+    dependencies: (typeof TooltipComponent)[];
+    /**
+     * How long the pointer has to rest before a tooltip appears, in seconds.
+     *
+     * @type {number}
+     */
+    display_delay: number;
+    /**
+     * The screen-space rectangle the tooltip points at. Follows the pointer while a tooltip is up.
+     *
+     * @readonly
+     * @type {Rectangle}
+     */
+    readonly target: Rectangle;
+    /**
+     * Which entity the tooltip currently on screen describes, or {@link PickingResult.NOTHING}.
+     *
+     * @returns {number}
+     */
+    get tip_entity(): number;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {TooltipComponent} tooltip
+     * @param {number} entity
+     */
+    unlink(tooltip: TooltipComponent, entity: number): void;
+    update(time_delta: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { TooltipComponent } from "../ecs/tooltip/TooltipComponent.js";
+import Rectangle from "../../core/geom/2d/Rectangle.js";
+//# sourceMappingURL=TooltipComponentSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TooltipComponentSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/TooltipComponentSystem.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA0EI;;;;;;OAMG;IACH,oFAcC;IA9FD,0CAAkC;IAElC;;;;OAIG;IACH,eAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,iBAFU,SAAS,CAEM;IAiFzB;;;;OAIG;IACH,yBAEC;IAED,2CAMC;IAED,4CAMC;IAED;;;OAGG;IACH,gBAHW,gBAAgB,UAChB,MAAM,QAOhB;IAED,8BAyBC;;CAmHJ;uBAlUsB,kBAAkB;iCACR,oCAAoC;sBAL/C,iCAAiC"}