@newkrok/three-particles 2.6.6 → 2.7.0

package/dist/index.d.ts

@@ -116,6 +116,23 @@ declare const enum LifeTimeCurve {
      */
     EASING = "EASING"
 }
+/**
+ * Defines when a sub-emitter is triggered relative to a particle's lifecycle.
+ *
+ * @enum {string}
+ */
+declare const enum SubEmitterTrigger {
+    /**
+     * Trigger the sub-emitter when a particle is born (activated).
+     * Useful for trail effects that start immediately with each particle.
+     */
+    BIRTH = "BIRTH",
+    /**
+     * Trigger the sub-emitter when a particle dies (reaches end of lifetime).
+     * Useful for cascading effects like explosions spawning smoke.
+     */
+    DEATH = "DEATH"
+}
 
 /**
  * A fixed numerical value.
@@ -701,6 +718,41 @@ type VelocityOverLifetime = {
         z?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
     };
 };
+/**
+ * Configuration for a sub-emitter that spawns child particle systems
+ * based on parent particle lifecycle events.
+ *
+ * @example
+ * ```typescript
+ * const subEmitter: SubEmitterConfig = {
+ *   trigger: SubEmitterTrigger.DEATH,
+ *   config: { startLifeTime: 0.5, startSpeed: 2, emission: { rateOverTime: 20 } },
+ *   inheritVelocity: 0.5,
+ *   maxInstances: 16,
+ * };
+ * ```
+ */
+type SubEmitterConfig = {
+    /** The particle system configuration used when spawning the sub-emitter. */
+    config: ParticleSystemConfig;
+    /**
+     * When to trigger the sub-emitter.
+     * @default SubEmitterTrigger.DEATH
+     */
+    trigger?: SubEmitterTrigger;
+    /**
+     * Multiplier (0–1) for inheriting the parent particle's velocity.
+     * 0 = no inheritance, 1 = full velocity inheritance.
+     * @default 0
+     */
+    inheritVelocity?: number;
+    /**
+     * Maximum number of concurrent sub-emitter instances for this configuration.
+     * Older completed instances are cleaned up to make room for new ones.
+     * @default 32
+     */
+    maxInstances?: number;
+};
 /**
  * Configuration object for the particle system.
  * Defines all aspects of the particle system, including its appearance, behavior, and runtime events.
@@ -1188,6 +1240,22 @@ type ParticleSystemConfig = {
      * }
      */
     textureSheetAnimation?: TextureSheetAnimation;
+    /**
+     * Sub-emitters that spawn child particle systems on particle lifecycle events.
+     * Each sub-emitter is triggered when a particle is born or dies, creating a new
+     * particle system at the parent particle's position.
+     *
+     * @example
+     * ```typescript
+     * subEmitters: [
+     *   {
+     *     trigger: SubEmitterTrigger.DEATH,
+     *     config: { startLifeTime: 0.5, startSpeed: 1, emission: { rateOverTime: 10 } },
+     *   },
+     * ]
+     * ```
+     */
+    subEmitters?: Array<SubEmitterConfig>;
     /**
      * Called on every update frame with particle system data.
      */
@@ -1288,6 +1356,10 @@ type ParticleSystemInstance = {
         activationTime: number;
         position: Required<Point3D>;
     }) => void;
+    /** Called when a particle dies to trigger death sub-emitters */
+    onParticleDeath?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
+    /** Called when a particle is born to trigger birth sub-emitters */
+    onParticleBirth?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
 };
 /**
  * Represents a particle system instance, providing methods to control and manage its lifecycle.
@@ -1779,4 +1851,4 @@ declare const getDefaultParticleSystemConfig: () => any;
 declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
 declare const updateParticleSystems: (cycleData: CycleData) => void;
 
-export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, type Rgb, Shape, type ShapeConfig, SimulationSpace, type Sphere, type TextureSheetAnimation, TimeMode, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, type Rgb, Shape, type ShapeConfig, SimulationSpace, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };

package/dist/index.js

@@ -160,6 +160,11 @@ var LifeTimeCurve = /* @__PURE__ */ ((LifeTimeCurve2) => {
   LifeTimeCurve2["EASING"] = "EASING";
   return LifeTimeCurve2;
 })(LifeTimeCurve || {});
+var SubEmitterTrigger = /* @__PURE__ */ ((SubEmitterTrigger2) => {
+  SubEmitterTrigger2["BIRTH"] = "BIRTH";
+  SubEmitterTrigger2["DEATH"] = "DEATH";
+  return SubEmitterTrigger2;
+})(SubEmitterTrigger || {});
 var calculateRandomPositionAndVelocityOnSphere = (position, quaternion, velocity, speed, {
   radius,
   radiusThickness,
@@ -589,6 +594,7 @@ var particle_system_vertex_shader_glsl_default = ParticleSystemVertexShader;
 // src/js/effects/three-particles/three-particles.ts
 var _particleSystemId = 0;
 var createdParticleSystems = [];
+var _subEmitterPosition = new THREE3.Vector3();
 var _lastWorldPositionSnapshot = new THREE3.Vector3();
 var _distanceStep = { x: 0, y: 0, z: 0 };
 var _tempPosition = { x: 0, y: 0, z: 0 };
@@ -903,7 +909,8 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     velocityOverLifetime,
     onUpdate,
     onComplete,
-    textureSheetAnimation
+    textureSheetAnimation,
+    subEmitters
   } = normalizedConfig;
   if (typeof renderer?.blending === "string")
     renderer.blending = blendingMap[renderer.blending];
@@ -1311,6 +1318,68 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       particleIndex
     });
   };
+  const subEmitterArr = subEmitters ?? [];
+  const deathSubEmitters = subEmitterArr.filter(
+    (s) => (s.trigger ?? "DEATH" /* DEATH */) === "DEATH" /* DEATH */
+  );
+  const birthSubEmitters = subEmitterArr.filter(
+    (s) => s.trigger === "BIRTH" /* BIRTH */
+  );
+  const subEmitterInstancesMap = /* @__PURE__ */ new Map();
+  for (const cfg of subEmitterArr) {
+    subEmitterInstancesMap.set(cfg, []);
+  }
+  const cleanupCompletedInstances = (instances) => {
+    for (let i = instances.length - 1; i >= 0; i--) {
+      const sub = instances[i];
+      const points = sub.instance;
+      const isActiveArr = points.geometry?.attributes?.isActive?.array;
+      if (!isActiveArr) {
+        sub.dispose();
+        instances.splice(i, 1);
+        continue;
+      }
+      let hasActive = false;
+      for (let j = 0; j < isActiveArr.length; j++) {
+        if (isActiveArr[j]) {
+          hasActive = true;
+          break;
+        }
+      }
+      if (!hasActive) {
+        sub.dispose();
+        instances.splice(i, 1);
+      }
+    }
+  };
+  const spawnSubEmitters = (configs, position, velocity, spawnNow) => {
+    for (const subConfig of configs) {
+      const instances = subEmitterInstancesMap.get(subConfig);
+      const maxInst = subConfig.maxInstances ?? 32;
+      if (instances.length >= maxInst) {
+        cleanupCompletedInstances(instances);
+        if (instances.length >= maxInst) continue;
+      }
+      const inheritVelocity = subConfig.inheritVelocity ?? 0;
+      const subSystem = createParticleSystem(
+        {
+          ...subConfig.config,
+          looping: false,
+          transform: {
+            ...subConfig.config.transform,
+            position: new THREE3.Vector3(position.x, position.y, position.z)
+          },
+          ...inheritVelocity > 0 ? {
+            startSpeed: (typeof subConfig.config.startSpeed === "number" ? subConfig.config.startSpeed : typeof subConfig.config.startSpeed === "object" && subConfig.config.startSpeed !== null && "min" in subConfig.config.startSpeed ? subConfig.config.startSpeed.min ?? 0 : 0) + velocity.length() * inheritVelocity
+          } : {}
+        },
+        spawnNow
+      );
+      const parentObj = (wrapper || particleSystem).parent;
+      if (parentObj) parentObj.add(subSystem.instance);
+      instances.push(subSystem);
+    }
+  };
   let particleSystem = new THREE3.Points(geometry, material);
   particleSystem.position.copy(transform.position);
   particleSystem.rotation.x = THREE3.MathUtils.degToRad(transform.rotation.x);
@@ -1323,6 +1392,36 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     wrapper = new Gyroscope();
     wrapper.add(particleSystem);
   }
+  const hasDeathSubEmitters = deathSubEmitters.length > 0;
+  const hasBirthSubEmitters = birthSubEmitters.length > 0;
+  const onParticleDeath = hasDeathSubEmitters ? (particleIndex, positionArr, velocity, deathNow) => {
+    const posIdx = particleIndex * 3;
+    _subEmitterPosition.set(
+      positionArr[posIdx],
+      positionArr[posIdx + 1],
+      positionArr[posIdx + 2]
+    );
+    spawnSubEmitters(
+      deathSubEmitters,
+      _subEmitterPosition,
+      velocity,
+      deathNow
+    );
+  } : void 0;
+  const onParticleBirth = hasBirthSubEmitters ? (particleIndex, positionArr, velocity, birthNow) => {
+    const posIdx = particleIndex * 3;
+    _subEmitterPosition.set(
+      positionArr[posIdx],
+      positionArr[posIdx + 1],
+      positionArr[posIdx + 2]
+    );
+    spawnSubEmitters(
+      birthSubEmitters,
+      _subEmitterPosition,
+      velocity,
+      birthNow
+    );
+  } : void 0;
   const instanceData = {
     particleSystem,
     wrapper,
@@ -1342,12 +1441,20 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     velocities,
     freeList,
     deactivateParticle,
-    activateParticle
+    activateParticle,
+    onParticleDeath,
+    onParticleBirth
   };
   createdParticleSystems.push(instanceData);
   const resumeEmitter = () => generalData.isEnabled = true;
   const pauseEmitter = () => generalData.isEnabled = false;
-  const dispose = () => destroyParticleSystem(particleSystem);
+  const dispose = () => {
+    for (const instances of subEmitterInstancesMap.values()) {
+      for (const sub of instances) sub.dispose();
+      instances.length = 0;
+    }
+    destroyParticleSystem(particleSystem);
+  };
   const update = (cycleData) => updateParticleSystemInstance(instanceData, cycleData);
   return {
     instance: wrapper || particleSystem,
@@ -1377,7 +1484,9 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
     deactivateParticle,
     activateParticle,
     simulationSpace,
-    gravity
+    gravity,
+    onParticleDeath,
+    onParticleBirth
   } = props;
   const lifetime = now - creationTime;
   const normalizedLifetime = lifetime % (duration * 1e3);
@@ -1439,6 +1548,8 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
     if (isActiveArr[index]) {
       const particleLifetime = now - creationTimes[index];
       if (particleLifetime > startLifetimeArr[index]) {
+        if (onParticleDeath)
+          onParticleDeath(index, positionArr, velocities[index], now);
         deactivateParticle(index);
       } else {
         const velocity = velocities[index];
@@ -1550,6 +1661,13 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
           activationTime: now,
           position: _tempPosition
         });
+        if (onParticleBirth)
+          onParticleBirth(
+            particleIndex,
+            attributes.position.array,
+            velocities[particleIndex],
+            now
+          );
         props.lastEmissionTime = now;
       }
     }
@@ -1573,6 +1691,6 @@ var updateParticleSystems = (cycleData) => {
   );
 };
 
-export { CurveFunctionId, EmitFrom, LifeTimeCurve, Shape, SimulationSpace, TimeMode, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+export { CurveFunctionId, EmitFrom, LifeTimeCurve, Shape, SimulationSpace, SubEmitterTrigger, TimeMode, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map