@woosh/meep-engine 3.13.1 → 3.14.0

package/src/engine/graphics/ecs/highlight/system/ShadedGeometryHighlightSystem.js

@@ -0,0 +1,109 @@
+import { assert } from "../../../../../core/assert.js";
+import { System } from "../../../../ecs/System.js";
+import Highlight from "../Highlight.js";
+import { ShadedGeometry } from "../../mesh-v2/ShadedGeometry.js";
+
+/**
+ * Outlines a highlighted primitive — one that is not a model.
+ *
+ * **A `ShadedGeometry` is not an `SGMesh`, and {@link SGMeshHighlightSystem} reads only the latter.**
+ * A model is a file that expanded into entities, and the highlight sits on the root; a primitive is
+ * a geometry and a material some tool built directly, and the highlight sits on the thing itself.
+ * This tuple was the last `HighlightSystemBase` subclass still standing when the three renderer was
+ * deleted, and it went with it — so between then and now, everything built rather than loaded had no
+ * outline. This file is that path restored, at the import path it used to occupy.
+ *
+ * **It is a second source, not a second pass.** Everything about drawing the outline —
+ * the pass, the lookup table, the renderer — belongs to {@link HighlightOutlineSystem}, and this
+ * contributes entries to it through {@link HighlightOutlineSystem#add_entry}. Two passes would each
+ * read the whole visibility buffer and the later would paint over the earlier's outline wherever
+ * they named the same row.
+ *
+ * The walk is one node, because that is what the component is: `ShadedGeometry` is *"not a
+ * hierarchical data structure"* in its own words, and `ShadedGeometrySystem` gives it exactly one
+ * row. A primitive whose system has not linked it yet has no node and contributes nothing, which is
+ * the same silence every other reader of `ShadedGeometry.node` already tolerates.
+ */
+export class ShadedGeometryHighlightSystem extends System {
+    dependencies = [Highlight, ShadedGeometry];
+
+    /**
+     * @type {HighlightOutlineSystem}
+     */
+    #outline;
+
+    /**
+     * The entry each highlighted primitive has with {@link #outline}, which is the only handle on
+     * it: an entity that is both a model and a primitive has an entry from each contributing system,
+     * so the shared list cannot be keyed by entity and each contributor remembers its own.
+     *
+     * @type {Map<number, object>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {HighlightOutlineSystem} outline the system that owns the outline pass
+     */
+    constructor(outline) {
+        super();
+
+        assert.defined(outline, 'outline');
+
+        this.#outline = outline;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        /*
+         Handing every entry back rather than trusting the outline system to have cleared its list
+         makes shutdown order between the two free — and `remove_entry` tolerates an entry that is
+         already gone, which is the case when the outline system went down first.
+        */
+        for (const entry of this.#entries.values()) {
+            this.#outline.remove_entry(entry);
+        }
+
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    link(highlight, geometry, entity) {
+        const entry = this.#outline.add_entry(entity, highlight, visitor => {
+            const node = geometry.node;
+
+            if (node === null || node === undefined) {
+                // not in the scene: either `ShadedGeometrySystem` has not linked it yet, or it is
+                // not running at all, and neither is this system's to complain about
+                return;
+            }
+
+            visitor(node);
+        });
+
+        this.#entries.set(entity, entry);
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    unlink(highlight, geometry, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        this.#outline.remove_entry(entry);
+    }
+}

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.d.ts

@@ -1,34 +1,46 @@
+/**
+ * Outlines a highlighted model.
+ *
+ * **The rows come from `MeshSystem`, because a model's nodes are its.** An `SGMesh` is a file, and
+ * what a file becomes in the scene is several nodes — instanced ones the mesh system holds, plus the
+ * primitives of an expanded model, which are components on descendant entities. `traverse_meshes`
+ * answers for both, so this system asks one question per highlight and does not care which kind of
+ * model it got.
+ *
+ * **What it no longer does is push the component downwards.** The system this replaces copied the
+ * `Highlight` onto every entity the model expanded into, so that the system watching
+ * `[Highlight, ShadedGeometry]` would find them — the walk existed because nothing else could see a
+ * model whole. `MeshSystem.traverse_meshes` can, so the propagation buys nothing, and the
+ * `SGMesh.__node` / `SGMeshEvents.AssetLoaded` pair it was driven by has had nothing writing to it
+ * since `SGMeshSystem`. The name and the tuple are the same; the mechanism underneath is Shade's.
+ *
+ * The drawing is not here — see {@link HighlightOutlineSystem}, which this contributes entries to
+ * alongside {@link ShadedGeometryHighlightSystem}. One outline pass reads the whole visibility
+ * buffer, so a pass per kind of highlighted thing would read it once per kind and the last would
+ * paint over the rest.
+ */
 export class SGMeshHighlightSystem extends System<any> {
-    constructor();
-    dependencies: (typeof SGMesh | typeof Highlight)[];
-    /**
-     *
-     * @param event
-     * @param {number} entity
-     * @private
-     */
-    private __apply_highlight;
     /**
-     *
-     * @param event
-     * @param {number} entity
-     * @private
+     * @param {HighlightOutlineSystem} outline the system that owns the outline pass
+     * @param {MeshSystem} meshes resolves an entity to the nodes its model has in the scene
      */
-    private __remove_highlight;
+    constructor(outline: HighlightOutlineSystem, meshes: MeshSystem);
+    dependencies: (typeof SGMesh | typeof Highlight)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
     /**
-     *
      * @param {Highlight} highlight
      * @param {SGMesh} mesh
      * @param {number} entity
      */
     link(highlight: Highlight, mesh: SGMesh, entity: number): void;
     /**
-     *
      * @param {Highlight} highlight
      * @param {SGMesh} mesh
      * @param {number} entity
      */
     unlink(highlight: Highlight, mesh: SGMesh, entity: number): void;
+    #private;
 }
 import { System } from "../../../../ecs/System.js";
 import { SGMesh } from "./SGMesh.js";

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SGMeshHighlightSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js"],"names":[],"mappings":"AAKA;;IACI,mDAAmC;IAEnC;;;;;OAKG;IACH,0BA0BC;IAED;;;;;OAKG;IACH,2BAWC;IAED;;;;;OAKG;IACH,gBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAUhB;IAED;;;;;OAKG;IACH,kBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAShB;CACJ;uBA3FsB,2BAA2B;uBAE3B,aAAa;sBADd,8BAA8B"}
+{"version":3,"file":"SGMeshHighlightSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAsBI;;;OAGG;IACH,iEAQC;IAjCD,mDAAmC;IAmCnC,2CAEC;IAED,4CAWC;IAED;;;;OAIG;IACH,gBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAUhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAYhB;;CACJ;uBA7GsB,2BAA2B;uBAE3B,aAAa;sBADd,8BAA8B"}

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js

@@ -1,92 +1,111 @@
-import { System } from "../../../../ecs/System.js";
-import Highlight from "../../highlight/Highlight.js";
-import { SGMesh } from "./SGMesh.js";
-import { SGMeshEvents } from "./SGMeshEvents.js";
-
-export class SGMeshHighlightSystem extends System {
-    dependencies = [Highlight, SGMesh];
-
-    /**
-     *
-     * @param event
-     * @param {number} entity
-     * @private
-     */
-    __apply_highlight(event, entity) {
-        const ecd = this.entityManager.dataset;
-
-        const sg_mesh = ecd.getComponent(entity, SGMesh);
-
-        if (sg_mesh === undefined) {
-            return;
-        }
-
-        const highlight = ecd.getComponent(entity, Highlight);
-
-        if (highlight === undefined) {
-            return;
-        }
-
-        const node = sg_mesh.__node;
-
-        if (node === null) {
-            // not loaded yet
-            console.warn(`SGMesh is not loaded yet: ${sg_mesh.url}`);
-            return;
-        }
-
-        node.traverse(t => {
-            t.entity.add(highlight);
-        });
-    }
-
-    /**
-     *
-     * @param event
-     * @param {number} entity
-     * @private
-     */
-    __remove_highlight(event, entity) {
-
-        const ecd = this.entityManager.dataset;
-
-        const sg_mesh = ecd.getComponent(entity, SGMesh);
-
-        const node = sg_mesh.__node;
-
-        node.traverse(t => {
-            t.entity.removeComponent(Highlight);
-        });
-    }
-
-    /**
-     *
-     * @param {Highlight} highlight
-     * @param {SGMesh} mesh
-     * @param {number} entity
-     */
-    link(highlight, mesh, entity) {
-        if (mesh.__node !== null) {
-            this.__apply_highlight(undefined, entity);
-        }
-
-        const ecd = this.entityManager.dataset;
-
-        ecd.addEntityEventListener(entity, SGMeshEvents.AssetLoaded, this.__apply_highlight, this);
-    }
-
-    /**
-     *
-     * @param {Highlight} highlight
-     * @param {SGMesh} mesh
-     * @param {number} entity
-     */
-    unlink(highlight, mesh, entity) {
-        const ecd = this.entityManager.dataset;
-        ecd.removeEntityEventListener(entity, SGMeshEvents.AssetLoaded, this.__apply_highlight, this);
-
-        if (mesh.__node !== null) {
-            this.__remove_highlight(undefined, entity);
-        }
-    }
-}
+import { assert } from "../../../../../core/assert.js";
+import { System } from "../../../../ecs/System.js";
+import Highlight from "../../highlight/Highlight.js";
+import { SGMesh } from "./SGMesh.js";
+
+/**
+ * Outlines a highlighted model.
+ *
+ * **The rows come from `MeshSystem`, because a model's nodes are its.** An `SGMesh` is a file, and
+ * what a file becomes in the scene is several nodes — instanced ones the mesh system holds, plus the
+ * primitives of an expanded model, which are components on descendant entities. `traverse_meshes`
+ * answers for both, so this system asks one question per highlight and does not care which kind of
+ * model it got.
+ *
+ * **What it no longer does is push the component downwards.** The system this replaces copied the
+ * `Highlight` onto every entity the model expanded into, so that the system watching
+ * `[Highlight, ShadedGeometry]` would find them — the walk existed because nothing else could see a
+ * model whole. `MeshSystem.traverse_meshes` can, so the propagation buys nothing, and the
+ * `SGMesh.__node` / `SGMeshEvents.AssetLoaded` pair it was driven by has had nothing writing to it
+ * since `SGMeshSystem`. The name and the tuple are the same; the mechanism underneath is Shade's.
+ *
+ * The drawing is not here — see {@link HighlightOutlineSystem}, which this contributes entries to
+ * alongside {@link ShadedGeometryHighlightSystem}. One outline pass reads the whole visibility
+ * buffer, so a pass per kind of highlighted thing would read it once per kind and the last would
+ * paint over the rest.
+ */
+export class SGMeshHighlightSystem extends System {
+    dependencies = [Highlight, SGMesh];
+
+    /**
+     * @type {HighlightOutlineSystem}
+     */
+    #outline;
+
+    /**
+     * @type {MeshSystem}
+     */
+    #meshes;
+
+    /**
+     * The entry each highlighted model has with {@link #outline}, which is the only handle on it: an
+     * entity that is both a model and a primitive has an entry from each contributing system, so the
+     * shared list cannot be keyed by entity and each contributor remembers its own.
+     *
+     * @type {Map<number, object>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {HighlightOutlineSystem} outline the system that owns the outline pass
+     * @param {MeshSystem} meshes resolves an entity to the nodes its model has in the scene
+     */
+    constructor(outline, meshes) {
+        super();
+
+        assert.defined(outline, 'outline');
+        assert.defined(meshes, 'meshes');
+
+        this.#outline = outline;
+        this.#meshes = meshes;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        /*
+         Handing every entry back rather than trusting the outline system to have cleared its list
+         makes shutdown order between the two free — and `remove_entry` tolerates an entry that is
+         already gone, which is the case when the outline system went down first.
+        */
+        for (const entry of this.#entries.values()) {
+            this.#outline.remove_entry(entry);
+        }
+
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {SGMesh} mesh
+     * @param {number} entity
+     */
+    link(highlight, mesh, entity) {
+        const entry = this.#outline.add_entry(
+            entity,
+            highlight,
+            visitor => this.#meshes.traverse_meshes(entity, visitor)
+        );
+
+        this.#entries.set(entity, entry);
+    }
+
+    /**
+     * @param {Highlight} highlight
+     * @param {SGMesh} mesh
+     * @param {number} entity
+     */
+    unlink(highlight, mesh, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        this.#outline.remove_entry(entry);
+    }
+}

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

@@ -67,7 +67,7 @@ import { System } from "../ecs/System.js";
 import Terrain from "../ecs/terrain/ecs/Terrain.js";
 import { FogOfWar } from "../ecs/fow/FogOfWar.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { HighlightExtension } from "./HighlightSystem.js";
+import { HighlightExtension } from "./HighlightOutlineSystem.js";
 import { ParticleExtension } from "./ParticleEmitterSystem.js";
 import { PathDisplayExtension } from "./PathDisplaySystem.js";
 import { TrailExtension } from "./Trail3DSystem.js";

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

@@ -1 +1 @@
-{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/FogOfWarSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;GAYG;AACH;IAwCI;;OAEG;IACH,sCAMC;IAhDD,mDAAmC;IA8BnC;;;;OAIG;IACH,yBAEC;IAaD,2CAIC;IAED,4CAeC;IAED;;OAEG;IACH,kCAwBC;IAED;;;;OAIG;IACH,UAJW,QAAQ,WACR,OAAO,UACP,MAAM,QA8BhB;IAED;;;;OAIG;IACH,YAJW,QAAQ,WACR,OAAO,UACP,MAAM,QAkBhB;IAED,6BASC;;CA4BJ;AAED;;;;;;;;;GASG;AACH;IAYI;;OAEG;IACH,oBAFW,cAAc,EAMxB;IAdD,sHAAsF;IAgBtF,yBAEC;;CACJ;uBAzPsB,kBAAkB;oBADrB,+BAA+B;yBAH1B,wBAAwB;gCAHjB,mDAAmD;mCALhD,sBAAsB;kCACvB,4BAA4B;qCACzB,wBAAwB;+BAC9B,oBAAoB"}
+{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/FogOfWarSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;GAYG;AACH;IAwCI;;OAEG;IACH,sCAMC;IAhDD,mDAAmC;IA8BnC;;;;OAIG;IACH,yBAEC;IAaD,2CAIC;IAED,4CAeC;IAED;;OAEG;IACH,kCAwBC;IAED;;;;OAIG;IACH,UAJW,QAAQ,WACR,OAAO,UACP,MAAM,QA8BhB;IAED;;;;OAIG;IACH,YAJW,QAAQ,WACR,OAAO,UACP,MAAM,QAkBhB;IAED,6BASC;;CA4BJ;AAED;;;;;;;;;GASG;AACH;IAYI;;OAEG;IACH,oBAFW,cAAc,EAMxB;IAdD,sHAAsF;IAgBtF,yBAEC;;CACJ;uBAzPsB,kBAAkB;oBADrB,+BAA+B;yBAH1B,wBAAwB;gCAHjB,mDAAmD;mCALhD,6BAA6B;kCAC9B,4BAA4B;qCACzB,wBAAwB;+BAC9B,oBAAoB"}

package/src/engine/graphics3/FogOfWarSystem.js

@@ -1,7 +1,7 @@
 import { assert } from "../../core/assert.js";
 import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
 import { GPUFogOfWarRenderer } from "../../shade/renderer/fow/GPUFogOfWarRenderer.js";
-import { HighlightExtension } from "./HighlightSystem.js";
+import { HighlightExtension } from "./HighlightOutlineSystem.js";
 import { ParticleExtension } from "./ParticleEmitterSystem.js";
 import { PathDisplayExtension } from "./PathDisplaySystem.js";
 import { TrailExtension } from "./Trail3DSystem.js";

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

@@ -0,0 +1,99 @@
+/**
+ * Draws the outline, for everything that is highlighted.
+ *
+ * **An outline is a neighbourhood test on the visibility buffer**, which already says which mesh
+ * every pixel came from. The renderer this replaces drew each highlighted object a second time into
+ * an id target of its own, dilated the mask across two ping-ponged render targets, blurred it, and
+ * decoded ids back to colours — five render targets and a duplicated scene graph, for a picture this
+ * gets from a texture the frame was already writing.
+ *
+ * **Highlights no longer show through what stands in front of them (D27).** The old id pass cleared
+ * the depth buffer, so a unit behind a building was outlined in full; the visibility buffer knows
+ * only what was rasterized, so it is outlined where it can be seen and nowhere else. That is the
+ * accepted cost of not drawing the scene twice.
+ *
+ * The table is rebuilt every frame, and that is the cheaper arrangement rather than a concession:
+ * the game's highlights animate their colour and alpha continuously (0.2 s in, 0.7 s out), so
+ * nothing would be saved by watching for changes — and a `Color`'s change signal does not fire for
+ * alpha-only edits, which is exactly what this animation is.
+ *
+ * **It observes no entities, which is why it is one pass and not one pass per kind of highlighted
+ * thing.** What an entity has in the scene depends on what kind of thing it is — a model's rows
+ * come from `MeshSystem`, a primitive's from its own component — and a system per pairing is how
+ * that stays legible. But there is nothing to draw twice: the outline reads the whole visibility
+ * buffer once, so a second pass would read it again and paint over the first wherever the two named
+ * the same row. So the pairings are systems and the drawing is here, and they meet at
+ * {@link add_entry}. `SGMeshHighlightSystem` and `ShadedGeometryHighlightSystem` are the two.
+ */
+export class HighlightOutlineSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics: GraphicsEngine);
+    /**
+     * No tuple. `System` allows this and drives such a system purely from startup and shutdown,
+     * which is exactly what owning a render pass needs — the entities are the contributing systems'
+     * business.
+     *
+     * @type {Array}
+     */
+    dependencies: any[];
+    /**
+     * How wide the outline is drawn, in pixels.
+     *
+     * @type {number}
+     */
+    thickness: number;
+    /**
+     * What is highlighted. Read-only — highlights follow their entities.
+     *
+     * @returns {Array}
+     */
+    get highlights(): any[];
+    /**
+     * @returns {Uint32Array} the table the last update packed
+     */
+    get table(): Uint32Array;
+    /**
+     * @returns {number} rows of {@link table} in use
+     */
+    get table_size(): number;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * Outline a highlight whose rows the caller knows how to find.
+     *
+     * @param {number} entity for reading back through {@link highlights}; nothing here resolves it
+     * @param {Highlight} highlight read every frame, so its animation is followed without being watched
+     * @param {function(function(Mesh): void): void} traverse visits the scene nodes this highlight
+     * covers, and visits none of them while they are still loading
+     * @returns {object} the entry — hand it back to {@link remove_entry}, which is the only handle
+     * on it: an entity that is both a model and a primitive contributes one entry per system, so an
+     * entity is not a key here
+     */
+    add_entry(entity: number, highlight: Highlight, traverse: (arg0: (arg0: Mesh) => void) => void): object;
+    /**
+     * @param {object} entry as returned by {@link add_entry}. One this system no longer holds is not
+     * an error, which is what leaves shutdown order between the contributing systems free.
+     */
+    remove_entry(entry: object): void;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    #private;
+}
+/**
+ * The outline is drawn into the scene, so the fog of war conceals it along with what it outlines.
+ */
+export class HighlightExtension extends RenderExtension {
+    /**
+     * @param {HighlightOutlineSystem} system
+     */
+    constructor(system: HighlightOutlineSystem);
+    record(frame: any): void;
+    #private;
+}
+import { System } from "../ecs/System.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+//# sourceMappingURL=HighlightOutlineSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HighlightOutlineSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/HighlightOutlineSystem.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IA2EI;;OAEG;IACH,sCAMC;IAnFD;;;;;;OAMG;IACH,oBAAkB;IAqClB;;;;OAIG;IACH,WAFU,MAAM,CAEwB;IAExC;;;;OAIG;IACH,wBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAaD,2CAIC;IAED,4CAWC;IAED;;;;;;;;;;OAUG;IACH,kBARW,MAAM,yDAEmB,IAAI,KAAG,IAAI,GAElC,MAAM,CAUlB;IAED;;;OAGG;IACH,oBAHW,MAAM,QAWhB;IAkBD;;OAEG;IACH,kCAmBC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,sBAAsB,EAMhC;IAED,yBAEC;;CACJ;uBA5OsB,kBAAkB;gCADT,mDAAmD"}