@newkrok/three-particles 2.12.0 → 2.14.0

package/README.md

@@ -21,6 +21,8 @@ Particle system for ThreeJS.
 *   Serialization support for saving and loading particle system configs.
 *   GPU instancing renderer (`RendererType.INSTANCED`) — removes `gl_PointSize` hardware limit, ideal for large particles or high particle counts.
 *   Trail / Ribbon renderer (`RendererType.TRAIL`) — continuous ribbon trails behind particles with configurable width, opacity, and color tapering.
+*   Mesh particle renderer (`RendererType.MESH`) — render each particle as a 3D mesh (debris, gems, coins) using GPU instancing with full 3D rotation and simple directional lighting.
+*   Soft particles — depth-based alpha fade near opaque geometry, eliminating hard intersection lines.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples

package/dist/index.d.ts

@@ -180,7 +180,23 @@ declare const enum RendererType {
      *
      * Configure trail-specific properties via {@link TrailConfig} on the renderer.
      */
-    TRAIL = "TRAIL"
+    TRAIL = "TRAIL",
+    /**
+     * Render each particle as a 3D mesh using GPU instancing (`InstancedBufferGeometry`).
+     * Instead of flat billboard sprites, particles are rendered as real 3D geometry
+     * (e.g., cubes, spheres, tori, or any custom `THREE.BufferGeometry`).
+     *
+     * Key differences from billboard renderers:
+     * - **3D rotation**: Particles rotate in all three axes (quaternion-based).
+     * - **Normals**: Mesh geometry retains normals, enabling basic lighting.
+     * - **Arbitrary geometry**: Any `THREE.BufferGeometry` can be used per particle.
+     *
+     * All existing modifiers (sizeOverLifetime, colorOverLifetime, noise, force fields,
+     * sub-emitters) work with mesh particles.
+     *
+     * Configure mesh-specific properties via {@link MeshConfig} on the renderer.
+     */
+    MESH = "MESH"
 }
 /**
  * Defines how force diminishes with distance from a POINT force field center.
@@ -681,6 +697,84 @@ type TrailConfig = {
         g: LifetimeCurve;
         b: LifetimeCurve;
     };
+    /**
+     * Minimum distance (in world units) a particle must travel before a new
+     * trail sample is recorded. When set, the trail becomes frame-rate
+     * independent — at high FPS the samples are spread further apart in time,
+     * at low FPS they cluster around sharp turns.
+     *
+     * When `0` or `undefined`, a sample is recorded every frame (legacy behavior).
+     * @default 0
+     */
+    minVertexDistance?: number;
+    /**
+     * Maximum trail duration in seconds. Trail segments older than this value
+     * are faded out and expired, regardless of the ring-buffer `length`.
+     * This enables time-based trail length (e.g. "2-second trails") in addition
+     * to the segment-count cap.
+     *
+     * When `0` or `undefined`, trail length is governed only by `length`.
+     * @default 0
+     */
+    maxTime?: number;
+    /**
+     * Enable Catmull-Rom spline interpolation between history samples.
+     * Inserts additional subdivided points between raw samples, eliminating
+     * sharp kinks at trail bends. The `smoothingSubdivisions` property controls
+     * how many extra points are inserted per segment.
+     *
+     * @default false
+     */
+    smoothing?: boolean;
+    /**
+     * Number of Catmull-Rom subdivisions inserted between each pair of raw
+     * history samples when `smoothing` is enabled. Higher values produce
+     * smoother curves at the cost of more vertices.
+     *
+     * @default 3
+     */
+    smoothingSubdivisions?: number;
+    /**
+     * Enable twist prevention for the ribbon. Uses frame tracking to maintain
+     * consistent ribbon orientation during rapid direction changes, preventing
+     * self-intersecting or flipped ribbon quads.
+     *
+     * @default false
+     */
+    twistPrevention?: boolean;
+    /**
+     * Connect multiple particles into a single continuous ribbon.
+     * All particles that share the same `ribbonId` are sorted by age and
+     * their positions are chained into one continuous strip.
+     *
+     * When `undefined`, each particle has its own independent trail (default behavior).
+     */
+    ribbonId?: number;
+};
+/**
+ * Configuration for the mesh particle renderer.
+ * Controls which 3D geometry is used when `rendererType` is `RendererType.MESH`.
+ *
+ * @property geometry - A `THREE.BufferGeometry` to render for each particle.
+ *   Built-in Three.js primitives like `BoxGeometry`, `SphereGeometry`, `TorusGeometry`
+ *   all work. The geometry's own normals and UVs are preserved.
+ *
+ * @example
+ * ```typescript
+ * // Cube mesh particles
+ * mesh: {
+ *   geometry: new THREE.BoxGeometry(1, 1, 1),
+ * }
+ *
+ * // Icosahedron mesh particles
+ * mesh: {
+ *   geometry: new THREE.IcosahedronGeometry(0.5, 0),
+ * }
+ * ```
+ */
+type MeshConfig = {
+    /** The geometry to render for each particle. */
+    geometry: THREE.BufferGeometry;
 };
 /**
  * Configuration for the particle system renderer, controlling blending, transparency, depth, and background color behavior.
@@ -742,6 +836,60 @@ type Renderer = {
      * @see TrailConfig
      */
     trail?: TrailConfig;
+    /**
+     * Mesh particle renderer configuration.
+     * Only used when `rendererType` is `RendererType.MESH`.
+     *
+     * @see MeshConfig
+     */
+    mesh?: MeshConfig;
+    /**
+     * Soft particles configuration.
+     * When enabled, particles fade smoothly near opaque geometry instead of
+     * producing a hard intersection line. Requires a depth texture from a
+     * `WebGLRenderTarget`.
+     *
+     * @see SoftParticlesConfig
+     */
+    softParticles?: SoftParticlesConfig;
+};
+/**
+ * Configuration for soft (depth-faded) particles.
+ * When enabled, particles fade out smoothly near opaque geometry instead
+ * of producing a hard intersection line.
+ *
+ * Requires a depth texture from a `WebGLRenderTarget` with `DepthTexture`.
+ * If `depthTexture` is not provided, soft particles are automatically disabled
+ * regardless of the `enabled` flag.
+ *
+ * @property enabled - Whether soft particle fading is active. @default false
+ * @property intensity - Controls the fade distance in world units. Higher values
+ *   produce a wider fade zone. Typical range: 0.1 to 5.0. @default 1.0
+ * @property depthTexture - A `THREE.DepthTexture` attached to the render target
+ *   that contains the scene's depth pass. Must be updated every frame before
+ *   the particle system renders.
+ *
+ * @example
+ * // Create a render target with a depth texture
+ * const rt = new THREE.WebGLRenderTarget(width, height, {
+ *   depthTexture: new THREE.DepthTexture(width, height),
+ * });
+ *
+ * // Pass it to the particle system config
+ * const config = {
+ *   renderer: {
+ *     softParticles: {
+ *       enabled: true,
+ *       intensity: 1.5,
+ *       depthTexture: rt.depthTexture,
+ *     },
+ *   },
+ * };
+ */
+type SoftParticlesConfig = {
+    enabled?: boolean;
+    intensity?: number;
+    depthTexture?: THREE.DepthTexture;
 };
 /**
  * Configuration for noise effects applied to particles in a particle system.
@@ -1565,6 +1713,22 @@ type GeneralData = {
     trailLength?: number;
     /** Cached camera world position, updated each frame via onBeforeRender for billboard trails. */
     trailCameraPosition?: THREE.Vector3;
+    /**
+     * Timestamp (in ms) when each trail history sample was recorded.
+     * Used by `maxTime` to expire old segments.
+     * Layout: `maxParticles * trailLength` entries.
+     */
+    trailSampleTimes?: Float64Array;
+    /**
+     * Last recorded position per particle for adaptive sampling (`minVertexDistance`).
+     * Layout: `maxParticles * 3` (x, y, z).
+     */
+    trailLastSampledPosition?: Float32Array;
+    /**
+     * Per-particle previous ribbon normal vector for twist prevention.
+     * Layout: `maxParticles * 3` (nx, ny, nz).
+     */
+    trailPrevNormal?: Float32Array;
 };
 /** Union of all buffer attribute types Three.js uses in geometry. */
 type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
@@ -1585,6 +1749,8 @@ type MappedAttributes = {
     colorG: AnyBufferAttribute;
     colorB: AnyBufferAttribute;
     colorA: AnyBufferAttribute;
+    /** Packed quaternion vec4 for 3D mesh rotation (only present for RendererType.MESH). */
+    quat?: AnyBufferAttribute;
 };
 type ParticleSystemInstance = {
     particleSystem: THREE.Points | THREE.Mesh;
@@ -1645,10 +1811,16 @@ type ParticleSystemInstance = {
         g: CurveFunction;
         b: CurveFunction;
     };
-    /** Trail config (length, width) */
+    /** Trail config (length, width, and advanced features) */
     trailConfig?: {
         length: number;
         width: number;
+        minVertexDistance: number;
+        maxTime: number;
+        smoothing: boolean;
+        smoothingSubdivisions: number;
+        twistPrevention: boolean;
+        ribbonId?: number;
     };
 };
 /**
@@ -2028,6 +2200,13 @@ declare const calculateRandomPositionAndVelocityOnRectangle: (position: THREE.Ve
     rotation: Point3D;
     scale: Point3D;
 }) => void;
+/**
+ * Creates a solid white 1x1 texture for mesh particles.
+ * Unlike the circle texture used by point/billboard renderers, mesh particles
+ * need a neutral texture so the geometry shape is visible.
+ * @returns {THREE.CanvasTexture | null} The generated texture or null if context fails.
+ */
+declare const createDefaultMeshTexture: () => THREE.CanvasTexture | null;
 /**
  * Creates a default white circle texture using CanvasTexture.
  * @returns {THREE.CanvasTexture | null} The generated texture or null if context fails.
@@ -2142,4 +2321,4 @@ declare const getDefaultParticleSystemConfig: () => any;
 declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
 declare const updateParticleSystems: (cycleData: CycleData) => void;
 
-export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, Shape, type ShapeConfig, SimulationSpace, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MeshConfig, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, Shape, type ShapeConfig, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };