@woosh/meep-engine 3.13.1 → 3.14.1

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"}

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);
+    }
+}