@newkrok/three-particles 2.11.2 → 2.13.0

package/README.md

@@ -20,6 +20,8 @@ Particle system for ThreeJS.
 *   Sub-emitters triggered on particle birth or death events.
 *   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.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples

package/dist/index.d.ts

@@ -169,7 +169,34 @@ declare const enum RendererType {
      * and enables batching multiple emitters into fewer draw calls.
      * Recommended for 10 000+ particles or when large on-screen particle sizes are needed.
      */
-    INSTANCED = "INSTANCED"
+    INSTANCED = "INSTANCED",
+    /**
+     * Render each particle as a ribbon trail connecting its current and previous positions.
+     * Each particle stores a configurable number of position history samples, and the
+     * renderer builds a camera-facing triangle-strip ribbon through those samples.
+     *
+     * Trail width and opacity can taper along the ribbon length for effects like
+     * sword slashes, magic missiles, comet tails, and speed lines.
+     *
+     * Configure trail-specific properties via {@link TrailConfig} on the renderer.
+     */
+    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.
@@ -620,6 +647,82 @@ type TextureSheetAnimation = {
     fps?: number;
     startFrame?: Constant | RandomBetweenTwoConstants;
 };
+/**
+ * Configuration for the trail/ribbon renderer.
+ * Controls how particle trails are drawn when using `RendererType.TRAIL`.
+ *
+ * @property length - Number of position history samples per particle (trail segments).
+ *   Higher values produce longer, smoother trails but cost more memory.
+ *   @default 20
+ * @property widthOverTrail - Lifetime curve that controls the ribbon width along its length.
+ *   At 0 the trail head (current position), at 1 the trail tail (oldest position).
+ *   @default constant 1.0
+ * @property opacityOverTrail - Lifetime curve that controls opacity along the trail length.
+ *   @default linear fade from 1 (head) to 0 (tail)
+ *
+ * @example
+ * ```typescript
+ * // Long comet-style trail tapering to nothing
+ * trail: {
+ *   length: 40,
+ *   widthOverTrail: {
+ *     type: LifeTimeCurve.BEZIER,
+ *     scale: 1,
+ *     bezierPoints: [
+ *       { x: 0, y: 1, percentage: 0 },
+ *       { x: 0.5, y: 0.4 },
+ *       { x: 1, y: 0, percentage: 1 },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+type TrailConfig = {
+    /** Number of position history samples per particle. @default 20 */
+    length?: number;
+    /** Base ribbon width in world units. @default 1.0 */
+    width?: number;
+    /** Curve controlling ribbon width from head (0) to tail (1). */
+    widthOverTrail?: LifetimeCurve;
+    /** Curve controlling opacity from head (0) to tail (1). */
+    opacityOverTrail?: LifetimeCurve;
+    /**
+     * Per-channel color multiplier curves along the trail (head=0, tail=1).
+     * Works as multipliers on the particle's current color, same as colorOverLifetime.
+     * To achieve full color transitions, use white startColor.
+     */
+    colorOverTrail?: {
+        isActive: boolean;
+        r: LifetimeCurve;
+        g: LifetimeCurve;
+        b: LifetimeCurve;
+    };
+};
+/**
+ * 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.
  *
@@ -673,6 +776,20 @@ type Renderer = {
      * @default RendererType.POINTS
      */
     rendererType?: RendererType;
+    /**
+     * Trail/ribbon renderer configuration.
+     * Only used when `rendererType` is `RendererType.TRAIL`.
+     *
+     * @see TrailConfig
+     */
+    trail?: TrailConfig;
+    /**
+     * Mesh particle renderer configuration.
+     * Only used when `rendererType` is `RendererType.MESH`.
+     *
+     * @see MeshConfig
+     */
+    mesh?: MeshConfig;
 };
 /**
  * Configuration for noise effects applied to particles in a particle system.
@@ -1482,6 +1599,20 @@ type GeneralData = {
     isEnabled: boolean;
     /** Tracks the state of each burst emission event */
     burstStates?: Array<BurstState>;
+    /**
+     * Circular buffer storing position history for trail renderer.
+     * Each particle has `trailLength` slots of (x, y, z) positions.
+     * Only allocated when `RendererType.TRAIL` is used.
+     */
+    positionHistory?: Float32Array;
+    /** Write index per particle into the circular position history buffer. */
+    positionHistoryIndex?: Uint16Array;
+    /** Number of valid history samples per particle (fills up from 0 to trailLength). */
+    positionHistoryCount?: Uint16Array;
+    /** Trail length (number of history samples per particle). */
+    trailLength?: number;
+    /** Cached camera world position, updated each frame via onBeforeRender for billboard trails. */
+    trailCameraPosition?: THREE.Vector3;
 };
 /** Union of all buffer attribute types Three.js uses in geometry. */
 type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
@@ -1502,6 +1633,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;
@@ -1544,6 +1677,29 @@ type ParticleSystemInstance = {
     onParticleDeath?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
     /** Called when a particle is born to trigger birth sub-emitters */
     onParticleBirth?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
+    /** Trail mesh for RendererType.TRAIL */
+    trailMesh?: THREE.Mesh;
+    /** Trail geometry position attribute */
+    trailPositionAttr?: THREE.BufferAttribute;
+    /** Trail geometry alpha attribute */
+    trailAlphaAttr?: THREE.BufferAttribute;
+    /** Trail geometry color attribute */
+    trailColorAttr?: THREE.BufferAttribute;
+    /** Trail width curve function */
+    trailWidthCurveFn?: CurveFunction;
+    /** Trail opacity curve function */
+    trailOpacityCurveFn?: CurveFunction;
+    /** Trail color-over-trail curve functions (r, g, b multipliers) */
+    trailColorOverTrailFns?: {
+        r: CurveFunction;
+        g: CurveFunction;
+        b: CurveFunction;
+    };
+    /** Trail config (length, width) */
+    trailConfig?: {
+        length: number;
+        width: number;
+    };
 };
 /**
  * Represents a particle system instance, providing methods to control and manage its lifecycle.
@@ -1922,6 +2078,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.
@@ -2036,4 +2199,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 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 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 };