@woosh/meep-engine 3.13.0 → 3.14.0

package/src/engine/graphics3/HighlightOutlineSystem.js

@@ -0,0 +1,240 @@
+import { assert } from "../../core/assert.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { System } from "../ecs/System.js";
+import { GPUHighlightRenderer } from "./highlight/GPUHighlightRenderer.js";
+import { HIGHLIGHT_OUTLINE_THICKNESS } from "./highlight/HIGHLIGHT_OUTLINE.js";
+import { pack_highlight_table } from "./highlight/pack_highlight_table.js";
+
+/**
+ * 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 {
+    /**
+     * 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 = [];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUHighlightRenderer}
+     */
+    #renderer = new GPUHighlightRenderer();
+
+    /**
+     * What is highlighted, in the order it was contributed. Each entry carries the walk to its own
+     * rows — see {@link add_entry}.
+     *
+     * @type {Array<{entity: number, highlight: Highlight, traverse: function(function(Mesh): void): void}>}
+     */
+    #entries = [];
+
+    /**
+     * One packed rgba8 colour per mesh row, indexed by the row the visibility buffer writes.
+     *
+     * @type {Uint32Array}
+     */
+    #table = new Uint32Array(0);
+
+    /**
+     * @type {number}
+     */
+    #table_size = 0;
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * How wide the outline is drawn, in pixels.
+     *
+     * @type {number}
+     */
+    thickness = HIGHLIGHT_OUTLINE_THICKNESS;
+
+    /**
+     * What is highlighted. Read-only — highlights follow their entities.
+     *
+     * @returns {Array}
+     */
+    get highlights() {
+        return this.#entries;
+    }
+
+    /**
+     * @returns {Uint32Array} the table the last update packed
+     */
+    get table() {
+        return this.#table;
+    }
+
+    /**
+     * @returns {number} rows of {@link table} in use
+     */
+    get table_size() {
+        return this.#table_size;
+    }
+
+    /**
+     * @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 HighlightExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#renderer.destroy();
+
+        this.#entries.length = 0;
+        this.#table_size = 0;
+    }
+
+    /**
+     * 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, highlight, traverse) {
+        const entry = { entity, highlight, traverse };
+
+        this.#entries.push(entry);
+
+        return entry;
+    }
+
+    /**
+     * @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) {
+        const index = this.#entries.indexOf(entry);
+
+        if (index === -1) {
+            return;
+        }
+
+        this.#entries.splice(index, 1);
+    }
+
+    /**
+     * Pack this frame's table. See {@link pack_highlight_table} for why it is every frame.
+     *
+     * @param {GPUSceneContext} scene
+     */
+    #pack(scene) {
+        const packed = pack_highlight_table({
+            entries: this.#entries,
+            scene,
+            table: this.#table
+        });
+
+        this.#table = packed.table;
+        this.#table_size = packed.size;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (this.#entries.length === 0) {
+            // nothing highlighted, so the frame keeps the colour it had and pays nothing
+            return;
+        }
+
+        this.#pack(frame.view.scene);
+
+        if (this.#table_size === 0) {
+            // highlighted entities whose models are not in the scene yet
+            return;
+        }
+
+        this.#renderer.graph_draw({
+            frame,
+            table: this.#table,
+            table_size: this.#table_size,
+            thickness: this.thickness
+        });
+    }
+}
+
+/**
+ * The outline is drawn into the scene, so the fog of war conceals it along with what it outlines.
+ */
+export class HighlightExtension extends RenderExtension {
+    name = "highlight";
+
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {HighlightOutlineSystem}
+     */
+    #system;
+
+    /**
+     * @param {HighlightOutlineSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -1,82 +1,19 @@
 /**
- * Outlines highlighted entities under Shade.
+ * @deprecated Renamed to {@link SGMeshHighlightSystem} and moved back beside the component it reads.
+ * The name said "highlight" where the tuple says `[Highlight, SGMesh]`, and one of the two systems
+ * that outline things is not the highlight system.
  *
- * **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.
+ * **The class behind this name no longer owns the outline pass**, so a constructor call does not
+ * survive the rename: it is now `new SGMeshHighlightSystem(outline, meshes)` against a
+ * {@link HighlightOutlineSystem}, which is registered alongside it and does the drawing for every
+ * kind of highlighted thing. That is a change no alias can absorb — this one keeps `instanceof` and
+ * `EntityManager.getSystem` answering for callers still holding the old name.
  *
- * **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.
- */
-export class HighlightSystem extends System<any> {
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {MeshSystem} meshes
-     */
-    constructor(graphics: GraphicsEngine, meshes: MeshSystem);
-    dependencies: (typeof SGMesh | typeof Highlight)[];
-    /**
-     * 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>;
-    /**
-     * @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;
-    /**
-     * @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.
+ * 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 HighlightExtension extends RenderExtension {
-    /**
-     * @param {HighlightSystem} system
-     */
-    constructor(system: HighlightSystem);
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import Highlight from "../graphics/ecs/highlight/Highlight.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+export const HighlightSystem: typeof SGMeshHighlightSystem;
+export { HighlightExtension };
+import { SGMeshHighlightSystem } from "../graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js";
+import { HighlightExtension } from "./HighlightOutlineSystem.js";
 //# sourceMappingURL=HighlightSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"HighlightSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/HighlightSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA6EI;;;OAGG;IACH,0DAQC;IAxFD,mDAAmC;IA8CnC;;;;OAIG;IACH,WAFU,MAAM,CAEwB;IAExC;;;;OAIG;IACH,wBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAgBD,2CAIC;IAED,4CAYC;IAED;;;;OAIG;IACH,gBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAOhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,QACT,MAAM,UACN,MAAM,QAgBhB;IAmBD;;OAEG;IACH,kCAmBC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,eAAe,EAMzB;IAED,yBAEC;;CACJ;uBA7OsB,kBAAkB;uBAElB,6CAA6C;sBAD9C,wCAAwC;gCAF9B,mDAAmD"}
+{"version":3,"file":"HighlightSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/HighlightSystem.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,2DAAqD;;sCAjB9C,4DAA4D;mCAChC,6BAA6B"}

package/src/engine/graphics3/HighlightSystem.js

@@ -1,241 +1,27 @@
-import { assert } from "../../core/assert.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { System } from "../ecs/System.js";
-import Highlight from "../graphics/ecs/highlight/Highlight.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import { GPUHighlightRenderer } from "./highlight/GPUHighlightRenderer.js";
-import { HIGHLIGHT_OUTLINE_THICKNESS } from "./highlight/HIGHLIGHT_OUTLINE.js";
-import { pack_highlight_table } from "./highlight/pack_highlight_table.js";
+import {
+    SGMeshHighlightSystem
+} from "../graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js";
+import { HighlightExtension } from "./HighlightOutlineSystem.js";
 
 /**
- * Outlines highlighted entities under Shade.
+ * @deprecated Renamed to {@link SGMeshHighlightSystem} and moved back beside the component it reads.
+ * The name said "highlight" where the tuple says `[Highlight, SGMesh]`, and one of the two systems
+ * that outline things is not the highlight system.
  *
- * **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.
+ * **The class behind this name no longer owns the outline pass**, so a constructor call does not
+ * survive the rename: it is now `new SGMeshHighlightSystem(outline, meshes)` against a
+ * {@link HighlightOutlineSystem}, which is registered alongside it and does the drawing for every
+ * kind of highlighted thing. That is a change no alias can absorb — this one keeps `instanceof` and
+ * `EntityManager.getSystem` answering for callers still holding the old name.
  *
- * **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.
+ * 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 HighlightSystem extends System {
-    dependencies = [Highlight, SGMesh];
-
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {MeshSystem}
-     */
-    #meshes;
-
-    /**
-     * @type {GPUHighlightRenderer}
-     */
-    #renderer = new GPUHighlightRenderer();
-
-    /**
-     * Highlighted entities, in link order.
-     *
-     * @type {Array<{entity: number, highlight: Highlight}>}
-     */
-    #entries = [];
-
-    /**
-     * @type {Map<number, object>}
-     */
-    #by_entity = new Map();
-
-    /**
-     * One packed rgba8 colour per mesh row, indexed by the row the visibility buffer writes.
-     *
-     * @type {Uint32Array}
-     */
-    #table = new Uint32Array(0);
-
-    /**
-     * @type {number}
-     */
-    #table_size = 0;
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * How wide the outline is drawn, in pixels.
-     *
-     * @type {number}
-     */
-    thickness = HIGHLIGHT_OUTLINE_THICKNESS;
-
-    /**
-     * What is highlighted. Read-only — highlights follow their entities.
-     *
-     * @returns {Array}
-     */
-    get highlights() {
-        return this.#entries;
-    }
-
-    /**
-     * @returns {Uint32Array} the table the last update packed
-     */
-    get table() {
-        return this.#table;
-    }
-
-    /**
-     * @returns {number} rows of {@link table} in use
-     */
-    get table_size() {
-        return this.#table_size;
-    }
-
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {MeshSystem} meshes
-     */
-    constructor(graphics, meshes) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(meshes, 'meshes');
-
-        this.#graphics = graphics;
-        this.#meshes = meshes;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new HighlightExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        this.#entries.length = 0;
-        this.#by_entity.clear();
-        this.#table_size = 0;
-    }
-
-    /**
-     * @param {Highlight} highlight
-     * @param {SGMesh} mesh
-     * @param {number} entity
-     */
-    link(highlight, mesh, entity) {
-        const entry = { entity, highlight };
-
-        this.#entries.push(entry);
-        this.#by_entity.set(entity, entry);
-    }
-
-    /**
-     * @param {Highlight} highlight
-     * @param {SGMesh} mesh
-     * @param {number} entity
-     */
-    unlink(highlight, mesh, entity) {
-        const entry = this.#by_entity.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        const index = this.#entries.indexOf(entry);
-
-        if (index !== -1) {
-            this.#entries.splice(index, 1);
-        }
-
-        this.#by_entity.delete(entity);
-    }
-
-    /**
-     * Pack this frame's table. See {@link pack_highlight_table} for why it is every frame.
-     *
-     * @param {GPUSceneContext} scene
-     */
-    #pack(scene) {
-        const packed = pack_highlight_table({
-            entries: this.#entries,
-            meshes: this.#meshes,
-            scene,
-            table: this.#table
-        });
-
-        this.#table = packed.table;
-        this.#table_size = packed.size;
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        if (this.#entries.length === 0) {
-            // nothing highlighted, so the frame keeps the colour it had and pays nothing
-            return;
-        }
-
-        this.#pack(frame.view.scene);
-
-        if (this.#table_size === 0) {
-            // highlighted entities whose models are not in the scene yet
-            return;
-        }
-
-        this.#renderer.graph_draw({
-            frame,
-            table: this.#table,
-            table_size: this.#table_size,
-            thickness: this.thickness
-        });
-    }
-}
+export const HighlightSystem = SGMeshHighlightSystem;
 
 /**
- * The outline is drawn into the scene, so the fog of war conceals it along with what it outlines.
+ * Re-exported because this is where it was published from, and because it is the ordering token
+ * `FogOfWarExtension` and anything else sequencing against the outline names. It lives in
+ * {@link HighlightOutlineSystem}'s file now, with the pass it registers.
  */
-export class HighlightExtension extends RenderExtension {
-    name = "highlight";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {HighlightSystem}
-     */
-    #system;
-
-    /**
-     * @param {HighlightSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export { HighlightExtension };

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

@@ -1,10 +1,13 @@
 /**
- * @deprecated Renamed to {@link HighlightSystem}. 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.
+ * @deprecated Renamed to {@link SGMeshHighlightSystem}. 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. It pointed at `HighlightSystem` for one release, which is itself now a deprecated alias
+ * of the same class — this chains straight through rather than through that, so there is one hop
+ * from either old name.
  *
  * 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 const HighlightSystem3: typeof HighlightSystem;
-import { HighlightSystem } from "./HighlightSystem.js";
+export const HighlightSystem3: typeof SGMeshHighlightSystem;
+import { SGMeshHighlightSystem } from "../graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js";
 //# sourceMappingURL=HighlightSystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"HighlightSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/HighlightSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,sDAAgD;gCAThB,sBAAsB"}
+{"version":3,"file":"HighlightSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/HighlightSystem3.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,4DAAsD;sCAZ/C,4DAA4D"}

package/src/engine/graphics3/HighlightSystem3.js

@@ -1,10 +1,15 @@
-import { HighlightSystem } from "./HighlightSystem.js";
-
-/**
- * @deprecated Renamed to {@link HighlightSystem}. 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.
- *
- * 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 const HighlightSystem3 = HighlightSystem;
+import {
+    SGMeshHighlightSystem
+} from "../graphics/ecs/mesh-v2/aggregate/SGMeshHighlightSystem.js";
+
+/**
+ * @deprecated Renamed to {@link SGMeshHighlightSystem}. 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. It pointed at `HighlightSystem` for one release, which is itself now a deprecated alias
+ * of the same class — this chains straight through rather than through that, so there is one hop
+ * from either old name.
+ *
+ * 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 const HighlightSystem3 = SGMeshHighlightSystem;