sparcoon 0.4.3 → 0.4.5

package/dist/emitter/FXEmitter.Internal.d.ts

@@ -1,13 +1,31 @@
+import type { Camera } from "three";
 import type { FXPropertyName, GLTypeInfo } from "../instancedParticle/shared";
+import type { FXEmitter } from "./FXEmitter";
+export interface FXEmitterOptions {
+    expectedCapacity: number;
+    capacityStep: number;
+    automaticallyDestroyModules: boolean;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    sortCamera: Camera;
+    sortFraction: number;
+}
+export interface FXEmitterBurstOptions {
+    delay: number;
+}
 export interface FXEmitterPlayOptions {
+    delay: number;
     duration: number;
 }
+export declare const EMITTERS: FXEmitter[];
 export declare const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
 export declare const EMITTER_DEFAULT_CAPACITY_STEP = 32;
 export declare const EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES = true;
 export declare const EMITTER_DEFAULT_CAST_SHADOW = false;
 export declare const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
 export declare const EMITTER_DEFAULT_SORT_FRACTION: number;
+export declare const EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION: number;
+export declare const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 10;
 export declare function collectProperties(keeper: Record<string, GLTypeInfo>, modules: readonly {
     requiredProperties?: Record<string, FXPropertyName>;
 }[], debugContext: string): void;

package/dist/emitter/FXEmitter.Internal.js

@@ -1,11 +1,14 @@
 import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
 
+const EMITTERS = new Array();
 const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
 const EMITTER_DEFAULT_CAPACITY_STEP = 32;
 const EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES = true;
 const EMITTER_DEFAULT_CAST_SHADOW = false;
 const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
 const EMITTER_DEFAULT_SORT_FRACTION = 1 / 10;
+const EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION = 1 / 60;
+const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 10;
 function collectProperties(keeper, modules, debugContext) {
     for (const module of modules) {
         if (module.requiredProperties === undefined) {
@@ -24,4 +27,4 @@ function collectProperties(keeper, modules, debugContext) {
     }
 }
 
-export { EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };
+export { EMITTERS, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };

package/dist/emitter/FXEmitter.d.ts

@@ -2,17 +2,8 @@ import type { Camera } from "three";
 import { Object3D } from "three";
 import type { FXMaterial } from "../materials/FXMaterial/FXMaterial";
 import type { FXBehavior } from "./behavior/FXBehavior";
-import type { FXEmitterPlayOptions } from "./FXEmitter.Internal";
+import type { FXEmitterBurstOptions, FXEmitterOptions, FXEmitterPlayOptions } from "./FXEmitter.Internal";
 import type { FXSpawn } from "./spawn/FXSpawn";
-export interface FXEmitterOptions {
-    expectedCapacity: number;
-    capacityStep: number;
-    automaticallyDestroyModules: boolean;
-    castShadow: boolean;
-    receiveShadow: boolean;
-    sortCamera: Camera;
-    sortFraction: number;
-}
 export declare class FXEmitter extends Object3D {
     private readonly spawnSequence;
     private readonly behaviorSequence;
@@ -21,18 +12,20 @@ export declare class FXEmitter extends Object3D {
     sortFraction: number;
     private readonly mesh;
     private readonly material;
-    private emissionRate;
-    private emissionAccumulator;
-    private emissionDuration;
-    private emissionElapsed;
+    private nextHandler;
+    private readonly pendingBursts;
+    private readonly activePlays;
     private sortingAccumulator;
     private readonly sortingCameraWorldPosition;
     constructor(spawnSequence: FXSpawn[], behaviorSequence: readonly FXBehavior[], material: FXMaterial, options?: Partial<FXEmitterOptions>);
     static onWillRender: (deltaTime: number) => void;
     destroy(): void;
-    burst(count: number): void;
+    burst(count: number, options?: Partial<FXEmitterBurstOptions>): number;
+    play(rate: number, options?: Partial<FXEmitterPlayOptions>): number;
+    stop(handler?: number): boolean;
+    prewarm(duration: number, stepDuration?: number): void;
     reset(): void;
-    play(rate: number, options?: Partial<FXEmitterPlayOptions>): void;
-    stop(): void;
+    private tick;
     private readonly onRendering;
+    private spawnBurst;
 }

package/dist/emitter/FXEmitter.js

@@ -2,76 +2,21 @@ import { Object3D, Vector3 } from 'three';
 import { FXInstancedParticle } from '../instancedParticle/FXInstancedParticle.js';
 import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
 import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_VELOCITY_Z, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C } from '../miscellaneous/miscellaneous.js';
-import { collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_SORT_FRACTION } from './FXEmitter.Internal.js';
+import { EMITTERS, collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_SORT_FRACTION, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT } from './FXEmitter.Internal.js';
 
-const EMITTERS = new Array();
 class FXEmitter extends Object3D {
     constructor(_private_spawnSequence, _private_behaviorSequence, material, options = {}) {
         super();
         this._private_spawnSequence = _private_spawnSequence;
         this._private_behaviorSequence = _private_behaviorSequence;
-        this._private_emissionRate = 0;
-        this._private_emissionAccumulator = 0;
-        this._private_emissionDuration = Infinity;
-        this._private_emissionElapsed = 0;
+        this._private_nextHandler = 0;
+        this._private_pendingBursts = [];
+        this._private_activePlays = [];
         this._private_sortingAccumulator = 0;
         this._private_sortingCameraWorldPosition = new Vector3();
         this._private_onRendering = (deltaTime) => {
-            {
-                const { builtin } = this._private_mesh.propertyBuffers;
-                const { array, itemSize } = builtin;
-                for (let i = 0; i < this._private_mesh.instanceCount; i++) {
-                    array[i * itemSize + BUILTIN_OFFSET_AGE] += deltaTime;
-                }
-                builtin.needsUpdate = true;
-                this._private_mesh.removeDeadParticles();
-            }
-            if (this._private_emissionRate > 0) {
-                this._private_emissionElapsed += deltaTime;
-                if (this._private_emissionElapsed >= this._private_emissionDuration) {
-                    this.stop();
-                }
-                else {
-                    this._private_emissionAccumulator += this._private_emissionRate * deltaTime;
-                    const particlesToSpawn = Math.floor(this._private_emissionAccumulator);
-                    if (particlesToSpawn > 0) {
-                        this.burst(particlesToSpawn);
-                        this._private_emissionAccumulator -= particlesToSpawn;
-                    }
-                }
-            }
-            if (this._private_mesh.instanceCount === 0) {
-                return;
-            }
-            {
-                const { propertyBuffers, instanceCount } = this._private_mesh;
-                for (const module of this._private_behaviorSequence) {
-                    module.update(propertyBuffers, instanceCount, deltaTime);
-                }
-            }
-            const { builtin } = this._private_mesh.propertyBuffers;
-            const { array, itemSize } = builtin;
-            {
-                for (let i = 0; i < this._private_mesh.instanceCount; i++) {
-                    const itemOffset = i * itemSize;
-                    array[itemOffset + BUILTIN_OFFSET_POSITION_X] +=
-                        array[itemOffset + BUILTIN_OFFSET_VELOCITY_X] * deltaTime;
-                    array[itemOffset + BUILTIN_OFFSET_POSITION_Y] +=
-                        array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y] * deltaTime;
-                    array[itemOffset + BUILTIN_OFFSET_POSITION_Z] +=
-                        array[itemOffset + BUILTIN_OFFSET_VELOCITY_Z] * deltaTime;
-                }
-                builtin.needsUpdate = true;
-            }
-            {
-                for (let i = 0; i < this._private_mesh.instanceCount; i++) {
-                    const itemOffset = i * itemSize;
-                    array[itemOffset + BUILTIN_OFFSET_ROTATION] +=
-                        array[itemOffset + BUILTIN_OFFSET_TORQUE] * deltaTime;
-                }
-                builtin.needsUpdate = true;
-            }
-            if (this.sortCamera !== undefined) {
+            this._private_tick(deltaTime);
+            if (this.sortCamera !== undefined && this._private_mesh.instanceCount > 0) {
                 this._private_sortingAccumulator += this.sortFraction;
                 if (this._private_sortingAccumulator >= 1) {
                     this._private_sortingAccumulator -= 1;
@@ -119,7 +64,136 @@ class FXEmitter extends Object3D {
         }
         this.removeFromParent();
     }
-    burst(count) {
+    burst(count, options = {}) {
+        const handler = this._private_nextHandler++;
+        const delay = options.delay ?? 0;
+        if (delay <= 0) {
+            this._private_spawnBurst(count);
+        }
+        else {
+            this._private_pendingBursts.push({ handler, count, delay });
+        }
+        return handler;
+    }
+    play(rate, options = {}) {
+        const handler = this._private_nextHandler++;
+        this._private_activePlays.push({
+            handler,
+            rate,
+            duration: options.duration ?? Infinity,
+            elapsed: 0,
+            accumulator: 0,
+            delay: options.delay ?? 0,
+        });
+        return handler;
+    }
+    stop(handler) {
+        if (handler === undefined) {
+            const hadAnything = this._private_pendingBursts.length > 0 || this._private_activePlays.length > 0;
+            this._private_pendingBursts.length = 0;
+            this._private_activePlays.length = 0;
+            return hadAnything;
+        }
+        const burstIndex = this._private_pendingBursts.findIndex((b) => b.handler === handler);
+        if (burstIndex !== -1) {
+            this._private_pendingBursts.splice(burstIndex, 1);
+            return true;
+        }
+        const playIndex = this._private_activePlays.findIndex((p) => p.handler === handler);
+        if (playIndex !== -1) {
+            this._private_activePlays.splice(playIndex, 1);
+            return true;
+        }
+        return false;
+    }
+    prewarm(duration, stepDuration = EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION) {
+        const stepCount = Math.min(duration / Math.max(stepDuration, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION), EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT);
+        const step = duration / stepCount;
+        let remaining = duration;
+        while (remaining > 0) {
+            const deltaTime = Math.min(remaining, step);
+            this._private_tick(deltaTime);
+            remaining -= deltaTime;
+        }
+    }
+    reset() {
+        this._private_pendingBursts.length = 0;
+        this._private_activePlays.length = 0;
+        this._private_mesh.drop();
+    }
+    _private_tick(deltaTime) {
+        // Age increment & cull dead particles
+        {
+            const { builtin } = this._private_mesh.propertyBuffers;
+            const { array, itemSize } = builtin;
+            for (let i = 0; i < this._private_mesh.instanceCount; i++) {
+                array[i * itemSize + BUILTIN_OFFSET_AGE] += deltaTime;
+            }
+        }
+        this._private_mesh.removeDeadParticles();
+        // Pending bursts (delayed)
+        for (let i = this._private_pendingBursts.length - 1; i >= 0; i--) {
+            const pending = this._private_pendingBursts[i];
+            pending.delay -= deltaTime;
+            if (pending.delay <= 0) {
+                this._private_pendingBursts.splice(i, 1);
+                this._private_spawnBurst(pending.count);
+            }
+        }
+        // Active plays
+        for (let i = this._private_activePlays.length - 1; i >= 0; i--) {
+            const play = this._private_activePlays[i];
+            let effectiveDeltaTime = deltaTime;
+            if (play.delay > 0) {
+                play.delay -= deltaTime;
+                if (play.delay > 0) {
+                    continue;
+                }
+                // Delay just expired - use the overshoot as effective dt this tick
+                effectiveDeltaTime = -play.delay;
+                play.delay = 0;
+            }
+            play.elapsed += effectiveDeltaTime;
+            if (play.elapsed >= play.duration) {
+                this._private_activePlays.splice(i, 1);
+                continue;
+            }
+            play.accumulator += play.rate * effectiveDeltaTime;
+            const particlesToSpawn = Math.floor(play.accumulator);
+            if (particlesToSpawn > 0) {
+                this._private_spawnBurst(particlesToSpawn);
+                play.accumulator -= particlesToSpawn;
+            }
+        }
+        if (this._private_mesh.instanceCount === 0) {
+            return;
+        }
+        {
+            const { propertyBuffers, instanceCount } = this._private_mesh;
+            for (const module of this._private_behaviorSequence) {
+                module.update(propertyBuffers, instanceCount, deltaTime);
+            }
+        }
+        {
+            const { builtin } = this._private_mesh.propertyBuffers;
+            const { array, itemSize } = builtin;
+            for (let i = 0; i < this._private_mesh.instanceCount; i++) {
+                const offset = i * itemSize;
+                // Position += velocity * dt
+                array[offset + BUILTIN_OFFSET_POSITION_X] +=
+                    array[offset + BUILTIN_OFFSET_VELOCITY_X] * deltaTime;
+                array[offset + BUILTIN_OFFSET_POSITION_Y] +=
+                    array[offset + BUILTIN_OFFSET_VELOCITY_Y] * deltaTime;
+                array[offset + BUILTIN_OFFSET_POSITION_Z] +=
+                    array[offset + BUILTIN_OFFSET_VELOCITY_Z] * deltaTime;
+                // Rotation += torque * dt
+                array[offset + BUILTIN_OFFSET_ROTATION] +=
+                    array[offset + BUILTIN_OFFSET_TORQUE] * deltaTime;
+            }
+            builtin.needsUpdate = true;
+        }
+    }
+    _private_spawnBurst(count) {
         const instanceBegin = this._private_mesh.instanceCount;
         this._private_mesh.createInstances(count);
         const instanceEnd = this._private_mesh.instanceCount;
@@ -138,21 +212,6 @@ class FXEmitter extends Object3D {
             spawnModule.spawn(this._private_mesh.propertyBuffers, instanceBegin, instanceEnd);
         }
     }
-    reset() {
-        this._private_mesh.drop();
-    }
-    play(rate, options = {}) {
-        this._private_emissionRate = rate;
-        this._private_emissionAccumulator = 0;
-        this._private_emissionDuration = options.duration ?? Infinity;
-        this._private_emissionElapsed = 0;
-    }
-    stop() {
-        this._private_emissionRate = 0;
-        this._private_emissionAccumulator = 0;
-        this._private_emissionDuration = Infinity;
-        this._private_emissionElapsed = 0;
-    }
 }
 FXEmitter.onWillRender = (deltaTime) => {
     for (const instance of EMITTERS) {

package/dist/emitter/spawn/FXSpawnSphere.d.ts

@@ -21,8 +21,8 @@ export declare class FXSpawnSphere extends FXSpawn<{
     constructor(innerRadius?: number, outerRadius?: number, angle?: number);
     /**
      * Polar half-angle from the equatorial plane.
-     * - `0` — flat disk
-     * - `Math.PI / 2` — full sphere
+     * - `0` - flat disk
+     * - `Math.PI / 2` - full sphere
      */
     get angle(): number;
     /** Minimum spawn radius */

package/dist/emitter/spawn/FXSpawnSphere.js

@@ -30,8 +30,8 @@ class FXSpawnSphere extends FXSpawn {
     }
     /**
      * Polar half-angle from the equatorial plane.
-     * - `0` — flat disk
-     * - `Math.PI / 2` — full sphere
+     * - `0` - flat disk
+     * - `Math.PI / 2` - full sphere
      */
     get angle() {
         return this._private_angleInternal;

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { FXUnlitMaterial } from "./materials/FXUnlitMaterial/FXUnlitMaterial";
 export { FXColor } from "./miscellaneous/color/FXColor";
 export { FXColorNode } from "./nodes/color/FXColorNode";
 export { FXColorOverLifeNode } from "./nodes/color/FXColorOverLifeNode";
+export { FXSphericalClipNode } from "./nodes/color/FXSphericalClipNode";
 export { FXFlatNormalNode } from "./nodes/normal/FXFlatNormalNode";
 export { FXNormalNode } from "./nodes/normal/FXNormalNode";
 export { FXSphericalNormalNode } from "./nodes/normal/FXSphericalNormalNode";

package/dist/index.js

@@ -20,6 +20,7 @@ export { FXUnlitMaterial } from './materials/FXUnlitMaterial/FXUnlitMaterial.js'
 export { FXColor } from './miscellaneous/color/FXColor.js';
 export { FXColorNode } from './nodes/color/FXColorNode.js';
 export { FXColorOverLifeNode } from './nodes/color/FXColorOverLifeNode.js';
+export { FXSphericalClipNode } from './nodes/color/FXSphericalClipNode.js';
 export { FXFlatNormalNode } from './nodes/normal/FXFlatNormalNode.js';
 export { FXNormalNode } from './nodes/normal/FXNormalNode.js';
 export { FXSphericalNormalNode } from './nodes/normal/FXSphericalNormalNode.js';

package/dist/materials/FXMaterial/FXDistanceMaterial.Internal.js

@@ -11,7 +11,7 @@ import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
  *
  * `vWorldPosition` is a Three.js convention consumed by the distance fragment
  * shader. `viewMatrix` here is the shadow camera's view matrix, so the
- * billboard faces the light — which is correct for shadow shape.
+ * billboard faces the light - which is correct for shadow shape.
  */
 const DISTANCE_VERTEX_SHADER = `
   #define DISTANCE
@@ -77,9 +77,9 @@ const DISTANCE_VERTEX_SHADER = `
  * the smaller scale dimension. Fragments outside the sphere are discarded.
  *
  * The depth offset is subtracted from the flat distance, bringing the
- * perceived surface closer to the light. This is an approximation — the
+ * perceived surface closer to the light. This is an approximation - the
  * true offset direction depends on the light-to-fragment vector, not the
- * camera-to-fragment vector — but for smoke particles the error is
+ * camera-to-fragment vector - but for smoke particles the error is
  * negligible.
  */
 const SPHERICAL_DISTANCE_SNIPPET = `
@@ -130,7 +130,7 @@ function buildDistanceMaterial(albedoNodes, distanceAlphaTest, useDistanceAlphaH
             Object.assign(shader.uniforms, node.uniforms);
         }
         let fragmentShader = shader.fragmentShader;
-        // Alpha from nodes — MeshDistanceMaterial may or may not include
+        // Alpha from nodes - MeshDistanceMaterial may or may not include
         // <map_fragment> depending on the Three.js version. If the chunk is
         // absent, insert the alpha discard before the distance calculation.
         if (distanceNodes.length > 0) {
@@ -149,7 +149,7 @@ function buildDistanceMaterial(albedoNodes, distanceAlphaTest, useDistanceAlphaH
                     "This may indicate a Three.js version mismatch.");
             }
         }
-        // Spherical distance adjustment — offset the flat-billboard distance by
+        // Spherical distance adjustment - offset the flat-billboard distance by
         // the sphere's front surface depth.
         if (useSphericalDepth) {
             if (!DISTANCE_CALCULATION_PATTERN.test(fragmentShader)) {

package/dist/nodes/color/FXSphericalClipNode.d.ts

@@ -0,0 +1,5 @@
+import { FXColorNode } from "./FXColorNode";
+export declare class FXSphericalClipNode extends FXColorNode {
+    constructor(innerRadius?: number);
+    destroy(): void;
+}

package/dist/nodes/color/FXSphericalClipNode.js

@@ -0,0 +1,30 @@
+import { FXColorNode } from './FXColorNode.js';
+
+const INSTANCES = [];
+class FXSphericalClipNode extends FXColorNode {
+    constructor(innerRadius = 0.5) {
+        super();
+        INSTANCES.push(this);
+        const uniformName = `u_SphericalClip_${INSTANCES.length - 1}`;
+        this.cacheKey = "spherical-clip";
+        this.uniformDeclarations = [`uniform float ${uniformName};`];
+        this.uniforms = {
+            [uniformName]: { value: innerRadius },
+        };
+        this.helperFunctions = `
+      vec4 applySphericalClip(float innerRadius) {
+        float distanceToCenter = distance(p_uv, vec2(0.5, 0.5));
+        return vec4(1.0, 1.0, 1.0, 1.0 - smoothstep(innerRadius, 0.5, distanceToCenter));
+      }
+    `;
+        this.colorExpression = `applySphericalClip(${uniformName})`;
+    }
+    destroy() {
+        const index = INSTANCES.indexOf(this);
+        if (index !== -1) {
+            INSTANCES.splice(index, 1);
+        }
+    }
+}
+
+export { FXSphericalClipNode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparcoon",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "",
   "keywords": [
     "particles",