@woosh/meep-engine 3.11.2 → 3.12.0

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

@@ -1,73 +1,10 @@
 /**
- * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ * @deprecated Renamed to {@link Trail3DSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
- * the same one particles, paths and debug shapes take.
- *
- * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
- * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
- * are a property of the trail, not of the renderer drawing it, and two implementations of them
- * would be two trails that age differently. What is this system's is turning those knots into
- * vertices, once a frame, per trail.
- *
- * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
- * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
- * — a trail that has stopped is a trail fading out.
- *
- * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
- * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
- * (straight alpha over the finished scene, depth tested, never written), which is what a trail
- * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
- * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
- */
-export class Trail3DSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics: GraphicsEngine3);
-    dependencies: (typeof Transform | typeof Trail3D)[];
-    /**
-     * What the pass draws. Read-only — the meshes follow the entities.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch(): DynamicMeshBatch;
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(trail: Trail3D, transform: Transform, entity: number): void;
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(trail: Trail3D, transform: Transform, entity: number): void;
-    update(timeDelta: any): void;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class TrailExtension extends RenderExtension {
-    /**
-     * @param {Trail3DSystem3} system
-     */
-    constructor(system: Trail3DSystem3);
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+export const Trail3DSystem3: typeof Trail3DSystem;
+import { Trail3DSystem } from "./Trail3DSystem.js";
 //# sourceMappingURL=Trail3DSystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Trail3DSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem3.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA0CI;;OAEG;IACH,uCAMC;IAlDD,oDAAoC;IAgCpC;;;;OAIG;IACH,8BAEC;IAaD,2CAIC;IAED,4CAWC;IAED;;;;OAIG;IACH,YAJW,OAAO,aACP,SAAS,UACT,MAAM,QAkBhB;IAED;;;;OAIG;IACH,cAJW,OAAO,aACP,SAAS,UACT,MAAM,QAiBhB;IAED,6BAYC;IAED;;OAEG;IACH,kCAeC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,cAAc,EAMxB;IAED,yBAEC;;CACJ;uBAnNsB,kBAAkB;0BACf,+BAA+B;oBAGrC,oCAAoC;iCALvB,gDAAgD;gCAJjD,mDAAmD"}
+{"version":3,"file":"Trail3DSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/Trail3DSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,kDAA4C;8BATd,oBAAoB"}

package/src/engine/graphics3/Trail3DSystem3.js

@@ -1,221 +1,10 @@
-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 { Transform } from "../ecs/transform/Transform.js";
-import { advance_trail } from "../graphics/ecs/trail3d/advance_trail.js";
-import { seed_trail_tube } from "../graphics/ecs/trail3d/seed_trail_tube.js";
-import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
-import { Trail3DFlags } from "../graphics/ecs/trail3d/Trail3DFlags.js";
-import {
-    TubeXFixedPhysicsSimulator
-} from "../graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
-import { trail_tube_write_geometry } from "./trail/trail_tube_write_geometry.js";
+import { Trail3DSystem } from "./Trail3DSystem.js";
 
 /**
- * Draws {@link Trail3D}'s tubes under Shade, on the dynamic-geometry path.
+ * @deprecated Renamed to {@link Trail3DSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so it goes down S4's dedicated non-meshlet path (D5/I-10),
- * the same one particles, paths and debug shapes take.
- *
- * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
- * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
- * are a property of the trail, not of the renderer drawing it, and two implementations of them
- * would be two trails that age differently. What is this system's is turning those knots into
- * vertices, once a frame, per trail.
- *
- * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
- * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
- * — a trail that has stopped is a trail fading out.
- *
- * **What the tube material had and this does not**: a texture, and per-trail depth writing. The
- * dynamic path has one pipeline, one vertex layout — position and colour — and one blend mode
- * (straight alpha over the finished scene, depth tested, never written), which is what a trail
- * wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws untinted
- * here; nothing in the game's own effects sets it to anything a flat colour does not carry.
- */
-export class Trail3DSystem3 extends System {
-    dependencies = [Trail3D, Transform];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {GPUDynamicMeshRenderer}
-     */
-    #renderer = new GPUDynamicMeshRenderer();
-
-    /**
-     * @type {DynamicMeshBatch}
-     */
-    #batch = new DynamicMeshBatch();
-
-    /**
-     * @type {Map<number, {trail: Trail3D, transform: Transform, mesh: DynamicMesh}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @type {TubeXFixedPhysicsSimulator}
-     */
-    #simulator = new TubeXFixedPhysicsSimulator();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the meshes follow the entities.
-     *
-     * @returns {DynamicMeshBatch}
-     */
-    get batch() {
-        return this.#batch;
-    }
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     */
-    constructor(graphics) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-
-        this.#graphics = graphics;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new TrailExtension(this));
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        this.#batch.clear();
-        this.#entries.clear();
-    }
-
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(trail, transform, entity) {
-        if (!trail.getFlag(Trail3DFlags.Built)) {
-            seed_trail_tube(trail, transform);
-        }
-
-        const mesh = DynamicMesh.from(new Geometry());
-
-        // the extrusion produces world-space vertices, so what the draw applies is identity — but a
-        // node's world transform is derived and stays unset until it is asked for
-        mesh.updateMatrices();
-
-        trail_tube_write_geometry(mesh.geometry, trail.tube);
-
-        this.#batch.add(mesh);
-
-        this.#entries.set(entity, { trail, transform, mesh });
-    }
-
-    /**
-     * @param {Trail3D} trail
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(trail, transform, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        this.#batch.remove(entry.mesh);
-
-        // residency deliberately survives leaving the batch, so nothing else would free it
-        this.#renderer.release(entry.mesh.geometry);
-
-        this.#entries.delete(entity);
-
-        trail.dispose();
-    }
-
-    update(timeDelta) {
-        for (const entry of this.#entries.values()) {
-            const trail = entry.trail;
-
-            advance_trail(trail, entry.transform, timeDelta, this.#simulator);
-
-            // bounds are the GPU's business on this path (§4.5), so the flag the head raises has
-            // nobody else to answer it
-            trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
-
-            trail_tube_write_geometry(entry.mesh.geometry, trail.tube);
-        }
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        if (this.#batch.count === 0) {
-            // nothing to draw, and the frame's colour is left exactly as it was
-            return;
-        }
-
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            batch: this.#batch,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: frame.view.camera.buffer
-        });
-    }
-}
-
-/**
- * A trail is drawn into the scene and is concealed by the fog of war like anything else in it.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class TrailExtension extends RenderExtension {
-    name = "trails";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {Trail3DSystem3}
-     */
-    #system;
-
-    /**
-     * @param {Trail3DSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const Trail3DSystem3 = Trail3DSystem;

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

@@ -6,7 +6,7 @@
  * is in Brick4 mode — so a level's lightmap is a property of the level, not of a thing standing in
  * it. Making it a component is what gives it a lifetime an entity already has: it arrives when the
  * level's entity is built, it is saved with it, and it goes away when the entity does. See
- * {@link VolumetricLightMapSystem3} for what happens when two entities claim the scene at once.
+ * {@link VolumetricLightMapSystem} for what happens when two entities claim the scene at once.
  *
  * **The payload is opaque here on purpose.** It is brick4's own GPU structure — the format
  * `brick4_to_gpu_structure` writes and the indirect-lighting shaders read — and everything inside
@@ -18,7 +18,7 @@
  * with the world-space bounds it was baked against, so the map already knows where it is. Moving
  * the entity that carries it moves nothing.
  *
- * @see VolumetricLightMapSystem3
+ * @see VolumetricLightMapSystem
  * @see Brick4LightMap
  */
 export class VolumetricLightMap {

package/src/engine/graphics3/VolumetricLightMap.js

@@ -10,7 +10,7 @@ import { is_array_buffer_equals } from "../../core/collection/array/typed/is_arr
  * is in Brick4 mode — so a level's lightmap is a property of the level, not of a thing standing in
  * it. Making it a component is what gives it a lifetime an entity already has: it arrives when the
  * level's entity is built, it is saved with it, and it goes away when the entity does. See
- * {@link VolumetricLightMapSystem3} for what happens when two entities claim the scene at once.
+ * {@link VolumetricLightMapSystem} for what happens when two entities claim the scene at once.
  *
  * **The payload is opaque here on purpose.** It is brick4's own GPU structure — the format
  * `brick4_to_gpu_structure` writes and the indirect-lighting shaders read — and everything inside
@@ -22,7 +22,7 @@ import { is_array_buffer_equals } from "../../core/collection/array/typed/is_arr
  * with the world-space bounds it was baked against, so the map already knows where it is. Moving
  * the entity that carries it moves nothing.
  *
- * @see VolumetricLightMapSystem3
+ * @see VolumetricLightMapSystem
  * @see Brick4LightMap
  */
 export class VolumetricLightMap {

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

@@ -0,0 +1,98 @@
+/**
+ * The bytes the scene's lightmap buffer should hold for a given claim.
+ *
+ * **A claim with nothing usable in it is still a claim.** A component whose bake has not finished
+ * loading holds `null`, and one whose file turned out to be empty holds a zero-length buffer —
+ * neither is a structure the shader can traverse, and neither can simply be handed to
+ * `Brick4LightMap.upload`: it copies what it is given and no more, so a zero-length upload writes
+ * nothing at all and leaves the previous level's lighting exactly where it was. Both therefore
+ * resolve to an empty map, which is a real structure that lights nothing.
+ *
+ * @param {VolumetricLightMap|null} map `null` when nothing claims the scene
+ * @returns {ArrayBuffer}
+ */
+export function volumetric_light_map_payload(map: VolumetricLightMap | null): ArrayBuffer;
+/**
+ * Whether the scene's lightmap buffer is already holding what the claim says it should.
+ *
+ * The whole of what {@link VolumetricLightMapSystem.update} decides, and true on all but a handful
+ * of frames in a session — an upload is a state change, and there are only so many of those.
+ *
+ * **A claim is identified by the component, not by its bytes.** Comparing the buffers would answer
+ * the same question and cost a full read of a megabyte-scale map to do it; the version is what makes
+ * a component that swapped its bytes distinguishable from one that did not.
+ *
+ * **No claim and nothing uploaded is current; no claim after an upload is not.** That asymmetry is
+ * the unlink: a buffer nobody has written to holds nothing, and a buffer holding the last level's
+ * lighting has to be given an empty map before it holds nothing too.
+ *
+ * @param {VolumetricLightMap|null} active what claims the scene now
+ * @param {VolumetricLightMap|null} uploaded what the buffer was last given, `null` for none
+ * @param {number} uploaded_version {@link VolumetricLightMap.version} as of that upload
+ * @returns {boolean}
+ */
+export function volumetric_light_map_is_current(active: VolumetricLightMap | null, uploaded: VolumetricLightMap | null, uploaded_version: number): boolean;
+/**
+ * Feeds the scene's baked volumetric lightmap to the GPU, and takes it away again.
+ *
+ * **The whole system is one buffer's worth of state.** Shade keeps a single `Brick4LightMap` on the
+ * scene's GPU context; a `VolumetricLightMap` component is a claim on it. So unlike the systems
+ * around it there is no per-entity object to build and place — there is one upload, and the work is
+ * deciding when it has to happen.
+ *
+ * **A scene has one lightmap, so a second claim waits rather than wins.** {@link active} is the
+ * *first* component to link and stays that way until it unlinks, at which point the next in line
+ * takes over. The alternative — last writer wins — makes the scene's lighting depend on the order
+ * entities happened to be built in, which is not a thing a level author controls. Swapping one map
+ * for another is therefore: remove the old component, add the new one.
+ *
+ * **The upload is decided in {@link update}, not in {@link link}.** A lightmap arrives whenever its
+ * level does, including before the renderer has a device — `scene_context` answers `null` until one
+ * exists, and answers with a *different* context after a restart, whose buffer is empty again. Both
+ * are the same question asked once a frame: is what the GPU holds still what the components say. A
+ * link is therefore eventually consistent, by at most one frame.
+ *
+ * **Unlinking uploads an empty map rather than leaving the last one there.** There is no way to
+ * un-upload — the shader reads the buffer unconditionally in Brick4 mode — so a component that
+ * removed itself and left the scene lit exactly as before would make the lifetime a fiction. A
+ * claim carrying nothing usable resolves the same way; see {@link volumetric_light_map_payload}.
+ *
+ * **What this does not do is turn Brick4 on.** Which indirect-lighting technique a frame uses is the
+ * renderer's setting, and a scene in IBL or LPV mode never reads this buffer no matter what is in
+ * it. Uploading a lightmap is necessary for Brick4 lighting and not sufficient for it.
+ *
+ * @see VolumetricLightMap
+ */
+export class VolumetricLightMapSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine, scene: Scene);
+    dependencies: (typeof VolumetricLightMap)[];
+    /**
+     * The component the scene is lit from, or `null` when nothing claims it.
+     *
+     * Read-only — it follows the entities. What the GPU holds catches up with this on the next
+     * {@link update}.
+     *
+     * @returns {VolumetricLightMap|null}
+     */
+    get active(): VolumetricLightMap;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    link(map: VolumetricLightMap, entity: number): void;
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    unlink(map: VolumetricLightMap, entity: number): void;
+    #private;
+}
+import { VolumetricLightMap } from "./VolumetricLightMap.js";
+import { System } from "../ecs/System.js";
+//# sourceMappingURL=VolumetricLightMapSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VolumetricLightMapSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/VolumetricLightMapSystem.js"],"names":[],"mappings":"AAoNA;;;;;;;;;;;;GAYG;AACH,kDAHW,kBAAkB,GAAC,IAAI,GACrB,WAAW,CAUvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDALW,kBAAkB,GAAC,IAAI,YACvB,kBAAkB,GAAC,IAAI,oBACvB,MAAM,GACJ,OAAO,CAQnB;AA7PD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAyDI;;;OAGG;IACH,oDAQC;IAnED,4CAAoC;IAyCpC;;;;;;;OAOG;IACH,iCAIC;IAgBD,2CAEC;IAED,4CAUC;IAED;;;OAGG;IACH,UAHW,kBAAkB,UAClB,MAAM,QAIhB;IAED;;;OAGG;IACH,YAHW,kBAAkB,UAClB,MAAM,QAYhB;;CA+DJ;mCA7MkC,yBAAyB;uBADrC,kBAAkB"}