@newkrok/three-particles 2.14.1 → 2.15.1

package/README.md

@@ -64,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

@@ -1171,6 +1171,10 @@ var _particleSystemId = 0;
 var createdParticleSystems = [];
 var _subEmitterPosition = new THREE4.Vector3();
 var _lastWorldPositionSnapshot = new THREE4.Vector3();
+var _localForceFieldPos = new THREE4.Vector3();
+var _localForceFieldDir = new THREE4.Vector3();
+var _inverseQuat = new THREE4.Quaternion();
+var _localForceFields = [];
 new THREE4.Vector3();
 new THREE4.Vector3();
 new THREE4.Vector3();
@@ -1184,6 +1188,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 +1521,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 +1957,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 +2016,8 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       );
     calculatePositionAndVelocity(
       generalData,
-      shape,
-      startSpeed,
+      normalizedConfig.shape,
+      normalizedConfig.startSpeed,
       startPositions[particleIndex],
       velocities[particleIndex]
     );
@@ -2406,12 +2412,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 }) => {
@@ -2484,6 +2531,37 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
     );
     particleSystem.worldToLocal(gravityVelocity);
   }
+  if (hasForceFields) {
+    _inverseQuat.copy(worldQuaternion).invert();
+    _localForceFields.length = normalizedForceFields.length;
+    for (let i = 0; i < normalizedForceFields.length; i++) {
+      const src = normalizedForceFields[i];
+      let dst = _localForceFields[i];
+      if (!dst) {
+        dst = {
+          isActive: true,
+          type: "POINT" /* POINT */,
+          position: new THREE4.Vector3(),
+          direction: new THREE4.Vector3(),
+          strength: 0,
+          range: 0,
+          falloff: "LINEAR" /* LINEAR */
+        };
+        _localForceFields[i] = dst;
+      }
+      dst.isActive = src.isActive;
+      dst.type = src.type;
+      dst.strength = src.strength;
+      dst.range = src.range;
+      dst.falloff = src.falloff;
+      _localForceFieldPos.copy(src.position);
+      particleSystem.worldToLocal(_localForceFieldPos);
+      dst.position.copy(_localForceFieldPos);
+      _localForceFieldDir.copy(src.direction);
+      _localForceFieldDir.applyQuaternion(_inverseQuat);
+      dst.direction.copy(_localForceFieldDir);
+    }
+  }
   const creationTimes = generalData.creationTimes;
   const isActiveArr = ma.isActive.array;
   const startLifetimeArr = ma.startLifetime.array;
@@ -2511,7 +2589,7 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
         if (hasForceFields) {
           applyForceFields({
             particleSystemId: generalData.particleSystemId,
-            forceFields: normalizedForceFields,
+            forceFields: _localForceFields,
             velocity,
             positionArr,
             positionIndex: index * 3,