custom-pixi-particles 4.34.0 → 4.36.0

package/README.md

@@ -9,12 +9,15 @@
 - [Installation](#️-installation)
 - [Quick Start](#-quick-start)
 - [API Reference](#-api-reference)
+  - [Textures: static, animated, and mixed](#textures-static-animated-and-mixed)
 - [Configuration Guide](#-configuration-guide)
   - [Emission Types](#emission-types)
   - [Behaviours](#behaviours)
 - [Examples](#-examples)
 - [Performance Tips](#-performance-tips)
 - [Troubleshooting](#-troubleshooting)
+- [Common Use Cases](#-common-use-cases)
+- [Best Practices](#-best-practices)
 - [Special Effects](#special-effects)
   - [Shatter Effect](#shatter-effect)
   - [Dissolve Effect](#dissolve-effect)
@@ -22,8 +25,15 @@
   - [Ghost Effect](#ghost-effect)
   - [Glitch Effect](#glitch-effect)
   - [Melt Effect](#melt-effect)
+  - [Pixel Sort Effect](#pixel-sort-effect)
+  - [Prism Refraction Effect](#prism-refraction-effect)
+  - [Crystallize Effect](#crystallize-effect)
+  - [Slit-Scan Effect](#slit-scan-effect)
+  - [Granular Erosion Effect](#granular-erosion-effect)
+  - [Liquid Mercury Effect](#liquid-mercury-effect)
 - [Versions Compatibility](#️-versions-compatibility)
 - [Advanced Editor](#️-advanced-editor)
+- [License](#-license)
 - [Contributing](#-contributing)
 
 ---
@@ -39,8 +49,9 @@ If you find **custom-pixi-particles** useful and would like to support my work,
 - **Simple API**: Effortlessly create particle emitters with minimal code.
 - **Highly Configurable**: Adjust particle behavior, appearance, animation, and more.
 - **Performance Optimized**: Handle thousands of particles with minimal performance overhead.
-- **PIXI.js Compatibility**: Fully compatible with **PIXI.js v8**, **PIXI.js v7**, with legacy support for v5.x and v6.x.
+- **PIXI.js Compatibility**: Current releases target **PIXI.js v8**. For legacy **v5/v6** projects, use `custom-pixi-particles@4.x`.
 - **Real-Time Customization**: Dynamically update textures, positions, configurations, and emitters on the fly.
+- **Static and animated textures**: Use single-frame textures, frame sequences (`prefix00.png`, `prefix01.png`, …), or **mix both** per particle via `textureVariants` and optional `variantWeights`.
 - **Shatter Effect**: Create dramatic sprite shattering effects with realistic physics and automatic cleanup.
 
 ---
@@ -58,17 +69,25 @@ Install via npm:
 npm install custom-pixi-particles
 ```
 
-**Peer dependency:** This library requires **PIXI.js** (or **pixi.js-legacy**). Install the version compatible with your project:
+This package targets modern PixiJS and includes `pixi.js` in its dependencies by default.
+For legacy PixiJS v5/v6 compatibility, use `custom-pixi-particles@4.x` with `pixi.js-legacy`.
 
 ```bash
-# For PIXI.js v8
-npm install pixi.js
+# For PIXI.js v8 (current)
+npm install custom-pixi-particles pixi.js
 
-# For PIXI.js v7
-npm install pixi.js
+# For PIXI.js v5/v6 (legacy line)
+npm install custom-pixi-particles@4 pixi.js-legacy
+```
+
+If you need prebuilt browser bundles from this repo, run:
 
-# For PIXI.js v5/v6 (legacy)
-npm install pixi.js-legacy
+```bash
+npm run build
+npm run build:browser:v8
+# optional:
+# npm run build:browser:v7
+# npm run build:browser:v6
 ```
 
 ---
@@ -77,17 +96,22 @@ npm install pixi.js-legacy
 
 ### Import or Require
 ```javascript
-// ES6 Modules
-import customPixiParticles from 'custom-pixi-particles'
+// ES modules
+import { customPixiParticles } from 'custom-pixi-particles'
 
 // CommonJS
-const customPixiParticles = require('custom-pixi-particles')
+const { customPixiParticles } = require('custom-pixi-particles')
+```
+
+You can also import Pixi helpers directly from this package:
+```javascript
+import { Application, Assets } from 'custom-pixi-particles'
 ```
 
 ### Basic Example
 ```javascript
 import { Application } from 'pixi.js'
-import customPixiParticles from 'custom-pixi-particles'
+import { customPixiParticles } from 'custom-pixi-particles'
 
 // Create PIXI application
 const app = new Application()
@@ -172,7 +196,7 @@ Initializes a particle emitter with the specified configuration.
 
 ```javascript
 const particles = customPixiParticles.create({
-  textures: [String],             // Array of particle texture paths or PIXI.Texture objects
+  textures: [String],             // Array of particle texture paths
   emitterConfig: Object,          // Configuration object for the emitter (see Configuration section)
   animatedSpriteZeroPad: Number,  // Zero-padding for animated sprite names (default: 2)
   animatedSpriteIndexToStart: Number, // Initial frame index for animated sprites (default: 0)
@@ -186,9 +210,13 @@ const particles = customPixiParticles.create({
   maxFPS: Number,                 // Cap emitter update frequency (default: 60)
   minFPS: Number,                 // Minimum FPS threshold (default: 30)
   tickerSpeed: Number,            // Speed of the PIXI ticker (default: 0.02)
+  particleLinks: Object,          // Optional proximity-line mesh between particles
+  canvasSizeProvider: Function,   // Optional callback returning { width, height } for canvas-aware bounds
 })
 ```
 
+`create(...)` returns a `Renderer`.
+
 ### Configuration Object Structure
 
 The `emitterConfig` object contains all the settings for your particle system:
@@ -208,14 +236,79 @@ const emitterConfig = {
   duration: -1,                   // Emitter duration in seconds (-1 = infinite)
   alpha: 1,                       // Global alpha (0-1)
   blendMode: 0,                   // PIXI.js blend mode
+  anchor: { x: 0.5, y: 0.5 },    // Particle anchor point (default: center)
   
   // Behaviours Array
   behaviours: [
     // See Behaviours section for details
   ],
+
+  // Optional — see "Textures: static, animated, and mixed" below
+  // animatedSprite: { enabled: true, frameRate: 0.25, loop: true, randomFrameStart: false },
+  // textureVariants: [ /* mix static + animated */ ],
+  // variantWeights: [0.5, 0.5],
 }
 ```
 
+### Textures: static, animated, and mixed
+
+Particle visuals come from the `textures` array you pass to `customPixiParticles.create({ textures, emitterConfig, ... })` **plus** texture-related fields on **`emitterConfig`**. All asset keys must be loaded with Pixi’s **`Assets`** (or equivalent) before particles spawn.
+
+#### 1. Static textures only (default)
+
+If animated sprites are **not** enabled, each entry in `textures` is treated as a **full texture id** (e.g. `'spark.png'`). Each new particle picks one at random.
+
+```javascript
+const textures = ['a.png', 'b.png', 'c.png']
+// emitterConfig without animatedSprite.enabled / without textureVariants
+```
+
+#### 2. Animated sprites (legacy mode, all entries are sequences)
+
+Set **`emitterConfig.animatedSprite.enabled: true`**. Then each string in `textures` is a **filename prefix** (no extension). The renderer loads consecutive frames:
+
+`{prefix}{index}.png` — e.g. `fire00.png`, `fire01.png`, … until a frame is missing.
+
+- **Padding**: use `animatedSpriteZeroPad` / `animatedSpriteIndexToStart` on `create({ ... })` (defaults: pad `2`, start index `0`). Per-sequence overrides exist on each `frames` variant when using `textureVariants` (below).
+- **Playback**: `emitterConfig.animatedSprite` typically includes `frameRate`, `loop`, and optional `randomFrameStart` (see the live editor’s General → Animated sprite for the exact shape your JSON uses).
+
+```javascript
+customPixiParticles.create({
+  textures: ['explosion_', 'smoke_'], // two different frame sequences
+  animatedSpriteZeroPad: 2,
+  emitterConfig: {
+    animatedSprite: { enabled: true, frameRate: 0.25, loop: true },
+    // ...behaviours, emitController, etc.
+  },
+})
+```
+
+#### 3. Mix static and animated (`textureVariants`)
+
+For **some particles static and some animated**, set a non-empty **`emitterConfig.textureVariants`** array. Each item is either:
+
+| Type | Meaning |
+|------|--------|
+| `{ type: 'staticRandom', textures: ['x.png', 'y.png'] }` | Pick one static texture at random for that variant. |
+| `{ type: 'frames', prefix: 'boom_', frameRate?, loop?, randomFrameStart?, animatedSpriteZeroPad?, animatedSpriteIndexToStart? }` | Load `boom_00.png`, `boom_01.png`, … (PNG, same rules as legacy animated). |
+
+Optional **`emitterConfig.variantWeights`**: same length as `textureVariants`, relative probabilities (normalized internally). If omitted, variants are equally likely.
+
+```javascript
+emitterConfig: {
+  textureVariants: [
+    { type: 'staticRandom', textures: ['spark.png', 'glow.png'] },
+    { type: 'frames', prefix: 'fire_', frameRate: 0.3, loop: true },
+  ],
+  variantWeights: [0.6, 0.4], // 60% static pool, 40% fire_ sequence
+  // ...
+}
+```
+
+When `textureVariants` is set, it **replaces** the simple “all static” / “all prefixes” derivation from `textures` alone. You still pass `textures` to `create()` for updates like `setTextures` / defaults where the code falls back to the legacy list.
+
+**Note:** `finishingTextures` apply to **static** particles when a particle enters finishing state; animated display uses `AnimatedSprite` and does not swap to finishing textures the same way.
+
 ### Event Callbacks
 Triggered when the particle animation completes.
 ```javascript
@@ -233,14 +326,23 @@ particles.setTextures(['texture3.png', 'texture4.png'])
 ### Configuration Updates
 Dynamically update emitter configurations.
 ```javascript
-particles.updateConfig({ /* New configuration properties */ })
+particles.updateConfig({ /* New configuration properties */ }, resetDuration = false)
 ```
+`resetDuration` — when `true`, resets the emitter duration timer.
 
 ### State Control
-Starts or resumes the emitter.
+Starts the emitter and turbulence emitter (when applicable).
+```javascript
+particles.start()
+```
+Starts or resumes emission.
 ```javascript
 particles.play()
 ```
+Resumes after pause.
+```javascript
+particles.resume()
+```
 Toggles the paused state.
 ```javascript
 particles.pause(isPaused)
@@ -257,12 +359,25 @@ Resets the emitter to its initial state.
 ```javascript
 particles.resetEmitter()
 ```
+Sets the PIXI ticker speed multiplier (affects animation speed).
+```javascript
+particles.setTickerSpeed(0.02)
+```
+Refreshes the particle texture (e.g. after changing texture source).
+```javascript
+particles.updateTexture()
+```
+Updates particle-link settings at runtime.
+```javascript
+particles.setParticleLinks({ enabled: true, maxDistance: 100 })
+```
 
 ### Position Updates
 Dynamically adjust the emitter's position.
 ```javascript
-particles.updatePosition({ x: 100, y: 200 })
+particles.updatePosition({ x: 100, y: 200 }, resetDuration = true)
 ```
+`resetDuration` — when `true`, resets the emitter duration timer.
 
 ### Pool Management
 Clears internal object pools to free memory.
@@ -309,7 +424,7 @@ app.stage.addChild(shatterEffect)
 // Trigger explosion with optional completion callback
 shatterEffect.Explode().then(() => {
   console.log("Boom! Animation complete.");
-  effect.destroy();
+  shatterEffect.destroy();
 });
 
 // Or Simple Usage (Static Method)
@@ -519,6 +634,210 @@ meltEffect.melt().then(() => {
 - `reset()` - Resets the effect to its initial state.
 - `destroy()` - Destroys the effect and cleans up all resources.
 
+### Pixel Sort Effect
+Creates a glitch-art style distortion by sorting pixels within rows or columns by luminance, hue, saturation, or RGB channel. Pixels within a threshold range are reordered, producing characteristic stretchy bands.
+
+```javascript
+import { PixelSortEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const pixelSortEffect = new PixelSortEffect(sprite, {
+  direction: 'horizontal',        // 'horizontal' | 'vertical' (default: 'horizontal')
+  sortMode: 'luminance',         // 'luminance' | 'hue' | 'saturation' | 'red' | 'green' | 'blue' (default: 'luminance')
+  sortOrder: 'ascending',        // 'ascending' | 'descending' (default: 'ascending')
+  thresholdLow: 0.2,             // 0-1, min key to sort (default: 0.2)
+  thresholdHigh: 0.8,            // 0-1, max key to sort (default: 0.8)
+  duration: 1.5,                 // Effect duration in seconds (default: 1.5)
+  refreshRate: 0.016,            // How often to refresh the effect (default: 0.016)
+  rowStep: 1,                    // Process every Nth row for performance (default: 1)
+  intensity: 1                   // 0-1, fraction of line affected (default: 1)
+})
+
+app.stage.addChild(pixelSortEffect)
+
+pixelSortEffect.play().then(() => {
+  console.log("Pixel sort complete!")
+  pixelSortEffect.destroy()
+})
+```
+
+**PixelSortEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
+### Prism Refraction Effect
+Creates a holographic prism effect with chromatic dispersion—RGB channels are offset to produce rainbow fringing and a spectral/hologram feel.
+
+```javascript
+import { PrismRefractionEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const prismEffect = new PrismRefractionEffect(sprite, {
+  dispersionStrength: 8,         // Pixels of R/B offset (default: 8)
+  dispersionAngle: 0,            // Radians, 0 = horizontal (default: 0)
+  duration: 1.5,                 // Effect duration (default: 1.5)
+  scanSpeed: 0,                  // Optional scan line speed, 0 = no scan (default: 0)
+  fresnelPower: 0                // 0 = no fresnel, higher = edge-only (default: 0)
+})
+
+app.stage.addChild(prismEffect)
+
+prismEffect.play().then(() => {
+  console.log("Prism effect complete!")
+  prismEffect.destroy()
+})
+```
+
+**PrismRefractionEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
+### Crystallize Effect
+Transforms sprites into crystal/gem-like facets using Voronoi-style cells. Each cell gets an averaged color with optional facet highlights and tint variation.
+
+```javascript
+import { CrystallizeEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const crystallizeEffect = new CrystallizeEffect(sprite, {
+  cellScale: 16,                 // Approximate cell size in pixels (default: 16)
+  jitter: 0.5,                   // 0-1, random offset of cell centers (default: 0.5)
+  highlightStrength: 0.3,        // 0-1, facet sheen (default: 0.3)
+  edgeSoftness: 0.2,             // 0-1, smooth cell edges (default: 0.2)
+  tintByCell: false,             // Slight tint variation per cell (default: false)
+  duration: 1                    // Blend from original to crystallize (default: 1)
+})
+
+app.stage.addChild(crystallizeEffect)
+
+crystallizeEffect.play().then(() => {
+  console.log("Crystallize complete!")
+  crystallizeEffect.destroy()
+})
+```
+
+**CrystallizeEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
+### Slit-Scan Effect
+Creates temporal/slit-scan distortion where each row (or column) samples a different offset over time, producing wave-like or ribbon distortion effects.
+
+```javascript
+import { SlitScanEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const slitScanEffect = new SlitScanEffect(sprite, {
+  mode: 'wave',                  // 'wave' | 'slit-scan' (default: 'wave')
+  speed: 2,                      // Phase/offset speed (default: 2)
+  amplitude: 20,                 // Pixel displacement for wave mode (default: 20)
+  frequency: 0.02,               // Rows per wave cycle (default: 0.02)
+  direction: 'horizontal',       // 'horizontal' | 'vertical' (default: 'horizontal')
+  duration: 2                    // Effect duration (default: 2)
+})
+
+app.stage.addChild(slitScanEffect)
+
+slitScanEffect.play().then(() => {
+  console.log("Slit-scan complete!")
+  slitScanEffect.destroy()
+})
+```
+
+**SlitScanEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
+### Granular Erosion Effect
+Simulates granular erosion where the sprite appears to break apart into falling grains with gravity and wind turbulence.
+
+```javascript
+import { GranularErosionEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const erosionEffect = new GranularErosionEffect(sprite, {
+  erosionProgress: 0.5,          // 0-1, how much has broken loose (default: 0.5)
+  gravityScale: 80,              // Vertical fall speed (default: 80)
+  windTurbulence: 15,            // Horizontal sine amplitude (default: 15)
+  grainSize: 0.08,               // Noise frequency, higher = finer grains (default: 0.08)
+  duration: 2                    // Effect duration (default: 2)
+})
+
+app.stage.addChild(erosionEffect)
+
+erosionEffect.play().then(() => {
+  console.log("Erosion complete!")
+  erosionEffect.destroy()
+})
+```
+
+**GranularErosionEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
+### Liquid Mercury Effect
+Creates a liquid metal look with viscosity, reflectivity, and rippling. Sprites appear to morph into blobby mercury-like shapes.
+
+```javascript
+import { LiquidMercuryEffect } from 'custom-pixi-particles'
+import { Sprite, Texture } from 'pixi.js'
+
+const sprite = new Sprite(Texture.from('my-image.png'))
+sprite.anchor.set(0.5, 0.5)
+sprite.x = 400
+sprite.y = 300
+
+const mercuryEffect = new LiquidMercuryEffect(sprite, {
+  viscosity: 0.3,                // 0-1, blur/smooth (default: 0.3)
+  reflectivity: 0.6,             // 0-1, MatCap strength (default: 0.6)
+  rippleSpeed: 2,                // Scroll speed (default: 2)
+  edgeRoundness: 2,              // Smooth-step power for blobby edges (default: 2)
+  duration: 2                    // Effect duration (default: 2)
+})
+
+app.stage.addChild(mercuryEffect)
+
+mercuryEffect.play().then(() => {
+  console.log("Liquid mercury complete!")
+  mercuryEffect.destroy()
+})
+```
+
+**LiquidMercuryEffect Methods:**
+- `play(onComplete?)` - Triggers the effect. Returns a Promise that resolves when complete.
+- `reset()` - Resets the effect to its initial state.
+- `destroy()` - Destroys the effect and cleans up all resources.
+
 ---
 
 ## 📚 Configuration Guide
@@ -602,7 +921,7 @@ particles.emitter.behaviours.add(myCustomBehaviour)
 // New and existing particles will use the new behaviour on the next update
 ```
 
-**Extending built-in behaviours:** All built-in behaviour classes are exported from the package so you can extend any of them: `SpawnBehaviour`, `LifeBehaviour`, `PositionBehaviour`, `ColorBehaviour`, `SizeBehaviour`, `AngularVelocityBehaviour`, `EmitDirectionBehaviour`, `RotationBehaviour`, `TurbulenceBehaviour`, `CollisionBehaviour`, `AttractionRepulsionBehaviour`, `NoiseBasedMotionBehaviour`, `ForceFieldsBehaviour`, `TimelineBehaviour`, `GroupingBehaviour`, `SoundReactiveBehaviour`, `LightEffectBehaviour`, `StretchBehaviour`, `TemperatureBehaviour`, `MoveToPointBehaviour`, `Wireframe3DBehaviour`, `VortexBehaviour`, `PulseBehaviour`, `RippleBehaviour`, `OrbitBehaviour`, `FlickerBehaviour`, `WobbleBehaviour`, `ColorCycleBehaviour`, `ConstrainToShapeBehaviour`, `GravityWellBehaviour`, `TrailBehaviour`, `BounceBehaviour`, `HomingBehaviour`, `FloatUpBehaviour`, `MagnetBehaviour`, `NearMissDispersionBehaviour`, `ConversionCascadeBehaviour`, `BoidsFlockingBehaviour`, `ProximityStateBehaviour`, `PhaseFieldFlowBehaviour`, `PhaseCoherenceBehaviour`, `CurvatureFlowBehaviour`, `LimitCycleBehaviour`, `AizawaAttractorBehaviour`, `ToroidalFlowBehaviour`, `ProximityTriggeredPhaseBehaviour`, `LissajousHarmonicLatticeBehaviour`, `JacobianCurlFieldBehaviour`. Also exported: `Behaviour`, `BehaviourRegistry`, `EmitterBehaviours`, `BehaviourNames`.
+**Extending built-in behaviours:** Core behaviour classes are exported directly from the package (for example `SpawnBehaviour`, `LifeBehaviour`, `PositionBehaviour`, `ColorBehaviour`, `SizeBehaviour`, `FormPatternBehaviour`, `ToroidalWrapBehaviour`, plus `Behaviour`, `BehaviourRegistry`, `EmitterBehaviours`, `BehaviourNames`). Advanced behaviours are available by name in emitter configs/editor presets; if you need class-level inheritance for one that is not exported at top-level, import from the package source in this repo.
 
 **Replacing a built-in behaviour:** Register your class under the same name as a built-in (e.g. `SpawnBehaviour`) **before** creating the renderer or loading config. The registry is checked first, so your implementation is used instead. Use this for customizations like multiple trails on one shape, different trailing logic (e.g. CCV-style), or any variant of spawn/trail/position without changing the library.
 
@@ -696,7 +1015,7 @@ Defines where and how particles spawn. Supports multiple spawn types.
 - `Path` - Custom path defined by points
 - `Oval` - Elliptical distributions
 
-**Additional behaviours** (see the [editor](https://okuniewicz.eu/) for full documentation): Aizawa Attractor, Boids Flocking, Bounce, Color Cycle, Constrain To Shape, Conversion Cascade, Curvature Flow, Flicker, Float Up, Gravity Well, Homing, Jacobian Curl-Field, Lissajous Harmonic Lattice, Limit Cycle, Magnet, Near Miss Dispersion, Orbit, Phase Coherence, Phase Field Flow, Proximity State, Proximity Triggered Phase, Pulse, Ripple, Trail, Toroidal Flow, Vortex, Wobble, SubEmitter.
+**Additional behaviours** (see the [editor](https://okuniewicz.eu/) for full documentation): Aizawa Attractor, Beat Phase Lock, Bezier Flow Tube, Boids Flocking, Bounce, Color Cycle, Constrain To Shape, Conversion Cascade, Curvature Flow, Damage Flash Ripple, Emitter Attractor Link, Flicker, Float Up, Form Pattern, Gravity Well, Homing, Jacobian Curl-Field, Kelvin Wake, Lissajous Harmonic Lattice, Limit Cycle, Magnet, Near Miss Dispersion, Obstacle SDF Steer, Orbit, Phase Coherence, Phase Field Flow, Proximity State, Proximity Triggered Phase, Pulse, Ripple, RVO Avoidance, Screen Space Flow Map, Shear Flow, Toroidal Wrap, Trail, Toroidal Flow, Vortex, Wobble.
 
 #### Size Behaviour
 Controls particle size over time.
@@ -961,60 +1280,6 @@ Moves particles toward specific points.
 }
 ```
 
-#### Wireframe3D Behaviour
-Renders 3D wireframe shapes (cube, sphere, pyramid, torus, cylinder, etc.) with optional orbit, pulsate, path motion, dashed lines, and depth styling. When this behaviour is present, the emitter is wrapped in a container that provides a Graphics object for the wireframe; use it for 3D-style particle backdrops or decorative shapes.
-
-```javascript
-{
-  priority: 50,
-  enabled: true,
-  shapeType: 'cube',           // 'cube' | 'sphere' | 'pyramid' | 'torus' | 'cylinder' | 'tetrahedron' | 'octahedron' | 'grid' | 'lattice' | 'custom'
-  size: 100,
-  rotationSpeedX: 0.5,
-  rotationSpeedY: 0.3,
-  rotationSpeedZ: 0.2,
-  lineColor: 0xffffff,
-  lineWidth: 1,
-  perspective: 400,
-  cameraZ: 500,
-  depthStyle: 'none',          // 'none' | 'fade' | 'thickness' | 'both'
-  sortByDepth: false,
-  orbitEnabled: false,
-  orbitRadius: 50,
-  orbitSpeed: 1,
-  pulsateEnabled: false,
-  pulsateMin: 80,
-  pulsateMax: 120,
-  pulsateSpeed: 2,
-  pathType: 'none',
-  pathSpeed: 1,
-  pathScale: 50,
-  dashedEnabled: false,
-  dashLength: 10,
-  gapLength: 5,
-  colorOverTimeEnabled: false,
-  colorOverTimeSpeed: 1,
-  perVertexColor: false,
-  noiseWobbleEnabled: false,
-  noiseWobbleAmount: 10,
-  noiseWobbleSpeed: 1,
-  attractParticlesEnabled: false,
-  attractStrength: 0,
-  latticeSegmentsX: 4,
-  latticeSegmentsY: 4,
-  latticeSegmentsZ: 4,
-  gridSegments: 4,
-  torusInnerRadius: 0.5,
-  cylinderHeight: 1,
-  customVertices: [],
-  customEdges: [],
-  wireframes: [],
-  name: 'Wireframe3DBehaviour',
-}
-```
-
----
-
 ## 💡 Examples
 
 ### Fire Effect
@@ -1189,6 +1454,14 @@ const textConfig = {
 5. **FPS Capping**: Use `maxFPS` and `minFPS` to control update frequency
 6. **Batch Updates**: Update multiple emitters in a single frame when possible
 7. **Clean Up**: Call `destroy()` and `clearPool()` when done with emitters
+8. **Runtime `behaviour.enabled` toggles**: If you flip `enabled` on an existing behaviour instance without re-running the emitter parser (add/remove), call `emitter.behaviours.invalidateEnabledApplySnapshot()` before particle simulation runs, or rely on the next full `emitter.update()` after toggling in the same frame as other code paths that only call `apply`/`init` without going through `update()`.
+
+### Profiling checklist (Chrome / Chromium)
+
+1. Open **Performance** (or **JavaScript Profiler**), record while your effect runs at target particle count.
+2. In the flame chart, look for **`Emitter.update`**, **`EmitterBehaviours.apply`**, and behaviour names in hot frames.
+3. Confirm **GC** time: high allocation rates often come from per-frame object creation outside this library; spatial grids here use numeric cell keys to avoid string churn on neighbor queries.
+4. Compare **GPU** vs **CPU**: if the bottleneck is upload/draw, reduce `ParticleContainer` feature flags (`rotation`, `tint`, `uvs`) and particle count before micro-optimizing simulation.
 
 ---
 

package/dist/index.d.ts

@@ -1,20 +1,28 @@
 import Renderer from './lib/pixi/Renderer';
+import SpriteContainerRenderer from './lib/pixi/SpriteContainerRenderer';
 import { ICustomPixiParticlesSettings } from './lib/customPixiParticlesSettingsInterface';
 import TestRenderer from './lib/pixi/TestRenderer';
-import { ShatterEffect, DissolveEffect, MagneticAssemblyEffect, GhostEffect, GlitchEffect, MeltEffect, PixelSortEffect, PrismRefractionEffect, CrystallizeEffect, SlitScanEffect, GranularErosionEffect, LiquidMercuryEffect } from './lib/effects';
-export type { IShatterEffectOptions, ShatterMode, IDissolveEffectOptions, DissolveDirection, IMagneticAssemblyOptions, AssemblyMode, IGhostEffectOptions, IGlitchEffectOptions, IMeltEffectOptions, IPixelSortEffectOptions, PixelSortDirection, PixelSortMode, PixelSortOrder, IPrismRefractionEffectOptions, ICrystallizeEffectOptions, ISlitScanEffectOptions, SlitScanMode, IGranularErosionEffectOptions, ILiquidMercuryEffectOptions } from './lib/effects';
+import { CrystallizeEffect, DissolveEffect, GhostEffect, GlitchEffect, GranularErosionEffect, LiquidMercuryEffect, MagneticAssemblyEffect, MetaballPass, MeltEffect, PixelSortEffect, PrismRefractionEffect, ShatterEffect, SlitScanEffect } from './lib/effects';
+export type { IShatterEffectOptions, ShatterMode, IDissolveEffectOptions, DissolveDirection, IMagneticAssemblyOptions, AssemblyMode, IGhostEffectOptions, IGlitchEffectOptions, IMeltEffectOptions, IPixelSortEffectOptions, PixelSortDirection, PixelSortMode, PixelSortOrder, IPrismRefractionEffectOptions, ICrystallizeEffectOptions, ISlitScanEffectOptions, SlitScanMode, IGranularErosionEffectOptions, ILiquidMercuryEffectOptions, IMetaballPassOptions, } from './lib/effects';
 /**
  * Constructs a renderer for custom pixi particles
  * @class Renderer
  * @param {ICustomPixiParticlesSettings} settings The settings for the renderer
  */
 declare const customPixiParticles: {
-    create(settings: ICustomPixiParticlesSettings): any;
+    create(settings: ICustomPixiParticlesSettings): Renderer | SpriteContainerRenderer;
 };
 declare const _customPixiParticlesEditorOnly: {
     create(settings: ICustomPixiParticlesSettings): TestRenderer;
 };
+export type { TextureVariant, TextureVariantFrames, TextureVariantStaticRandom } from './lib/textureVariants';
+export type { IParticleLinkSettings } from './lib/pixi/particleLinkLayer';
+export { drawParticleLinks, mergeParticleLinkSettings, PARTICLE_LINK_DEFAULTS, } from './lib/pixi/particleLinkLayer';
 export type { IBehaviour } from './lib/behaviour';
-export { Behaviour, BehaviourRegistry, EmitterBehaviours, SpawnBehaviour, LifeBehaviour, PositionBehaviour, ColorBehaviour, SizeBehaviour, AngularVelocityBehaviour, EmitDirectionBehaviour, RotationBehaviour, TurbulenceBehaviour, CollisionBehaviour, AttractionRepulsionBehaviour, NoiseBasedMotionBehaviour, ForceFieldsBehaviour, TimelineBehaviour, GroupingBehaviour, SoundReactiveBehaviour, LightEffectBehaviour, StretchBehaviour, TemperatureBehaviour, MoveToPointBehaviour, Wireframe3DBehaviour, BehaviourNames, } from './lib/behaviour';
-export { Application, Loader } from 'pixi.js';
-export { Renderer, customPixiParticles, _customPixiParticlesEditorOnly, ICustomPixiParticlesSettings, ShatterEffect, DissolveEffect, MagneticAssemblyEffect, GhostEffect, GlitchEffect, MeltEffect, PixelSortEffect, PrismRefractionEffect, CrystallizeEffect, SlitScanEffect, GranularErosionEffect, LiquidMercuryEffect, };
+export { Behaviour, BehaviourRegistry, EmitterBehaviours, SpawnBehaviour, LifeBehaviour, PositionBehaviour, ColorBehaviour, SizeBehaviour, AngularVelocityBehaviour, EmitDirectionBehaviour, RotationBehaviour, TurbulenceBehaviour, CollisionBehaviour, AttractionRepulsionBehaviour, NoiseBasedMotionBehaviour, ForceFieldsBehaviour, TimelineBehaviour, GroupingBehaviour, SoundReactiveBehaviour, LightEffectBehaviour, StretchBehaviour, TemperatureBehaviour, MoveToPointBehaviour, FormPatternBehaviour, type FormPatternMode, type FormPatternProgressMode, type FormPatternAssignmentMode, type FormPatternBakedPolylineMode, type FormPatternPathKind, type FormPatternSinePhaseMode, type FormPatternStaggerOrder, type FormPatternPathVarietySeedMode, type FormPatternVisualModulation, ToroidalWrapBehaviour, BehaviourNames, } from './lib/behaviour';
+export { rasterizeTextToPoints, buildPresetShape, matchPointsToCount, resampleToCount, flattenSvgPathToPoints, assignGreedyNearest, assignByPolarAngle, assignHungarian, hungarianMinAssignment, assignHungarianTargetIndices, assignGreedyNearestTargetIndices, assignByPolarAngleTargetIndices, sortTargetIndicesByAngle, blendMorphedPresets, rasterizeOpaquePixelsToPoints, rasterizeOpaquePixelsToPointsWithColors, matchSamplesToCount, sortPointsByAngle, shuffledIndices, seededUnit, extractSvgPathDFromMarkup, parseSvgViewBox, normalizePointsToBounds, replicatePointsByWeights, sampleMorphKeyframes, assignPathOrderTargetIndices, rasterizeOpaquePixelsToPointsWeighted, rasterizeOpaquePixelsToPointsWithColorsWeighted, } from './lib/util/formPatternSampling';
+export type { PresetShapeType, PresetShapeParams, TextRasterMode, RasterizeTextOptions, PointRgb, MorphKeyframe, IParticleXYWithUid, } from './lib/util/formPatternSampling';
+export { PersistentFillEmission } from './lib/emission';
+export { PersistentWrapEmitter } from './lib/emitter';
+export { Application, Loader } from 'pixi.js-legacy';
+export { Renderer, customPixiParticles, _customPixiParticlesEditorOnly, ICustomPixiParticlesSettings, ShatterEffect, DissolveEffect, MagneticAssemblyEffect, GhostEffect, GlitchEffect, MeltEffect, PixelSortEffect, PrismRefractionEffect, CrystallizeEffect, SlitScanEffect, GranularErosionEffect, LiquidMercuryEffect, MetaballPass, };