@newkrok/three-particles 2.12.0 → 2.14.0

package/dist/index.js

@@ -174,6 +174,7 @@ var RendererType = /* @__PURE__ */ ((RendererType2) => {
   RendererType2["POINTS"] = "POINTS";
   RendererType2["INSTANCED"] = "INSTANCED";
   RendererType2["TRAIL"] = "TRAIL";
+  RendererType2["MESH"] = "MESH";
   return RendererType2;
 })(RendererType || {});
 var ForceFieldFalloff = /* @__PURE__ */ ((ForceFieldFalloff2) => {
@@ -310,6 +311,24 @@ var calculateRandomPositionAndVelocityOnRectangle = (position, quaternion, veloc
   velocity.set(0, 0, speed);
   velocity.applyQuaternion(quaternion);
 };
+var createDefaultMeshTexture = () => {
+  try {
+    const canvas = document.createElement("canvas");
+    canvas.width = 1;
+    canvas.height = 1;
+    const context = canvas.getContext("2d");
+    if (context) {
+      context.fillStyle = "white";
+      context.fillRect(0, 0, 1, 1);
+      const texture = new THREE4.CanvasTexture(canvas);
+      texture.needsUpdate = true;
+      return texture;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
 var createDefaultParticleTexture = () => {
   try {
     const canvas = document.createElement("canvas");
@@ -494,6 +513,16 @@ var applyModifiers = ({
     positionArr[positionIndex + 2] += noiseOnPosition * noisePower * positionAmount;
     attributes.position.needsUpdate = true;
   }
+  if (attributes.quat) {
+    const rotZ = attributes.rotation.array[particleIndex];
+    const halfZ = rotZ * 0.5;
+    const qi = particleIndex * 4;
+    attributes.quat.array[qi] = 0;
+    attributes.quat.array[qi + 1] = 0;
+    attributes.quat.array[qi + 2] = Math.sin(halfZ);
+    attributes.quat.array[qi + 3] = Math.cos(halfZ);
+    attributes.quat.needsUpdate = true;
+  }
 };
 
 // src/js/effects/three-particles/shaders/instanced-particle-fragment-shader.glsl.ts
@@ -506,6 +535,10 @@ var InstancedParticleFragmentShader = `
   uniform bool discardBackgroundColor;
   uniform vec3 backgroundColor;
   uniform float backgroundColorTolerance;
+  uniform bool softParticlesEnabled;
+  uniform float softParticlesIntensity;
+  uniform sampler2D sceneDepthTexture;
+  uniform vec2 cameraNearFar;
 
   varying vec2 vUv;
   varying vec4 vColor;
@@ -513,10 +546,16 @@ var InstancedParticleFragmentShader = `
   varying float vStartLifetime;
   varying float vStartFrame;
   varying float vRotation;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_fragment>
 
+  float linearizeDepth(float depthSample, float near, float far) {
+    float z_ndc = 2.0 * depthSample - 1.0;
+    return 2.0 * near * far / (far + near - z_ndc * (far - near));
+  }
+
   void main()
   {
     gl_FragColor = vColor;
@@ -559,6 +598,16 @@ var InstancedParticleFragmentShader = `
 
     if (discardBackgroundColor && abs(length(rotatedTexture.rgb - backgroundColor.rgb)) < backgroundColorTolerance) discard;
 
+    if (softParticlesEnabled) {
+      vec2 screenUV = gl_FragCoord.xy / vec2(textureSize(sceneDepthTexture, 0));
+      float sceneDepthSample = texture2D(sceneDepthTexture, screenUV).r;
+      float sceneDepthLinear = linearizeDepth(sceneDepthSample, cameraNearFar.x, cameraNearFar.y);
+      float depthDiff = sceneDepthLinear - vViewZ;
+      float softFade = smoothstep(0.0, softParticlesIntensity, depthDiff);
+      gl_FragColor.a *= softFade;
+      if (gl_FragColor.a < 0.001) discard;
+    }
+
     #include <logdepthbuf_fragment>
   }
 `;
@@ -585,6 +634,7 @@ var InstancedParticleVertexShader = `
   varying float vStartLifetime;
   varying float vStartFrame;
   varying float vRotation;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_vertex>
@@ -619,6 +669,7 @@ var InstancedParticleVertexShader = `
     // identical to the Points renderer).
     mvPosition.xy += position.xy * perspectiveSize;
 
+    vViewZ = -mvPosition.z;
     gl_Position = projectionMatrix * mvPosition;
 
     // Pass UV for texture sampling (quad ranges from -0.5..0.5, map to 0..1).
@@ -630,6 +681,151 @@ var InstancedParticleVertexShader = `
 `;
 var instanced_particle_vertex_shader_glsl_default = InstancedParticleVertexShader;
 
+// src/js/effects/three-particles/shaders/mesh-particle-fragment-shader.glsl.ts
+var MeshParticleFragmentShader = `
+  uniform sampler2D map;
+  uniform float elapsed;
+  uniform float fps;
+  uniform bool useFPSForFrameIndex;
+  uniform vec2 tiles;
+  uniform bool discardBackgroundColor;
+  uniform vec3 backgroundColor;
+  uniform float backgroundColorTolerance;
+  uniform bool softParticlesEnabled;
+  uniform float softParticlesIntensity;
+  uniform sampler2D sceneDepthTexture;
+  uniform vec2 cameraNearFar;
+
+  varying vec4 vColor;
+  varying float vLifetime;
+  varying float vStartLifetime;
+  varying float vStartFrame;
+  varying float vRotation;
+  varying vec3 vNormal;
+  varying vec2 vUv;
+  varying float vViewZ;
+
+  #include <common>
+  #include <logdepthbuf_pars_fragment>
+
+  float linearizeDepth(float depthSample, float near, float far) {
+    float z_ndc = 2.0 * depthSample - 1.0;
+    return 2.0 * near * far / (far + near - z_ndc * (far - near));
+  }
+
+  void main()
+  {
+    gl_FragColor = vColor;
+
+    // Use mesh UVs directly for texture sampling
+    vec2 uvPoint = vUv;
+
+    // Apply texture sheet animation if tiles > 1x1
+    if (tiles.x > 1.0 || tiles.y > 1.0) {
+      float frameIndex = round(vStartFrame) + (
+        useFPSForFrameIndex == true
+          ? fps == 0.0
+              ? 0.0
+              : max((vLifetime / 1000.0) * fps, 0.0)
+          : max(min(floor(min(vLifetime / vStartLifetime, 1.0) * (tiles.x * tiles.y)), tiles.x * tiles.y - 1.0), 0.0)
+      );
+
+      float spriteXIndex = floor(mod(frameIndex, tiles.x));
+      float spriteYIndex = floor(mod(frameIndex / tiles.x, tiles.y));
+
+      uvPoint = vec2(
+        vUv.x / tiles.x + spriteXIndex / tiles.x,
+        vUv.y / tiles.y + spriteYIndex / tiles.y
+      );
+    }
+
+    vec4 texColor = texture2D(map, uvPoint);
+    gl_FragColor = gl_FragColor * texColor;
+
+    if (discardBackgroundColor && abs(length(texColor.rgb - backgroundColor.rgb)) < backgroundColorTolerance) discard;
+
+    // Simple directional lighting from camera direction
+    float lightIntensity = 0.5 + 0.5 * max(dot(vNormal, vec3(0.0, 0.0, 1.0)), 0.0);
+    gl_FragColor.rgb *= lightIntensity;
+
+    if (softParticlesEnabled) {
+      vec2 screenUV = gl_FragCoord.xy / vec2(textureSize(sceneDepthTexture, 0));
+      float sceneDepthSample = texture2D(sceneDepthTexture, screenUV).r;
+      float sceneDepthLinear = linearizeDepth(sceneDepthSample, cameraNearFar.x, cameraNearFar.y);
+      float depthDiff = sceneDepthLinear - vViewZ;
+      float softFade = smoothstep(0.0, softParticlesIntensity, depthDiff);
+      gl_FragColor.a *= softFade;
+      if (gl_FragColor.a < 0.001) discard;
+    }
+
+    #include <logdepthbuf_fragment>
+  }
+`;
+var mesh_particle_fragment_shader_glsl_default = MeshParticleFragmentShader;
+
+// src/js/effects/three-particles/shaders/mesh-particle-vertex-shader.glsl.ts
+var MeshParticleVertexShader = `
+  attribute float instanceSize;
+  attribute float instanceColorR;
+  attribute float instanceColorG;
+  attribute float instanceColorB;
+  attribute float instanceColorA;
+  attribute float instanceLifetime;
+  attribute float instanceStartLifetime;
+  attribute float instanceRotation;
+  attribute float instanceStartFrame;
+  attribute vec3 instanceOffset;
+  attribute vec4 instanceQuat;
+
+  varying vec4 vColor;
+  varying float vLifetime;
+  varying float vStartLifetime;
+  varying float vStartFrame;
+  varying float vRotation;
+  varying vec3 vNormal;
+  varying vec2 vUv;
+  varying float vViewZ;
+
+  #include <common>
+  #include <logdepthbuf_pars_vertex>
+
+  vec3 applyQuaternion(vec3 v, vec4 q) {
+    vec3 t = 2.0 * cross(q.xyz, v);
+    return v + q.w * t + cross(q.xyz, t);
+  }
+
+  void main()
+  {
+    vColor = vec4(instanceColorR, instanceColorG, instanceColorB, instanceColorA);
+    vLifetime = instanceLifetime;
+    vStartLifetime = instanceStartLifetime;
+    vStartFrame = instanceStartFrame;
+    vRotation = instanceRotation;
+
+    // Apply quaternion rotation to the mesh vertex position
+    vec3 rotatedPosition = applyQuaternion(position, instanceQuat);
+
+    // Scale mesh by particle size
+    vec3 scaledPosition = rotatedPosition * instanceSize;
+
+    // Apply instance offset (particle world position)
+    vec3 worldPos = scaledPosition + instanceOffset;
+
+    vec4 mvPosition = modelViewMatrix * vec4(worldPos, 1.0);
+    vViewZ = -mvPosition.z;
+    gl_Position = projectionMatrix * mvPosition;
+
+    // Transform normal by quaternion for lighting
+    vNormal = normalize((modelViewMatrix * vec4(applyQuaternion(normal, instanceQuat), 0.0)).xyz);
+
+    // Pass through UVs from the mesh geometry
+    vUv = uv;
+
+    #include <logdepthbuf_vertex>
+  }
+`;
+var mesh_particle_vertex_shader_glsl_default = MeshParticleVertexShader;
+
 // src/js/effects/three-particles/shaders/particle-system-fragment-shader.glsl.ts
 var ParticleSystemFragmentShader = `
   uniform sampler2D map;
@@ -640,16 +836,26 @@ var ParticleSystemFragmentShader = `
   uniform bool discardBackgroundColor;
   uniform vec3 backgroundColor;
   uniform float backgroundColorTolerance;
+  uniform bool softParticlesEnabled;
+  uniform float softParticlesIntensity;
+  uniform sampler2D sceneDepthTexture;
+  uniform vec2 cameraNearFar;
 
   varying vec4 vColor;
   varying float vLifetime;
   varying float vStartLifetime;
   varying float vRotation;
   varying float vStartFrame;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_fragment>
 
+  float linearizeDepth(float depthSample, float near, float far) {
+    float z_ndc = 2.0 * depthSample - 1.0;
+    return 2.0 * near * far / (far + near - z_ndc * (far - near));
+  }
+
   void main()
   {
     gl_FragColor = vColor;
@@ -697,7 +903,17 @@ var ParticleSystemFragmentShader = `
     gl_FragColor = gl_FragColor * rotatedTexture;
 
     if (discardBackgroundColor && abs(length(rotatedTexture.rgb - backgroundColor.rgb)) < backgroundColorTolerance) discard;
-    
+
+    if (softParticlesEnabled) {
+      vec2 screenUV = gl_FragCoord.xy / vec2(textureSize(sceneDepthTexture, 0));
+      float sceneDepthSample = texture2D(sceneDepthTexture, screenUV).r;
+      float sceneDepthLinear = linearizeDepth(sceneDepthSample, cameraNearFar.x, cameraNearFar.y);
+      float depthDiff = sceneDepthLinear - vViewZ;
+      float softFade = smoothstep(0.0, softParticlesIntensity, depthDiff);
+      gl_FragColor.a *= softFade;
+      if (gl_FragColor.a < 0.001) discard;
+    }
+
     #include <logdepthbuf_fragment>
   }
 `;
@@ -721,6 +937,7 @@ var ParticleSystemVertexShader = `
   varying float vStartLifetime;
   varying float vRotation;
   varying float vStartFrame;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_vertex>
@@ -735,6 +952,7 @@ var ParticleSystemVertexShader = `
 
     vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
     gl_PointSize = size * (100.0 / length(mvPosition.xyz));
+    vViewZ = -mvPosition.z;
     gl_Position = projectionMatrix * mvPosition;
 
     #include <logdepthbuf_vertex>
@@ -749,14 +967,24 @@ var TrailFragmentShader = `
   uniform bool discardBackgroundColor;
   uniform vec3 backgroundColor;
   uniform float backgroundColorTolerance;
+  uniform bool softParticlesEnabled;
+  uniform float softParticlesIntensity;
+  uniform sampler2D sceneDepthTexture;
+  uniform vec2 cameraNearFar;
 
   varying float vAlpha;
   varying vec4 vColor;
   varying vec2 vUv;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_fragment>
 
+  float linearizeDepth(float depthSample, float near, float far) {
+    float z_ndc = 2.0 * depthSample - 1.0;
+    return 2.0 * near * far / (far + near - z_ndc * (far - near));
+  }
+
   void main()
   {
     // Soft edge: always fade near ribbon edges
@@ -777,6 +1005,16 @@ var TrailFragmentShader = `
 
     if (gl_FragColor.a < 0.001) discard;
 
+    if (softParticlesEnabled) {
+      vec2 screenUV = gl_FragCoord.xy / vec2(textureSize(sceneDepthTexture, 0));
+      float sceneDepthSample = texture2D(sceneDepthTexture, screenUV).r;
+      float sceneDepthLinear = linearizeDepth(sceneDepthSample, cameraNearFar.x, cameraNearFar.y);
+      float depthDiff = sceneDepthLinear - vViewZ;
+      float softFade = smoothstep(0.0, softParticlesIntensity, depthDiff);
+      gl_FragColor.a *= softFade;
+      if (gl_FragColor.a < 0.001) discard;
+    }
+
     if (discardBackgroundColor && abs(length(gl_FragColor.rgb - backgroundColor.rgb)) < backgroundColorTolerance) discard;
 
     #include <logdepthbuf_fragment>
@@ -796,6 +1034,7 @@ var TrailVertexShader = `
   varying float vAlpha;
   varying vec4 vColor;
   varying vec2 vUv;
+  varying float vViewZ;
 
   #include <common>
   #include <logdepthbuf_pars_vertex>
@@ -822,28 +1061,27 @@ var TrailVertexShader = `
     float perpLen = length(perp);
 
     // When tangent is nearly parallel to view direction, the cross product
-    // collapses and the ribbon becomes edge-on (invisible). Use a secondary
-    // perpendicular from cross(tangent, up) and blend it in to guarantee
-    // a minimum visible width.
-    vec3 upPerp = cross(tangent, vec3(0.0, 1.0, 0.0));
-    float upPerpLen = length(upPerp);
-    if (upPerpLen < 0.0001) {
-      upPerp = cross(tangent, vec3(1.0, 0.0, 0.0));
-      upPerpLen = length(upPerp);
-    }
-    upPerp = upPerp / max(upPerpLen, 0.0001);
+    // collapses and the ribbon becomes edge-on (invisible). Build a stable
+    // fallback perpendicular from the camera's right axis \u2014 this keeps the
+    // ribbon in screen-space and prevents it from flipping into an arbitrary
+    // plane when viewed edge-on.
+    vec3 camRight = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
+    vec3 fallbackPerp = normalize(camRight - tangent * dot(camRight, tangent));
 
     if (perpLen < 0.0001) {
-      perp = upPerp;
+      perp = fallbackPerp;
     } else {
       perp = perp / perpLen;
-      // Blend in the secondary perp when billboard perp gets weak
-      float blendFactor = smoothstep(0.0, 0.5, perpLen);
-      perp = normalize(mix(upPerp, perp, blendFactor));
+      // Smoothly blend toward the fallback when the billboard perp weakens.
+      // The wide range (0..0.7) ensures a gradual transition so the ribbon
+      // does not snap abruptly when rotating toward edge-on.
+      float blendFactor = smoothstep(0.0, 0.7, perpLen);
+      perp = normalize(mix(fallbackPerp, perp, blendFactor));
     }
 
     vec3 offsetPos = position + perp * trailOffset * trailHalfWidth;
     vec4 mvPosition = modelViewMatrix * vec4(offsetPos, 1.0);
+    vViewZ = -mvPosition.z;
     gl_Position = projectionMatrix * mvPosition;
 
     #include <logdepthbuf_vertex>
@@ -1016,7 +1254,11 @@ var DEFAULT_PARTICLE_SYSTEM_CONFIG = {
     backgroundColor: { r: 1, g: 1, b: 1 },
     transparent: true,
     depthTest: true,
-    depthWrite: false
+    depthWrite: false,
+    softParticles: {
+      enabled: false,
+      intensity: 1
+    }
   },
   velocityOverLifetime: {
     isActive: false,
@@ -1239,7 +1481,7 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     config,
     { applyToFirstObject: false, skippedProperties: [] }
   );
-  let particleMap = normalizedConfig.map || createDefaultParticleTexture();
+  let particleMap = normalizedConfig.map || (normalizedConfig.renderer.rendererType === "MESH" /* MESH */ ? createDefaultMeshTexture() : createDefaultParticleTexture());
   const {
     transform,
     duration,
@@ -1424,7 +1666,9 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     }));
   }
   const useTrail = renderer.rendererType === "TRAIL" /* TRAIL */;
-  const useInstancing = !useTrail && renderer.rendererType === "INSTANCED" /* INSTANCED */;
+  const useMesh = renderer.rendererType === "MESH" /* MESH */;
+  const useInstancing = !useTrail && !useMesh && renderer.rendererType === "INSTANCED" /* INSTANCED */;
+  const useInstancedAttributes = useInstancing || useMesh;
   const defaultTrailCurve = {
     type: "BEZIER" /* BEZIER */,
     scale: 1,
@@ -1444,7 +1688,13 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       renderer.trail?.opacityOverTrail,
       defaultTrailCurve
     ),
-    colorOverTrail: renderer.trail?.colorOverTrail
+    colorOverTrail: renderer.trail?.colorOverTrail,
+    minVertexDistance: renderer.trail?.minVertexDistance ?? 0,
+    maxTime: renderer.trail?.maxTime ?? 0,
+    smoothing: renderer.trail?.smoothing ?? false,
+    smoothingSubdivisions: renderer.trail?.smoothingSubdivisions ?? 3,
+    twistPrevention: renderer.trail?.twistPrevention ?? false,
+    ribbonId: renderer.trail?.ribbonId
   } : void 0;
   if (useTrail && trailConfig) {
     const trailLength = trailConfig.length;
@@ -1454,9 +1704,21 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     );
     generalData.positionHistoryIndex = new Uint16Array(maxParticles);
     generalData.positionHistoryCount = new Uint16Array(maxParticles);
+    if (trailConfig.minVertexDistance > 0) {
+      generalData.trailLastSampledPosition = new Float32Array(maxParticles * 3);
+    }
+    if (trailConfig.maxTime > 0) {
+      generalData.trailSampleTimes = new Float64Array(
+        maxParticles * trailLength
+      );
+    }
+    if (trailConfig.twistPrevention) {
+      generalData.trailPrevNormal = new Float32Array(maxParticles * 3);
+    }
   }
-  const attr = (name) => useInstancing ? `instance${name.charAt(0).toUpperCase()}${name.slice(1)}` : name;
-  const posAttr = useInstancing ? "instanceOffset" : "position";
+  const attr = (name) => useInstancedAttributes ? `instance${name.charAt(0).toUpperCase()}${name.slice(1)}` : name;
+  const posAttr = useInstancedAttributes ? "instanceOffset" : "position";
+  const softParticlesEnabled = !!(renderer.softParticles?.enabled && renderer.softParticles?.depthTexture);
   const sharedUniforms = {
     elapsed: { value: 0 },
     map: { value: particleMap },
@@ -1468,19 +1730,56 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     backgroundColor: { value: renderer.backgroundColor },
     discardBackgroundColor: { value: renderer.discardBackgroundColor },
     backgroundColorTolerance: { value: renderer.backgroundColorTolerance },
-    ...useInstancing ? { viewportHeight: { value: 1 } } : {}
+    ...useInstancing ? { viewportHeight: { value: 1 } } : {},
+    softParticlesEnabled: { value: softParticlesEnabled },
+    softParticlesIntensity: {
+      value: Math.max(renderer.softParticles?.intensity ?? 1, 1e-3)
+    },
+    sceneDepthTexture: {
+      value: renderer.softParticles?.depthTexture ?? null
+    },
+    cameraNearFar: { value: new THREE4.Vector2(0.1, 1e3) }
+  };
+  const getVertexShader = () => {
+    if (useMesh) return mesh_particle_vertex_shader_glsl_default;
+    if (useInstancing) return instanced_particle_vertex_shader_glsl_default;
+    return particle_system_vertex_shader_glsl_default;
+  };
+  const getFragmentShader = () => {
+    if (useMesh) return mesh_particle_fragment_shader_glsl_default;
+    if (useInstancing) return instanced_particle_fragment_shader_glsl_default;
+    return particle_system_fragment_shader_glsl_default;
   };
   const material = new THREE4.ShaderMaterial({
     uniforms: sharedUniforms,
-    vertexShader: useInstancing ? instanced_particle_vertex_shader_glsl_default : particle_system_vertex_shader_glsl_default,
-    fragmentShader: useInstancing ? instanced_particle_fragment_shader_glsl_default : particle_system_fragment_shader_glsl_default,
+    vertexShader: getVertexShader(),
+    fragmentShader: getFragmentShader(),
     transparent: renderer.transparent,
     blending: renderer.blending,
     depthTest: renderer.depthTest,
     depthWrite: renderer.depthWrite
   });
   let geometry;
-  if (useInstancing) {
+  if (useMesh) {
+    const meshConfig = renderer.mesh;
+    if (!meshConfig?.geometry) {
+      throw new Error(
+        "RendererType.MESH requires a mesh configuration with a geometry. Set renderer.mesh.geometry to a THREE.BufferGeometry instance."
+      );
+    }
+    const instancedGeometry = new THREE4.InstancedBufferGeometry();
+    const sourceGeom = meshConfig.geometry;
+    const srcPos = sourceGeom.getAttribute("position");
+    if (srcPos) instancedGeometry.setAttribute("position", srcPos);
+    const srcNormal = sourceGeom.getAttribute("normal");
+    if (srcNormal) instancedGeometry.setAttribute("normal", srcNormal);
+    const srcUv = sourceGeom.getAttribute("uv");
+    if (srcUv) instancedGeometry.setAttribute("uv", srcUv);
+    const srcIndex = sourceGeom.getIndex();
+    if (srcIndex) instancedGeometry.setIndex(srcIndex);
+    instancedGeometry.instanceCount = maxParticles;
+    geometry = instancedGeometry;
+  } else if (useInstancing) {
     const instancedGeometry = new THREE4.InstancedBufferGeometry();
     const quadPositions = new Float32Array([
       -0.5,
@@ -1521,28 +1820,28 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     positionArray[i * 3 + 1] = startPositions[i].y;
     positionArray[i * 3 + 2] = startPositions[i].z;
   }
-  const positionAttribute = useInstancing ? new THREE4.InstancedBufferAttribute(positionArray, 3) : new THREE4.BufferAttribute(positionArray, 3);
+  const positionAttribute = useInstancedAttributes ? new THREE4.InstancedBufferAttribute(positionArray, 3) : new THREE4.BufferAttribute(positionArray, 3);
   geometry.setAttribute(posAttr, positionAttribute);
   createFloat32Attributes({
     geometry,
     propertyName: attr("isActive"),
     maxParticles,
     factory: 0,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("lifetime"),
     maxParticles,
     factory: 0,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("startLifetime"),
     maxParticles,
     factory: () => calculateValue(generalData.particleSystemId, startLifetime, 0) * 1e3,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
@@ -1553,21 +1852,21 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       textureSheetAnimation.startFrame,
       0
     ) : 0,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("size"),
     maxParticles,
     factory: (_, index) => generalData.startValues.startSize[index],
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("rotation"),
     maxParticles,
     factory: 0,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   const colorRandomRatio = Math.random();
   createFloat32Attributes({
@@ -1575,29 +1874,39 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     propertyName: attr("colorR"),
     maxParticles,
     factory: () => startColor.min.r + colorRandomRatio * (startColor.max.r - startColor.min.r),
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("colorG"),
     maxParticles,
     factory: () => startColor.min.g + colorRandomRatio * (startColor.max.g - startColor.min.g),
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("colorB"),
     maxParticles,
     factory: () => startColor.min.b + colorRandomRatio * (startColor.max.b - startColor.min.b),
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
   createFloat32Attributes({
     geometry,
     propertyName: attr("colorA"),
     maxParticles,
     factory: 0,
-    instanced: useInstancing
+    instanced: useInstancedAttributes
   });
+  if (useMesh) {
+    const quatArray = new Float32Array(maxParticles * 4);
+    for (let i = 0; i < maxParticles; i++) {
+      quatArray[i * 4 + 3] = 1;
+    }
+    geometry.setAttribute(
+      attr("quat"),
+      new THREE4.InstancedBufferAttribute(quatArray, 4)
+    );
+  }
   const a = geometry.attributes;
   const aIsActive = a[attr("isActive")];
   const aColorR = a[attr("colorR")];
@@ -1610,6 +1919,7 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
   const aRotation = a[attr("rotation")];
   const aLifetime = a[attr("lifetime")];
   const aPosition = a[posAttr];
+  const aQuat = useMesh ? a[attr("quat")] : void 0;
   const deactivateParticle = (particleIndex) => {
     aIsActive.array[particleIndex] = 0;
     aColorA.array[particleIndex] = 0;
@@ -1626,6 +1936,18 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     if (generalData.positionHistoryCount) {
       generalData.positionHistoryCount[particleIndex] = 0;
       generalData.positionHistoryIndex[particleIndex] = 0;
+      if (generalData.trailLastSampledPosition) {
+        const lsIdx = particleIndex * 3;
+        generalData.trailLastSampledPosition[lsIdx] = 0;
+        generalData.trailLastSampledPosition[lsIdx + 1] = 0;
+        generalData.trailLastSampledPosition[lsIdx + 2] = 0;
+      }
+      if (generalData.trailPrevNormal) {
+        const nIdx = particleIndex * 3;
+        generalData.trailPrevNormal[nIdx] = 0;
+        generalData.trailPrevNormal[nIdx + 1] = 0;
+        generalData.trailPrevNormal[nIdx + 2] = 0;
+      }
     }
     if (generalData.noise.offsets)
       generalData.noise.offsets[particleIndex] = Math.random() * 100;
@@ -1671,6 +1993,16 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       generalData.normalizedLifetimePercentage
     );
     aRotation.needsUpdate = true;
+    if (aQuat) {
+      const rotZ = aRotation.array[particleIndex];
+      const halfZ = rotZ * 0.5;
+      const qi = particleIndex * 4;
+      aQuat.array[qi] = 0;
+      aQuat.array[qi + 1] = 0;
+      aQuat.array[qi + 2] = Math.sin(halfZ);
+      aQuat.array[qi + 3] = Math.cos(halfZ);
+      aQuat.needsUpdate = true;
+    }
     if (normalizedConfig.rotationOverLifetime.isActive)
       generalData.lifetimeValues.rotationOverLifetime[particleIndex] = THREE4.MathUtils.randFloat(
         normalizedConfig.rotationOverLifetime.min,
@@ -1796,7 +2128,7 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
           },
           renderer: {
             ...subConfig.config.renderer ?? {},
-            rendererType: renderer.rendererType
+            ...subConfig.config.renderer?.rendererType ? {} : renderer.rendererType === "MESH" /* MESH */ || renderer.rendererType === "TRAIL" /* TRAIL */ ? {} : { rendererType: renderer.rendererType }
           },
           ...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
@@ -1881,7 +2213,15 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
         useMap: { value: !!particleMap },
         discardBackgroundColor: { value: renderer.discardBackgroundColor },
         backgroundColor: { value: renderer.backgroundColor },
-        backgroundColorTolerance: { value: renderer.backgroundColorTolerance }
+        backgroundColorTolerance: { value: renderer.backgroundColorTolerance },
+        softParticlesEnabled: { value: softParticlesEnabled },
+        softParticlesIntensity: {
+          value: Math.max(renderer.softParticles?.intensity ?? 1, 1e-3)
+        },
+        sceneDepthTexture: {
+          value: renderer.softParticles?.depthTexture ?? null
+        },
+        cameraNearFar: { value: new THREE4.Vector2(0.1, 1e3) }
       },
       vertexShader: trail_vertex_shader_glsl_default,
       fragmentShader: trail_fragment_shader_glsl_default,
@@ -1896,6 +2236,14 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     const trailCameraPos = new THREE4.Vector3();
     trailMesh.onBeforeRender = (_renderer, _scene, camera) => {
       camera.getWorldPosition(trailCameraPos);
+      if (softParticlesEnabled && camera.isPerspectiveCamera) {
+        const perspCam = camera;
+        const trailUniforms = trailMaterial.uniforms;
+        trailUniforms.cameraNearFar.value.set(
+          perspCam.near,
+          perspCam.far
+        );
+      }
     };
     generalData.trailCameraPosition = trailCameraPos;
     trailWidthCurveFn = getCurveFunctionFromConfig(
@@ -1923,11 +2271,20 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       };
     }
   }
-  let particleSystem = useInstancing ? new THREE4.Mesh(geometry, material) : new THREE4.Points(geometry, material);
-  if (useInstancing) {
-    particleSystem.onBeforeRender = (glRenderer) => {
-      const size = glRenderer.getSize(new THREE4.Vector2());
-      sharedUniforms.viewportHeight.value = size.y * glRenderer.getPixelRatio();
+  let particleSystem = useInstancing || useMesh ? new THREE4.Mesh(geometry, material) : new THREE4.Points(geometry, material);
+  if (useInstancing || softParticlesEnabled) {
+    particleSystem.onBeforeRender = (glRenderer, _scene, camera) => {
+      if (useInstancing) {
+        const size = glRenderer.getSize(new THREE4.Vector2());
+        sharedUniforms.viewportHeight.value = size.y * glRenderer.getPixelRatio();
+      }
+      if (softParticlesEnabled && camera.isPerspectiveCamera) {
+        const perspCam = camera;
+        sharedUniforms.cameraNearFar.value.set(
+          perspCam.near,
+          perspCam.far
+        );
+      }
     };
   }
   if (useTrail && trailMesh) {
@@ -1950,7 +2307,8 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
     colorR: aColorR,
     colorG: aColorG,
     colorB: aColorB,
-    colorA: aColorA
+    colorA: aColorA,
+    ...useMesh ? { quat: aQuat } : {}
   };
   const calculatedCreationTime = now + calculateValue(generalData.particleSystemId, startDelay) * 1e3;
   let wrapper;
@@ -2022,7 +2380,13 @@ var createParticleSystem = (config = DEFAULT_PARTICLE_SYSTEM_CONFIG, externalNow
       trailColorOverTrailFns,
       trailConfig: {
         length: trailConfig.length,
-        width: trailConfig.width
+        width: trailConfig.width,
+        minVertexDistance: trailConfig.minVertexDistance,
+        maxTime: trailConfig.maxTime,
+        smoothing: trailConfig.smoothing,
+        smoothingSubdivisions: trailConfig.smoothingSubdivisions,
+        twistPrevention: trailConfig.twistPrevention,
+        ribbonId: trailConfig.ribbonId
       }
     } : {}
   };
@@ -2284,10 +2648,84 @@ var updateParticleSystemInstance = (props, { now, delta, elapsed }) => {
       particleSystem
     });
   if (props.trailMesh) {
-    updateTrailGeometry(props);
+    updateTrailGeometry(props, now);
   }
 };
-var updateTrailGeometry = (props) => {
+var catmullRom = (out, outIdx, p0x, p0y, p0z, p1x, p1y, p1z, p2x, p2y, p2z, p3x, p3y, p3z, t) => {
+  const t2 = t * t;
+  const t3 = t2 * t;
+  out[outIdx] = 0.5 * (2 * p1x + (-p0x + p2x) * t + (2 * p0x - 5 * p1x + 4 * p2x - p3x) * t2 + (-p0x + 3 * p1x - 3 * p2x + p3x) * t3);
+  out[outIdx + 1] = 0.5 * (2 * p1y + (-p0y + p2y) * t + (2 * p0y - 5 * p1y + 4 * p2y - p3y) * t2 + (-p0y + 3 * p1y - 3 * p2y + p3y) * t3);
+  out[outIdx + 2] = 0.5 * (2 * p1z + (-p0z + p2z) * t + (2 * p0z - 5 * p1z + 4 * p2z - p3z) * t2 + (-p0z + 3 * p1z - 3 * p2z + p3z) * t3);
+};
+var clearTrailVertex = (vIdx, cIdx, aIdx, uvIdx, trailPosArr, trailNextArr, trailHalfWidthArr, trailUVArr, trailAlphaArr, trailColorArr, fallbackX, fallbackY, fallbackZ) => {
+  trailPosArr[vIdx] = fallbackX;
+  trailPosArr[vIdx + 1] = fallbackY;
+  trailPosArr[vIdx + 2] = fallbackZ;
+  trailPosArr[vIdx + 3] = fallbackX;
+  trailPosArr[vIdx + 4] = fallbackY;
+  trailPosArr[vIdx + 5] = fallbackZ;
+  trailNextArr[vIdx] = fallbackX;
+  trailNextArr[vIdx + 1] = fallbackY;
+  trailNextArr[vIdx + 2] = fallbackZ;
+  trailNextArr[vIdx + 3] = fallbackX;
+  trailNextArr[vIdx + 4] = fallbackY;
+  trailNextArr[vIdx + 5] = fallbackZ;
+  trailHalfWidthArr[aIdx] = 0;
+  trailHalfWidthArr[aIdx + 1] = 0;
+  trailUVArr[uvIdx] = 0;
+  trailUVArr[uvIdx + 1] = 0;
+  trailUVArr[uvIdx + 2] = 0;
+  trailUVArr[uvIdx + 3] = 0;
+  trailAlphaArr[aIdx] = 0;
+  trailAlphaArr[aIdx + 1] = 0;
+  trailColorArr[cIdx] = 0;
+  trailColorArr[cIdx + 1] = 0;
+  trailColorArr[cIdx + 2] = 0;
+  trailColorArr[cIdx + 3] = 0;
+  trailColorArr[cIdx + 4] = 0;
+  trailColorArr[cIdx + 5] = 0;
+  trailColorArr[cIdx + 6] = 0;
+  trailColorArr[cIdx + 7] = 0;
+};
+var writeTrailVertex = (vIdx, cIdx, aIdx, uvIdx, hx, hy, hz, nx, ny, nz, halfWidth, t, alpha, fr, fg, fb, ca, trailPosArr, trailNextArr, trailHalfWidthArr, trailUVArr, trailAlphaArr, trailColorArr) => {
+  trailPosArr[vIdx] = hx;
+  trailPosArr[vIdx + 1] = hy;
+  trailPosArr[vIdx + 2] = hz;
+  trailPosArr[vIdx + 3] = hx;
+  trailPosArr[vIdx + 4] = hy;
+  trailPosArr[vIdx + 5] = hz;
+  trailNextArr[vIdx] = nx;
+  trailNextArr[vIdx + 1] = ny;
+  trailNextArr[vIdx + 2] = nz;
+  trailNextArr[vIdx + 3] = nx;
+  trailNextArr[vIdx + 4] = ny;
+  trailNextArr[vIdx + 5] = nz;
+  trailHalfWidthArr[aIdx] = halfWidth;
+  trailHalfWidthArr[aIdx + 1] = halfWidth;
+  trailUVArr[uvIdx] = 0;
+  trailUVArr[uvIdx + 1] = t;
+  trailUVArr[uvIdx + 2] = 1;
+  trailUVArr[uvIdx + 3] = t;
+  trailAlphaArr[aIdx] = alpha;
+  trailAlphaArr[aIdx + 1] = alpha;
+  trailColorArr[cIdx] = fr;
+  trailColorArr[cIdx + 1] = fg;
+  trailColorArr[cIdx + 2] = fb;
+  trailColorArr[cIdx + 3] = ca;
+  trailColorArr[cIdx + 4] = fr;
+  trailColorArr[cIdx + 5] = fg;
+  trailColorArr[cIdx + 6] = fb;
+  trailColorArr[cIdx + 7] = ca;
+};
+var _rawPoints = null;
+var _rawPointsSize = 0;
+var _smoothedPoints = null;
+var _smoothedPointsSize = 0;
+var _ribbonIndices = null;
+var _ribbonIndicesSize = 0;
+var _ribbonCount = 0;
+var updateTrailGeometry = (props, now) => {
   const {
     generalData,
     trailPositionAttr,
@@ -2305,13 +2743,23 @@ var updateTrailGeometry = (props) => {
   const positionHistory = generalData.positionHistory;
   const historyIndex = generalData.positionHistoryIndex;
   const historyCount = generalData.positionHistoryCount;
+  const sampleTimes = generalData.trailSampleTimes;
+  const lastSampledPos = generalData.trailLastSampledPosition;
+  const prevNormal = generalData.trailPrevNormal;
+  const minVertexDist = trailConfig.minVertexDistance;
+  const minVertexDistSq = minVertexDist * minVertexDist;
+  const maxTime = trailConfig.maxTime;
+  const maxTimeMs = maxTime * 1e3;
+  const useSmoothing = trailConfig.smoothing;
+  const subdivisions = trailConfig.smoothingSubdivisions;
+  const useTwistPrevention = trailConfig.twistPrevention;
+  const ribbonId = trailConfig.ribbonId;
   const isActiveArr = ma.isActive.array;
   const positionArr = ma.position.array;
   const colorRArr = ma.colorR.array;
   const colorGArr = ma.colorG.array;
   const colorBArr = ma.colorB.array;
   const colorAArr = ma.colorA.array;
-  ma.size.array;
   const trailPosArr = trailPositionAttr.array;
   const trailAlphaArr = trailAlphaAttr.array;
   const trailColorArr = trailColorAttr.array;
@@ -2322,115 +2770,329 @@ var updateTrailGeometry = (props) => {
   const verticesPerParticle = trailLength * 2;
   const creationTimesLength = generalData.creationTimes.length;
   let hasUpdates = false;
+  const useRibbon = ribbonId !== void 0;
+  let ribbonLeader = -1;
+  if (useRibbon) {
+    if (!_ribbonIndices || _ribbonIndicesSize < creationTimesLength) {
+      _ribbonIndices = new Uint16Array(creationTimesLength);
+      _ribbonIndicesSize = creationTimesLength;
+    }
+    _ribbonCount = 0;
+    for (let i = 0; i < creationTimesLength; i++) {
+      if (isActiveArr[i]) _ribbonIndices[_ribbonCount++] = i;
+    }
+    for (let i = 1; i < _ribbonCount; i++) {
+      const key = _ribbonIndices[i];
+      const keyTime = generalData.creationTimes[key];
+      let j = i - 1;
+      while (j >= 0 && generalData.creationTimes[_ribbonIndices[j]] > keyTime) {
+        _ribbonIndices[j + 1] = _ribbonIndices[j];
+        j--;
+      }
+      _ribbonIndices[j + 1] = key;
+    }
+    if (_ribbonCount > 0) ribbonLeader = _ribbonIndices[0];
+  }
   for (let index = 0; index < creationTimesLength; index++) {
     const vertBase = index * verticesPerParticle;
     if (isActiveArr[index]) {
+      if (useRibbon && _ribbonCount >= 2 && index !== ribbonLeader) {
+        const posIdx2 = index * 3;
+        const px2 = positionArr[posIdx2];
+        const py2 = positionArr[posIdx2 + 1];
+        const pz2 = positionArr[posIdx2 + 2];
+        const histBase = (index * trailLength + historyIndex[index]) * 3;
+        positionHistory[histBase] = px2;
+        positionHistory[histBase + 1] = py2;
+        positionHistory[histBase + 2] = pz2;
+        if (sampleTimes) {
+          sampleTimes[index * trailLength + historyIndex[index]] = now;
+        }
+        historyIndex[index] = (historyIndex[index] + 1) % trailLength;
+        if (historyCount[index] < trailLength) historyCount[index]++;
+        continue;
+      }
       hasUpdates = true;
       const posIdx = index * 3;
       const px = positionArr[posIdx];
       const py = positionArr[posIdx + 1];
       const pz = positionArr[posIdx + 2];
-      const histBase = (index * trailLength + historyIndex[index]) * 3;
-      positionHistory[histBase] = px;
-      positionHistory[histBase + 1] = py;
-      positionHistory[histBase + 2] = pz;
-      historyIndex[index] = (historyIndex[index] + 1) % trailLength;
-      if (historyCount[index] < trailLength) historyCount[index]++;
-      const count = historyCount[index];
+      let shouldSample = true;
+      if (minVertexDist > 0 && lastSampledPos && historyCount[index] > 0) {
+        const lsIdx = index * 3;
+        const dx = px - lastSampledPos[lsIdx];
+        const dy = py - lastSampledPos[lsIdx + 1];
+        const dz = pz - lastSampledPos[lsIdx + 2];
+        if (dx * dx + dy * dy + dz * dz < minVertexDistSq) {
+          shouldSample = false;
+        }
+      }
+      if (shouldSample) {
+        const histBase = (index * trailLength + historyIndex[index]) * 3;
+        positionHistory[histBase] = px;
+        positionHistory[histBase + 1] = py;
+        positionHistory[histBase + 2] = pz;
+        if (sampleTimes) {
+          sampleTimes[index * trailLength + historyIndex[index]] = now;
+        }
+        historyIndex[index] = (historyIndex[index] + 1) % trailLength;
+        if (historyCount[index] < trailLength) historyCount[index]++;
+        if (lastSampledPos) {
+          const lsIdx = index * 3;
+          lastSampledPos[lsIdx] = px;
+          lastSampledPos[lsIdx + 1] = py;
+          lastSampledPos[lsIdx + 2] = pz;
+        }
+      }
+      let rawCount = historyCount[index];
+      let effectiveCount = rawCount;
+      if (maxTime > 0 && sampleTimes && rawCount > 0) {
+        const sampleBase = index * trailLength;
+        effectiveCount = 0;
+        for (let s = 0; s < rawCount; s++) {
+          const sampleSlot = (historyIndex[index] - 1 - s + trailLength * 2) % trailLength;
+          const age = now - sampleTimes[sampleBase + sampleSlot];
+          if (age <= maxTimeMs) {
+            effectiveCount++;
+          } else {
+            break;
+          }
+        }
+      }
+      const count = effectiveCount;
       const ribbonWidth = trailConfig.width;
       const cr = colorRArr[index];
       const cg = colorGArr[index];
       const cb = colorBArr[index];
       const ca = colorAArr[index];
       const ringOff = index * trailLength * 3;
+      const rawPtsSize = count * 3;
+      if (!_rawPoints || _rawPointsSize < rawPtsSize) {
+        _rawPoints = new Float32Array(rawPtsSize);
+        _rawPointsSize = rawPtsSize;
+      }
+      const rawPts = _rawPoints;
+      for (let s = 0; s < count; s++) {
+        const histSlot = (historyIndex[index] - 1 - s + trailLength * 2) % trailLength * 3 + ringOff;
+        rawPts[s * 3] = positionHistory[histSlot];
+        rawPts[s * 3 + 1] = positionHistory[histSlot + 1];
+        rawPts[s * 3 + 2] = positionHistory[histSlot + 2];
+      }
+      let finalPts;
+      let finalCount;
+      if (useSmoothing && count >= 3) {
+        const segmentCount = count - 1;
+        finalCount = segmentCount * subdivisions + 1;
+        const neededSize = finalCount * 3;
+        if (!_smoothedPoints || _smoothedPointsSize < neededSize) {
+          _smoothedPoints = new Float32Array(neededSize);
+          _smoothedPointsSize = neededSize;
+        }
+        finalPts = _smoothedPoints;
+        for (let seg = 0; seg < segmentCount; seg++) {
+          const i0 = Math.max(0, seg - 1);
+          const i1 = seg;
+          const i2 = Math.min(count - 1, seg + 1);
+          const i3 = Math.min(count - 1, seg + 2);
+          const p0x = rawPts[i0 * 3], p0y = rawPts[i0 * 3 + 1], p0z = rawPts[i0 * 3 + 2];
+          const p1x = rawPts[i1 * 3], p1y = rawPts[i1 * 3 + 1], p1z = rawPts[i1 * 3 + 2];
+          const p2x = rawPts[i2 * 3], p2y = rawPts[i2 * 3 + 1], p2z = rawPts[i2 * 3 + 2];
+          const p3x = rawPts[i3 * 3], p3y = rawPts[i3 * 3 + 1], p3z = rawPts[i3 * 3 + 2];
+          for (let sub = 0; sub < subdivisions; sub++) {
+            const t = sub / subdivisions;
+            const outIdx = (seg * subdivisions + sub) * 3;
+            catmullRom(
+              finalPts,
+              outIdx,
+              p0x,
+              p0y,
+              p0z,
+              p1x,
+              p1y,
+              p1z,
+              p2x,
+              p2y,
+              p2z,
+              p3x,
+              p3y,
+              p3z,
+              t
+            );
+          }
+        }
+        const lastOutIdx = (finalCount - 1) * 3;
+        finalPts[lastOutIdx] = rawPts[(count - 1) * 3];
+        finalPts[lastOutIdx + 1] = rawPts[(count - 1) * 3 + 1];
+        finalPts[lastOutIdx + 2] = rawPts[(count - 1) * 3 + 2];
+      } else {
+        finalPts = rawPts;
+        finalCount = count;
+      }
+      if (finalCount > trailLength) finalCount = trailLength;
+      if (useSmoothing && finalCount >= 2) {
+        const MIN_SEG_DIST_SQ = 1e-4 * 1e-4;
+        for (let d = 1; d < finalCount; d++) {
+          const pi = (d - 1) * 3;
+          const ci = d * 3;
+          const dx = finalPts[ci] - finalPts[pi];
+          const dy = finalPts[ci + 1] - finalPts[pi + 1];
+          const dz = finalPts[ci + 2] - finalPts[pi + 2];
+          if (dx * dx + dy * dy + dz * dz < MIN_SEG_DIST_SQ) {
+            finalPts[ci] = finalPts[pi];
+            finalPts[ci + 1] = finalPts[pi + 1];
+            finalPts[ci + 2] = finalPts[pi + 2];
+          }
+        }
+      }
       for (let s = 0; s < trailLength; s++) {
         const vIdx = (vertBase + s * 2) * 3;
         const cIdx = (vertBase + s * 2) * 4;
         const aIdx = vertBase + s * 2;
-        if (s >= count) {
-          trailPosArr[vIdx] = px;
-          trailPosArr[vIdx + 1] = py;
-          trailPosArr[vIdx + 2] = pz;
-          trailPosArr[vIdx + 3] = px;
-          trailPosArr[vIdx + 4] = py;
-          trailPosArr[vIdx + 5] = pz;
-          trailNextArr[vIdx] = px;
-          trailNextArr[vIdx + 1] = py;
-          trailNextArr[vIdx + 2] = pz;
-          trailNextArr[vIdx + 3] = px;
-          trailNextArr[vIdx + 4] = py;
-          trailNextArr[vIdx + 5] = pz;
-          trailHalfWidthArr[aIdx] = 0;
-          trailHalfWidthArr[aIdx + 1] = 0;
-          const uvIdx2 = (vertBase + s * 2) * 2;
-          trailUVArr[uvIdx2] = 0;
-          trailUVArr[uvIdx2 + 1] = 0;
-          trailUVArr[uvIdx2 + 2] = 0;
-          trailUVArr[uvIdx2 + 3] = 0;
-          trailAlphaArr[aIdx] = 0;
-          trailAlphaArr[aIdx + 1] = 0;
-          trailColorArr[cIdx] = 0;
-          trailColorArr[cIdx + 1] = 0;
-          trailColorArr[cIdx + 2] = 0;
-          trailColorArr[cIdx + 3] = 0;
-          trailColorArr[cIdx + 4] = 0;
-          trailColorArr[cIdx + 5] = 0;
-          trailColorArr[cIdx + 6] = 0;
-          trailColorArr[cIdx + 7] = 0;
+        const uvIdxBase = (vertBase + s * 2) * 2;
+        if (s >= finalCount) {
+          clearTrailVertex(
+            vIdx,
+            cIdx,
+            aIdx,
+            uvIdxBase,
+            trailPosArr,
+            trailNextArr,
+            trailHalfWidthArr,
+            trailUVArr,
+            trailAlphaArr,
+            trailColorArr,
+            px,
+            py,
+            pz
+          );
           continue;
         }
-        const histIdx = (historyIndex[index] - 1 - s + trailLength * 2) % trailLength * 3 + ringOff;
-        const hx = positionHistory[histIdx];
-        const hy = positionHistory[histIdx + 1];
-        const hz = positionHistory[histIdx + 2];
+        const hx = finalPts[s * 3];
+        const hy = finalPts[s * 3 + 1];
+        const hz = finalPts[s * 3 + 2];
         let nx, ny, nz;
-        if (s < count - 1) {
-          const ni = (historyIndex[index] - 2 - s + trailLength * 2) % trailLength * 3 + ringOff;
-          nx = positionHistory[ni];
-          ny = positionHistory[ni + 1];
-          nz = positionHistory[ni + 2];
+        if (s > 0 && s < finalCount - 1) {
+          const px2 = finalPts[(s - 1) * 3];
+          const py2 = finalPts[(s - 1) * 3 + 1];
+          const pz2 = finalPts[(s - 1) * 3 + 2];
+          const nx2 = finalPts[(s + 1) * 3];
+          const ny2 = finalPts[(s + 1) * 3 + 1];
+          const nz2 = finalPts[(s + 1) * 3 + 2];
+          const atx = nx2 - px2;
+          const aty = ny2 - py2;
+          const atz = nz2 - pz2;
+          const atLen = Math.sqrt(atx * atx + aty * aty + atz * atz);
+          if (atLen > 1e-4) {
+            nx = hx + atx / atLen;
+            ny = hy + aty / atLen;
+            nz = hz + atz / atLen;
+          } else {
+            nx = finalPts[(s + 1) * 3];
+            ny = finalPts[(s + 1) * 3 + 1];
+            nz = finalPts[(s + 1) * 3 + 2];
+          }
+        } else if (s < finalCount - 1) {
+          nx = finalPts[(s + 1) * 3];
+          ny = finalPts[(s + 1) * 3 + 1];
+          nz = finalPts[(s + 1) * 3 + 2];
         } else {
           nx = hx;
           ny = hy + 1e-3;
           nz = hz;
         }
-        const t = count > 1 ? s / (count - 1) : 0;
+        const t = finalCount > 1 ? s / (finalCount - 1) : 0;
+        let timeFade = 1;
+        if (maxTime > 0 && sampleTimes && effectiveCount > 0) {
+          const rawS = useSmoothing ? Math.min(
+            Math.floor(s / Math.max(finalCount - 1, 1) * (rawCount - 1)),
+            rawCount - 1
+          ) : Math.min(s, rawCount - 1);
+          const sampleSlot = (historyIndex[index] - 1 - rawS + trailLength * 2) % trailLength;
+          const sampleBase = index * trailLength;
+          const age = now - sampleTimes[sampleBase + sampleSlot];
+          timeFade = 1 - Math.min(age / maxTimeMs, 1);
+        }
         const widthScale = trailWidthCurveFn(t);
         const opacityScale = trailOpacityCurveFn(t);
         const halfWidth = ribbonWidth * widthScale * 0.5;
-        trailPosArr[vIdx] = hx;
-        trailPosArr[vIdx + 1] = hy;
-        trailPosArr[vIdx + 2] = hz;
-        trailPosArr[vIdx + 3] = hx;
-        trailPosArr[vIdx + 4] = hy;
-        trailPosArr[vIdx + 5] = hz;
-        trailNextArr[vIdx] = nx;
-        trailNextArr[vIdx + 1] = ny;
-        trailNextArr[vIdx + 2] = nz;
-        trailNextArr[vIdx + 3] = nx;
-        trailNextArr[vIdx + 4] = ny;
-        trailNextArr[vIdx + 5] = nz;
-        trailHalfWidthArr[aIdx] = halfWidth;
-        trailHalfWidthArr[aIdx + 1] = halfWidth;
-        const uvIdx = (vertBase + s * 2) * 2;
-        trailUVArr[uvIdx] = 0;
-        trailUVArr[uvIdx + 1] = t;
-        trailUVArr[uvIdx + 2] = 1;
-        trailUVArr[uvIdx + 3] = t;
-        const alpha = ca * opacityScale;
-        trailAlphaArr[aIdx] = alpha;
-        trailAlphaArr[aIdx + 1] = alpha;
+        const alpha = ca * opacityScale * timeFade;
         const fr = trailColorOverTrailFns ? cr * trailColorOverTrailFns.r(t) : cr;
         const fg = trailColorOverTrailFns ? cg * trailColorOverTrailFns.g(t) : cg;
         const fb = trailColorOverTrailFns ? cb * trailColorOverTrailFns.b(t) : cb;
-        trailColorArr[cIdx] = fr;
-        trailColorArr[cIdx + 1] = fg;
-        trailColorArr[cIdx + 2] = fb;
-        trailColorArr[cIdx + 3] = ca;
-        trailColorArr[cIdx + 4] = fr;
-        trailColorArr[cIdx + 5] = fg;
-        trailColorArr[cIdx + 6] = fb;
-        trailColorArr[cIdx + 7] = ca;
+        writeTrailVertex(
+          vIdx,
+          cIdx,
+          aIdx,
+          uvIdxBase,
+          hx,
+          hy,
+          hz,
+          nx,
+          ny,
+          nz,
+          halfWidth,
+          t,
+          alpha,
+          fr,
+          fg,
+          fb,
+          ca,
+          trailPosArr,
+          trailNextArr,
+          trailHalfWidthArr,
+          trailUVArr,
+          trailAlphaArr,
+          trailColorArr
+        );
+      }
+      if (useTwistPrevention && prevNormal && finalCount >= 2) {
+        const nIdx = index * 3;
+        const tx = finalPts[3] - finalPts[0];
+        const ty = finalPts[4] - finalPts[1];
+        const tz = finalPts[5] - finalPts[2];
+        const tLen = Math.sqrt(tx * tx + ty * ty + tz * tz);
+        if (tLen > 1e-4) {
+          const ntx = tx / tLen;
+          const nty = ty / tLen;
+          const ntz = tz / tLen;
+          let upx = 0, upy = 1, upz = 0;
+          const dot = ntx * upx + nty * upy + ntz * upz;
+          if (Math.abs(dot) > 0.999) {
+            upx = 1;
+            upy = 0;
+            upz = 0;
+          }
+          let cnx = nty * upz - ntz * upy;
+          let cny = ntz * upx - ntx * upz;
+          let cnz = ntx * upy - nty * upx;
+          const cnLen = Math.sqrt(cnx * cnx + cny * cny + cnz * cnz);
+          if (cnLen > 1e-4) {
+            cnx /= cnLen;
+            cny /= cnLen;
+            cnz /= cnLen;
+          }
+          const prevNx = prevNormal[nIdx];
+          const prevNy = prevNormal[nIdx + 1];
+          const prevNz = prevNormal[nIdx + 2];
+          const hasPrev = prevNx !== 0 || prevNy !== 0 || prevNz !== 0;
+          if (hasPrev) {
+            const normalDot = cnx * prevNx + cny * prevNy + cnz * prevNz;
+            if (normalDot < 0) {
+              for (let s = 0; s < Math.min(finalCount, trailLength); s++) {
+                const aIdx = vertBase + s * 2;
+                const hw = trailHalfWidthArr[aIdx];
+                trailHalfWidthArr[aIdx] = -hw;
+                trailHalfWidthArr[aIdx + 1] = -hw;
+              }
+              cnx = -cnx;
+              cny = -cny;
+              cnz = -cnz;
+            }
+          }
+          prevNormal[nIdx] = cnx;
+          prevNormal[nIdx + 1] = cny;
+          prevNormal[nIdx + 2] = cnz;
+        }
       }
     } else if (historyCount[index] > 0) {
       hasUpdates = true;
@@ -2440,30 +3102,209 @@ var updateTrailGeometry = (props) => {
         const vIdx = (vertBase + s * 2) * 3;
         const cIdx = (vertBase + s * 2) * 4;
         const aIdx = vertBase + s * 2;
-        trailPosArr[vIdx] = 0;
-        trailPosArr[vIdx + 1] = 0;
-        trailPosArr[vIdx + 2] = 0;
-        trailPosArr[vIdx + 3] = 0;
-        trailPosArr[vIdx + 4] = 0;
-        trailPosArr[vIdx + 5] = 0;
-        trailNextArr[vIdx] = 0;
-        trailNextArr[vIdx + 1] = 0;
-        trailNextArr[vIdx + 2] = 0;
-        trailNextArr[vIdx + 3] = 0;
-        trailNextArr[vIdx + 4] = 0;
-        trailNextArr[vIdx + 5] = 0;
-        trailHalfWidthArr[aIdx] = 0;
-        trailHalfWidthArr[aIdx + 1] = 0;
-        trailAlphaArr[aIdx] = 0;
-        trailAlphaArr[aIdx + 1] = 0;
-        trailColorArr[cIdx] = 0;
-        trailColorArr[cIdx + 1] = 0;
-        trailColorArr[cIdx + 2] = 0;
-        trailColorArr[cIdx + 3] = 0;
-        trailColorArr[cIdx + 4] = 0;
-        trailColorArr[cIdx + 5] = 0;
-        trailColorArr[cIdx + 6] = 0;
-        trailColorArr[cIdx + 7] = 0;
+        const uvIdxBase = (vertBase + s * 2) * 2;
+        clearTrailVertex(
+          vIdx,
+          cIdx,
+          aIdx,
+          uvIdxBase,
+          trailPosArr,
+          trailNextArr,
+          trailHalfWidthArr,
+          trailUVArr,
+          trailAlphaArr,
+          trailColorArr,
+          0,
+          0,
+          0
+        );
+      }
+    }
+  }
+  if (useRibbon && _ribbonCount >= 2 && _ribbonIndices) {
+    hasUpdates = true;
+    const leader = _ribbonIndices[0];
+    const leaderVertBase = leader * verticesPerParticle;
+    const controlCount = _ribbonCount;
+    const filledCount = Math.min(
+      trailLength,
+      Math.max(controlCount * 4, controlCount)
+    );
+    const chainSize = filledCount * 3;
+    if (!_rawPoints || _rawPointsSize < chainSize) {
+      _rawPoints = new Float32Array(chainSize);
+      _rawPointsSize = chainSize;
+    }
+    if (controlCount === 2) {
+      const p0Idx = _ribbonIndices[0] * 3;
+      const p1Idx = _ribbonIndices[1] * 3;
+      for (let i = 0; i < filledCount; i++) {
+        const t = i / (filledCount - 1);
+        _rawPoints[i * 3] = positionArr[p0Idx] + t * (positionArr[p1Idx] - positionArr[p0Idx]);
+        _rawPoints[i * 3 + 1] = positionArr[p0Idx + 1] + t * (positionArr[p1Idx + 1] - positionArr[p0Idx + 1]);
+        _rawPoints[i * 3 + 2] = positionArr[p0Idx + 2] + t * (positionArr[p1Idx + 2] - positionArr[p0Idx + 2]);
+      }
+    } else {
+      const segments = controlCount - 1;
+      const ptsPerSeg = Math.max(1, Math.floor((filledCount - 1) / segments));
+      let wi = 0;
+      for (let seg = 0; seg < segments && wi < filledCount; seg++) {
+        const i0 = Math.max(0, seg - 1);
+        const i1 = seg;
+        const i2 = Math.min(controlCount - 1, seg + 1);
+        const i3 = Math.min(controlCount - 1, seg + 2);
+        const p0i = _ribbonIndices[i0] * 3;
+        const p1i = _ribbonIndices[i1] * 3;
+        const p2i = _ribbonIndices[i2] * 3;
+        const p3i = _ribbonIndices[i3] * 3;
+        const subCount = seg === segments - 1 ? filledCount - wi : ptsPerSeg;
+        for (let sub = 0; sub < subCount && wi < filledCount; sub++) {
+          const t = sub / subCount;
+          catmullRom(
+            _rawPoints,
+            wi * 3,
+            positionArr[p0i],
+            positionArr[p0i + 1],
+            positionArr[p0i + 2],
+            positionArr[p1i],
+            positionArr[p1i + 1],
+            positionArr[p1i + 2],
+            positionArr[p2i],
+            positionArr[p2i + 1],
+            positionArr[p2i + 2],
+            positionArr[p3i],
+            positionArr[p3i + 1],
+            positionArr[p3i + 2],
+            t
+          );
+          wi++;
+        }
+      }
+      if (wi > 0) {
+        const lastPIdx = _ribbonIndices[controlCount - 1] * 3;
+        _rawPoints[(wi - 1) * 3] = positionArr[lastPIdx];
+        _rawPoints[(wi - 1) * 3 + 1] = positionArr[lastPIdx + 1];
+        _rawPoints[(wi - 1) * 3 + 2] = positionArr[lastPIdx + 2];
+      }
+    }
+    const leaderCr = colorRArr[leader];
+    const leaderCg = colorGArr[leader];
+    const leaderCb = colorBArr[leader];
+    const leaderCa = colorAArr[leader];
+    for (let s = 0; s < trailLength; s++) {
+      const vIdx = (leaderVertBase + s * 2) * 3;
+      const cIdx = (leaderVertBase + s * 2) * 4;
+      const aIdx = leaderVertBase + s * 2;
+      const uvIdxBase = (leaderVertBase + s * 2) * 2;
+      if (s >= filledCount) {
+        clearTrailVertex(
+          vIdx,
+          cIdx,
+          aIdx,
+          uvIdxBase,
+          trailPosArr,
+          trailNextArr,
+          trailHalfWidthArr,
+          trailUVArr,
+          trailAlphaArr,
+          trailColorArr,
+          0,
+          0,
+          0
+        );
+        continue;
+      }
+      const ptIdx = s * 3;
+      const ptx = _rawPoints[ptIdx];
+      const pty = _rawPoints[ptIdx + 1];
+      const ptz = _rawPoints[ptIdx + 2];
+      let nx, ny, nz;
+      if (s > 0 && s < filledCount - 1) {
+        const px2 = _rawPoints[(s - 1) * 3];
+        const py2 = _rawPoints[(s - 1) * 3 + 1];
+        const pz2 = _rawPoints[(s - 1) * 3 + 2];
+        const nx2 = _rawPoints[(s + 1) * 3];
+        const ny2 = _rawPoints[(s + 1) * 3 + 1];
+        const nz2 = _rawPoints[(s + 1) * 3 + 2];
+        const atx = nx2 - px2;
+        const aty = ny2 - py2;
+        const atz = nz2 - pz2;
+        const atLen = Math.sqrt(atx * atx + aty * aty + atz * atz);
+        if (atLen > 1e-4) {
+          nx = ptx + atx / atLen;
+          ny = pty + aty / atLen;
+          nz = ptz + atz / atLen;
+        } else {
+          nx = _rawPoints[(s + 1) * 3];
+          ny = _rawPoints[(s + 1) * 3 + 1];
+          nz = _rawPoints[(s + 1) * 3 + 2];
+        }
+      } else if (s < filledCount - 1) {
+        nx = _rawPoints[(s + 1) * 3];
+        ny = _rawPoints[(s + 1) * 3 + 1];
+        nz = _rawPoints[(s + 1) * 3 + 2];
+      } else {
+        nx = ptx;
+        ny = pty + 1e-3;
+        nz = ptz;
+      }
+      const t = filledCount > 1 ? s / (filledCount - 1) : 0;
+      const widthScale = trailWidthCurveFn(t);
+      const opacityScale = trailOpacityCurveFn(t);
+      const halfWidth = trailConfig.width * widthScale * 0.5;
+      const alpha = leaderCa * opacityScale;
+      const fr = trailColorOverTrailFns ? leaderCr * trailColorOverTrailFns.r(t) : leaderCr;
+      const fg = trailColorOverTrailFns ? leaderCg * trailColorOverTrailFns.g(t) : leaderCg;
+      const fb = trailColorOverTrailFns ? leaderCb * trailColorOverTrailFns.b(t) : leaderCb;
+      writeTrailVertex(
+        vIdx,
+        cIdx,
+        aIdx,
+        uvIdxBase,
+        ptx,
+        pty,
+        ptz,
+        nx,
+        ny,
+        nz,
+        halfWidth,
+        t,
+        alpha,
+        fr,
+        fg,
+        fb,
+        leaderCa,
+        trailPosArr,
+        trailNextArr,
+        trailHalfWidthArr,
+        trailUVArr,
+        trailAlphaArr,
+        trailColorArr
+      );
+    }
+    for (let ri = 1; ri < _ribbonCount; ri++) {
+      const pIdx = _ribbonIndices[ri];
+      const pVertBase = pIdx * verticesPerParticle;
+      for (let s = 0; s < trailLength; s++) {
+        const vIdx = (pVertBase + s * 2) * 3;
+        const cIdx = (pVertBase + s * 2) * 4;
+        const aIdx = pVertBase + s * 2;
+        const uvIdxBase = (pVertBase + s * 2) * 2;
+        clearTrailVertex(
+          vIdx,
+          cIdx,
+          aIdx,
+          uvIdxBase,
+          trailPosArr,
+          trailNextArr,
+          trailHalfWidthArr,
+          trailUVArr,
+          trailAlphaArr,
+          trailColorArr,
+          0,
+          0,
+          0
+        );
       }
     }
   }
@@ -2491,6 +3332,6 @@ var updateParticleSystems = (cycleData) => {
   );
 };
 
-export { CurveFunctionId, EmitFrom, ForceFieldFalloff, ForceFieldType, LifeTimeCurve, RendererType, Shape, SimulationSpace, SubEmitterTrigger, TimeMode, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+export { CurveFunctionId, EmitFrom, ForceFieldFalloff, ForceFieldType, LifeTimeCurve, RendererType, Shape, SimulationSpace, SubEmitterTrigger, TimeMode, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map