@woosh/meep-engine 3.0.0 → 3.0.2

package/src/engine/graphics3/ParticleEmitterSystem3.js

@@ -1,265 +1,289 @@
-import { assert } from "../../core/assert.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 { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { MaterialManager } from "../graphics/material/manager/MaterialManager.js";
-import { ParticleEmitter } from "../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import { ParticleEmitterFlag } from "../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
-import { ParticularEngine } from "../graphics/particles/particular/engine/ParticularEngine.js";
-import { GPUParticularRenderer } from "./particles/GPUParticularRenderer.js";
-
-/**
- * Draws the game's particle effects under Shade.
- *
- * **The simulation does not move.** `particular` emits, ages, integrates and colours particles on
- * the CPU, and that is where it stays: the plan makes Shade's GPU particle system a later, opt-in
- * upgrade rather than this port. What changes is only what happens to the state it produces each
- * frame — instead of a three `Points` object per emitter, it is packed into the layout Shade's own
- * billboard renderer reads.
- *
- * **No visibility layer comes across.** The legacy system drives a render layer backed by a BVH and
- * puts emitters to sleep when they leave the visible set; §4.5 retires CPU render culling, so every
- * linked emitter simulates and the GPU decides what is on screen. An emitter that should not
- * simulate says so itself, through {@link ParticleEmitterFlag.Emitting}.
- */
-export class ParticleEmitterSystem3 extends System {
-    dependencies = [ParticleEmitter, Transform];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {AssetManager}
-     */
-    #assets;
-
-    /**
-     * @type {ParticularEngine}
-     */
-    #engine;
-
-    /**
-     * @type {GPUParticularRenderer}
-     */
-    #renderer = new GPUParticularRenderer();
-
-    /**
-     * The emitters to simulate and draw, in link order.
-     *
-     * @type {ParticleEmitter[]}
-     */
-    #emitters = [];
-
-    /**
-     * @type {Map<number, {emitter: ParticleEmitter, position: Function, rotation: Function, scale: Function}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the emitters follow the entities.
-     *
-     * @returns {ParticleEmitter[]}
-     */
-    get emitters() {
-        return this.#emitters;
-    }
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {AssetManager} assets
-     */
-    constructor(graphics, assets) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(assets, 'assets');
-
-        this.#graphics = graphics;
-        this.#assets = assets;
-
-        /*
-         The material manager is a carrier, not a consumer: `ShaderManager` is where the sprite atlas
-         lives — the part this system needs — and it builds a three `ShaderMaterial` per emitter on
-         the way past. Those materials are never drawn and never updated here, which is the same
-         situation `FogOfWar` is in with the `DataTexture` it builds; Phase 6 deletes both.
-        */
-        this.#engine = new ParticularEngine(assets, new MaterialManager());
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new ParticleExtension(this));
-
-        const assets = this.#assets;
-
-        if (!assets.hasLoaderForType('image')) {
-            await assets.registerLoader('image', new ImageRGBADataLoader());
-        }
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        // every emitter has been unlinked by this point — both teardown paths detach the dataset or
-        // remove the system observer first — so what is left is the shared sprite atlas
-        this.#engine.dispose();
-
-        this.#emitters.length = 0;
-        this.#entries.clear();
-    }
-
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(emitter, transform, entity) {
-        const position = (x, y, z) => emitter.position.set(x, y, z);
-        const rotation = (x, y, z, w) => emitter.rotation.set(x, y, z, w);
-        const scale = (x, y, z) => emitter.scale.set(x, y, z);
-
-        transform.position.process(position);
-        transform.rotation.process(rotation);
-        transform.scale.process(scale);
-
-        this.#entries.set(entity, { emitter, position, rotation, scale });
-
-        emitter.id = entity;
-
-        /*
-         Awake from the start. The legacy system links emitters asleep and lets its visibility layer
-         wake them; there is no such layer here, and an emitter that never wakes never emits.
-        */
-        emitter.clearFlag(ParticleEmitterFlag.Sleeping);
-
-        this.#engine.add(emitter);
-
-        this.#emitters.push(emitter);
-    }
-
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(emitter, transform, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        transform.position.onChanged.remove(entry.position);
-        transform.rotation.onChanged.remove(entry.rotation);
-        transform.scale.onChanged.remove(entry.scale);
-
-        this.#entries.delete(entity);
-
-        const index = this.#emitters.indexOf(emitter);
-
-        if (index !== -1) {
-            this.#emitters.splice(index, 1);
-        }
-
-        this.#engine.remove(emitter);
-
-        emitter.dispose();
-    }
-
-    update(timeDelta) {
-        this.#engine.advance(timeDelta);
-
-        const emitters = this.#emitters;
-
-        for (let i = 0; i < emitters.length; i++) {
-            // retires dead particles and compacts the pool, which is what makes the live ones a
-            // contiguous run for the packer
-            emitters[i].update();
-        }
-
-        // repacks the sprite atlas when an effect has brought a new sprite in
-        this.#engine.shaderManager.spriteAtlas.atlas.update();
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        const emitters = this.#emitters;
-
-        if (emitters.length === 0) {
-            return;
-        }
-
-        const camera_context = frame.view.camera;
-
-        // the camera's world transform, whose first two columns are the axes a billboard is built on
-        const m = camera_context.camera.transform.matrix;
-
-        /*
-         The particles are packed and uploaded inside the pass rather than here: that needs a
-         `GraphicsContext`, which the frame graph hands out at execution time and the frame does not
-         carry. So the pass is recorded whether or not anything is alive, and draws nothing when
-         nothing is — which leaves the frame's colour exactly as it was either way.
-        */
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: camera_context.buffer,
-            emitters,
-            atlas: this.#engine.shaderManager.spriteAtlas.atlas.sampler,
-            camera_position: [m[12], m[13], m[14]],
-            camera_right: [m[0], m[1], m[2]],
-            camera_up: [m[4], m[5], m[6]]
-        });
-    }
-}
-
-/**
- * Emitters draw into the scene, so they are subject to the fog of war that conceals it — which is
- * a declaration on the fog rather than a placement here.
- */
-export class ParticleExtension extends RenderExtension {
-    name = "particles";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {ParticleEmitterSystem3}
-     */
-    #system;
-
-    /**
-     * @param {ParticleEmitterSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+import { assert } from "../../core/assert.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 { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { ParticleEmitter } from "../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
+import { ParticleEmitterFlag } from "../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
+import { ParticularEngine } from "../graphics/particles/particular/engine/ParticularEngine.js";
+import { GPUParticularRenderer } from "./particles/GPUParticularRenderer.js";
+
+/**
+ * Draws the game's particle effects under Shade.
+ *
+ * **The simulation does not move.** `particular` emits, ages, integrates and colours particles on
+ * the CPU, and that is where it stays: the plan makes Shade's GPU particle system a later, opt-in
+ * upgrade rather than this port. What changes is only what happens to the state it produces each
+ * frame — instead of a three `Points` object per emitter, it is packed into the layout Shade's own
+ * billboard renderer reads.
+ *
+ * **No visibility layer comes across.** The legacy system drives a render layer backed by a BVH and
+ * puts emitters to sleep when they leave the visible set; §4.5 retires CPU render culling, so every
+ * linked emitter simulates and the GPU decides what is on screen. An emitter that should not
+ * simulate says so itself, through {@link ParticleEmitterFlag.Emitting}.
+ */
+export class ParticleEmitterSystem3 extends System {
+    dependencies = [ParticleEmitter, Transform];
+
+    /**
+     * @type {GraphicsEngine3}
+     */
+    #graphics;
+
+    /**
+     * @type {AssetManager}
+     */
+    #assets;
+
+    /**
+     * @type {ParticularEngine}
+     */
+    #engine;
+
+    /**
+     * @type {GPUParticularRenderer}
+     */
+    #renderer = new GPUParticularRenderer();
+
+    /**
+     * The emitters to simulate and draw, in link order.
+     *
+     * @type {ParticleEmitter[]}
+     */
+    #emitters = [];
+
+    /**
+     * @type {Map<number, {emitter: ParticleEmitter, position: Function, rotation: Function, scale: Function}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * What the pass draws. Read-only — the emitters follow the entities.
+     *
+     * @returns {ParticleEmitter[]}
+     */
+    get emitters() {
+        return this.#emitters;
+    }
+
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics, assets) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(assets, 'assets');
+
+        this.#graphics = graphics;
+        this.#assets = assets;
+
+        this.#engine = new ParticularEngine(assets);
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new ParticleExtension(this));
+
+        const assets = this.#assets;
+
+        if (!assets.hasLoaderForType('image')) {
+            await assets.registerLoader('image', new ImageRGBADataLoader());
+        }
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#renderer.destroy();
+
+        // every emitter has been unlinked by this point — both teardown paths detach the dataset or
+        // remove the system observer first — so what is left is the shared sprite atlas
+        this.#engine.dispose();
+
+        this.#emitters.length = 0;
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {ParticleEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(emitter, transform, entity) {
+        const position = (x, y, z) => emitter.position.set(x, y, z);
+        const rotation = (x, y, z, w) => emitter.rotation.set(x, y, z, w);
+        const scale = (x, y, z) => emitter.scale.set(x, y, z);
+
+        transform.position.process(position);
+        transform.rotation.process(rotation);
+        transform.scale.process(scale);
+
+        this.#entries.set(entity, { emitter, position, rotation, scale });
+
+        emitter.id = entity;
+
+        /*
+         Awake from the start. The legacy system links emitters asleep and lets its visibility layer
+         wake them; there is no such layer here, and an emitter that never wakes never emits.
+        */
+        emitter.clearFlag(ParticleEmitterFlag.Sleeping);
+
+        this.#engine.add(emitter);
+
+        this.#emitters.push(emitter);
+    }
+
+    /**
+     * Rebuild an emitter that has been edited structurally — layers added or removed, a sprite
+     * changed, a parameter curve redrawn.
+     *
+     * The pool, the parameter tracks and the atlas references are all built from the emitter's
+     * description, so an edit to that description is only visible once they are built again. Sleep
+     * state is preserved because it is the editor's, not the emitter's.
+     *
+     * @param {ParticleEmitter} emitter one this system has linked
+     */
+    rebuild(emitter) {
+        assert.ok(this.#emitters.includes(emitter), 'emitter is not linked to this system');
+
+        const engine = this.#engine;
+
+        const sleeping = emitter.getFlag(ParticleEmitterFlag.Sleeping);
+
+        engine.remove(emitter);
+
+        emitter.clearFlag(ParticleEmitterFlag.Built | ParticleEmitterFlag.Initialized);
+
+        emitter.registerLayerParameters();
+        emitter.build();
+        emitter.initialize();
+        emitter.computeBoundingBox();
+
+        engine.add(emitter);
+
+        emitter.writeFlag(ParticleEmitterFlag.Sleeping, sleeping);
+    }
+
+    /**
+     * @param {ParticleEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(emitter, transform, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        transform.position.onChanged.remove(entry.position);
+        transform.rotation.onChanged.remove(entry.rotation);
+        transform.scale.onChanged.remove(entry.scale);
+
+        this.#entries.delete(entity);
+
+        const index = this.#emitters.indexOf(emitter);
+
+        if (index !== -1) {
+            this.#emitters.splice(index, 1);
+        }
+
+        this.#engine.remove(emitter);
+
+        emitter.dispose();
+    }
+
+    update(timeDelta) {
+        this.#engine.advance(timeDelta);
+
+        const emitters = this.#emitters;
+
+        for (let i = 0; i < emitters.length; i++) {
+            // retires dead particles and compacts the pool, which is what makes the live ones a
+            // contiguous run for the packer
+            emitters[i].update();
+        }
+
+        // repacks the sprite atlas when an effect has brought a new sprite in
+        this.#engine.shaderManager.spriteAtlas.atlas.update();
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        const emitters = this.#emitters;
+
+        if (emitters.length === 0) {
+            return;
+        }
+
+        const camera_context = frame.view.camera;
+
+        // the camera's world transform, whose first two columns are the axes a billboard is built on
+        const m = camera_context.camera.transform.matrix;
+
+        /*
+         The particles are packed and uploaded inside the pass rather than here: that needs a
+         `GraphicsContext`, which the frame graph hands out at execution time and the frame does not
+         carry. So the pass is recorded whether or not anything is alive, and draws nothing when
+         nothing is — which leaves the frame's colour exactly as it was either way.
+        */
+        const scene = frame.get(SceneColor);
+
+        scene.color = this.#renderer.graph_draw({
+            graph: frame.graph,
+            color: scene.color,
+            depth: frame.get(ViewTextures).depth,
+            camera: camera_context.buffer,
+            emitters,
+            atlas: this.#engine.shaderManager.spriteAtlas.atlas.sampler,
+            camera_position: [m[12], m[13], m[14]],
+            camera_right: [m[0], m[1], m[2]],
+            camera_up: [m[4], m[5], m[6]]
+        });
+    }
+}
+
+/**
+ * Emitters draw into the scene, so they are subject to the fog of war that conceals it — which is
+ * a declaration on the fog rather than a placement here.
+ */
+export class ParticleExtension extends RenderExtension {
+    name = "particles";
+
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {ParticleEmitterSystem3}
+     */
+    #system;
+
+    /**
+     * @param {ParticleEmitterSystem3} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -6,9 +6,9 @@
  * projects every tracked entity through the result. That is three's spelling, and it is baked into
  * gameplay code the migration is not rewriting yet.
  *
- * **Nothing is converted.** Shade keeps `projection_matrix` and `view_matrix` as gl-matrix `mat4` —
- * column-major `Float32Array(16)`, which is exactly what three's `.elements` already is — so the
- * two are handed over as they stand, no copy and no per-frame work. Phase 1.5 measured the result:
+ * **Nothing is converted.** Shade keeps `projection_matrix` and `view_matrix` as column-major
+ * `Float32Array(16)`, which is exactly what three's `.elements` already is — so the two are handed
+ * over as they stand, no copy and no per-frame work. Phase 1.5 measured the result:
  * HUD viewport positions matched three's to four decimal places across scattered world points.
  *
  * The matrices are held by reference because Shade allocates them once and writes into them; a

package/src/engine/graphics3/ShadeCameraAdapter.js

@@ -6,9 +6,9 @@
  * projects every tracked entity through the result. That is three's spelling, and it is baked into
  * gameplay code the migration is not rewriting yet.
  *
- * **Nothing is converted.** Shade keeps `projection_matrix` and `view_matrix` as gl-matrix `mat4` —
- * column-major `Float32Array(16)`, which is exactly what three's `.elements` already is — so the
- * two are handed over as they stand, no copy and no per-frame work. Phase 1.5 measured the result:
+ * **Nothing is converted.** Shade keeps `projection_matrix` and `view_matrix` as column-major
+ * `Float32Array(16)`, which is exactly what three's `.elements` already is — so the two are handed
+ * over as they stand, no copy and no per-frame work. Phase 1.5 measured the result:
  * HUD viewport positions matched three's to four decimal places across scattered world points.
  *
  * The matrices are held by reference because Shade allocates them once and writes into them; a

package/src/engine/graphics3/WaterSystem3.js

@@ -226,7 +226,7 @@ export class WaterSystem3 extends System {
          past the terrain the height map clamps — which is what lets the shore line continue instead
          of stopping at the boundary.
 
-         `Water.updateShaderForTerrain` states the same thing as a UV transform,
+         The three path stated the same thing as a UV transform,
          `(uv - 0.25) * (WATER_SIZE / terrain_size)`, and the two agree by construction: world
          position is `(u - 0.25) * WATER_SIZE`, and terrain uv is that over the terrain's own size.
         */

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

@@ -2,8 +2,8 @@
  * Point a Shade camera at whatever an entity's transform says.
  *
  * **There is no inversion here, and that is the whole content of this function.** Driving a three
- * camera requires one — `three_camera_set_transform_rotation` inverts the orientation, with a
- * comment saying three's camera points the opposite way to a normal object. Shade takes the object
+ * camera required one — the legacy camera system inverted the orientation, on the grounds that
+ * three's camera points the opposite way to a normal object. Shade takes the object
  * convention instead: forward *is* the viewing direction. Phase 1.5 measured that rather than
  * assuming it — with the orientation `Transform.lookAt` produces, 64 of 64 instances landed inside
  * Shade's frustum, and inverted, 0 of 64.

package/src/engine/graphics3/camera_sync_from_transform.js

@@ -4,8 +4,8 @@ import { assert } from "../../core/assert.js";
  * Point a Shade camera at whatever an entity's transform says.
  *
  * **There is no inversion here, and that is the whole content of this function.** Driving a three
- * camera requires one — `three_camera_set_transform_rotation` inverts the orientation, with a
- * comment saying three's camera points the opposite way to a normal object. Shade takes the object
+ * camera required one — the legacy camera system inverted the orientation, on the grounds that
+ * three's camera points the opposite way to a normal object. Shade takes the object
  * convention instead: forward *is* the viewing direction. Phase 1.5 measured that rather than
  * assuming it — with the orientation `Transform.lookAt` produces, 64 of 64 instances landed inside
  * Shade's frustum, and inverted, 0 of 64.

package/src/engine/graphics3/shade_camera_projection_ray.js

@@ -1,4 +1,4 @@
-import { mat4 } from "gl-matrix";
+import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
 import { v3_matrix4_multiply } from "../../core/geom/vec3/v3_matrix4_multiply.js";
 
 /**
@@ -51,7 +51,7 @@ const SAMPLE_DEPTH = 0.5;
  * @param {Vector3} out_direction written with a unit direction
  */
 export function shade_camera_projection_ray(camera, x, y, out_source, out_direction) {
-    mat4.invert(SCRATCH_INVERSE, camera.view_projection_matrix);
+    m4_invert(SCRATCH_INVERSE, camera.view_projection_matrix);
 
     SCRATCH_CLIP[0] = x;
     SCRATCH_CLIP[1] = y;