@woosh/meep-engine 3.23.0 → 3.25.0

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -8,6 +8,7 @@ import { System } from "../ecs/System.js";
 import Name from "../ecs/name/Name.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
 import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
 import { GameAssetType } from "../asset/GameAssetType.js";
 import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
 import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
@@ -34,7 +35,10 @@ const BURST_QUEUE_LIMIT = 256;
  * @property {number} entity
  * @property {ParticleEffect} effect the entity's component — what to emit
  * @property {Transform64} transform the entity's transform — where to emit it
- * @property {ParticleEmitter|null} node the scene node, once the effect has a program to run
+ * @property {ParticleEmitter|null} emitter the emitter, once the effect has a program to run
+ * @property {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} context
+ * the scene context the emitter is registered with, at the entity's row; null until a frame has
+ * registered it, or after a device restart took that context away
  * @property {function():void} on_transform_changed
  * @property {string|null} url last observed {@link ParticleEffect#texture}
  * @property {ParticleAtlasTexture|null} texture shared image record, or null for an untextured effect
@@ -62,14 +66,14 @@ const BURST_QUEUE_LIMIT = 256;
  *
  * ## What this system does with the pair
  *
- * It builds a {@link ParticleEmitter} scene node per entity and owns it: the node is added to
- * {@link scene} when the component has a compiled effect, follows the entity's transform, carries
- * whatever the component currently says, and leaves the scene when the entity does. The node is not
- * hidden — {@link node_of} hands it out — but it is not the interface either: write to the
- * component and the next frame carries it.
+ * It builds a {@link ParticleEmitter} per entity and owns it: the emitter is registered with the
+ * scene's particle system at the entity's row when the component has a compiled effect, so it
+ * stands where the entity stands, carries whatever the component currently says, and is retired
+ * when the entity goes. The emitter is not hidden — {@link emitter_of} hands it out — but it is
+ * not the interface either: write to the component and the next frame carries it.
  *
  * Changes are found by **comparison** rather than announced. Once a frame each entity's
- * fields are compared against what was last written to its node, and the node is marked dirty only
+ * fields are compared against what was last written to its emitter, and the emitter is marked dirty only
  * where they differ; `EmitterRegistry` then restages exactly the rows that moved. A component nobody
  * touched costs a run of integer comparisons and no upload, so there is no change signal to fire and
  * none to forget. What that buys is that gameplay can write `effect.spawn_rate = 0` anywhere,
@@ -85,9 +89,9 @@ const BURST_QUEUE_LIMIT = 256;
  * whole rather than when a URL changes. Pending and failed images sample a transparent texel;
  * effects with no image sample a white one.
  *
- * An emitter node in this scene that this system did not build — one added to the `Scene` directly —
- * gets the white texel. The atlas is the scene's and that emitter has nothing in it, so the
- * alternative is not "its own texture" but a UV rectangle from somebody else's image.
+ * An emitter in this scene that this system did not build — one registered with the particle
+ * system directly — gets the white texel. The atlas is the scene's and that emitter has nothing in
+ * it, so the alternative is not "its own texture" but a UV rectangle from somebody else's image.
  *
  * ## What it is not
  *
@@ -117,11 +121,11 @@ export class GPUParticleEmitterSystem extends System {
     /** @type {Map<number, ParticleEmitterEntry>} */
     #entries = new Map();
     /**
-     * The same entries by the node they own, so that the emitters this system did not build can be
-     * told apart from the ones it did without a linear search per emitter per frame.
+     * The same entries by the emitter they own, so that the emitters this system did not build can
+     * be told apart from the ones it did without a linear search per emitter per frame.
      * @type {Map<ParticleEmitter, ParticleEmitterEntry>}
      */
-    #by_node = new Map();
+    #by_emitter = new Map();
     /** @type {Map<string, ParticleAtlasTexture>} */
     #textures = new Map();
     /**
@@ -183,35 +187,34 @@ export class GPUParticleEmitterSystem extends System {
     }
 
     /**
-     * The emitter nodes this system currently has in the scene, in no particular order. Read-only —
-     * they follow the entities.
+     * The emitters this system currently holds, in no particular order. Read-only — they follow
+     * the entities.
      *
      * @returns {ParticleEmitter[]}
      */
     get emitters() {
-        return Array.from(this.#by_node.keys());
+        return Array.from(this.#by_emitter.keys());
     }
 
     /**
-     * The scene node built for an entity.
+     * The emitter built for an entity.
      *
-     * Handed out for the things an entity reference cannot express — parenting something to the
-     * emitter, reading the world matrix the hierarchy pass composed — and for nothing routine: the
-     * component is how an effect is changed, and a node written to behind the component's back is
-     * overwritten by the next comparison.
+     * Handed out for what an entity reference cannot express — asking the particle system about
+     * it — and for nothing routine: the component is how an effect is changed, and an emitter
+     * written to behind the component's back is overwritten by the next comparison.
      *
      * @param {number} entity
      * @returns {ParticleEmitter|null} `null` for an entity this system has not linked, or one whose
      * component has no compiled effect yet
      */
-    node_of(entity) {
+    emitter_of(entity) {
         const entry = this.#entries.get(entity);
 
         if (entry === undefined) {
             return null;
         }
 
-        return entry.node;
+        return entry.emitter;
     }
 
     /**
@@ -261,6 +264,17 @@ export class GPUParticleEmitterSystem extends System {
     async startup(entityManager) {
         this.entityManager = entityManager;
 
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
         if (!this.#assets.hasLoaderForType(GameAssetType.Image)) {
             await this.#assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
         }
@@ -308,7 +322,8 @@ export class GPUParticleEmitterSystem extends System {
             entity,
             effect,
             transform,
-            node: null,
+            emitter: null,
+            context: null,
             on_transform_changed: null,
             url: null,
             texture: null
@@ -329,9 +344,13 @@ export class GPUParticleEmitterSystem extends System {
             entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
         );
 
-        // Everything else — building the node, acquiring the texture — is what a frame does anyway,
-        // and doing it here as well would be a second copy of it that has to stay in step.
+        // Everything else — building the emitter, acquiring the texture — is what a frame does
+        // anyway, and doing it here as well would be a second copy of it that has to stay in step.
         this.#sync(entry);
+
+        // Registered now when there is a context to register with, so an entity spawned mid-level
+        // stands where it should from its first frame.
+        this.#register_all();
     }
 
     /**
@@ -344,9 +363,9 @@ export class GPUParticleEmitterSystem extends System {
     }
 
     /**
-     * Bring every emitter in line with its entity: build nodes for effects that have arrived, retire
-     * nodes for effects that have gone, copy changed fields onto the ones that stay, and follow the
-     * texture URLs.
+     * Bring every emitter in line with its entity: build emitters for effects that have arrived,
+     * retire emitters for effects that have gone, copy changed fields onto the ones that stay, and
+     * follow the texture URLs.
      *
      * @param {number} [time_delta_seconds]
      * @returns {void}
@@ -356,9 +375,51 @@ export class GPUParticleEmitterSystem extends System {
             this.#sync(entry);
         }
 
+        /*
+         Registered here as well as at FrameStart, so an emitter whose effect arrived during a
+         simulation tick has its row written by the next frame's build rather than the one after:
+         a frame builds the scene context before FrameStart runs, so a row acquired at FrameStart
+         is not written until the frame after.
+        */
+        this.#register_all();
+
         this.atlas.update();
     }
 
+    /**
+     * The particle system a scene context's frames run, or null while there is no renderer.
+     *
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} context
+     * @returns {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null}
+     */
+    #particles_of(context) {
+        const renderer = this.#graphics.renderer;
+
+        if (renderer === null || renderer === undefined) {
+            return null;
+        }
+
+        return renderer.particles(context);
+    }
+
+    /**
+     * {@link #register} against whatever context and particle system the scene has right now, if
+     * it has any.
+     */
+    #register_all() {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            return;
+        }
+
+        const particles = this.#particles_of(context);
+
+        if (particles !== null) {
+            this.#register(particles, context);
+        }
+    }
+
     /**
      * Publish the atlas at FrameStart — after the scene context has established transform rows, and
      * before the renderer records the particle passes that read the emitter table.
@@ -399,7 +460,7 @@ export class GPUParticleEmitterSystem extends System {
             this.#previous_atlas = particles.atlas;
         }
 
-        particles.sync_membership();
+        this.#register(particles, frame.view.scene);
 
         this.#upload(renderer.graphics.device);
 
@@ -409,6 +470,34 @@ export class GPUParticleEmitterSystem extends System {
         this.#drain_bursts(particles);
     }
 
+    /**
+     * Register every emitter not yet registered with this context, at its entity's row.
+     *
+     * From {@link update} and {@link prepare} rather than at link, because a row needs a scene
+     * context and the context needs a device, and neither is a system's to wait for: a level loads
+     * before the device is up, and a device restart replaces the context under every entry. An
+     * entry registered with a context that is no longer this one is registered again with the one
+     * that is. Idempotent, and a comparison per entry when nothing has changed.
+     *
+     * @param {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem} particles
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
+     */
+    #register(particles, scene_context) {
+        const rows = scene_context.rows;
+
+        for (const entry of this.#entries.values()) {
+            if (entry.emitter === null || entry.context === scene_context) {
+                continue;
+            }
+
+            rows.acquire(entry.entity);
+
+            particles.add_emitter(entry.emitter, row_of_entity(entry.entity));
+
+            entry.context = scene_context;
+        }
+    }
+
     /**
      * Point every emitter of this scene at its patch in the atlas.
      *
@@ -424,7 +513,7 @@ export class GPUParticleEmitterSystem extends System {
 
         for (let i = 0; i < emitters.length; i++) {
             const emitter = emitters[i];
-            const entry = this.#by_node.get(emitter);
+            const entry = this.#by_emitter.get(emitter);
 
             // Not ours: it has nothing in this atlas, so it gets the one patch that is true for
             // everybody — a white texel, which draws it as a flat quad of its own colour.
@@ -467,15 +556,15 @@ export class GPUParticleEmitterSystem extends System {
         for (let i = 0; i < bursts.length; i += 2) {
             const entry = this.#entries.get(bursts[i]);
 
-            if (entry === undefined || entry.node === null) {
+            if (entry === undefined || entry.emitter === null) {
                 continue;
             }
 
-            if (particles.registry.context(entry.node) === undefined) {
+            if (particles.registry.context(entry.emitter) === undefined) {
                 continue;
             }
 
-            particles.spawn(entry.node, bursts[i + 1]);
+            particles.spawn(entry.emitter, bursts[i + 1]);
         }
 
         bursts.length = 0;
@@ -505,73 +594,84 @@ export class GPUParticleEmitterSystem extends System {
         if (effect.layout === null || effect.program === null) {
             // No effect (yet, or any more). An entity whose effect is still compiling is ordinary,
             // and so is one whose effect was cleared — both mean "emits nothing", and the emitter
-            // leaves the scene rather than keeping the last program it happened to have.
-            this.#detach_node(entry);
+            // is retired rather than keeping the last program it happened to have.
+            this.#detach_emitter(entry);
 
             return;
         }
 
-        if (entry.node === null) {
-            const node = new ParticleEmitter();
+        if (entry.emitter === null) {
+            const emitter = new ParticleEmitter();
 
             /*
-             The row takes the entity's name when it has one, exactly as `ShadedGeometrySystem` does
-             for a primitive. Nothing draws differently for it: what it buys is that a walk over what
-             is in the scene is readable in a debugger.
+             The emitter takes the entity's name when it has one, exactly as `ShadedGeometrySystem`
+             does for a primitive. Nothing draws differently for it: what it buys is that a walk over
+             the registry is readable in a debugger.
             */
             const name = this.entityManager.dataset.getComponent(entry.entity, Name);
 
-            node.name = name === undefined || name === null
+            emitter.name = name === undefined || name === null
                 ? `particles/entity ${entry.entity}`
                 : name.getValue();
 
-            entry.node = node;
-
-            apply_particle_effect(node, effect);
+            entry.emitter = emitter;
 
-            this.#place(entry);
+            apply_particle_effect(emitter, effect);
 
-            this.#by_node.set(node, entry);
-            this.#scene.add(node);
-        } else if (apply_particle_effect(entry.node, effect)) {
-            // The node's own change counter, which is what EmitterRegistry restages a row from.
-            entry.node.needsUpdate = true;
+            // registered at the entity's row by the next frame — see #register
+            this.#by_emitter.set(emitter, entry);
+        } else if (apply_particle_effect(entry.emitter, effect)) {
+            // The emitter's own change counter, which is what EmitterRegistry restages a row from.
+            entry.emitter.needsUpdate = true;
         }
     }
 
     /**
+     * The entity moved: its row is rewritten from its transform by the context that holds it.
+     *
      * @param {ParticleEmitterEntry} entry
      */
     #place(entry) {
-        const node = entry.node;
+        const context = entry.context;
 
-        if (node === null) {
+        if (context === null || context !== this.#graphics.scene_context(this.#scene)) {
             return;
         }
 
-        node.transform_local.copy(entry.transform);
-
-        // recomputes transform_global down the subtree, and bumps the version the scene database
-        // reads to decide what to upload
-        node.updateMatrices();
+        context.rows.mark_world(entry.entity);
     }
 
     /**
-     * Take an entity's emitter back out of the scene, leaving the entry linked.
+     * Retire an entity's emitter and let go of its row, leaving the entry linked.
      *
      * @param {ParticleEmitterEntry} entry
      */
-    #detach_node(entry) {
-        const node = entry.node;
+    #detach_emitter(entry) {
+        const emitter = entry.emitter;
 
-        if (node === null) {
+        if (emitter === null) {
             return;
         }
 
-        this.#scene.remove(node);
-        this.#by_node.delete(node);
+        const context = entry.context;
+
+        // A context that has been replaced took its rows and its particle system with it; only the
+        // one that is running is handed anything back.
+        if (context !== null && context === this.#graphics.scene_context(this.#scene)) {
+            const particles = this.#particles_of(context);
+
+            if (particles !== null && particles.registry.context(emitter) !== undefined) {
+                particles.remove_emitter(emitter);
+            }
+
+            context.rows.release(entry.entity);
+        }
+
+        entry.context = null;
+
+        this.#by_emitter.delete(emitter);
 
-        entry.node = null;
+        entry.emitter = null;
     }
 
     /**
@@ -592,7 +692,7 @@ export class GPUParticleEmitterSystem extends System {
             entry.on_transform_changed = null;
         }
 
-        this.#detach_node(entry);
+        this.#detach_emitter(entry);
         this.#release(entry.url);
 
         entry.url = null;
@@ -724,7 +824,7 @@ export class GPUParticleEmitterSystem extends System {
 }
 
 /**
- * Copy a component onto the scene node built for it, reporting whether anything actually moved.
+ * Copy a component onto the emitter built for it, reporting whether anything actually moved.
  *
  * Comparing while assigning rather than in a pass of its own is what makes change detection cost
  * nothing extra: the fields have to be read to be written, and the only addition is an `||` per
@@ -736,28 +836,28 @@ export class GPUParticleEmitterSystem extends System {
  * to. Layout and program are shared by reference, never copied — two entities of one effect belong
  * on one program id in the heap.
  *
- * @param {ParticleEmitter} node
+ * @param {ParticleEmitter} emitter
  * @param {ParticleEffect} effect
- * @returns {boolean} whether the node differs from what it held before
+ * @returns {boolean} whether the emitter differs from what it held before
  */
-export function apply_particle_effect(node, effect) {
+export function apply_particle_effect(emitter, effect) {
     let changed = false;
 
-    changed = assign(node, "layout", effect.layout) || changed;
-    changed = assign(node, "program", effect.program) || changed;
-    changed = assign(node, "texture", effect.texture) || changed;
-    changed = assign(node, "seed", effect.seed) || changed;
-    changed = assign(node, "spawn_rate", effect.effective_spawn_rate) || changed;
-    changed = assign(node, "prewarm", effect.prewarm) || changed;
-    changed = assign(node, "flags", effect.flags) || changed;
-    changed = assign(node, "render_position", effect.render_position) || changed;
-    changed = assign(node, "render_size", effect.render_size) || changed;
-    changed = assign(node, "render_color", effect.render_color) || changed;
-    changed = assign(node, "render_rotation", effect.render_rotation) || changed;
-    changed = assign(node, "render_frame", effect.render_frame) || changed;
-    changed = assign(node, "render_velocity", effect.render_velocity) || changed;
-
-    const flipbook = node.flipbook;
+    changed = assign(emitter, "layout", effect.layout) || changed;
+    changed = assign(emitter, "program", effect.program) || changed;
+    changed = assign(emitter, "texture", effect.texture) || changed;
+    changed = assign(emitter, "seed", effect.seed) || changed;
+    changed = assign(emitter, "spawn_rate", effect.effective_spawn_rate) || changed;
+    changed = assign(emitter, "prewarm", effect.prewarm) || changed;
+    changed = assign(emitter, "flags", effect.flags) || changed;
+    changed = assign(emitter, "render_position", effect.render_position) || changed;
+    changed = assign(emitter, "render_size", effect.render_size) || changed;
+    changed = assign(emitter, "render_color", effect.render_color) || changed;
+    changed = assign(emitter, "render_rotation", effect.render_rotation) || changed;
+    changed = assign(emitter, "render_frame", effect.render_frame) || changed;
+    changed = assign(emitter, "render_velocity", effect.render_velocity) || changed;
+
+    const flipbook = emitter.flipbook;
 
     if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
         flipbook.set(effect.flipbook);

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

@@ -65,13 +65,14 @@ export class HighlightOutlineSystem extends System<any> {
      *
      * @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
+     * @param {function(function(number): void): void} rows visits the mesh rows this highlight
+     * covers — an entity's row is `entity + 1` — and visits none of them while the model is 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;
+    add_entry(entity: number, highlight: Highlight, rows: (arg0: (arg0: number) => 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.

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

@@ -1 +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,aACN,SAAS,mCACgB,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"}
+{"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;;;;;;;;;;;OAWG;IACH,kBATW,MAAM,aACN,SAAS,sBACS,MAAM,KAAG,IAAI,KAAG,IAAI,GAGpC,MAAM,CAUlB;IAED;;;OAGG;IACH,oBAHW,MAAM,QAWhB;IAeD;;OAEG;IACH,kCAmBC;;CACJ;AAED;;GAEG;AACH;IAUI;;OAEG;IACH,oBAFW,sBAAsB,EAMhC;IAED,yBAEC;;CACJ;uBA1OsB,kBAAkB;gCADT,mDAAmD"}

package/src/engine/graphics3/HighlightOutlineSystem.js

@@ -143,14 +143,15 @@ export class HighlightOutlineSystem extends System {
      *
      * @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
+     * @param {function(function(number): void): void} rows visits the mesh rows this highlight
+     * covers — an entity's row is `entity + 1` — and visits none of them while the model is 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 };
+    add_entry(entity, highlight, rows) {
+        const entry = { entity, highlight, rows };
 
         this.#entries.push(entry);
 
@@ -173,13 +174,10 @@ export class HighlightOutlineSystem extends System {
 
     /**
      * Pack this frame's table. See {@link pack_highlight_table} for why it is every frame.
-     *
-     * @param {GPUSceneContext} scene
      */
-    #pack(scene) {
+    #pack() {
         const packed = pack_highlight_table({
             entries: this.#entries,
-            scene,
             table: this.#table
         });
 
@@ -196,7 +194,7 @@ export class HighlightOutlineSystem extends System {
             return;
         }
 
-        this.#pack(frame.view.scene);
+        this.#pack();
 
         if (this.#table_size === 0) {
             // highlighted entities whose models are not in the scene yet

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

@@ -1,11 +1,13 @@
 /**
  * Mirrors light entities into Shade's scene.
  *
- * The same shape as {@link MeshSystem} and for the same reason: the ECS says what exists and where,
- * and this keeps the renderer's own objects in step. A Shade light **is** a `Node3D`, so `Scene.add`
- * routes it into the light collection on its own and placement is the same transform copy meshes
- * get — which for a directional light is also what aims it, since the engine's convention is that a
- * light shines along its forward.
+ * The same shape as {@link ShadedGeometrySystem} and for the same reason: the ECS says what exists
+ * and where, and this keeps the renderer's own objects in step. A Shade light is placed at an
+ * entity — `scene.lights.add(light, entity)` — and the GPU reads its pose from the entity's row,
+ * which the scene context holds on the light collection's behalf; the light's own `transform` is
+ * the entity's `Transform64`, the one object, so there is no copy to fall behind. For a directional
+ * light the pose is also what aims it, since the engine's convention is that a light shines along
+ * its forward.
  *
  * **Ambient lights are deliberately not carried over.** Shade lights indirect from the environment
  * by default, and that environment is the ambient term — a separate flat ambient light would be

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

@@ -1 +1 @@
-{"version":3,"file":"LightSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/LightSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;GAYG;AACH;IAgBI;;;OAGG;IACH,oDAUC;IADG,oDAAwC;IAG5C,2CAIC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,KAAK,aACL,WAAW,UACX,MAAM,QAuEhB;IAED;;;;OAIG;IACH,kBAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;;CA4BJ;uBA9KsB,kBAAkB;4BACb,iCAAiC;sBACvC,gCAAgC"}
+{"version":3,"file":"LightSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/LightSystem.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH;IAgBI;;;OAGG;IACH,oDAUC;IADG,oDAAwC;IAG5C,2CAeC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,KAAK,aACL,WAAW,UACX,MAAM,QAwEhB;IAED;;;;OAIG;IACH,kBAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;;CA4BJ;uBA5LsB,kBAAkB;4BACb,iCAAiC;sBACvC,gCAAgC"}