@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -0,0 +1,70 @@
+/**
+ * Draws {@link PathDisplay}'s tubes under Shade, on the dynamic-geometry path.
+ *
+ * **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.
+ */
+export class PathDisplaySystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    dependencies: (typeof Path | typeof PathDisplay)[];
+    /**
+     * What the pass draws. Read-only — the meshes follow the entities.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch(): DynamicMeshBatch;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {PathDisplay} display
+     * @param {Path} path
+     * @param {number} entity
+     */
+    link(display: PathDisplay, path: Path, entity: number): void;
+    /**
+     * @param {PathDisplay} display
+     * @param {Path} path
+     * @param {number} entity
+     */
+    unlink(display: PathDisplay, path: Path, entity: number): void;
+    update(timeDelta: any): void;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * 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 {
+    /**
+     * @param {PathDisplaySystem} system
+     */
+    constructor(system: PathDisplaySystem);
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import Path from "../navigation/ecs/components/Path.js";
+import { PathDisplay } from "../graphics/ecs/path/PathDisplay.js";
+import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+//# sourceMappingURL=PathDisplaySystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PathDisplaySystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PathDisplaySystem.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA8CI;;OAEG;IACH,sCAMC;IAtDD,mDAAmC;IAoCnC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAYC;IAED;;;;OAIG;IACH,cAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAehB;IAED;;;;OAIG;IACH,gBAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAkBhB;IAED,6BAgBC;IAwFD;;OAEG;IACH,kCAeC;;CACJ;AAED;;;GAGG;AACH;IAUI;;OAEG;IACH,oBAFW,iBAAiB,EAM3B;IAED,yBAEC;;CACJ;uBA3SsB,kBAAkB;iBAIxB,sCAAsC;4BAH3B,qCAAqC;iCAFhC,gDAAgD;gCAJjD,mDAAmD"}

package/src/engine/graphics3/PathDisplaySystem.js

@@ -0,0 +1,309 @@
+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";
+
+/**
+ * Draws {@link PathDisplay}'s tubes under Shade, on the dynamic-geometry path.
+ *
+ * **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.
+ */
+export class PathDisplaySystem extends System {
+    dependencies = [PathDisplay, Path];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #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 {GraphicsEngine} 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 {PathDisplaySystem}
+     */
+    #system;
+
+    /**
+     * @param {PathDisplaySystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -1,70 +1,10 @@
 /**
- * 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.
- */
-export class PathDisplaySystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics: GraphicsEngine3);
-    dependencies: (typeof Path | typeof PathDisplay)[];
-    /**
-     * What the pass draws. Read-only — the meshes follow the entities.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch(): DynamicMeshBatch;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {PathDisplay} display
-     * @param {Path} path
-     * @param {number} entity
-     */
-    link(display: PathDisplay, path: Path, entity: number): void;
-    /**
-     * @param {PathDisplay} display
-     * @param {Path} path
-     * @param {number} entity
-     */
-    unlink(display: PathDisplay, path: Path, entity: number): void;
-    update(timeDelta: any): void;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * 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.
+ * 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 PathDisplayExtension extends RenderExtension {
-    /**
-     * @param {PathDisplaySystem3} system
-     */
-    constructor(system: PathDisplaySystem3);
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import Path from "../navigation/ecs/components/Path.js";
-import { PathDisplay } from "../graphics/ecs/path/PathDisplay.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+export const PathDisplaySystem3: typeof PathDisplaySystem;
+import { PathDisplaySystem } from "./PathDisplaySystem.js";
 //# sourceMappingURL=PathDisplaySystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PathDisplaySystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PathDisplaySystem3.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA8CI;;OAEG;IACH,uCAMC;IAtDD,mDAAmC;IAoCnC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAYC;IAED;;;;OAIG;IACH,cAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAehB;IAED;;;;OAIG;IACH,gBAJW,WAAW,QACX,IAAI,UACJ,MAAM,QAkBhB;IAED,6BAgBC;IAwFD;;OAEG;IACH,kCAeC;;CACJ;AAED;;;GAGG;AACH;IAUI;;OAEG;IACH,oBAFW,kBAAkB,EAM5B;IAED,yBAEC;;CACJ;uBA3SsB,kBAAkB;iBAIxB,sCAAsC;4BAH3B,qCAAqC;iCAFhC,gDAAgD;gCAJjD,mDAAmD"}
+{"version":3,"file":"PathDisplaySystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/PathDisplaySystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,0DAAoD;kCATlB,wBAAwB"}