@newkrok/three-particles 2.14.0 → 2.15.0

package/README.md

@@ -3,10 +3,12 @@
 </p>
 
 # THREE Particles
-[![Run Tests](https://github.com/NewKrok/three-particles/actions/workflows/test.yml/badge.svg)](https://github.com/NewKrok/three-particles/actions/workflows/test.yml)
-[![NPM Version](https://img.shields.io/npm/v/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
-[![NPM Downloads](https://img.shields.io/npm/dw/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@newkrok/three-particles)](https://bundlephobia.com/package/@newkrok/three-particles)
+[![npm](https://img.shields.io/npm/v/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
+[![downloads](https://img.shields.io/npm/dm/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
+[![CI](https://github.com/NewKrok/three-particles/actions/workflows/ci.yml/badge.svg)](https://github.com/NewKrok/three-particles/actions/workflows/ci.yml)
+[![gzip](https://img.shields.io/bundlephobia/minzip/@newkrok/three-particles)](https://bundlephobia.com/package/@newkrok/three-particles)
+[![license](https://img.shields.io/npm/l/@newkrok/three-particles.svg)](https://github.com/NewKrok/three-particles/blob/master/LICENSE)
+[![docs](https://img.shields.io/badge/docs-online-blue)](https://newkrok.github.io/three-particles/api/)
 
 Particle system for ThreeJS.
 
@@ -62,12 +64,18 @@ const effect = {
   // Your effect configuration here
   // It can be empty to use default settings
 };
-const { instance } = createParticleSystem(effect);
-scene.add(instance);
+const system = createParticleSystem(effect);
+scene.add(system.instance);
 
 // Update the particle system in your animation loop
 // Pass the current time, delta time, and elapsed time
 updateParticleSystems({now, delta, elapsed});
+
+// Update configuration at runtime without recreating the system
+system.updateConfig({
+  gravity: -9.8,
+  forceFields: [{ type: 'DIRECTIONAL', direction: { x: 1, y: 0, z: 0 }, strength: 5 }],
+});
 ```
 
 # Usage with React Three Fiber

package/dist/index.d.ts

@@ -1849,6 +1849,39 @@ type ParticleSystem = {
     pauseEmitter: () => void;
     dispose: () => void;
     update: (cycleData: CycleData) => void;
+    /**
+     * Updates the particle system configuration at runtime without recreating the system.
+     *
+     * System-level properties (gravity, force fields, noise, emission rates, color/size/opacity
+     * over lifetime curves) take effect immediately for all particles.
+     * Per-particle spawn properties (startColor, startSize, startSpeed, startLifetime, etc.)
+     * only affect newly emitted particles — already-alive particles retain their original values.
+     *
+     * @param config - A partial configuration object. Only the provided properties will be updated;
+     *   all other settings remain unchanged.
+     *
+     * @remarks
+     * Structural properties that are set at creation time cannot be changed at runtime:
+     * `maxParticles`, `renderer.rendererType`, `shape`, and `map` (texture).
+     * Passing these will update the internal config but have no visible effect since the
+     * geometry and material are pre-allocated.
+     *
+     * @example
+     * ```typescript
+     * const system = createParticleSystem(config);
+     *
+     * // Change wind direction in real time
+     * system.updateConfig({
+     *   forceFields: [{ type: ForceFieldType.DIRECTIONAL, direction: { x: 1, y: 0, z: 0 }, strength: 5 }],
+     * });
+     *
+     * // Gradually change color of new particles
+     * system.updateConfig({
+     *   startColor: { min: { r: 1, g: 0, b: 0 }, max: { r: 1, g: 0.5, b: 0 } },
+     * });
+     * ```
+     */
+    updateConfig: (config: Partial<ParticleSystemConfig>) => void;
 };
 /**
  * Data representing the current cycle of the particle system's update loop.

package/dist/index.js

@@ -1184,6 +1184,16 @@ var _modifierParams = {
   particleLifetimePercentage: 0,
   particleIndex: 0
 };
+var toVector3 = (v, fallback) => v ? new THREE4.Vector3(v.x ?? 0, v.y ?? 0, v.z ?? 0) : fallback.clone();
+var normalizeForceFields = (rawForceFields) => (rawForceFields ?? []).map((ff) => ({
+  isActive: ff.isActive ?? true,
+  type: ff.type ?? "POINT" /* POINT */,
+  position: toVector3(ff.position, new THREE4.Vector3(0, 0, 0)),
+  direction: toVector3(ff.direction, new THREE4.Vector3(0, 1, 0)).normalize(),
+  strength: ff.strength ?? 1,
+  range: Math.max(0, ff.range ?? Infinity),
+  falloff: ff.falloff ?? "LINEAR" /* LINEAR */
+}));
 var blendingMap = {
   "THREE.NoBlending": THREE4.NoBlending,
   "THREE.NormalBlending": THREE4.NormalBlending,
@@ -1507,16 +1517,7 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     subEmitters,
     forceFields: rawForceFields
   } = normalizedConfig;
-  const toVector3 = (v, fallback) => v ? new THREE4.Vector3(v.x ?? 0, v.y ?? 0, v.z ?? 0) : fallback.clone();
-  const normalizedForceFields = (rawForceFields ?? []).map((ff) => ({
-    isActive: ff.isActive ?? true,
-    type: ff.type ?? "POINT" /* POINT */,
-    position: toVector3(ff.position, new THREE4.Vector3(0, 0, 0)),
-    direction: toVector3(ff.direction, new THREE4.Vector3(0, 1, 0)).normalize(),
-    strength: ff.strength ?? 1,
-    range: Math.max(0, ff.range ?? Infinity),
-    falloff: ff.falloff ?? "LINEAR" /* LINEAR */
-  }));
+  const normalizedForceFields = normalizeForceFields(rawForceFields);
   if (typeof renderer?.blending === "string")
     renderer.blending = blendingMap[renderer.blending];
   const startPositions = Array.from(
@@ -1952,44 +1953,45 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     if (generalData.noise.offsets)
       generalData.noise.offsets[particleIndex] = Math.random() * 100;
     const colorRandomRatio2 = Math.random();
-    aColorR.array[particleIndex] = startColor.min.r + colorRandomRatio2 * (startColor.max.r - startColor.min.r);
+    const cfgStartColor = normalizedConfig.startColor;
+    aColorR.array[particleIndex] = cfgStartColor.min.r + colorRandomRatio2 * (cfgStartColor.max.r - cfgStartColor.min.r);
     aColorR.needsUpdate = true;
-    aColorG.array[particleIndex] = startColor.min.g + colorRandomRatio2 * (startColor.max.g - startColor.min.g);
+    aColorG.array[particleIndex] = cfgStartColor.min.g + colorRandomRatio2 * (cfgStartColor.max.g - cfgStartColor.min.g);
     aColorG.needsUpdate = true;
-    aColorB.array[particleIndex] = startColor.min.b + colorRandomRatio2 * (startColor.max.b - startColor.min.b);
+    aColorB.array[particleIndex] = cfgStartColor.min.b + colorRandomRatio2 * (cfgStartColor.max.b - cfgStartColor.min.b);
     aColorB.needsUpdate = true;
     generalData.startValues.startColorR[particleIndex] = aColorR.array[particleIndex];
     generalData.startValues.startColorG[particleIndex] = aColorG.array[particleIndex];
     generalData.startValues.startColorB[particleIndex] = aColorB.array[particleIndex];
-    aStartFrame.array[particleIndex] = textureSheetAnimation.startFrame ? calculateValue(
+    aStartFrame.array[particleIndex] = normalizedConfig.textureSheetAnimation.startFrame ? calculateValue(
       generalData.particleSystemId,
-      textureSheetAnimation.startFrame,
+      normalizedConfig.textureSheetAnimation.startFrame,
       0
     ) : 0;
     aStartFrame.needsUpdate = true;
     aStartLifetime.array[particleIndex] = calculateValue(
       generalData.particleSystemId,
-      startLifetime,
+      normalizedConfig.startLifetime,
       generalData.normalizedLifetimePercentage
     ) * 1e3;
     aStartLifetime.needsUpdate = true;
     generalData.startValues.startSize[particleIndex] = calculateValue(
       generalData.particleSystemId,
-      startSize,
+      normalizedConfig.startSize,
       generalData.normalizedLifetimePercentage
     );
     aSize.array[particleIndex] = generalData.startValues.startSize[particleIndex];
     aSize.needsUpdate = true;
     generalData.startValues.startOpacity[particleIndex] = calculateValue(
       generalData.particleSystemId,
-      startOpacity,
+      normalizedConfig.startOpacity,
       generalData.normalizedLifetimePercentage
     );
     aColorA.array[particleIndex] = generalData.startValues.startOpacity[particleIndex];
     aColorA.needsUpdate = true;
     aRotation.array[particleIndex] = calculateValue(
       generalData.particleSystemId,
-      startRotation,
+      normalizedConfig.startRotation,
       generalData.normalizedLifetimePercentage
     );
     aRotation.needsUpdate = true;
@@ -2010,8 +2012,8 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       );
     calculatePositionAndVelocity(
       generalData,
-      shape,
-      startSpeed,
+      normalizedConfig.shape,
+      normalizedConfig.startSpeed,
       startPositions[particleIndex],
       velocities[particleIndex]
     );
@@ -2406,12 +2408,53 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       for (const sub of instances) sub.update(cycleData);
     }
   };
+  const updateConfig = (partialConfig) => {
+    ObjectUtils.deepMerge(instanceData.normalizedConfig, partialConfig, {
+      applyToFirstObject: true,
+      skippedProperties: []
+    });
+    const cfg = instanceData.normalizedConfig;
+    if (partialConfig.gravity !== void 0) {
+      instanceData.gravity = cfg.gravity;
+      generalData.lastWorldQuaternion.x = -99999;
+    }
+    if (partialConfig.duration !== void 0)
+      instanceData.duration = cfg.duration;
+    if (partialConfig.looping !== void 0) instanceData.looping = cfg.looping;
+    if (partialConfig.simulationSpace !== void 0)
+      instanceData.simulationSpace = cfg.simulationSpace;
+    if (partialConfig.emission !== void 0)
+      instanceData.emission = cfg.emission;
+    if (partialConfig.forceFields !== void 0) {
+      instanceData.normalizedForceFields = normalizeForceFields(
+        cfg.forceFields
+      );
+    }
+    if (partialConfig.noise !== void 0) {
+      const n = cfg.noise;
+      generalData.noise = {
+        isActive: n.isActive,
+        strength: n.strength,
+        noisePower: 0.15 * n.strength,
+        positionAmount: n.positionAmount,
+        rotationAmount: n.rotationAmount,
+        sizeAmount: n.sizeAmount,
+        sampler: n.isActive ? new FBM({
+          seed: Math.random(),
+          scale: n.frequency,
+          octaves: n.octaves
+        }) : void 0,
+        offsets: n.useRandomOffset ? generalData.noise.offsets ?? Array.from({ length: maxParticles }, () => Math.random() * 100) : void 0
+      };
+    }
+  };
   return {
     instance: wrapper || particleSystem,
     resumeEmitter,
     pauseEmitter,
     dispose,
-    update
+    update,
+    updateConfig
   };
 };
 var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {