@woosh/meep-engine 3.17.1 → 3.18.0

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

@@ -32,9 +32,18 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
  * 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
- * compiled {@link program}, the {@link texture} to draw with, spawn rate, blend / projection /
- * feature flags, bounds sphere, render-attribute bindings and flipbook grid. Every one of those is
- * the author's, means the same thing with no device present, and is what a saved effect is made of.
+ * compiled {@link program}, the {@link texture} to draw with, spawn rate, pre-warm duration, blend /
+ * projection / feature flags, render-attribute bindings and flipbook grid. Every one of those is the author's,
+ * means the same thing with no device present, and is what a saved effect is made of.
+ *
+ * There are no bounds among them, and there is nowhere here they could go. An emitter's particles
+ * are simulated in world space by arbitrary bytecode: they go where the program sends them, at
+ * whatever size it gives them, for as long as it keeps them alive. Nothing an author could write
+ * down would bound that except "infinite", which culls nothing and marks every depth slice. So the
+ * box is measured instead — from the live particles, by a pass of its own at the end of every frame
+ * (`../bounds/`) — and it lives with the rest of the measured state in
+ * {@link ../data/PARTICLE_EMITTER_STATE.js}. The one thing that IS the author's is whether the
+ * 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
@@ -68,8 +77,8 @@ export class ParticleEmitter extends Node3D {
      * @param {string|null} [config.texture] image URL to draw with
      * @param {number} [config.seed]
      * @param {number} [config.spawn_rate] particles/second
+     * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
      * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {{center?: ArrayLike<number>, radius?: number}} [config.bounds]
      * @param {Object<string,string>} [config.render] render channel -> attribute name
      * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
      * @param {string} [config.name]
@@ -82,11 +91,8 @@ export class ParticleEmitter extends Node3D {
         texture?: string | null;
         seed?: number;
         spawn_rate?: number;
+        prewarm?: number;
         flags?: object;
-        bounds?: {
-            center?: ArrayLike<number>;
-            radius?: number;
-        };
         render?: {
             [x: string]: string;
         };
@@ -102,6 +108,7 @@ export class ParticleEmitter extends Node3D {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
     /**
      * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
+     * Replace the immutable program to edit it; do not mutate its bytecode in place.
      *
      * @type {import("../isa/ParticleProgram.js").ParticleProgram}
      */
@@ -110,8 +117,8 @@ export class ParticleEmitter extends Node3D {
      * Image to draw the particles with, by URL, or `null` to draw against the default atlas — a
      * single white texel, so an untextured emitter is a flat quad of its colour.
      *
-     * A URL rather than a texture, and no uv rect: the particle system packs every emitter's image
-     * into one sheet so that a hundred effects sharing a puff of smoke pay for one image, and where
+     * The ECS GPUParticleEmitterSystem loads this URL through AssetManager and packs the image
+     * into a shared sheet. Standalone callers provide their own atlas and regions. Where
      * a given image lands in that sheet is the system's answer, not the author's — it changes on
      * every repack, without the emitter changing. The resolved patch is
      * {@link ./GPUParticleEmitterContext.js#atlas_region}.
@@ -136,30 +143,31 @@ export class ParticleEmitter extends Node3D {
      */
     spawn_rate: number;
     /**
-     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
-     * @type {number}
-     */
-    flags: number;
-    /**
-     * Bounding sphere in emitter-local space, scaled and placed by the node's world matrix.
+     * Seconds this emitter is run forward before it is first shown, `0` for none.
      *
-     * Two passes read it: the optional simulation culling (a culled emitter sleeps), and the AVBOIT
-     * occupancy, which marks the depth slices this emitter's particles may reach. The second gives
-     * it teeth even for an emitter that does not opt into culling — a particle outside the sphere
-     * still draws, but its extinction lands in whatever physical slice the warp put nearest, so it
-     * occludes at slightly the wrong depth. Size it to hold the effect.
+     * A continuous effect — a smoke column, a dust field — starts empty and grows into its steady
+     * state over one particle lifetime, in front of whoever is watching. Setting this to about the
+     * effect's particle lifetime means the population that arrives on the first visible frame is the
+     * one the emitter would have had by then: spawned, aged, and thinned by its own program over
+     * that long, rather than a crowd of newborns.
      *
-     * Hold the *quads*, not the centres. A camera-facing billboard has almost no depth extent, but
-     * an axis-locked, world-oriented or velocity-stretched one reaches a particle size — or, when
-     * stretched, several — in front of and behind the particle it belongs to.
+     * The author's number, and the only thing about a warm-up that is authored. It is not written to
+     * the GPU record: the system queues an emitter that has one at the moment it is registered, and
+     * the warm-up pipeline (`../warmup/`) runs its simulation forward on that frame, over a
+     * population of its own, before moving the result into the scene. Longer costs a longer loop on
+     * that one frame and nothing after it.
      *
-     * @type {Float32Array}
+     * Prewarm controls the initial population's age distribution. It is not needed to bootstrap
+     * culling: emitters without a measured population have unknown bounds and remain eligible to spawn.
+     *
+     * @type {number}
      */
-    bounds_center: Float32Array;
+    prewarm: number;
     /**
+     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
      * @type {number}
      */
-    bounds_radius: number;
+    flags: number;
     /**
      * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
      * is a single frame.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA+QI;;;;;;;;;;;;;;;;;;;;;;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,KAAK,GAArB,MAAM;QACiD,MAAM,GAA7D;YAAC,MAAM,CAAC,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACd,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CAqD3B;IAvVD;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;OAIG;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;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;OAcG;IACH,eAFU,YAAY,CAEc;IAEpC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;;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,CAwBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CA0BlB;IAED;;;;;;;;;;;;OAYG;IACH,YAFW,eAAe,QAyBzB;IAED;;;;;;OAMG;IACH,SAFa,eAAe,CAgB3B;IA+EL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;uBA3ZsB,uBAAuB"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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;uBA1ZsB,uBAAuB"}