@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/PathDisplaySystem3.js

@@ -1,309 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { GPUDynamicMeshRenderer } from "../../shade/renderer/dynamic/GPUDynamicMeshRenderer.js";
-import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
-import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
-import { DynamicMesh } from "../../shade/renderer/scene/DynamicMesh.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
-import { System } from "../ecs/System.js";
-import { PathDisplay } from "../graphics/ecs/path/PathDisplay.js";
-import { PathDisplayEvents } from "../graphics/ecs/path/PathDisplayEvents.js";
-import { PathDisplayType } from "../graphics/ecs/path/PathDisplayType.js";
-import Path from "../navigation/ecs/components/Path.js";
-import { PathEvents } from "../navigation/ecs/components/PathEvents.js";
-import { build_tube_path_streams } from "./path/build_tube_path_streams.js";
-import { tube_stream_write_geometry } from "./path/tube_stream_write_geometry.js";
+import { PathDisplaySystem } from "./PathDisplaySystem.js";
 
 /**
- * Draws {@link PathDisplay}'s tubes under Shade, on the dynamic-geometry path.
+ * @deprecated Renamed to {@link PathDisplaySystem}. 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.
  *
- * **A tube is dynamic content by definition** — the game's one path display is the combat targeting
- * arc, rebuilt every time the cursor moves — so it goes down S4's dedicated non-meshlet path rather
- * than becoming a `ShadedGeometry` behind the meshlet encode that D5/I-10 rule out (D21).
- *
- * **No owned entities.** The legacy system spawns a child entity per mask span because three needs
- * an object-carrying entity per drawable; here the system holds the meshes itself, so link builds
- * them, a path or style change rewrites them, and unlink releases them.
- *
- * **The geometry is kept and rewritten, never replaced.** GPU residency on this path is keyed on
- * the geometry and survives leaving the batch, so a rebuild that produced a new one each time would
- * strand a vertex buffer per cursor move.
- *
- * Tubes are all it draws. `PathDisplayType.Ribbon` retires with the three path (I-6c) and
- * `PathDisplayType.Entity` builds marker entities that carry their own components — neither is
- * this system's to render.
+ * 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 PathDisplaySystem3 extends System {
-    dependencies = [PathDisplay, Path];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {GPUDynamicMeshRenderer}
-     */
-    #renderer = new GPUDynamicMeshRenderer();
-
-    /**
-     * @type {DynamicMeshBatch}
-     */
-    #batch = new DynamicMeshBatch();
-
-    /**
-     * @type {Map<number, {display: PathDisplay, path: Path, meshes: DynamicMesh[], listener: Function}>}
-     */
-    #entries = new Map();
-
-    /**
-     * Entities whose tubes are out of date. A path change and a style change both arrive as events,
-     * and the arc sends one of each per cursor move — coalescing to one rebuild a tick is what the
-     * queue is for.
-     *
-     * @type {Set<number>}
-     */
-    #dirty = new Set();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the meshes follow the entities.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch() {
-        return this.#batch;
-    }
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-
-        this.#graphics = graphics;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new PathDisplayExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        this.#batch.clear();
-        this.#entries.clear();
-        this.#dirty.clear();
-    }
-
-    /**
-     * @param {PathDisplay} display
-     * @param {Path} path
-     * @param {number} entity
-     */
-    link(display, path, entity) {
-        const dataset = this.entityManager.dataset;
-
-        const listener = () => this.#dirty.add(entity);
-
-        dataset.addEntityEventListener(entity, PathEvents.Changed, listener);
-        dataset.addEntityEventListener(entity, PathDisplayEvents.Changed, listener);
-
-        const entry = { display, path, meshes: [], listener };
-
-        this.#entries.set(entity, entry);
-
-        this.#rebuild(entry);
-    }
-
-    /**
-     * @param {PathDisplay} display
-     * @param {Path} path
-     * @param {number} entity
-     */
-    unlink(display, path, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        const dataset = this.entityManager.dataset;
-
-        dataset.removeEntityEventListener(entity, PathEvents.Changed, entry.listener);
-        dataset.removeEntityEventListener(entity, PathDisplayEvents.Changed, entry.listener);
-
-        this.#release(entry, 0);
-
-        this.#entries.delete(entity);
-        this.#dirty.delete(entity);
-    }
-
-    update(timeDelta) {
-        if (this.#dirty.size === 0) {
-            return;
-        }
-
-        for (const entity of this.#dirty) {
-            const entry = this.#entries.get(entity);
-
-            if (entry === undefined) {
-                continue;
-            }
-
-            this.#rebuild(entry);
-        }
-
-        this.#dirty.clear();
-    }
-
-    /**
-     * @param {{display: PathDisplay, path: Path, meshes: DynamicMesh[]}} entry
-     */
-    #rebuild(entry) {
-        const specs = entry.display.specs;
-
-        let written = 0;
-
-        for (let i = 0; i < specs.length; i++) {
-            const spec = specs[i];
-
-            if (spec.type !== PathDisplayType.Tube) {
-                continue;
-            }
-
-            const style = spec.style;
-
-            const streams = build_tube_path_streams(entry.path, style);
-
-            const color = style.color;
-
-            for (let j = 0; j < streams.length; j++) {
-                const mesh = this.#obtain_mesh(entry, written);
-
-                tube_stream_write_geometry(mesh.geometry, streams[j]);
-
-                mesh.color[0] = color.r;
-                mesh.color[1] = color.g;
-                mesh.color[2] = color.b;
-                mesh.color[3] = style.opacity;
-
-                written++;
-            }
-        }
-
-        this.#release(entry, written);
-    }
-
-    /**
-     * The mesh drawing span `index` of this entity, created on first use.
-     *
-     * @param {{meshes: DynamicMesh[]}} entry
-     * @param {number} index
-     * @returns {DynamicMesh}
-     */
-    #obtain_mesh(entry, index) {
-        const existing = entry.meshes[index];
-
-        if (existing !== undefined) {
-            return existing;
-        }
-
-        const mesh = DynamicMesh.from(new Geometry());
-
-        // the sweep produces world-space vertices, so what the draw applies is identity — but a
-        // node's world transform is derived and stays unset until it is asked for
-        mesh.updateMatrices();
-
-        entry.meshes.push(mesh);
-
-        this.#batch.add(mesh);
-
-        return mesh;
-    }
-
-    /**
-     * Give up every mesh from `count` on — a style whose mask lost a span, or an entity going away.
-     *
-     * @param {{meshes: DynamicMesh[]}} entry
-     * @param {number} count
-     */
-    #release(entry, count) {
-        const meshes = entry.meshes;
-
-        for (let i = count; i < meshes.length; i++) {
-            const mesh = meshes[i];
-
-            this.#batch.remove(mesh);
-
-            // residency deliberately survives leaving the batch, so nothing else would free it
-            this.#renderer.release(mesh.geometry);
-        }
-
-        meshes.length = count;
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        if (this.#batch.count === 0) {
-            // nothing to draw, and the frame's colour is left exactly as it was
-            return;
-        }
-
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            batch: this.#batch,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: frame.view.camera.buffer
-        });
-    }
-}
-
-/**
- * The targeting arc draws into the scene, so it belongs before the fog of war that conceals it and
- * before the upscale that resolves it.
- */
-export class PathDisplayExtension extends RenderExtension {
-    name = "path display";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {PathDisplaySystem3}
-     */
-    #system;
-
-    /**
-     * @param {PathDisplaySystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const PathDisplaySystem3 = PathDisplaySystem;

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

@@ -13,7 +13,7 @@
  * A marker, deliberately: the bounds come from what the entity actually looks like, so there is
  * nothing to configure and no second way for an entity's picking shape to disagree with its model.
  *
- * @see PickingSystem3
+ * @see PickingSystem
  */
 export class Pickable {
     /**

package/src/engine/graphics3/Pickable.js

@@ -1,65 +1,65 @@
-import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
-
-/**
- * Opts an entity into picking.
- *
- * Picking keeps a CPU-side spatial index of where things are, which is state the renderer already
- * holds on the GPU — so it is duplication, and it is paid for **per entity that asks**. A level is
- * mostly scenery that nothing will ever click on, and scenery costs nothing here.
- *
- * That is also what makes the index disposable. The backend is a CPU bounding-volume hierarchy today
- * and is meant to become a GPU visibility-buffer id readback; when it does, this component stops
- * implying a duplicate and starts implying nothing but "answers picking queries", with no change to
- * anything that uses it.
- *
- * A marker, deliberately: the bounds come from what the entity actually looks like, so there is
- * nothing to configure and no second way for an entity's picking shape to disagree with its model.
- *
- * @see PickingSystem3
- */
-export class Pickable {
-    /**
-     * @returns {number}
-     */
-    hash() {
-        return 0;
-    }
-
-    /**
-     * @param {Pickable} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return other instanceof Pickable;
-    }
-
-    toJSON() {
-        return {};
-    }
-
-    fromJSON() {
-    }
-
-    /**
-     * @returns {Pickable}
-     */
-    static fromJSON() {
-        return new Pickable();
-    }
-}
-
-/**
- * @readonly
- * @type {string}
- */
-Pickable.typeName = "Pickable";
-
-
-/**
- * A marker carries no data, so this writes none — what has to survive a save is that the entity
- * opted in at all, and the presence of the component is that.
- */
-export class PickableSerializationAdapter extends BinaryClassSerializationAdapter {
-    klass = Pickable;
-    version = 0;
-}
+import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+
+/**
+ * Opts an entity into picking.
+ *
+ * Picking keeps a CPU-side spatial index of where things are, which is state the renderer already
+ * holds on the GPU — so it is duplication, and it is paid for **per entity that asks**. A level is
+ * mostly scenery that nothing will ever click on, and scenery costs nothing here.
+ *
+ * That is also what makes the index disposable. The backend is a CPU bounding-volume hierarchy today
+ * and is meant to become a GPU visibility-buffer id readback; when it does, this component stops
+ * implying a duplicate and starts implying nothing but "answers picking queries", with no change to
+ * anything that uses it.
+ *
+ * A marker, deliberately: the bounds come from what the entity actually looks like, so there is
+ * nothing to configure and no second way for an entity's picking shape to disagree with its model.
+ *
+ * @see PickingSystem
+ */
+export class Pickable {
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return 0;
+    }
+
+    /**
+     * @param {Pickable} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return other instanceof Pickable;
+    }
+
+    toJSON() {
+        return {};
+    }
+
+    fromJSON() {
+    }
+
+    /**
+     * @returns {Pickable}
+     */
+    static fromJSON() {
+        return new Pickable();
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Pickable.typeName = "Pickable";
+
+
+/**
+ * A marker carries no data, so this writes none — what has to survive a save is that the entity
+ * opted in at all, and the presence of the component is that.
+ */
+export class PickableSerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = Pickable;
+    version = 0;
+}

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

@@ -1,5 +1,5 @@
 /**
- * One ray to be answered by {@link PickingSystem3#pick}.
+ * One ray to be answered by {@link PickingSystem#pick}.
  *
  * A type rather than a pair of loose vectors because queries travel in batches, and a batch of
  * `[origin, direction, origin, direction, …]` is a shape that goes wrong silently.

package/src/engine/graphics3/PickingQuery.js

@@ -1,48 +1,48 @@
-import Vector3 from "../../core/geom/Vector3.js";
-
-/**
- * One ray to be answered by {@link PickingSystem3#pick}.
- *
- * A type rather than a pair of loose vectors because queries travel in batches, and a batch of
- * `[origin, direction, origin, direction, …]` is a shape that goes wrong silently.
- */
-export class PickingQuery {
-    /**
-     * Where the ray starts, in world space.
-     *
-     * @type {Vector3}
-     */
-    origin = new Vector3();
-
-    /**
-     * Which way it goes. Must be unit length — distances in the result are measured along it, so a
-     * direction of any other length rescales every one of them.
-     *
-     * @type {Vector3}
-     */
-    direction = new Vector3();
-
-    /**
-     * How far along the ray to look. Everything beyond is not a hit, which is how a caller asks
-     * "within reach" rather than "anywhere in the world".
-     *
-     * @type {number}
-     */
-    max_distance = Infinity;
-
-    /**
-     * @param {Vector3} origin
-     * @param {Vector3} direction unit length
-     * @param {number} [max_distance]
-     * @returns {PickingQuery}
-     */
-    static from(origin, direction, max_distance = Infinity) {
-        const r = new PickingQuery();
-
-        r.origin.copy(origin);
-        r.direction.copy(direction);
-        r.max_distance = max_distance;
-
-        return r;
-    }
-}
+import Vector3 from "../../core/geom/Vector3.js";
+
+/**
+ * One ray to be answered by {@link PickingSystem#pick}.
+ *
+ * A type rather than a pair of loose vectors because queries travel in batches, and a batch of
+ * `[origin, direction, origin, direction, …]` is a shape that goes wrong silently.
+ */
+export class PickingQuery {
+    /**
+     * Where the ray starts, in world space.
+     *
+     * @type {Vector3}
+     */
+    origin = new Vector3();
+
+    /**
+     * Which way it goes. Must be unit length — distances in the result are measured along it, so a
+     * direction of any other length rescales every one of them.
+     *
+     * @type {Vector3}
+     */
+    direction = new Vector3();
+
+    /**
+     * How far along the ray to look. Everything beyond is not a hit, which is how a caller asks
+     * "within reach" rather than "anywhere in the world".
+     *
+     * @type {number}
+     */
+    max_distance = Infinity;
+
+    /**
+     * @param {Vector3} origin
+     * @param {Vector3} direction unit length
+     * @param {number} [max_distance]
+     * @returns {PickingQuery}
+     */
+    static from(origin, direction, max_distance = Infinity) {
+        const r = new PickingQuery();
+
+        r.origin.copy(origin);
+        r.direction.copy(direction);
+        r.max_distance = max_distance;
+
+        return r;
+    }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Answers "what is under this ray" for entities that asked to be pickable.
+ *
+ * **Asynchronous and batched from the first line, on purpose (I-9).** The backend here is a CPU
+ * bounding-volume hierarchy and could answer synchronously; the API does not let it, because the
+ * backend this is meant to grow into reads entity ids back off the GPU's visibility buffer, and that
+ * answer is inherently a frame late and arrives for a whole batch at once. A synchronous entry point
+ * would have to be broken to get there, and every caller broken with it.
+ *
+ * **Bounding boxes, not triangles.** A hit means the ray entered the entity's world bounding box.
+ * That is the precision this can offer for free — Shade maintains those boxes as part of drawing —
+ * and going finer means keeping CPU-side triangles for every pickable entity, which is the
+ * duplication {@link Pickable} exists to keep small. Terrain picking, which is where the game's
+ * precision actually matters, does not come through here at all: it is an exact raycast against the
+ * terrain's own representation and is untouched by any of this.
+ *
+ * The index is refreshed **on query rather than per frame**. Nothing pays for picking on a frame where
+ * nobody picks, and there is no window in which the index disagrees with the scene, so no class of
+ * bug where a pick lands on where something used to be.
+ */
+export class PickingSystem extends System<any> {
+    /**
+     * @param {MeshSystem} meshes what an entity looks like, which is where its bounds come from
+     */
+    constructor(meshes: MeshSystem);
+    dependencies: (typeof Transform | typeof Pickable)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {Pickable} pickable
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(pickable: Pickable, transform: Transform, entity: number): void;
+    /**
+     * @param {Pickable} pickable
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(pickable: Pickable, transform: Transform, entity: number): void;
+    /**
+     * How many entities the index currently stands for.
+     *
+     * The index is built on query, so this is zero until the first {@link pick} — and stays behind by
+     * however many pickable entities are still waiting on their models.
+     *
+     * @returns {number}
+     */
+    get indexed_count(): number;
+    /**
+     * What each of these rays hits first.
+     *
+     * One result per query, in the order the queries were given. A ray that hits nothing still gets a
+     * result — `entity` is {@link PickingResult.NOTHING} — so the two arrays line up by position and a
+     * caller never has to search for the answer to its own question.
+     *
+     * @param {PickingQuery[]} queries
+     * @returns {Promise<PickingResult[]>}
+     */
+    pick(queries: PickingQuery[]): Promise<PickingResult[]>;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { Pickable } from "./Pickable.js";
+import { PickingResult } from "./PickingResult.js";
+//# sourceMappingURL=PickingSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PickingSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PickingSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA2BI;;OAEG;IACH,gCAQC;IADG,qDAAyC;IAG7C,2CAEC;IAED,4CAMC;IAED;;;;OAIG;IACH,eAJW,QAAQ,aACR,SAAS,UACT,MAAM,QAMhB;IAED;;;;OAIG;IACH,iBAJW,QAAQ,aACR,SAAS,UACT,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,QAAQ,aAAa,EAAE,CAAC,CAcpC;;CAiIJ;uBAzQsB,kBAAkB;0BACf,+BAA+B;yBAChC,eAAe;8BACV,oBAAoB"}