@woosh/meep-engine 3.27.0 → 3.29.0

package/src/engine/graphics3/DebugDrawSystem.js

@@ -1,203 +1,206 @@
-import { assert } from "../../core/assert.js";
-import { GPUDynamicMeshRenderer } from "../../shade/renderer/dynamic/GPUDynamicMeshRenderer.js";
-import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
-import { FogOfWarExtension } from "./FogOfWarSystem.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 { Gizmo } from "../graphics/render/gizmo/Gizmo.js";
-import { gizmo_view_from_camera } from "./debug/gizmo_view_from_camera.js";
-import { gizmo_write_geometry } from "./debug/gizmo_write_geometry.js";
-
-/**
- * Draws what {@link Gizmo} recorded this frame, under Shade.
- *
- * **The Shade half of the pair `GizmoRenderingPlugin` is the three half of.** The immediate-mode API
- * a tool calls is renderer-neutral and records into buffers; this turns one frame of those buffers
- * into geometry and puts it on the dynamic-mesh path (D5/D11), which is where every piece of
- * generated content in this phase belongs.
- *
- * **One mesh, one geometry, rewritten every frame.** Debug drawing has no persistent objects to key
- * anything on — a shape is a call, not a thing — so there is nothing to cache and nothing to
- * release between frames. Colour rides the vertices rather than the mesh, which is what lets one
- * draw carry a whole frame's worth of differently coloured shapes.
- *
- * **Blended and depth-tested, never depth-writing.** Debug shapes are occluded by the scene and
- * occlude nothing, including each other: two overlapping solid shapes composite in the order they
- * were recorded rather than by depth. Whether a gizmo should instead sit on top of everything is
- * the gizmo's question and V6 answers it.
- *
- * **The recording is cleared once the frame that consumed it has been submitted**, on the same
- * signal the three backend clears on. An immediate-mode API that leaks its contents keeps drawing a
- * world that has moved on, so "what was drawn last frame is gone this frame" is a property of the
- * pass rather than a courtesy of its callers.
- */
-export class DebugDrawSystem extends System {
-    /**
-     * Width of a drawn line, in CSS pixels of the display — so it is the same thickness whatever
-     * the device pixel ratio is and wherever the resolution controller has the frame this instant.
-     *
-     * **A property of the pass, not of a draw.** The recording API has no width — it is an
-     * immediate-mode debug surface, and one that asked every caller for a line width would be
-     * asking about the display rather than about the thing being drawn.
-     *
-     * @type {number}
-     */
-    line_width = 2;
-
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {GPUDynamicMeshRenderer}
-     */
-    #renderer = new GPUDynamicMeshRenderer();
-
-    /**
-     * @type {DynamicMeshBatch}
-     */
-    #batch = new DynamicMeshBatch();
-
-    /**
-     * @type {DynamicMesh}
-     */
-    #mesh = DynamicMesh.from(new Geometry());
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * @type {function}
-     */
-    #clear;
-
-    /**
-     * Where the camera is and what it looks along, refilled per frame — the pass runs once and
-     * nothing else reads this.
-     *
-     * @type {GizmoView}
-     */
-    #view = {
-        eye: new Float32Array(3),
-        forward: new Float32Array(3),
-        projection_scale: 1,
-        viewport_height: 1,
-        line_width: 1
-    };
-
-    /**
-     * What the pass draws. Read-only — the geometry follows the recording.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch() {
-        return this.#batch;
-    }
-
-    /**
-     * @param {GraphicsEngine} graphics
-     */
-    constructor(graphics) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-
-        this.#graphics = graphics;
-
-        // vertices are written in world space, and what the draw applies is the mesh's own
-        // transform, identity until moved
-        this.#batch.add(this.#mesh);
-
-        this.#clear = () => Gizmo.clear();
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new DebugDrawExtension(this));
-
-        this.#graphics.on.postRender.add(this.#clear);
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#graphics.on.postRender.remove(this.#clear);
-
-        this.#renderer.destroy();
-
-        Gizmo.clear();
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        gizmo_view_from_camera(
-            this.#view,
-            frame.view.camera.camera,
-            this.#graphics.viewport.size.y,
-            this.line_width
-        );
-
-        gizmo_write_geometry(this.#mesh.geometry, Gizmo, this.#view);
-
-        if (Gizmo.empty) {
-            // nothing was recorded, 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 single deliberate exception to the fog of war.** Everything else drawn into the scene is
- * concealed by it; developer geometry that the fog can hide is a debugging tool that stops working
- * exactly where debugging is needed, so this says so rather than relying on where it was registered.
- */
-export class DebugDrawExtension extends RenderExtension {
-    name = "debug draw";
-
-    phase = FramePhase.AfterTransparency;
-
-    after = [FogOfWarExtension];
-
-    /**
-     * @type {DebugDrawSystem}
-     */
-    #system;
-
-    /**
-     * @param {DebugDrawSystem} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+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 { Gizmo } from "../graphics/render/gizmo/Gizmo.js";
+import { gizmo_view_from_camera } from "./debug/gizmo_view_from_camera.js";
+import { gizmo_write_geometry } from "./debug/gizmo_write_geometry.js";
+
+/**
+ * Draws what {@link Gizmo} recorded this frame, under Shade.
+ *
+ * **The Shade half of the pair `GizmoRenderingPlugin` is the three half of.** The immediate-mode API
+ * a tool calls is renderer-neutral and records into buffers; this turns one frame of those buffers
+ * into geometry and puts it on the dynamic-mesh path (D5/D11), which is where every piece of
+ * generated content in this phase belongs.
+ *
+ * **One mesh, one geometry, rewritten every frame.** Debug drawing has no persistent objects to key
+ * anything on — a shape is a call, not a thing — so there is nothing to cache and nothing to
+ * release between frames. Colour rides the vertices rather than the mesh, which is what lets one
+ * draw carry a whole frame's worth of differently coloured shapes.
+ *
+ * **Blended and depth-tested, never depth-writing.** Debug shapes are occluded by the scene and
+ * occlude nothing, including each other: two overlapping solid shapes composite in the order they
+ * were recorded rather than by depth. Whether a gizmo should instead sit on top of everything is
+ * the gizmo's question and V6 answers it.
+ *
+ * **The recording is cleared once the frame that consumed it has been submitted**, on the same
+ * signal the three backend clears on. An immediate-mode API that leaks its contents keeps drawing a
+ * world that has moved on, so "what was drawn last frame is gone this frame" is a property of the
+ * pass rather than a courtesy of its callers.
+ */
+export class DebugDrawSystem extends System {
+    /**
+     * Width of a drawn line, in CSS pixels of the display — so it is the same thickness whatever
+     * the device pixel ratio is and wherever the resolution controller has the frame this instant.
+     *
+     * **A property of the pass, not of a draw.** The recording API has no width — it is an
+     * immediate-mode debug surface, and one that asked every caller for a line width would be
+     * asking about the display rather than about the thing being drawn.
+     *
+     * @type {number}
+     */
+    line_width = 2;
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUDynamicMeshRenderer}
+     */
+    #renderer = new GPUDynamicMeshRenderer();
+
+    /**
+     * @type {DynamicMeshBatch}
+     */
+    #batch = new DynamicMeshBatch();
+
+    /**
+     * @type {DynamicMesh}
+     */
+    #mesh = DynamicMesh.from(new Geometry());
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * @type {function}
+     */
+    #clear;
+
+    /**
+     * Where the camera is and what it looks along, refilled per frame — the pass runs once and
+     * nothing else reads this.
+     *
+     * @type {GizmoView}
+     */
+    #view = {
+        eye: new Float32Array(3),
+        forward: new Float32Array(3),
+        projection_scale: 1,
+        viewport_height: 1,
+        line_width: 1
+    };
+
+    /**
+     * What the pass draws. Read-only — the geometry follows the recording.
+     *
+     * @returns {DynamicMeshBatch}
+     */
+    get batch() {
+        return this.#batch;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     */
+    constructor(graphics) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+
+        this.#graphics = graphics;
+
+        // vertices are written in world space, and what the draw applies is the mesh's own
+        // transform, identity until moved
+        this.#batch.add(this.#mesh);
+
+        this.#clear = () => Gizmo.clear();
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new DebugDrawExtension(this));
+
+        this.#graphics.on.postRender.add(this.#clear);
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#graphics.on.postRender.remove(this.#clear);
+
+        this.#renderer.destroy();
+
+        Gizmo.clear();
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        gizmo_view_from_camera(
+            this.#view,
+            frame.view.camera.camera,
+            this.#graphics.viewport.size.y,
+            this.line_width
+        );
+
+        gizmo_write_geometry(this.#mesh.geometry, Gizmo, this.#view);
+
+        if (Gizmo.empty) {
+            // nothing was recorded, 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
+        });
+    }
+}
+
+/**
+ * **On top.** Developer geometry that a later effect can conceal is a debugging tool that stops
+ * working exactly where debugging is needed, so this asks to be last rather than relying on where it
+ * was registered.
+ *
+ * The number is far out of the way of the ordinary ones rather than one above the fog, so that a
+ * composite added later can push past the fog without having to know this exists. It is not a
+ * guarantee — nothing here can be — but out here it takes a deliberate act to land above it.
+ */
+export class DebugDrawExtension extends RenderExtension {
+    name = "debug draw";
+
+    phase = FramePhase.AfterTransparency;
+
+    relative_order = 1000;
+
+    /**
+     * @type {DebugDrawSystem}
+     */
+    #system;
+
+    /**
+     * @param {DebugDrawSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -68,16 +68,16 @@ export class DecalSystem extends System<any> {
     #private;
 }
 /**
- * **After the terrain**, because the decal composite has to see the textured ground rather than
- * precede it. That requirement used to be met by putting a registration call above an `await` and
- * writing a comment about it; here it is the declaration below.
+ * **Late on the phase**, because a decal composites over surfaces that are already written — the
+ * textured ground above all — rather than preceding them. That requirement used to be met by
+ * putting a registration call above an `await` and writing a comment about it; here it is the
+ * declaration below.
  */
 export class DecalExtension extends RenderExtension {
     /**
      * @param {DecalSystem} system
      */
     constructor(system: DecalSystem);
-    after: (typeof TerrainExtension)[];
     record(frame: any): void;
     #private;
 }
@@ -85,5 +85,4 @@ import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
 import { Decal } from "../graphics/ecs/decal/v2/Decal.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { TerrainExtension } from "./TerrainSystem.js";
 //# sourceMappingURL=DecalSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"DecalSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DecalSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwHI;;;OAGG;IACH,4DAeC;IA1ID,oDAAoC;IA8FpC;;;;OAIG;IACH,oBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,4BAEC;IAuBD,2CAUC;IAED,4CAYC;IAED;;;;;;;;;;;;OAYG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAmBhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAkBhB;IAiFD,6BAiDC;IAED;;OAEG;IACH,kCAkBC;;CACJ;AAED;;;;GAIG;AACH;IAYI;;OAEG;IACH,oBAFW,WAAW,EAMrB;IAdD,mCAA2B;IAgB3B,yBAEC;;CACJ;uBAvbsB,kBAAkB;4BACb,iCAAiC;sBACvC,mCAAmC;gCALzB,mDAAmD;iCADlD,oBAAoB"}
+{"version":3,"file":"DecalSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/DecalSystem.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwHI;;;OAGG;IACH,4DAeC;IA1ID,oDAAoC;IA8FpC;;;;OAIG;IACH,oBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,4BAEC;IAuBD,2CAUC;IAED,4CAYC;IAED;;;;;;;;;;;;OAYG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAmBhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAkBhB;IAiFD,6BAiDC;IAED;;OAEG;IACH,kCAkBC;;CACJ;AAED;;;;;GAKG;AACH;IAYI;;OAEG;IACH,oBAFW,WAAW,EAMrB;IAED,yBAEC;;CACJ;uBAxbsB,kBAAkB;4BACb,iCAAiC;sBACvC,mCAAmC;gCALzB,mDAAmD"}

package/src/engine/graphics3/DecalSystem.js

@@ -3,7 +3,6 @@ import { LoadingCache } from "../../core/cache/LoadingCache.js";
 import { strictEquals } from "../../core/function/strictEquals.js";
 import { computeStringHash } from "../../core/primitives/strings/computeStringHash.js";
 import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { TerrainExtension } from "./TerrainSystem.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
 import { GameAssetType } from "../asset/GameAssetType.js";
 import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
@@ -418,16 +417,17 @@ export class DecalSystem extends System {
 }
 
 /**
- * **After the terrain**, because the decal composite has to see the textured ground rather than
- * precede it. That requirement used to be met by putting a registration call above an `await` and
- * writing a comment about it; here it is the declaration below.
+ * **Late on the phase**, because a decal composites over surfaces that are already written — the
+ * textured ground above all — rather than preceding them. That requirement used to be met by
+ * putting a registration call above an `await` and writing a comment about it; here it is the
+ * declaration below.
  */
 export class DecalExtension extends RenderExtension {
     name = "decals";
 
     phase = FramePhase.AfterGBuffer;
 
-    after = [TerrainExtension];
+    relative_order = 1;
 
     /**
      * @type {DecalSystem}

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

@@ -45,21 +45,20 @@ export class FogOfWarSystem extends System<any> {
     #private;
 }
 /**
- * **Last among the content extensions**, because the fog conceals and therefore belongs over
- * everything it is meant to conceal — particles, trails, the path display and the selection
- * highlight all draw before it and are all subject to it. Written down here rather than being a
- * property of where a registration call happened to sit, which is how it came to be wrong.
+ * **Late on the phase**, because the fog conceals and therefore belongs over everything it is meant
+ * to conceal — content drawn at the phase's default order is subject to it. Written down here
+ * rather than being a property of where a registration call happened to sit, which is how it came
+ * to be wrong.
  *
- * The declaration is stated from this side, over the content extensions, so that adding another one
- * is a change to that extension and not to this list. {@link DebugDrawExtension} is the one thing
- * that goes after the fog, and it says so itself.
+ * Nothing is named: a content extension added later is concealed because it sits at the default,
+ * not because a list here was updated. Whatever must not be concealed asks for a later order of its
+ * own.
  */
 export class FogOfWarExtension extends RenderExtension {
     /**
      * @param {FogOfWarSystem} system
      */
     constructor(system: FogOfWarSystem);
-    after: (typeof HighlightExtension | typeof ParticleExtension | typeof PathDisplayExtension | typeof TrailExtension)[];
     record(frame: any): void;
     #private;
 }
@@ -67,8 +66,4 @@ 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 "./HighlightOutlineSystem.js";
-import { ParticleExtension } from "./ParticleEmitterSystem.js";
-import { PathDisplayExtension } from "./PathDisplaySystem.js";
-import { TrailExtension } from "./Trail3DSystem.js";
 //# sourceMappingURL=FogOfWarSystem.d.ts.map

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,6BAA6B;kCAC9B,4BAA4B;qCACzB,wBAAwB;+BAC9B,oBAAoB"}
+{"version":3,"file":"FogOfWarSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/FogOfWarSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;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;IAED,yBAEC;;CACJ;uBAzPsB,kBAAkB;oBADrB,+BAA+B;yBAH1B,wBAAwB;gCAHjB,mDAAmD"}

package/src/engine/graphics3/FogOfWarSystem.js

@@ -1,10 +1,6 @@
 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 "./HighlightOutlineSystem.js";
-import { ParticleExtension } from "./ParticleEmitterSystem.js";
-import { PathDisplayExtension } from "./PathDisplaySystem.js";
-import { TrailExtension } from "./Trail3DSystem.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";
@@ -229,21 +225,21 @@ export class FogOfWarSystem extends System {
 }
 
 /**
- * **Last among the content extensions**, because the fog conceals and therefore belongs over
- * everything it is meant to conceal — particles, trails, the path display and the selection
- * highlight all draw before it and are all subject to it. Written down here rather than being a
- * property of where a registration call happened to sit, which is how it came to be wrong.
+ * **Late on the phase**, because the fog conceals and therefore belongs over everything it is meant
+ * to conceal — content drawn at the phase's default order is subject to it. Written down here
+ * rather than being a property of where a registration call happened to sit, which is how it came
+ * to be wrong.
  *
- * The declaration is stated from this side, over the content extensions, so that adding another one
- * is a change to that extension and not to this list. {@link DebugDrawExtension} is the one thing
- * that goes after the fog, and it says so itself.
+ * Nothing is named: a content extension added later is concealed because it sits at the default,
+ * not because a list here was updated. Whatever must not be concealed asks for a later order of its
+ * own.
  */
 export class FogOfWarExtension extends RenderExtension {
     name = "fog of war";
 
     phase = FramePhase.AfterTransparency;
 
-    after = [ParticleExtension, PathDisplayExtension, TrailExtension, HighlightExtension];
+    relative_order = 1;
 
     /**
      * @type {FogOfWarSystem}

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

@@ -351,7 +351,11 @@ export class GraphicsEngine {
     /**
      * Draw a frame, if there is anything to draw it with.
      *
-     * @param {number} [time_delta_seconds]
+     * @param {number} [time_delta_seconds] simulation seconds to advance the frame by — GPU
+     * particles, the animation tick and exposure adaptation all step by this. Defaults to zero, so
+     * a caller that just wants the current state on screen (a scene transition, a preview) draws it
+     * without moving anything. It deliberately does NOT default to a frame's worth of time: doing
+     * that silently ran the simulation at a fixed 60 Hz regardless of the real clock.
      * @returns {boolean} whether a frame was submitted
      */
     render(time_delta_seconds?: number): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"GraphicsEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine.js"],"names":[],"mappings":"AA0DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IA0DG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAID;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFW,YAAY,QAStB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAHW,eAAe,GACb,eAAe,CAa3B;IAED;;;;;;;;;;OAUG;IACH,uBAHW,UAAU,GACR,MAAM,CAclB;IAED;;;;;;OAMG;IACH,4BAHW,eAAe,GACb,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,eAAe,GAAC,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,UACL,MAAM,SACN,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CAkDzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAFW,iBAAiB,QAc3B;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,GAAC,OAAO,UACf,OAAO,GAAC,OAAO,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,UACN,OAAO,aACP,OAAO,QAIjB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAyBC;IAED;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,OAAO,CAoDnB;;CACJ;sBA7yBY,OAAO,4BAA4B,EAAE,OAAO;yBAC5C,OAAO,8CAA8C,EAAE,UAAU;8BACjE,OAAO,mDAAmD,EAAE,eAAe;8BAC3E,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,8CAA8C,EAAE,YAAY;qBACnE,OAAO,kCAAkC,EAAE,MAAM;yBAdrC,kCAAkC;mCAMxB,yBAAyB;mBAZzC,oCAAoC;wBAC/B,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}
+{"version":3,"file":"GraphicsEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine.js"],"names":[],"mappings":"AA0DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IA0DG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAID;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFW,YAAY,QAStB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yBAHW,eAAe,GACb,eAAe,CAa3B;IAED;;;;;;;;;;OAUG;IACH,uBAHW,UAAU,GACR,MAAM,CAclB;IAED;;;;;;OAMG;IACH,4BAHW,eAAe,GACb,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,eAAe,GAAC,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,UACL,MAAM,SACN,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CAkDzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAFW,iBAAiB,QAc3B;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,GAAC,OAAO,UACf,OAAO,GAAC,OAAO,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,UACN,OAAO,aACP,OAAO,QAIjB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAyBC;IAED;;;;;;;;;OASG;IACH,4BAPW,MAAM,GAKJ,OAAO,CAoDnB;;CACJ;sBAjzBY,OAAO,4BAA4B,EAAE,OAAO;yBAC5C,OAAO,8CAA8C,EAAE,UAAU;8BACjE,OAAO,mDAAmD,EAAE,eAAe;8BAC3E,OAAO,+CAA+C,EAAE,eAAe;2BACvE,OAAO,8CAA8C,EAAE,YAAY;qBACnE,OAAO,kCAAkC,EAAE,MAAM;yBAdrC,kCAAkC;mCAMxB,yBAAyB;mBAZzC,oCAAoC;wBAC/B,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}