@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/particles/runtime/GPUParticleEmitterContext.d.ts

@@ -2,10 +2,10 @@
  * Everything the GPU side knows about one {@link ./ParticleEmitter.js} that the emitter itself has
  * no business knowing.
  *
- * An emitter is a scene node and a description of an effect: what to run, how fast, how big, which
- * attribute is the colour. None of that depends on a device. The rest — which row of the emitter
- * table it was given, which tenancy of that row it is, where its program was placed in the program
- * heap, which `transforms` row its node ended up in, where its texture was packed into the atlas —
+ * An emitter is a description of an effect: what to run, how fast, how big, which attribute is
+ * the colour. None of that depends on a device. The rest — which row of the emitter table it was
+ * given, which tenancy of that row it is, where its program was placed in the program heap, which
+ * `transforms` row it was registered at, where its texture was packed into the atlas —
  * is the particle system's bookkeeping, true only while the emitter is registered and only for the
  * registry that registered it. Kept on the emitter it would travel with a saved effect, mean
  * nothing when loaded, and be there for an author to set to a number the table has never heard of.
@@ -25,8 +25,7 @@ export class GPUParticleEmitterContext {
      * registered — it is what every live particle's record header stores, so it cannot be
      * renumbered while particles are in flight.
      *
-     * Not to be confused with {@link ./ParticleEmitter.js Node3D#id}, which is the node's own
-     * identity and the key the scene context maps to a `transforms` row.
+     * Not to be confused with {@link transform_row}, which is where the emitter is.
      *
      * @type {number}
      */
@@ -40,9 +39,9 @@ export class GPUParticleEmitterContext {
      */
     generation: number;
     /**
-     * Row of the scene database's `transforms` table the emitter's node occupies, as the scene
-     * context reported it — what the record's `node` field carries. `0` (the scene root) until
-     * bound, so an emitter registered before its node is placed still reads a valid row.
+     * Row of the scene database's `transforms` table the emitter is placed at — its entity's,
+     * one on — what the record's `node` field carries. `0` (the scene root) until bound, so an
+     * emitter registered before it is placed still reads a valid row.
      *
      * @type {number}
      */
@@ -73,20 +72,15 @@ export class GPUParticleEmitterContext {
      */
     atlas_region: Float32Array;
     /**
-     * The emitter's {@link ../../scene/Node3D.js Node3D#version} as of the last time its row was
+     * The emitter's version as of the last time its row was
      * staged, or `-1` for a row that must be restaged whatever the emitter says.
      *
      * This is the whole of the dirty tracking: {@link ./EmitterRegistry.js#flush} restages an
-     * emitter whose version has moved since. A node already counts its own changes for the
-     * renderer, and a second flag on the emitter saying the same thing would be one more thing to
-     * forget to set — so the emitter carries none, and an author who changes a field marks it the
-     * way they mark any node change, with `needsUpdate = true`.
+     * emitter whose version has moved since. The emitter counts its own changes, and a second
+     * flag saying the same thing would be one more thing to forget to set — so it carries none, and
+     * an author who changes a field marks it with `needsUpdate = true`.
      *
-     * The version is the node's, so it also moves when the node merely moves, and the row is
-     * restaged for a change it does not hold. That costs one row: an emitter that moved is an
-     * emitter whose `transforms` row the scene context is uploading this frame anyway.
-     *
-     * A version of `-1` is unreachable for a node — the counter starts at 0 and only rises — so it
+     * A version of `-1` is unreachable for an emitter — the counter starts at 0 and only rises — so it
      * is safe as the "not staged" sentinel, and it is what the fields above are set back to when
      * one of *them* changes, since those move without the emitter moving.
      *

package/src/shade/renderer/particles/runtime/GPUParticleEmitterContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleEmitterContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;;;;;;;OASG;IACH,KAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;OAOG;IACH,WAFU,OAAO,uBAAuB,EAAE,gBAAgB,GAAC,IAAI,CAE9C;IAEjB;;OAEG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,GAAC,IAAI,CAEnD;IAEf;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEwB;IAE9C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,OAAO,CAInB;IAED;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAFW,OAAO,sBAAsB,EAAE,eAAe,QAMxD;CACJ"}
+{"version":3,"file":"GPUParticleEmitterContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;;;;;;OAQG;IACH,KAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;OAOG;IACH,WAFU,OAAO,uBAAuB,EAAE,gBAAgB,GAAC,IAAI,CAE9C;IAEjB;;OAEG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,GAAC,IAAI,CAEnD;IAEf;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEwB;IAE9C;;;;;;;;;;;;;;OAcG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,OAAO,CAInB;IAED;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAFW,OAAO,sBAAsB,EAAE,eAAe,QAMxD;CACJ"}

package/src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js

@@ -4,10 +4,10 @@ import { assert } from "../../../../core/assert.js";
  * Everything the GPU side knows about one {@link ./ParticleEmitter.js} that the emitter itself has
  * no business knowing.
  *
- * An emitter is a scene node and a description of an effect: what to run, how fast, how big, which
- * attribute is the colour. None of that depends on a device. The rest — which row of the emitter
- * table it was given, which tenancy of that row it is, where its program was placed in the program
- * heap, which `transforms` row its node ended up in, where its texture was packed into the atlas —
+ * An emitter is a description of an effect: what to run, how fast, how big, which attribute is
+ * the colour. None of that depends on a device. The rest — which row of the emitter table it was
+ * given, which tenancy of that row it is, where its program was placed in the program heap, which
+ * `transforms` row it was registered at, where its texture was packed into the atlas —
  * is the particle system's bookkeeping, true only while the emitter is registered and only for the
  * registry that registered it. Kept on the emitter it would travel with a saved effect, mean
  * nothing when loaded, and be there for an author to set to a number the table has never heard of.
@@ -28,8 +28,7 @@ export class GPUParticleEmitterContext {
      * registered — it is what every live particle's record header stores, so it cannot be
      * renumbered while particles are in flight.
      *
-     * Not to be confused with {@link ./ParticleEmitter.js Node3D#id}, which is the node's own
-     * identity and the key the scene context maps to a `transforms` row.
+     * Not to be confused with {@link transform_row}, which is where the emitter is.
      *
      * @type {number}
      */
@@ -45,9 +44,9 @@ export class GPUParticleEmitterContext {
     generation = 0;
 
     /**
-     * Row of the scene database's `transforms` table the emitter's node occupies, as the scene
-     * context reported it — what the record's `node` field carries. `0` (the scene root) until
-     * bound, so an emitter registered before its node is placed still reads a valid row.
+     * Row of the scene database's `transforms` table the emitter is placed at — its entity's,
+     * one on — what the record's `node` field carries. `0` (the scene root) until bound, so an
+     * emitter registered before it is placed still reads a valid row.
      *
      * @type {number}
      */
@@ -61,12 +60,12 @@ export class GPUParticleEmitterContext {
      *
      * @type {import("./ProgramPlacement.js").ProgramPlacement|null}
      */
-    placement = null;
-
-    /** Author's immutable program reference, distinct from the heap's owned copy.
-     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
-     */
-    program = null;
+    placement = null;
+
+    /** Author's immutable program reference, distinct from the heap's owned copy.
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    program = null;
 
     /**
      * Where {@link ./ParticleEmitter.js#texture} landed in the particle system's atlas: uv offset
@@ -82,20 +81,15 @@ export class GPUParticleEmitterContext {
     atlas_region = new Float32Array([0, 0, 1, 1]);
 
     /**
-     * The emitter's {@link ../../scene/Node3D.js Node3D#version} as of the last time its row was
+     * The emitter's version as of the last time its row was
      * staged, or `-1` for a row that must be restaged whatever the emitter says.
      *
      * This is the whole of the dirty tracking: {@link ./EmitterRegistry.js#flush} restages an
-     * emitter whose version has moved since. A node already counts its own changes for the
-     * renderer, and a second flag on the emitter saying the same thing would be one more thing to
-     * forget to set — so the emitter carries none, and an author who changes a field marks it the
-     * way they mark any node change, with `needsUpdate = true`.
-     *
-     * The version is the node's, so it also moves when the node merely moves, and the row is
-     * restaged for a change it does not hold. That costs one row: an emitter that moved is an
-     * emitter whose `transforms` row the scene context is uploading this frame anyway.
+     * emitter whose version has moved since. The emitter counts its own changes, and a second
+     * flag saying the same thing would be one more thing to forget to set — so it carries none, and
+     * an author who changes a field marks it with `needsUpdate = true`.
      *
-     * A version of `-1` is unreachable for a node — the counter starts at 0 and only rises — so it
+     * A version of `-1` is unreachable for an emitter — the counter starts at 0 and only rises — so it
      * is safe as the "not staged" sentinel, and it is what the fields above are set back to when
      * one of *them* changes, since those move without the emitter moving.
      *

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts

@@ -22,20 +22,20 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
     [x: string]: number;
 };
 /**
- * One particle emitter: a scene node that runs a compiled effect.
+ * One particle emitter: a compiled effect, run at a place in the scene.
  *
  * **In a game, this is built for you.** An entity carrying
  * {@link ../../../../engine/graphics/ecs/particles/ParticleEffect.js ParticleEffect} and a
  * `Transform64` gets one of these from `engine/graphics3/GPUParticleEmitterSystem.js`, which owns it
  * and keeps every field below in step with the component. Build one by hand for the cases with no
  * ECS behind them — a playground, a tool, a spec — or reach for the one the system built through its
- * `node_of(entity)` when an entity reference cannot say what you mean.
+ * `emitter_of(entity)` when an entity reference cannot say what you mean.
  *
- * Being a {@link Node3D} is what places it. Add it to a scene and it gets a row in the scene
- * database's `transforms` table like any other node; parent it to a joint and the GPU hierarchy
- * pass composes its world matrix from the joint's every frame, animation included, with nothing
- * copied through the CPU. Remove it from the scene and the row goes with it — and so do its
- * particles, within a frame, because the emitter's table row is retired with it and its particles
+ * Where it is comes from the `transforms` row it is registered at
+ * ({@link ../GPUParticleSystem.js#add_emitter}), which is an entity's row, one on. The hierarchy
+ * pass composes that row's world every frame — register an emitter at a joint's row and it moves
+ * with the joint, animation included, with nothing copied through the CPU. Unregister it and its
+ * row in the emitter table is retired, and its particles with it within a frame, because they
  * carry that row's generation. There is no transform of its own to keep in step with anything.
  *
  * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
@@ -53,7 +53,7 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
  * emitter opts into culling at all: `EMITTER_FLAG.CULL` in {@link flags}.
  *
  * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
- * its program was placed in the program heap, which `transforms` row its node ended up in, where
+ * its program was placed in the program heap, which `transforms` row it was registered at, where
  * its texture was packed into the atlas — all of that is
  * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
  * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
@@ -62,12 +62,11 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
  * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
  *
  * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
- * node's own change counter, the same one the renderer reads to decide whether a transform needs
- * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
- * counter rather than a setter per field because a row is restaged whole either way: one changed
- * field and ten cost the same upload.
+ * emitter's change counter — and {@link ./EmitterRegistry.js#flush} restages the row on its next
+ * flush. One counter rather than a setter per field because a row is restaged whole either way:
+ * one changed field and ten cost the same upload.
  */
-export class ParticleEmitter extends Node3D {
+export class ParticleEmitter {
     /**
      * Build an emitter from a plain description. Every parameter is optional except the compiled
      * effect — an emitter with no program has nothing to run.
@@ -106,6 +105,22 @@ export class ParticleEmitter extends Node3D {
         flipbook?: ArrayLike<number>;
         name?: string;
     }): ParticleEmitter;
+    /**
+     * For a debugger, and for nothing else.
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * @returns {number}
+     */
+    get version(): number;
+    /**
+     * Say that a field changed. Reading it back answers nothing: the counter is the record.
+     *
+     * @param {boolean} value
+     */
+    set needsUpdate(value: boolean);
     /**
      * The per-particle attribute schema: which named attributes a particle of this emitter has, how
      * wide each is, and what word of the record it sits at.
@@ -215,10 +230,8 @@ export class ParticleEmitter extends Node3D {
      * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
      * effect in one place, and one row would serve both.
      *
-     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
-     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
-     * be compared. {@link transform_global} is left out too, being derived from
-     * {@link transform_local} and the parent chain.
+     * Where it is registered is not part of it — the row says where an emitter is, not what it is
+     * — and neither is anything the GPU assigned it, which is not here to be compared.
      *
      * @param {ParticleEmitter} other
      * @returns {boolean}
@@ -233,23 +246,20 @@ export class ParticleEmitter extends Node3D {
      */
     hash(): number;
     /**
-     * Make this emitter a copy of `other`: same effect, same settings, same placement.
+     * Make this emitter a copy of `other`: same effect, same settings.
      *
      * The layout and the compiled program are shared rather than duplicated — both are immutable
      * once compiled, and sharing them is what puts two emitters of one effect on one program id in
      * the program heap, hence in one simulation bucket.
      *
-     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
-     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
+     * What is not copied is anything a registry gave the original: a copy is a second emitter, not
      * a second reference to the first one's table row.
      *
      * @param {ParticleEmitter} other
      */
     copy(other: ParticleEmitter): void;
     /**
-     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
-     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
-     * `Node3D`, which would keep the transform and drop the effect.
+     * A second emitter equal to this one, and registered with nothing.
      *
      * @returns {ParticleEmitter}
      */
@@ -259,6 +269,6 @@ export class ParticleEmitter extends Node3D {
      * @type {boolean}
      */
     readonly isParticleEmitter: boolean;
+    #private;
 }
-import { Node3D } from "../../scene/Node3D.js";
 //# sourceMappingURL=ParticleEmitter.d.ts.map

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA0QI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CAgD3B;IA7UD;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;;;OAYG;IACH,cAHW,eAAe,GACb,OAAO,CAuBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;;;OAYG;IACH,YAFW,eAAe,QAwBzB;IAED;;;;;;OAMG;IACH,SAFa,eAAe,CAgB3B;IA0EL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;uBAjasB,uBAAuB"}
+{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IA0RI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CA+C3B;IA7VD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAUV;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;OAUG;IACH,cAHW,eAAe,GACb,OAAO,CAsBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;;OAWG;IACH,YAFW,eAAe,QAsBzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAQ3B;IAyEL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C"}

package/src/shade/renderer/particles/runtime/ParticleEmitter.js

@@ -5,7 +5,6 @@ import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { Node3D } from "../../scene/Node3D.js";
 import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
 /**
@@ -41,20 +40,20 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
 });
 
 /**
- * One particle emitter: a scene node that runs a compiled effect.
+ * One particle emitter: a compiled effect, run at a place in the scene.
  *
  * **In a game, this is built for you.** An entity carrying
  * {@link ../../../../engine/graphics/ecs/particles/ParticleEffect.js ParticleEffect} and a
  * `Transform64` gets one of these from `engine/graphics3/GPUParticleEmitterSystem.js`, which owns it
  * and keeps every field below in step with the component. Build one by hand for the cases with no
  * ECS behind them — a playground, a tool, a spec — or reach for the one the system built through its
- * `node_of(entity)` when an entity reference cannot say what you mean.
+ * `emitter_of(entity)` when an entity reference cannot say what you mean.
  *
- * Being a {@link Node3D} is what places it. Add it to a scene and it gets a row in the scene
- * database's `transforms` table like any other node; parent it to a joint and the GPU hierarchy
- * pass composes its world matrix from the joint's every frame, animation included, with nothing
- * copied through the CPU. Remove it from the scene and the row goes with it — and so do its
- * particles, within a frame, because the emitter's table row is retired with it and its particles
+ * Where it is comes from the `transforms` row it is registered at
+ * ({@link ../GPUParticleSystem.js#add_emitter}), which is an entity's row, one on. The hierarchy
+ * pass composes that row's world every frame — register an emitter at a joint's row and it moves
+ * with the joint, animation included, with nothing copied through the CPU. Unregister it and its
+ * row in the emitter table is retired, and its particles with it within a frame, because they
  * carry that row's generation. There is no transform of its own to keep in step with anything.
  *
  * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
@@ -72,7 +71,7 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
  * emitter opts into culling at all: `EMITTER_FLAG.CULL` in {@link flags}.
  *
  * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
- * its program was placed in the program heap, which `transforms` row its node ended up in, where
+ * its program was placed in the program heap, which `transforms` row it was registered at, where
  * its texture was packed into the atlas — all of that is
  * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
  * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
@@ -81,12 +80,43 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
  * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
  *
  * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
- * node's own change counter, the same one the renderer reads to decide whether a transform needs
- * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
- * counter rather than a setter per field because a row is restaged whole either way: one changed
- * field and ten cost the same upload.
+ * emitter's change counter — and {@link ./EmitterRegistry.js#flush} restages the row on its next
+ * flush. One counter rather than a setter per field because a row is restaged whole either way:
+ * one changed field and ten cost the same upload.
  */
-export class ParticleEmitter extends Node3D {
+export class ParticleEmitter {
+    /**
+     * For a debugger, and for nothing else.
+     *
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * Moved by every {@link needsUpdate}; what a registry compares against the version it last
+     * staged the row from.
+     *
+     * @type {number}
+     */
+    #version = 0;
+
+    /**
+     * @returns {number}
+     */
+    get version() {
+        return this.#version;
+    }
+
+    /**
+     * Say that a field changed. Reading it back answers nothing: the counter is the record.
+     *
+     * @param {boolean} value
+     */
+    set needsUpdate(value) {
+        if (value) {
+            this.#version++;
+        }
+    }
 
     /**
      * The per-particle attribute schema: which named attributes a particle of this emitter has, how
@@ -232,10 +262,8 @@ export class ParticleEmitter extends Node3D {
      * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
      * effect in one place, and one row would serve both.
      *
-     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
-     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
-     * be compared. {@link transform_global} is left out too, being derived from
-     * {@link transform_local} and the parent chain.
+     * Where it is registered is not part of it — the row says where an emitter is, not what it is
+     * — and neither is anything the GPU assigned it, which is not here to be compared.
      *
      * @param {ParticleEmitter} other
      * @returns {boolean}
@@ -258,7 +286,6 @@ export class ParticleEmitter extends Node3D {
             && this.render_frame === other.render_frame
             && this.render_velocity === other.render_velocity
             && is_typed_array_equals(this.flipbook, other.flipbook)
-            && this.transform_local.equals(other.transform_local)
             && this.layout.equals(other.layout)
             && this.program.equals(other.program);
     }
@@ -287,27 +314,24 @@ export class ParticleEmitter extends Node3D {
 
         return hash_mix3(
             hash_mix2(bindings, flipbook),
-            hash_mix2(appearance, this.transform_local.hash()),
+            appearance,
             hash_mix2(this.layout.hash(), this.program.hash())
         );
     }
 
     /**
-     * Make this emitter a copy of `other`: same effect, same settings, same placement.
+     * Make this emitter a copy of `other`: same effect, same settings.
      *
      * The layout and the compiled program are shared rather than duplicated — both are immutable
      * once compiled, and sharing them is what puts two emitters of one effect on one program id in
      * the program heap, hence in one simulation bucket.
      *
-     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
-     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
+     * What is not copied is anything a registry gave the original: a copy is a second emitter, not
      * a second reference to the first one's table row.
      *
      * @param {ParticleEmitter} other
      */
     copy(other) {
-        super.copy(other);
-
         this.name = other.name;
 
         this.layout = other.layout;
@@ -330,9 +354,7 @@ export class ParticleEmitter extends Node3D {
     }
 
     /**
-     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
-     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
-     * `Node3D`, which would keep the transform and drop the effect.
+     * A second emitter equal to this one, and registered with nothing.
      *
      * @returns {ParticleEmitter}
      */
@@ -341,14 +363,6 @@ export class ParticleEmitter extends Node3D {
 
         r.copy(this);
 
-        for (const child of this.children) {
-            const clone = child.clone();
-
-            clone.parent = r;
-
-            r.children.push(clone);
-        }
-
         return r;
     }
 
@@ -393,10 +407,9 @@ export class ParticleEmitter extends Node3D {
             emitter.texture = config.texture;
         }
 
-        if (config.position !== undefined) {
-            emitter.transform_local.setTranslation(config.position[0], config.position[1], config.position[2]);
-            emitter.updateMatrices();
-        }
+        // an emitter is placed by the row it is registered at, which is an entity's; a position
+        // here would be a second placement nothing reads
+        assert.equal(config.position, undefined, "config.position: place the emitter's entity, not the emitter");
 
         if (config.seed !== undefined) {
             emitter.seed = config.seed;

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js

@@ -376,7 +376,7 @@ export class AccumulatingPathTracer {
             const r_materials = graphics.materials_resident;
             const scene_ctx = view.scene;
 
-            r_materials.ensure_scene_materials(scene_ctx.scene);
+            r_materials.ensure_scene_materials(scene_ctx);
             r_materials.update();
 
             const geometries = scene_ctx.geometries;

package/src/shade/renderer/path_tracer/graph_path_trace_scene.js

@@ -128,7 +128,7 @@ export function graph_path_trace_scene({
 
         const scene_ctx = view.scene;
 
-        r_materials.ensure_scene_materials(scene_ctx.scene);
+        r_materials.ensure_scene_materials(scene_ctx);
         r_materials.update();
 
         const geometries = scene_ctx.geometries;

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -53,7 +53,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#166@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#173@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CAuTnH"}
+{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CAgUnH"}

package/src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js

@@ -129,6 +129,15 @@ export function graph_prepare_meshlet_draw_commands_by_material({
         expected_output_size: meshlet_buffer_size,
     });
 
+    /*
+     No virtual-geometry seam here, and not for want of a place to put one. This path serves the
+     transparent and alpha-tested draws, and it is handed a `scene` and an optional camera
+     *resource* rather than a `GPUViewContext` — where a cut needs the camera's uniform buffer to
+     put each instance into object space. The deeper reason is that it would be the wrong thing to
+     add: `VIRTUAL_GEOMETRY_DESIGN.md` §9 scopes v1 to static opaque geometry, and the opaque paths
+     are where the seam lives.
+     */
+
     graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, meshlets);
 
     if (hzb !== -1 && camera !== -1) {

package/src/shade/renderer/rasterize/expand/bucket/mesh/graph_meshes_classify_buckets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_meshes_classify_buckets.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/mesh/graph_meshes_classify_buckets.js"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACT,MAAM,EAAtB,MAAM;IACmB,SAAS;IACL,MAAM;IACjC,MAAM,CAuHlB"}
+{"version":3,"file":"graph_meshes_classify_buckets.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/mesh/graph_meshes_classify_buckets.js"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACT,MAAM,EAAtB,MAAM;IACmB,SAAS;IACL,MAAM;IACjC,MAAM,CAwHlB"}

package/src/shade/renderer/rasterize/expand/bucket/mesh/graph_meshes_classify_buckets.js

@@ -50,7 +50,8 @@ export function graph_meshes_classify_buckets({
 
         const encoder = context.encoder;
 
-        const instance_count = scene_ctx.scene.instance_count;
+        // occupied mesh rows: the table the cull ran over, and everything a scene draws
+        const instance_count = scene_ctx.scene_database.get('meshes').count;
 
         if (instance_count === 0) {
             // nothing to do

package/src/shade/renderer/rasterize/expand/bucket/mesh/graph_scene_meshes_cull_and_classify_buckets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_scene_meshes_cull_and_classify_buckets.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/mesh/graph_scene_meshes_cull_and_classify_buckets.js"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACA,SAAS;IAClB,MAAM,EAAtB,MAAM;IACJ,MAAM,CA6HlB"}
+{"version":3,"file":"graph_scene_meshes_cull_and_classify_buckets.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/rasterize/expand/bucket/mesh/graph_scene_meshes_cull_and_classify_buckets.js"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH;IAN+B,KAAK;IACA,SAAS;IAClB,MAAM,EAAtB,MAAM;IACJ,MAAM,CAgIlB"}

package/src/shade/renderer/rasterize/expand/bucket/mesh/graph_scene_meshes_cull_and_classify_buckets.js

@@ -114,10 +114,13 @@ export function graph_scene_meshes_cull_and_classify_buckets({
 
     const pass = graph.add('classify mesh buckets', pass_data, execute);
 
+    // occupied mesh rows, as the buffers are sized when the graph is built
+    const instance_count = scene_ctx.scene_database.get('meshes').count;
+
     pass_data.buffer_0 = pass.create(
         '0',
         BufferResourceDescriptor.from(
-            HEADER_0_SIZE + u32.size * scene_ctx.scene.instance_count,
+            HEADER_0_SIZE + u32.size * instance_count,
             GPUBufferUsage.STORAGE,
             0, HEADER_0_SIZE,
         )
@@ -127,7 +130,7 @@ export function graph_scene_meshes_cull_and_classify_buckets({
         '1',
         BufferResourceDescriptor.from(
             round_up(
-                RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE.aligned_size + u32.size * Math.max(16, scene_ctx.scene.instance_count),
+                RASTERIZATION_BUCKET_SORT_OUTPUT_HEADER_STRUCT_WRITE.aligned_size + u32.size * Math.max(16, instance_count),
                 RASTERIZATION_BUCKET_SORT_OUTPUT_STRUCT_WRITE.align,
             ),
             GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0I3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}
+{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CAoJ3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js

@@ -9,6 +9,7 @@ import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterizat
 import { graph_meshes_classify_buckets } from "../expand/bucket/mesh/graph_meshes_classify_buckets.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
+import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state } from "../bucket/construct_primitive_state.js";
 import { graph_mesh_frustum_cull } from "../compute/graph_mesh_frustum_cull.js";
@@ -54,7 +55,7 @@ export function graph_rasterize_scene_fast_raw({
         limits,
     });
 
-    const cached_materials = scene_ctx.scene.instances.materials;
+    const cached_materials = scene_ctx.drawn_materials;
 
     /**
      * @type {Set<number>}
@@ -91,7 +92,7 @@ export function graph_rasterize_scene_fast_raw({
                 limits,
             });
 
-            const gr_bucket_meshlets = graph_expand_meshes_to_meshlets({
+            let gr_bucket_meshlets = graph_expand_meshes_to_meshlets({
                 graph,
                 input_meshes: gr_bucket_meshes,
                 scene: scene_ctx,
@@ -99,6 +100,16 @@ export function graph_rasterize_scene_fast_raw({
                 limits,
             });
 
+            // the seam: this bucket's virtual-geometry instances select their cut and append it to
+            // the same collection, which is the whole of what the rest of this function is told
+            gr_bucket_meshlets = graph_vgeo_expand_if_enabled({
+                graph,
+                input_meshes: gr_bucket_meshes,
+                output_meshlets: gr_bucket_meshlets,
+                view: view_ctx,
+                limits,
+            });
+
             graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, gr_bucket_meshlets);
 
             const primitive_state = construct_primitive_state(draw_mode, side, job.cull_policy);