@newkrok/three-particles 0.2.2 → 0.3.0

package/README.md

@@ -18,4 +18,4 @@ Install with npm
 `npm i @newkrok/three-particles`
 
 Add as a package.json dependency
-`"dependencies": { ... "@newkrok/three-particles": "0.2.1" ... }, `
+`"dependencies": { ... "@newkrok/three-particles": "0.2.2" ... }, `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newkrok/three-particles",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Particle system for ThreeJS",
   "main": "src/js/three-particles.js",
   "bin": {
@@ -23,7 +23,8 @@
   },
   "homepage": "https://github.com/NewKrok/three-particles#readme",
   "dependencies": {
-    "three": "^0.135.0"
+    "three": "0.135.0",
+    "easing-functions": "1.0.1"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/src/js/effects/shaders/particle-system-vertex-shader.glsl.js

@@ -1,5 +1,5 @@
 const ParticleSystemVertexShader = `
-  attribute float startSize;
+  attribute float size;
   attribute float colorR;
   attribute float colorG;
   attribute float colorB;
@@ -25,7 +25,7 @@ const ParticleSystemVertexShader = `
     vStartFrame = startFrame;
 
     vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
-    gl_PointSize = startSize * (100.0 / length(mvPosition.xyz));
+    gl_PointSize = size * (100.0 / length(mvPosition.xyz));
     gl_Position = projectionMatrix * mvPosition;
   }
 `;

package/src/js/effects/three-particles/three-particles-curves.js

@@ -0,0 +1,74 @@
+import Easing from "easing-functions";
+
+export const CurveFunction = {
+  LINEAR: "LINEAR",
+  QUADRATIC_IN: "QUADRATIC_IN",
+  QUADRATIC_OUT: "QUADRATIC_OUT",
+  QUADRATIC_IN_OUT: "QUADRATIC_IN_OUT",
+  CUBIC_IN: "CUBIC_IN",
+  CUBIC_OUT: "CUBIC_OUT",
+  CUBIC_IN_OUT: "CUBIC_IN_OUT",
+  QUARTIC_IN: "QUARTIC_IN",
+  QUARTIC_OUT: "QUARTIC_OUT",
+  QUARTIC_IN_OUT: "QUARTIC_IN_OUT",
+  QUINTIC_IN: "QUINTIC_IN",
+  QUINTIC_OUT: "QUINTIC_OUT",
+  QUINTIC_IN_OUT: "QUINTIC_IN_OUT",
+  SINUSOIDAL_IN: "SINUSOIDAL_IN",
+  SINUSOIDAL_OUT: "SINUSOIDAL_OUT",
+  SINUSOIDAL_IN_OUT: "SINUSOIDAL_IN_OUT",
+  EXPONENTIAL_IN: "EXPONENTIAL_IN",
+  EXPONENTIAL_OUT: "EXPONENTIAL_OUT",
+  EXPONENTIAL_IN_OUT: "EXPONENTIAL_IN_OUT",
+  CIRCULAR_IN: "CIRCULAR_IN",
+  CIRCULAR_OUT: "CIRCULAR_OUT",
+  CIRCULAR_IN_OUT: "CIRCULAR_IN_OUT",
+  ELASTIC_IN: "ELASTIC_IN",
+  ELASTIC_OUT: "ELASTIC_OUT",
+  ELASTIC_IN_OUT: "ELASTIC_IN_OUT",
+  BACK_IN: "BACK_IN",
+  BACK_OUT: "BACK_OUT",
+  BACK_IN_OUT: "BACK_IN_OUT",
+  BOUNCE_IN: "BOUNCE_IN",
+  BOUNCE_OUT: "BOUNCE_OUT",
+  BOUNCE_IN_OUT: "BOUNCE_IN_OUT",
+};
+
+const CurveFunctionMap = {
+  [CurveFunction.LINEAR]: Easing.Linear.None,
+  [CurveFunction.QUADRATIC_IN]: Easing.Quadratic.In,
+  [CurveFunction.QUADRATIC_OUT]: Easing.Quadratic.Out,
+  [CurveFunction.QUADRATIC_IN_OUT]: Easing.Quadratic.InOut,
+  [CurveFunction.CUBIC_IN]: Easing.Cubic.In,
+  [CurveFunction.CUBIC_OUT]: Easing.Cubic.Out,
+  [CurveFunction.CUBIC_IN_OUT]: Easing.Cubic.InOut,
+  [CurveFunction.QUARTIC_IN]: Easing.Quartic.In,
+  [CurveFunction.QUARTIC_OUT]: Easing.Quartic.Out,
+  [CurveFunction.QUARTIC_IN_OUT]: Easing.Quartic.InOut,
+  [CurveFunction.QUINTIC_IN]: Easing.Quintic.In,
+  [CurveFunction.QUINTIC_OUT]: Easing.Quintic.Out,
+  [CurveFunction.QUINTIC_IN_OUT]: Easing.Quintic.InOut,
+  [CurveFunction.SINUSOIDAL_IN]: Easing.Sinusoidal.In,
+  [CurveFunction.SINUSOIDAL_OUT]: Easing.Sinusoidal.Out,
+  [CurveFunction.SINUSOIDAL_IN_OUT]: Easing.Sinusoidal.InOut,
+  [CurveFunction.EXPONENTIAL_IN]: Easing.Exponential.In,
+  [CurveFunction.EXPONENTIAL_OUT]: Easing.Exponential.Out,
+  [CurveFunction.EXPONENTIAL_IN_OUT]: Easing.Exponential.InOut,
+  [CurveFunction.CIRCULAR_IN]: Easing.Circular.In,
+  [CurveFunction.CIRCULAR_OUT]: Easing.Circular.Out,
+  [CurveFunction.CIRCULAR_IN_OUT]: Easing.Circular.InOut,
+  [CurveFunction.ELASTIC_IN]: Easing.Elastic.In,
+  [CurveFunction.ELASTIC_OUT]: Easing.Elastic.Out,
+  [CurveFunction.ELASTIC_IN_OUT]: Easing.Elastic.InOut,
+  [CurveFunction.BACK_IN]: Easing.Back.In,
+  [CurveFunction.BACK_OUT]: Easing.Back.Out,
+  [CurveFunction.BACK_IN_OUT]: Easing.Back.InOut,
+  [CurveFunction.BOUNCE_IN]: Easing.Bounce.In,
+  [CurveFunction.BOUNCE_OUT]: Easing.Bounce.Out,
+  [CurveFunction.BOUNCE_IN_OUT]: Easing.Bounce.InOut,
+};
+
+export const getCurveFunction = (curveFunction) =>
+  typeof curveFunction === "function"
+    ? curveFunction
+    : CurveFunctionMap[curveFunction];

package/src/js/effects/three-particles/three-particles-modifiers.js

@@ -0,0 +1,44 @@
+import { getCurveFunction } from "./three-particles-curves.js";
+
+const modifiers = [
+  // {key:"colorOverLifetime", attributeKeys:["colorR", "colorG", "colorB"]},
+  {
+    key: "opacityOverLifetime",
+    attributeKeys: ["colorA"],
+    startValueKeys: ["startOpacity"],
+  },
+  {
+    key: "sizeOverLifetime",
+    attributeKeys: ["size"],
+    startValueKeys: ["startSize"],
+  },
+];
+
+export const applyModifiers = ({
+  startValues,
+  normalizedConfig,
+  attributes,
+  particleLifetimePercentage,
+  particleIndex,
+  forceUpdate = false,
+}) => {
+  modifiers.forEach(({ key, attributeKeys, startValueKeys }) => {
+    const modifier = normalizedConfig[key];
+    if (modifier.isActive) {
+      const multiplier = getCurveFunction(modifier.curveFunction)(
+        particleLifetimePercentage
+      );
+      attributeKeys.forEach((attributeKey, index) => {
+        attributes[attributeKey].array[particleIndex] =
+          startValues[startValueKeys[index]][particleIndex] * multiplier;
+        attributes[attributeKey].needsUpdate = true;
+      });
+    } else if (forceUpdate) {
+      attributeKeys.forEach((attributeKey, index) => {
+        attributes[attributeKey].array[particleIndex] =
+          startValues[startValueKeys[index]][particleIndex];
+        attributes[attributeKey].needsUpdate = true;
+      });
+    }
+  });
+};

package/src/js/effects/{three-particles-utils.js → three-particles/three-particles-utils.js}

@@ -1,6 +1,6 @@
 import * as THREE from "three/build/three.module.js";
 
-export const deepMerge = (
+export const patchObject = (
   objectA,
   objectB,
   config = { skippedProperties: [], applyToFirstObject: false }
@@ -9,7 +9,7 @@ export const deepMerge = (
   Object.keys(objectA).forEach((key) => {
     if (!config.skippedProperties || !config.skippedProperties.includes(key)) {
       if (typeof objectA[key] === "object" && objectA[key] && objectB[key]) {
-        result[key] = deepMerge(objectA[key], objectB[key], config);
+        result[key] = patchObject(objectA[key], objectB[key], config);
       } else {
         result[key] = objectB[key] === 0 ? 0 : objectB[key] || objectA[key];
         if (config.applyToFirstObject) objectA[key] = result[key];
@@ -100,7 +100,7 @@ export const calculateRandomPositionAndVelocityOnCone = (
       sinNormalizedAngle *
       speedMultiplierByPosition *
       randomizedSpeed,
-    -Math.cos(normalizedAngle) * randomizedSpeed
+    Math.cos(normalizedAngle) * randomizedSpeed
   );
 };
 
@@ -157,5 +157,5 @@ export const calculateRandomPositionAndVelocityOnRectangle = (
     startSpeed.min,
     startSpeed.max
   );
-  velocity.set(0, 0, -randomizedSpeed);
+  velocity.set(0, 0, randomizedSpeed);
 };

package/src/js/effects/three-particles.js

@@ -5,11 +5,13 @@ import {
   calculateRandomPositionAndVelocityOnCone,
   calculateRandomPositionAndVelocityOnRectangle,
   calculateRandomPositionAndVelocityOnSphere,
-  deepMerge,
-} from "./three-particles-utils.js";
+  patchObject,
+} from "./three-particles/three-particles-utils.js";
 
-import ParticleSystemFragmentShader from "./shaders/particle-system-fragment-shader.glsl.js";
-import ParticleSystemVertexShader from "./shaders/particle-system-vertex-shader.glsl.js";
+import { CurveFunction } from "./three-particles/three-particles-curves.js";
+import ParticleSystemFragmentShader from "./three-particles/shaders/particle-system-fragment-shader.glsl.js";
+import ParticleSystemVertexShader from "./three-particles/shaders/particle-system-vertex-shader.glsl.js";
+import { applyModifiers } from "./three-particles/three-particles-modifiers.js";
 
 // Float32Array is not enough accurate when we are storing timestamp in it so we just remove unnecessary time
 const float32Helper = 1638200000000;
@@ -38,6 +40,11 @@ export const getDefaultParticleSystemConfig = () =>
   JSON.parse(JSON.stringify(DEFAULT_PARTICLE_SYSTEM_CONFIG));
 
 const DEFAULT_PARTICLE_SYSTEM_CONFIG = {
+  transform: {
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0 },
+    scale: { x: 1, y: 1, z: 1 },
+  },
   duration: 5.0,
   looping: true,
   startDelay: { min: 0.0, max: 0.0 },
@@ -81,6 +88,18 @@ const DEFAULT_PARTICLE_SYSTEM_CONFIG = {
     },
   },
   map: null,
+  sizeOverLifetime: {
+    isActive: false,
+    curveFunction: CurveFunction.LINEAR,
+  },
+  /* colorOverLifetime: {
+    isActive: false,
+    curveFunction: CurveFunction.LINEAR,
+  }, */
+  opacityOverLifetime: {
+    isActive: false,
+    curveFunction: CurveFunction.LINEAR,
+  },
   textureSheetAnimation: {
     tiles: new THREE.Vector2(1.0, 1.0),
     timeMode: TimeMode.LIFETIME,
@@ -158,11 +177,21 @@ export const createParticleSystem = (
   config = DEFAULT_PARTICLE_SYSTEM_CONFIG
 ) => {
   const now = Date.now();
-  const lastWorldPosition = new THREE.Vector3(-99999, -99999, -99999);
-  const worldPositionChange = new THREE.Vector3();
-  const generalData = { distanceFromLastEmitByDistance: 0 };
+  const generalData = {
+    distanceFromLastEmitByDistance: 0,
+    lastWorldPosition: new THREE.Vector3(-99999),
+    currentWorldPosition: new THREE.Vector3(-99999),
+    worldPositionChange: new THREE.Vector3(),
+    worldQuaternion: new THREE.Quaternion(),
+    lastWorldQuaternion: new THREE.Quaternion(-99999),
+    worldEuler: new THREE.Euler(),
+    gravityVelocity: new THREE.Vector3(0, 0, 0),
+    startValues: {},
+  };
 
+  const normalizedConfig = patchObject(DEFAULT_PARTICLE_SYSTEM_CONFIG, config);
   const {
+    transform,
     duration,
     looping,
     startDelay,
@@ -181,7 +210,7 @@ export const createParticleSystem = (
     onUpdate,
     onComplete,
     textureSheetAnimation,
-  } = deepMerge(DEFAULT_PARTICLE_SYSTEM_CONFIG, config);
+  } = normalizedConfig;
 
   const startPositions = Array.from(
     { length: maxParticles },
@@ -192,6 +221,16 @@ export const createParticleSystem = (
     () => new THREE.Vector3()
   );
 
+  const startValueKeys = ["startSize", "startOpacity"];
+  startValueKeys.forEach((key) => {
+    generalData.startValues[key] = Array.from({ length: maxParticles }, () =>
+      THREE.MathUtils.randFloat(
+        normalizedConfig[key].min,
+        normalizedConfig[key].max
+      )
+    );
+  });
+
   const material = new THREE.ShaderMaterial({
     uniforms: {
       elapsed: {
@@ -258,22 +297,16 @@ export const createParticleSystem = (
 
   createFloat32AttributesRequest("opacity", 0);
 
-  createFloat32Attributes({
-    geometry,
-    propertyName: "rotation",
-    maxParticles,
-    factory: () =>
-      THREE.Math.degToRad(
-        THREE.MathUtils.randFloat(startRotation.min, startRotation.max)
-      ),
-  });
+  createFloat32AttributesRequest("rotation", () =>
+    THREE.Math.degToRad(
+      THREE.MathUtils.randFloat(startRotation.min, startRotation.max)
+    )
+  );
 
-  createFloat32Attributes({
-    geometry,
-    propertyName: "startSize",
-    maxParticles,
-    factory: () => THREE.MathUtils.randFloat(startSize.min, startSize.max),
-  });
+  createFloat32AttributesRequest(
+    "size",
+    (_, index) => generalData.startValues.startSize[index]
+  );
 
   createFloat32AttributesRequest("rotation", 0);
 
@@ -300,8 +333,6 @@ export const createParticleSystem = (
 
   const deactivateParticle = (particleIndex) => {
     geometry.attributes.isActive.array[particleIndex] = false;
-    geometry.attributes.lifetime.array[particleIndex] = 0;
-    geometry.attributes.lifetime.needsUpdate = true;
     geometry.attributes.colorA.array[particleIndex] = 0;
     geometry.attributes.colorA.needsUpdate = true;
   };
@@ -328,12 +359,6 @@ export const createParticleSystem = (
       colorRandomRatio * (startColor.max.b - startColor.min.b);
     geometry.attributes.colorB.needsUpdate = true;
 
-    geometry.attributes.colorA.array[particleIndex] = THREE.MathUtils.randFloat(
-      startOpacity.min,
-      startOpacity.max
-    );
-    geometry.attributes.colorA.needsUpdate = true;
-
     geometry.attributes.startFrame.array[particleIndex] =
       THREE.MathUtils.randInt(
         textureSheetAnimation.startFrame.min,
@@ -345,14 +370,17 @@ export const createParticleSystem = (
       THREE.MathUtils.randFloat(startLifetime.min, startLifetime.max) * 1000;
     geometry.attributes.startLifetime.needsUpdate = true;
 
-    geometry.attributes.startSize.array[particleIndex] =
+    generalData.startValues.startSize[particleIndex] =
       THREE.MathUtils.randFloat(startSize.min, startSize.max);
-    geometry.attributes.startSize.needsUpdate = true;
+    generalData.startValues.startOpacity[particleIndex] =
+      THREE.MathUtils.randFloat(startOpacity.min, startOpacity.max);
 
     geometry.attributes.rotation.array[particleIndex] = THREE.Math.degToRad(
       THREE.MathUtils.randFloat(startRotation.min, startRotation.max)
     );
+
     geometry.attributes.rotation.needsUpdate = true;
+    geometry.attributes.colorB.needsUpdate = true;
 
     calculatePositionAndVelocity(
       shape,
@@ -371,19 +399,32 @@ export const createParticleSystem = (
 
     geometry.attributes.lifetime.array[particleIndex] = 0;
     geometry.attributes.lifetime.needsUpdate = true;
+
+    applyModifiers({
+      startValues: generalData.startValues,
+      normalizedConfig,
+      attributes: particleSystem.geometry.attributes,
+      particleLifetimePercentage: 0,
+      particleIndex,
+      forceUpdate: true,
+    });
   };
 
   const particleSystem = new THREE.Points(geometry, material);
   particleSystem.sortParticles = true;
 
+  particleSystem.position.copy(transform.position);
+  particleSystem.rotation.x = THREE.Math.degToRad(transform.rotation.x);
+  particleSystem.rotation.y = THREE.Math.degToRad(transform.rotation.y);
+  particleSystem.rotation.z = THREE.Math.degToRad(transform.rotation.z);
+  particleSystem.scale.copy(transform.scale);
+
   const calculatedCreationTime =
     now + THREE.MathUtils.randFloat(startDelay.min, startDelay.max) * 1000;
 
   createdParticleSystems.push({
     particleSystem,
     generalData,
-    lastWorldPosition,
-    worldPositionChange,
     onUpdate,
     onComplete,
     creationTime: calculatedCreationTime,
@@ -393,6 +434,7 @@ export const createParticleSystem = (
     simulationSpace,
     gravity,
     emission,
+    normalizedConfig,
     iterationCount: 0,
     velocities,
     deactivateParticle,
@@ -417,8 +459,6 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
     const {
       onUpdate,
       generalData,
-      lastWorldPosition,
-      worldPositionChange,
       onComplete,
       particleSystem,
       creationTime,
@@ -426,6 +466,7 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
       duration,
       looping,
       emission,
+      normalizedConfig,
       iterationCount,
       velocities,
       deactivateParticle,
@@ -433,21 +474,50 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
       simulationSpace,
       gravity,
     } = props;
+
+    const {
+      lastWorldPosition,
+      currentWorldPosition,
+      worldPositionChange,
+      lastWorldQuaternion,
+      worldQuaternion,
+      worldEuler,
+      gravityVelocity,
+    } = generalData;
+
     const lifetime = now - creationTime;
     particleSystem.material.uniforms.elapsed.value = elapsed;
 
-    if (
-      lastWorldPosition.x !== -99999 &&
-      lastWorldPosition.y !== -99999 &&
-      lastWorldPosition.z !== -99999
-    )
+    particleSystem.getWorldPosition(currentWorldPosition);
+    if (lastWorldPosition.x !== -99999)
       worldPositionChange.set(
-        particleSystem.position.x - lastWorldPosition.x,
-        particleSystem.position.y - lastWorldPosition.y,
-        particleSystem.position.z - lastWorldPosition.z
+        currentWorldPosition.x - lastWorldPosition.x,
+        currentWorldPosition.y - lastWorldPosition.y,
+        currentWorldPosition.z - lastWorldPosition.z
       );
     generalData.distanceFromLastEmitByDistance += worldPositionChange.length();
-    lastWorldPosition.copy(particleSystem.position);
+    particleSystem.getWorldPosition(lastWorldPosition);
+
+    particleSystem.getWorldQuaternion(worldQuaternion);
+    if (
+      lastWorldQuaternion.x === -99999 ||
+      lastWorldQuaternion.x != worldQuaternion.x ||
+      lastWorldQuaternion.y != worldQuaternion.y ||
+      lastWorldQuaternion.z != worldQuaternion.z
+    ) {
+      worldEuler.setFromQuaternion(worldQuaternion);
+      lastWorldQuaternion.copy(worldQuaternion);
+
+      const tempPosX = particleSystem.position.x;
+      const tempPosY = particleSystem.position.y;
+      const tempPosZ = particleSystem.position.z;
+      gravityVelocity.set(0, gravity, 0);
+      particleSystem.position.set(0, 0, 0);
+      particleSystem.updateMatrixWorld();
+      particleSystem.worldToLocal(gravityVelocity);
+      particleSystem.position.set(tempPosX, tempPosY, tempPosZ);
+      particleSystem.updateMatrixWorld();
+    }
 
     particleSystem.geometry.attributes.creationTime.array.forEach(
       (entry, index) => {
@@ -460,7 +530,9 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
             deactivateParticle(index);
           else {
             const velocity = velocities[index];
-            velocity.y -= gravity;
+            velocity.x -= gravityVelocity.x;
+            velocity.y -= gravityVelocity.y;
+            velocity.z -= gravityVelocity.z;
 
             if (
               gravity !== 0 ||
@@ -486,12 +558,16 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
               particleLifetime;
             particleSystem.geometry.attributes.lifetime.needsUpdate = true;
 
-            // TEMP
-            particleSystem.geometry.attributes.colorA.array[index] =
-              1 -
+            const particleLifetimePercentage =
               particleLifetime /
-                particleSystem.geometry.attributes.startLifetime.array[index];
-            particleSystem.geometry.attributes.colorA.needsUpdate = true;
+              particleSystem.geometry.attributes.startLifetime.array[index];
+            applyModifiers({
+              startValues: generalData.startValues,
+              normalizedConfig,
+              attributes: particleSystem.geometry.attributes,
+              particleLifetimePercentage,
+              particleIndex: index,
+            });
           }
         }
       }