R3F VFX

https://three-vfx.vercel.app/#/docs
Admin
R3F VFX is a high-performance GPU-accelerated particle system for React Three Fiber that targets...
Tokens:18,156
Snippets:128
Trust Score:7.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install vanilla-vfx Package

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Installs the experimental package for using Three VFX with vanilla Three.js.

```bash
npm install vanilla-vfx
```

--------------------------------

### Install makio-meshline for Trails (npm)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Command to install the 'makio-meshline' library, a peer dependency required for GPU-based trail rendering.

```bash
npm install makio-meshline

```

--------------------------------

### Install threlte-vfx Package

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Installs the experimental package for using Three VFX with Threlte (Svelte).

```bash
npm install threlte-vfx
```

--------------------------------

### Install r3f-vfx Package

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Installs the primary React Three Fiber package for Three VFX and its peer dependencies. Also includes optional installation for trail effects.

```bash
npm install r3f-vfx

# peer dependencies
npm install three @react-three/fiber react react-dom

# optional: trail effects
npm install makio-meshline
```

--------------------------------

### Trail Taper Customization Examples (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates various ways to customize the trail taper effect, from default linear to custom functions for unique visual styles.

```tsx
// Default linear taper (thick at head, thin at tail)
trail={{ taper: true }}


// No tapering (uniform width)
trail={{ taper: false }}


// Custom: fat middle, thin ends
trail={{ taper: (t) => Math.sin(t * Math.PI) }}


// Custom: wavy trail
trail={{ taper: (t) => Math.abs(Math.sin(t * Math.PI * 4)) }}

```

--------------------------------

### Quick Start with Vanilla Three.js

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Shows how to integrate Three VFX into a vanilla Three.js scene. It requires instantiating `VFXParticles` and adding its render object to the scene.

```typescript
import { VFXParticles } from "vanilla-vfx"


const particles = new VFXParticles(renderer, { debug: true })
scene.add(particles.renderObject)
```

--------------------------------

### Quick Start with Threlte (Svelte)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Illustrates the integration of Three VFX into a Threlte (Svelte) project. The `<VFXParticles>` component is placed within the Threlte Canvas.

```svelte
<script>
  import { Canvas } from "@threlte/core"
  import VFXParticles from "threlte-vfx/VFXParticles.svelte"
</script>


<Canvas>
  <VFXParticles debug />
</Canvas>
```

--------------------------------

### Install tres-vfx Package

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Installs the experimental package for integrating Three VFX with TresJS (Vue).

```bash
npm install tres-vfx
```

--------------------------------

### Quick Start with TresJS (Vue)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates using Three VFX within a TresJS (Vue) application. The `<VFXParticles>` component is used directly within the TresCanvas.

```vue
<script setup>
import { TresCanvas } from "@tresjs/core"
import { VFXParticles } from "tres-vfx"
</script>


<template>
  <TresCanvas>
    <VFXParticles debug />
  </TresCanvas>
</template>
```

--------------------------------

### Quick Start with React Three Fiber

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates adding a particle system to a Three.js scene using React Three Fiber. The `debug` prop enables an interactive control panel.

```tsx
import { Canvas } from "@react-three/fiber"
import { VFXParticles } from "r3f-vfx"


function App() {
  return (
    <Canvas>
      <VFXParticles debug />
    </Canvas>
  )
}
```

--------------------------------

### Configure GPU Trails for Particles (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Example of configuring GPU-based trails for VFX particles using the 'trail' prop. Allows customization of segments, width, taper, opacity, and length.

```tsx
<VFXParticles
  name="trails"
  autoStart={false}
  size={[0.001, 0.005]}
  speed={[0.1, 1]}
  lifetime={[0.9, 0.9]}
  gravity={[0, -0.5, 0]}
  intensity={39.6}
  appearance="gradient"
  trail={{
    segments: 64,          // trail resolution (number of line points)
    width: 0.02,
    taper: true,           // taper width from head to tail
    opacity: 1,
    length: 4.09,
    showParticles: false,  // hide the point sprites, show only trails
  }}
/>

```

--------------------------------

### Animated Sprite Sheet (Flipbook) Example (TSX)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Applies an animated sprite sheet (flipbook) to particles using the alphaMap and flipbook configuration. This example demonstrates setting up a 4x4 sprite sheet for particle appearance, controlling size and lifetime.

```tsx
<VFXParticles
  alphaMap={spriteSheetTexture}
  flipbook={{ rows: 4, columns: 4 }}
  size={0.5}
  lifetime={1}
/>
```

--------------------------------

### Define and Use VFXParticles and VFXEmitter Components

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates how to define a particle system using `<VFXParticles />` and attach emitters to scene objects using `<VFXEmitter />`. Includes examples for programmatic control of emitters.

```typescript
import { VFXParticles, VFXEmitter } from "r3f-vfx";

// 1. Define the particle system once
<VFXParticles
  name="dodge"
  autoStart={false}
  maxParticles={100}
  size={[2, 2]}
  colorStart={["#63acff"]}
  fadeOpacity={[0.01, 0]}
  lifetime={[0.3, 0.3]},
  emitterShape={1}
/>

// 2. Attach emitters to scene objects
<group ref={playerRef}>
  <VFXEmitter
    ref={dodgeEmitterRef}
    name="dodge"
    position={[0, 0.1, 0]}
    emitCount={1}
    autoStart={false}
    delay={0}
  />
</group>

// 3. Control programmatically
// dodgeEmitterRef.current?.start();   // begin continuous emission
// dodgeEmitterRef.current?.stop();    // stop emitting
// dodgeEmitterRef.current?.emit();    // single burst
// dodgeEmitterRef.current?.burst(20); // emit N particles once
```

--------------------------------

### VFXParticles Component Configuration

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Example of configuring the core `<VFXParticles>` component with various props for appearance, physics, and emitter settings. This component manages its own GPU buffers and shaders.

```tsx
<VFXParticles
  name="fire"
  maxParticles={10000}
  autoStart={true}


  // Appearance
  size={[0.05, 0.18]}
  colorStart={["#FF711E", "#3d91ff"]}
  colorEnd={["#ff6b3500"]}
  fadeOpacity={[1, 0]}
  fadeSize={[1, 0]}
  appearance="gradient"
  blending={2}
  intensity={40}


  // Physics
  gravity={[0, 0.3, 0]}
  speed={[0, 3]}
  lifetime={[0.5, 1]}
  friction={{ intensity: 0, easing: "linear" }}
  direction={[[-1, 1], [0, 1], [-1, 1]]}


  // Emitter
  emitterShape={2}
  emitterRadius={0.3}
  emitterAngle={0.4}
  emitCount={5}
/>
```

--------------------------------

### Configure 3D Geometry and Lighting in VFXParticles (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates using the VFXParticles component with custom 3D geometry and advanced lighting options. Includes examples for debris with shadows, gem-like particles with physical material, and stretched sparks aligned to velocity.

```jsx
import { BoxGeometry, SphereGeometry } from "three/webgpu"


// 3D debris with shadows
<VFXParticles
  geometry={new BoxGeometry(1, 1, 1)}
  maxParticles={500}
  size={[0.1, 0.2]}
  colorStart={["#ff00ff", "#aa00ff"]}
  gravity={[0, -2, 0]}
  lifetime={[1, 2]}
  rotation={[
    [0, Math.PI * 2],
    [0, Math.PI * 2],
    [0, Math.PI * 2],
  ]}
  shadow={true}
  lighting="standard"
/>


// Gem-like particles with physical material
<VFXParticles
  geometry={gemGeometry}
  lighting="physical"
  lightingParams={{
    roughness: 0.3,
    metalness: 0.8,
    clearcoat: 1,
    clearcoatRoughness: 0.1,
    iridescence: 1,
    iridescenceIOR: 1.5,
  }}
/>


// Stretched sparks aligned to velocity
<VFXParticles
  geometry={new SphereGeometry(0.3, 8, 6)}
  orientToDirection={true}
  orientAxis="z"
  stretchBySpeed={{ factor: 2, maxStretch: 5 }}
  speed={[1, 5]}
/>
```

--------------------------------

### Per-Frame Particle Emission with Overrides

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Shows how to emit particles on a per-frame basis with dynamic overrides. This example uses `useFrame` and a ref to an emitter to trigger emissions with changing properties like direction based on game state.

```tsx
useFrame((_, delta) => {
  if (isAttacking) {
    const direction = nextAttack === "ATTACK_02"
      ? [[1, 1], [-1, -1], [0, 0]]
      : [[-1, -1], [-1, -1], [0, 0]]


    sparkEmitterRef.current?.emit({ direction })
  }
})
```

--------------------------------

### Manage Particle Systems with useVFXStore (JavaScript)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

The useVFXStore hook from r3f-vfx provides low-level access to registered particle systems. It allows reactive access within React components or direct state manipulation outside of them. You can emit, start, stop, clear, and retrieve specific particle systems, as well as access their uniforms.

```javascript
import { useVFXStore } from "r3f-vfx"


// Access as a hook (reactive)
const particles = useVFXStore((state) => state.particles)


// Access outside React components
const store = useVFXStore.getState()
store.emit("sparks", { x: 0, y: 1, z: 0, count: 20 })
store.start("sparks")
store.stop("sparks")
store.clear("sparks")


// Get a specific particle system
const sparks = store.getParticles("sparks")
sparks?.spawn(0, 0, 0, 50)
```

--------------------------------

### Trail Opacity TSL Callback Example (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Shows how to use a TSL (Three.js Shader Language) callback function for per-vertex trail opacity, allowing dynamic fading based on trail progress and particle data.

```tsx
trail={{
  opacity: ({
    alpha,
    trailProgress,
    side,
    progress,
    lifetime,
    position,
    velocity,
    size,
    colorStart,
    colorEnd,
    particleColor,
    index,
  }) => {
    // Fade based on trail position and particle age
    return alpha.mul(trailProgress.oneMinus()).mul(lifetime)
  }
}}

```

--------------------------------

### Control Particle System Imperatively with Refs

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Access and control the particle system directly using a ref. This allows for programmatic spawning, starting, stopping, and clearing of particles, as well as checking the emission state.

```typescript
import { useRef } from "react";

const particlesRef = useRef(null);

// Spawn 50 particles at a specific position
// particlesRef.current.spawn(x, y, z, 50, overrides);

// Control emission
// particlesRef.current.start();
// particlesRef.current.stop();
// particlesRef.current.clear();

// Check state
// const isEmitting = particlesRef.current.isEmitting;
```

--------------------------------

### Using useVFXEmitter Hook for Event-Driven Particles (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Illustrates how to integrate the useVFXEmitter hook into a React component to trigger particle effects in response to application events. This example shows how to subscribe to an event and emit particles with specific positions and counts.

```jsx
import { useVFXEmitter } from "r3f-vfx"


const EnemyDeath = () => {
  const { emit } = useVFXEmitter("death")
  const { emit: emitCircle } = useVFXEmitter("death-ring")


  useEffect(() => {
    eventBus.on("enemy-dead", (position) => {
      const { x, y, z } = position
      emit([x, y, z], 50)       // position + count
      emitCircle([x, y, z], 1)  // single ring burst
    })
  }, [emit, emitCircle])


  return null
}
```

--------------------------------

### Enable Depth Sorting for Transparent Particles in VFXParticles (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Shows how to enable and configure depth sorting for transparent particles using the VFXParticles component. This ensures correct alpha blending by rendering particles from back to front. Includes an example with normal blending and fading opacity.

```jsx
// Sorted transparent particles
<VFXParticles
  sortParticles
  sortFrameInterval={2}  // sort every other frame for better perf
  blending={1}           // normal blending (needs sorting)
  colorStart={["#ffffff80"]}
  fadeOpacity={[0.8, 0]}
/>
```

--------------------------------

### Fresnel Effect for Rim Lighting (TSL/React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Applies a Fresnel effect to particle colors for a rim-lit appearance using the colorNode. This example uses TSL functions wrapped in `Fn` for pure shader logic and `three/tsl` utilities.

```typescript
import {
  dot, Fn, mix, normalView,
  positionViewDirection, pow, vec3
} from "three/tsl"


<VFXParticles
  geometry={new SphereGeometry(0.3, 16, 12)}
  size={0.1}
  orientToDirection={true}
  lighting="basic"


  // Fn(() => ...) wraps a pure TSL function (no ParticleData needed)
  colorNode={Fn(() => {
    const fresnel = pow(
      dot(normalView, positionViewDirection).oneMinus(),
      8,
    )
    return mix(vec3(2), vec3(0), fresnel)
  })}
/>

```

--------------------------------

### Implement Soft Particles for Smooth Intersections in VFXParticles (React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates enabling soft particles in VFXParticles to create smooth fading effects where particles intersect scene geometry. This removes hard edges by using depth buffer comparisons. Includes an example for smoke blending with the ground.

```jsx
// Smoke that blends smoothly with the ground
<VFXParticles
  softParticles
  softDistance={1.5}
  size={[0.5, 1]}
  colorStart={["#888888"]}
  fadeOpacity={[0.6, 0]}
  gravity={[0, 0.2, 0]}
  lifetime={[3, 5]}
/>
```

--------------------------------

### useVFXStore - Zustand Store

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Provides low-level access to all registered particle systems. Use this for direct management of multiple systems or accessing the particle registry.

```APIDOC
## useVFXStore

Zustand store for low-level access to all registered particle systems. Use this when you need to manage multiple systems directly or access the particle registry.

### Accessing the Store

```javascript
// Access as a hook (reactive)
const particles = useVFXStore((state) => state.particles)

// Access outside React components
const store = useVFXStore.getState()
```

### Store Methods

| Prop                  | Type                                  | Default | Description                                                                      |
| --------------------- | ------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `particles`           | `Record<string, ParticleSystemRef>`   | —       | Map of all registered particle systems by name.                                  |
| `registerParticles`   | `(name, ref) => void`                 | —       | Register a particle system (done automatically by VFXParticles with a name prop). |
| `unregisterParticles` | `(name) => void`                      | —       | Remove a particle system from the store.                                         |
| `getParticles`        | `(name) => ParticleSystemRef | null`  | —       | Get a specific registered system.                                                |
| `emit`                | `(name, options?) => boolean`         | —       | Emit from a named system. Options: `{ x?, y?, z?, count?, overrides? }`.         |
| `start / stop / clear`| `(name) => boolean`                   | —       | Control a named system. Returns false if system not found.                       |
| `isEmitting`          | `(name) => boolean`                   | —       | Check emission state of a named system.                                          |
| `getUniforms`         | `(name) => Record | null`             | —       | Access GPU uniforms of a named system.                                           |

### Example Usage

```javascript
// Emit from a system named 'sparks'
store.emit("sparks", { x: 0, y: 1, z: 0, count: 20 })

// Start, stop, or clear a system
store.start("sparks")
store.stop("sparks")
store.clear("sparks")

// Get a specific particle system and spawn particles
const sparks = store.getParticles("sparks")
sparks?.spawn(0, 0, 0, 50)
```
```

--------------------------------

### Configure Particle Physics

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Sets up initial particle velocity, gravity, turbulence for organic motion, and friction for damping. Physics are computed on the GPU via WebGPU, with a CPU fallback.

```tsx
<VFXParticles
  // Velocity
  speed={[0, 4.47]}
  direction={[[-1, 1], [0, 1], [-1, 1]]}  // random 3D direction
  lifetime={[1, 3]}


  // Gravity: [x, y, z] constant acceleration
  gravity={[0, -15, 0]}       // strong downward pull


  // Turbulence (3D curl noise)
  turbulence={{
    intensity: 400,            // force strength
    frequency: 2.7,            // noise spatial scale
    speed: 1,                  // noise animation speed
  }}


  // Friction: slow particles over time
  friction={{
    intensity: 0.5,            // drag amount (also accepts [min, max])
    easing: "easeOut",         // "linear" | "easeIn" | "easeOut" | "easeInOut"
  }}
/>
```

--------------------------------

### Event-Driven Particle Emission with useVFXEmitter

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates how to use `useVFXEmitter` with a custom event system to trigger particle effects. This approach allows for loosely coupled particle triggering, defining systems centrally and emitting them from any part of the application. It requires a global event bus and the `useVFXEmitter` hook.

```typescript
// 1. Define all systems in a central component
const Particles = () => (
  <>
    <VFXParticles name="death" autoStart={false}
      maxParticles={100} emitCount={100}
      gravity={[0, -15, 0]} speed={[0, 4.47]}
      collision={{ plane: { y: -1 }, bounce: 0.47, friction: 0.41 }}
    />
    <VFXParticles name="death-ring" autoStart={false}
      geometry={new PlaneGeometry(1, 1)}
      size={5} emitCount={1} lifetime={0.3}
    />
    <EnemyDeathHandler />
  </>
)


// 2. Subscribe to events and emit
const EnemyDeathHandler = () => {
  const { emit } = useVFXEmitter("death")
  const { emit: emitRing } = useVFXEmitter("death-ring")


  useEffect(() => {
    const off = eventBus.on("enemy-dead", ({ x, y, z }) => {
      emit([x, y, z], 50)
      emitRing([x, y, z], 1)
    })
    return off
  }, [emit, emitRing])


  return null
}


// 3. Trigger from game logic
enemy.onDeath(() => {
  eventBus.emit("enemy-dead", enemy.position)
})
```

--------------------------------

### Named Particle Systems with VFXParticles and useVFXEmitter

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Illustrates how to use the `name` prop with `VFXParticles` to register systems in a global Zustand store, enabling access via `VFXEmitter`, `useVFXEmitter`, or directly from the store. This pattern centralizes VFX configuration while allowing emission from various points. It also shows type-safe particle registration.

```typescript
// Pattern 1: VFXEmitter links by name
<VFXParticles name="sparks" ... />
<VFXEmitter name="sparks" emitCount={4} />


// Pattern 2: Hook access by name
const { emit, stop } = useVFXEmitter("sparks")


// Pattern 3: Store access outside React
const store = useVFXStore.getState()
store.emit("sparks", { x: 0, y: 1, z: 0, count: 20 })


// Pattern 4: Type-safe particle registry
const PARTICLES = {
  SLASH: "slash",
  SPARKS: "sparks",
  DODGE: "dodge",
  IMPACT: "impact",
  DEATH: "death",
} as const


type ParticleType = typeof PARTICLES[keyof typeof PARTICLES]


const useTypedEmitter = (name: ParticleType) => {
  return useVFXEmitter(name)
}
```

--------------------------------

### Custom Particle Color with Dissolve Effect (TSL/React)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Overrides the particle color and alpha using a custom colorNode. This example creates a dissolving ring effect using TSL functions and React components. It utilizes the 'progress' property from ParticleData to animate the dissolve.

```typescript
import { uv, vec2, vec4, float, step, color } from "three/tsl"


<VFXParticles
  geometry={new PlaneGeometry(1, 1)}
  size={5}
  emitCount={1}
  lifetime={0.3}
  rotation={[[-Math.PI/2, -Math.PI/2], [0,0], [0,0]]}


  // colorNode receives ParticleData + defaultColor
  colorNode={({ progress }) => {
    const dist = uv().mul(2).sub(1).length()
    const circle = step(dist, float(0.9))
    const innerCircle = float(
      float(1).add(progress)
    ).sub(dist).max(0)


    return vec4(
      color("#fc6717").mul(20),
      circle.sub(innerCircle)
    )
  }}
/>

```

--------------------------------

### Geometry & Lighting

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Configure particle geometry and PBR lighting for advanced visual effects. Supports custom 3D models and various lighting parameters.

```APIDOC
## POST /websites/three-vfx_vercel_app/geometry-lighting

### Description
Replace flat billboard sprites with 3D geometry and enable PBR lighting for particles. This mode utilizes instanced mesh rendering.

### Method
POST

### Endpoint
/websites/three-vfx_vercel_app/geometry-lighting

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **geometry** (BufferGeometry | null) - Required - Custom particle geometry. Switches from sprite to instanced mesh mode.
- **lighting** (string) - Optional - Lighting mode: "basic" (unlit), "standard" (PBR roughness/metalness), "physical" (full PBR).
- **lightingParams** (LightingParams | null) - Optional - PBR material parameters for standard/physical lighting.
- **shadow** (boolean) - Optional - Enable shadow casting and receiving on geometry instances.
- **orientToDirection** (boolean) - Optional - Rotate geometry to face velocity direction.
- **orientAxis** (string) - Optional - Which local axis aligns with velocity: "x", "y", "z", "-x", "-y", "-z".
- **stretchBySpeed** (StretchConfig | null) - Optional - Stretch geometry along velocity direction based on speed.

### Request Example
```json
{
  "geometry": "<BufferGeometry object>",
  "lighting": "standard",
  "shadow": true,
  "orientToDirection": true,
  "stretchBySpeed": {
    "factor": 2,
    "maxStretch": 5
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Geometry and lighting updated successfully."
}
```

### Types
```typescript
interface LightingParams {
  // Standard + Physical
  roughness?: number          // 0 = mirror, 1 = matte
  metalness?: number          // 0 = dielectric, 1 = metal
  emissive?: string           // Emissive color hex string
  emissiveIntensity?: number  // Emissive brightness
  envMapIntensity?: number    // Environment map strength

  // Physical only
  clearcoat?: number          // Clearcoat layer intensity
  clearcoatRoughness?: number // Clearcoat roughness
  transmission?: number       // Glass-like transparency
  thickness?: number          // Volume thickness for transmission
  ior?: number                // Index of refraction
  iridescence?: number        // Iridescence effect intensity
  iridescenceIOR?: number     // Iridescence index of refraction
}

interface StretchConfig {
  factor: number      // Stretch multiplier
  maxStretch: number  // Maximum stretch amount
}
```
```

--------------------------------

### Define Lighting and Stretch Parameters for VFXParticles

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Defines interfaces for configuring PBR lighting and geometry stretching in VFXParticles. `LightingParams` controls material properties like roughness, metalness, and iridescence. `StretchConfig` manages how particle geometry stretches based on speed.

```typescript
interface LightingParams {
  // Standard + Physical
  roughness?: number          // 0 = mirror, 1 = matte
  metalness?: number          // 0 = dielectric, 1 = metal
  emissive?: string           // Emissive color hex string
  emissiveIntensity?: number  // Emissive brightness
  envMapIntensity?: number    // Environment map strength


  // Physical only
  clearcoat?: number          // Clearcoat layer intensity
  clearcoatRoughness?: number // Clearcoat roughness
  transmission?: number       // Glass-like transparency
  thickness?: number          // Volume thickness for transmission
  ior?: number                // Index of refraction
  iridescence?: number        // Iridescence effect intensity
  iridescenceIOR?: number     // Iridescence index of refraction
}


interface StretchConfig {
  factor: number      // Stretch multiplier
  maxStretch: number  // Maximum stretch amount
}
```

--------------------------------

### Sorting

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Enable back-to-front depth sorting for correct alpha blending with transparent particles. Supports GPU bitonic sort on WebGPU and CPU radix sort on WebGL.

```APIDOC
## POST /websites/three-vfx_vercel_app/sorting

### Description
Enable and configure depth sorting for particles to ensure correct alpha blending, especially with transparent effects.

### Method
POST

### Endpoint
/websites/three-vfx_vercel_app/sorting

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **sortParticles** (boolean) - Required - Enable depth sorting. Required for correct transparency with normal blending.
- **sortFrameInterval** (number | null) - Optional - Run GPU sort every N frames (WebGPU only). 1 = every frame, 2 = every other frame. null = automatic.

### Request Example
```json
{
  "sortParticles": true,
  "sortFrameInterval": 2
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Sorting settings updated successfully."
}
```
```

--------------------------------

### VFXEmitter Configuration

Source: https://three-vfx.vercel.app/#/docs/index_/docs

This section details the properties that can be overridden for a single emission event using the `overrides` prop or parameter.

```APIDOC
## Overridable Properties

The `overrides` prop (and the overrides parameter in `emit()` / `spawn()`) temporarily changes particle properties for that single emission only. The base VFXParticles config is never modified. The following properties can be overridden:

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `number | [min, max]` | — | Override particle size range. |
| `speed` | `number | [min, max]` | — | Override initial velocity magnitude. |
| `lifetime` | `number | [min, max]` | — | Override particle lifespan. |
| `direction` | `Range3D` | — | Override emission direction per axis. |
| `startPosition` | `Range3D` | — | Override spawn position offset. |
| `gravity` | `[x, y, z]` | — | Override gravity vector. |
| `colorStart` | `string[]` | — | Override starting colors (up to 8). |
| `colorEnd` | `string[]` | — | Override ending colors (up to 8). |
| `rotation` | `Range3D` | — | Override initial rotation. |
| `emitterShape` | `0-5` | — | Override emitter shape type. |
| `emitterRadius` | `number | [inner, outer]` | — | Override emitter radius. |
| `emitterAngle` | `number` | — | Override cone angle. |
| `emitterHeight` | `number | [min, max]` | — | Override cone height. |
| `emitterSurfaceOnly` | `boolean` | — | Override surface-only emission. |
| `emitterDirection` | `[x, y, z]` | — | Override emitter normal direction. |

### Request Example
```jsx
// Emitter with per-spawn overrides
<VFXEmitter
  name="sparks"
  emitCount={10}
  delay={0.1}
  overrides={{
    colorStart: ["#ff0000", "#ff8800"],
    speed: [2, 5],
    direction: [[0, 0], [1, 1], [0, 0]],  // emit upward only
  }}
/>

// Direction + localDirection for attached emitters
// The direction rotates with the parent object
<group ref={swordRef}>
  <VFXEmitter
    name="slash-sparks"
    direction={[[0, 0], [0, 0], [-1, -1]]}  // emit along -Z
    localDirection={true}                     // rotate with sword
    emitCount={4}
    delay={0}
  />
</group>
```
```

--------------------------------

### Define Attractor Configuration Interface

Source: https://three-vfx.vercel.app/#/docs/index_/docs

TypeScript interface for configuring attractor properties, including position, strength, radius, type (point or vortex), and axis for vortex attractors.

```typescript
interface AttractorConfig {
  position?: [number, number, number]  // World position
  strength?: number    // Positive = attract, negative = repel
  radius?: number      // Effect radius (0 = infinite range)
  type?: "point" | "vortex"
  axis?: [number, number, number]  // Rotation axis (vortex only)
}
```

--------------------------------

### Configure Particle Rotation Input Formats (JavaScript)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates flexible input formats for rotation and direction properties in r3f-vfx. You can apply a single value to all axes, a random range for all axes, or specify independent ranges for each axis (X, Y, Z). This flexibility extends to `direction`, `startPosition`, and `rotationSpeed`.

```javascript
// Single value: applied to all axes
rotation={0}


// Range: random between min/max, applied to all axes
rotation={[-Math.PI, Math.PI]}


// Per-axis ranges: independent control per axis
rotation={[
  [-Math.PI, Math.PI],     // X axis
  [0, 0],                  // Y axis (no rotation)
  [-Math.PI, Math.PI],     // Z axis
]}
```

--------------------------------

### useVFXEmitter Hook

Source: https://three-vfx.vercel.app/#/docs/index_/docs

The `useVFXEmitter` hook provides programmatic control over named particle systems, ideal for triggering particles from game logic or event handlers.

```APIDOC
## useVFXEmitter

Programmatic control hook for named particle systems. Use this when you need to trigger particles from game logic, event handlers, or other non-component code. Links to a VFXParticles system by name through the global Zustand store.

### Return Value

| Prop | Type | Default | Description |
|---|---|---|---|
| `emit` | `(pos?, count?, overrides?) => boolean` | — | Emit particles at a world position with optional property overrides. Returns true if the system was found. |
| `burst` | `(pos?, count?, overrides?) => boolean` | — | One-shot burst emission. |
| `start` | `() => boolean` | — | Start continuous emission. |
| `stop` | `() => boolean` | — | Stop continuous emission. |
| `clear` | `() => boolean` | — | Kill all living particles. |
| `isEmitting` | `() => boolean` | — | Check if currently emitting. |
| `getUniforms` | `() => Record<string, unknown>` | — | Access GPU uniform values. |
| `getParticles` | `() => ParticleSystemRef | null` | — | Access the underlying particle system ref for direct control. |

### Request Example
```jsx
import { useVFXEmitter } from "r3f-vfx"

const EnemyDeath = () => {
  const { emit } = useVFXEmitter("death")
  const { emit: emitCircle } = useVFXEmitter("death-ring")

  useEffect(() => {
    eventBus.on("enemy-dead", (position) => {
      const { x, y, z } = position
      emit([x, y, z], 50)       // position + count
      emitCircle([x, y, z], 1)  // single ring burst
    })
  }, [emit, emitCircle])

  return null
}
```
```

--------------------------------

### Programmatic Emission with Overrides (React Hooks)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Shows how to trigger particle emissions programmatically using the useVFXEmitter hook and its returned 'emit' function. This method allows for dynamic control over particle properties based on application logic or user interactions.

```jsx
// Via ref: emit() accepts overrides for that call only
dodgeEmitterRef.current?.emit({
  colorStart: ["#63acff"],
  size: [2, 2],
  speed: [0.5, 1],
})


// Via useVFXEmitter hook: position + count + overrides
const { emit } = useVFXEmitter("sparks")
emit([x, y, z], 50, {
  direction: [[-1, -1], [0, 0], [0, 0]],
  gravity: [0, -20, 0],
  colorStart: ["#ff0000"],
})
```

--------------------------------

### Flipbook Configuration Interface (TS)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Defines the configuration interface for animated sprite sheets (flipbooks). It specifies the number of rows and columns in the sprite sheet, which is used to control frame advancement over particle lifetime.

```typescript
interface FlipbookConfig {
  rows: number     // Number of rows in the sprite sheet
  columns: number  // Number of columns in the sprite sheet
}
```

--------------------------------

### Programmatic Emission with Overrides

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Control particle emissions programmatically using refs or the `useVFXEmitter` hook, allowing for dynamic overrides.

```APIDOC
## Programmatic Emission with Overrides

### Ref Methods

| Prop | Type | Default | Description |
|---|---|---|---|
| `emit` | `(overrides?) => boolean` | — | Emit at current world position. Accepts optional per-call overrides. |
| `burst` | `(count?) => boolean` | — | One-shot burst of N particles at current position. |
| `start` | `() => void` | — | Start auto-emission loop. |
| `stop` | `() => void` | — | Stop auto-emission. |
| `isEmitting` | `boolean` | — | Current emission state. |
| `getParticleSystem` | `() => ParticleAPI` | — | Access the linked VFXParticles system directly. |
| `group` | `THREE.Group` | — | The underlying Three.js group element for manual transforms. |

### Request Example
```jsx
// Via ref: emit() accepts overrides for that call only
dodgeEmitterRef.current?.emit({
  colorStart: ["#63acff"],
  size: [2, 2],
  speed: [0.5, 1],
})

// Via useVFXEmitter hook: position + count + overrides
const { emit } = useVFXEmitter("sparks")
emit([x, y, z], 50, {
  direction: [[-1, -1], [0, 0], [0, 0]],
  gravity: [0, -20, 0],
  colorStart: ["#ff0000"],
})
```
```

--------------------------------

### Dynamic Particle Emission Overrides

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates how to dynamically override particle properties during emission using `emit()`. This allows for runtime changes to direction, color, speed, and gravity without altering the base particle system configuration.

```tsx
const { emit } = useVFXEmitter("sparks")


// Override direction based on game state
const direction = attackType === "right"
  ? [[1, 1], [0, 0], [0, 0]]
  : [[-1, -1], [0, 0], [0, 0]]


emit([x, y, z], 50, { direction })


// Override multiple properties at once
emit([x, y, z], 100, {
  colorStart: ["#ff0000"],
  speed: [2, 5],
  size: [0.1, 0.3],
  gravity: [0, -20, 0],
})
```

--------------------------------

### VFXEmitter with Per-Spawn Overrides (JSX)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Demonstrates how to apply temporary overrides to particle properties directly within the JSX definition of a VFXEmitter component. This allows for unique particle effects for specific instances without altering the base configuration.

```jsx
// Emitter with per-spawn overrides
<VFXEmitter
  name="sparks"
  emitCount={10}
  delay={0.1}
  overrides={{
    colorStart: ["#ff0000", "#ff8800"],
    speed: [2, 5],
    direction: [[0, 0], [1, 1], [0, 0]],  // emit upward only
  }}
/>


// Direction + localDirection for attached emitters
// The direction rotates with the parent object
<group ref={swordRef}>
  <VFXEmitter
    name="slash-sparks"
    direction={[[0, 0], [0, 0], [-1, -1]]}  // emit along -Z
    localDirection={true}                     // rotate with sword
    emitCount={4}
    delay={0}
  />
</group>
```

--------------------------------

### Define Turbulence and Friction Configurations

Source: https://three-vfx.vercel.app/#/docs/index_/docs

TypeScript interfaces for configuring turbulence and friction effects on particles. Turbulence adds swirling motion, while friction dampens velocity over time.

```typescript
interface TurbulenceConfig {
  intensity: number   // Force strength
  frequency?: number  // Noise spatial scale (default varies)
  speed?: number      // Noise animation speed (default varies)
}


interface FrictionConfig {
  intensity?: number | [number, number]  // Drag amount or range
  easing?: "linear" | "easeIn" | "easeOut" | "easeInOut"
}
```

--------------------------------

### Configure Particle Attractors

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Adds up to 4 attractors to influence particle movement. Supports point attractors pulling towards a position and vortex attractors spinning particles around an axis. Can also attract particles to the center.

```tsx
<VFXParticles
  attractors={[
            // Point attractor: pulls everything to center
            {
              position: [0, 0, 0],
              strength: 2,             // positive = attract, negative = repel
              radius: 4,               // 0 = infinite range
              type: "point",           // "point" or "vortex"
            },
            // Vortex: swirls around Y axis
            {
              position: [0, 1, 0],
              strength: 3,
              radius: 5,
              type: "vortex",
              axis: [0, 1, 0],         // spin axis
            },
          ]}


  // Shorthand: pull all particles toward emitter center
  attractToCenter={true}
/>
```

--------------------------------

### VFXParticles - Appearance & Size

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Configure the visual properties of particles, including size, color, opacity, blending, and rotation. Many properties support randomization using ranges.

```APIDOC
## Appearance & Size

Control how particles look — size, color, opacity, blend mode, rotation, and intensity. Most props accept ranges `[min, max]` for per-particle randomization.

### Props

| Prop              | Type                                       | Default | Description                                                                 |
| ----------------- | ------------------------------------------ | ------- | --------------------------------------------------------------------------- |
| `size`            | `number | [min, max]`                     | —       | Particle size.                                                              |
| `fadeSize`        | `[start, end]`                             | —       | Size change over particle lifetime (e.g., `[0.2, 1]` grows from 20% to 100%). |
| `colorStart`      | `string | string[]`                         | —       | Starting color(s) for particles. Accepts hex codes.                        |
| `colorEnd`        | `string | string[]`                         | —       | Ending color(s) for particles. Accepts hex codes (8-digit for alpha).       |
| `fadeOpacity`     | `[start, end]`                             | —       | Opacity change over particle lifetime (e.g., `[1, 0]` fades out).            |
| `appearance`      | `"default" | "gradient" | "circular"` | —       | Particle appearance style.                                                  |
| `blending`        | `number`                                   | —       | Blending mode (e.g., `2` for ADDITIVE glow effect).                         |
| `intensity`       | `number`                                   | —       | Brightness multiplier.                                                      |
| `rotation`        | `number | [min, max] | [axisRanges][]` | —       | Initial rotation in radians. Can be a single value, range, or per-axis.     |
| `rotationSpeed`   | `number | [min, max] | [axisRanges][]` | —       | Rotation speed in radians per second. Can be a single value, range, or per-axis. |

### Rotation Input Formats

Rotation and direction props accept flexible input formats:

```javascript
// Single value: applied to all axes
rotation={0}

// Range: random between min/max, applied to all axes
rotation={[-Math.PI, Math.PI]}

// Per-axis ranges: independent control per axis
rotation={[
  [-Math.PI, Math.PI],     // X axis
  [0, 0],                  // Y axis (no rotation)
  [-Math.PI, Math.PI],     // Z axis
]}
```

**Tip**: The same input format applies to `direction`, `startPosition`, `rotation`, and `rotationSpeed`.

### Example

```jsx
<VFXParticles
  size={[0.04, 0.1]}
  fadeSize={[0.2, 1]}
  colorStart={["#FF711E", "#3d91ff"]}
  colorEnd={["#ff6b3500"]}
  fadeOpacity={[1, 0]}
  appearance="circular"
  blending={2}
  intensity={40}
  rotation={[[-3.4, 6.7], [-7.6, 6.7], [-5.4, 6.4]]}
  rotationSpeed={[[-6.3, 5.9], [-5.9, 6], [-6.6, 6]]}
/>
```
```

--------------------------------

### Configure Particle Appearance and Size (JSX)

Source: https://three-vfx.vercel.app/#/docs/index_/docs

Control the visual aspects of particles, including size, color, opacity, blending, and rotation, using props on the VFXParticles component. Many properties accept ranges for per-particle randomization, and specific values can be used for uniform control. Blending modes like ADDITIVE (2) can create glow effects.

```jsx
<VFXParticles
  // Size: random between 0.04 and 0.1
  size={[0.04, 0.1]}
  fadeSize={[0.2, 1]}         // grow from 20% to 100% over life


  // Colors: random pick from array per particle
  colorStart={["#FF711E", "#3d91ff"]}
  colorEnd={["#ff6b3500"]}     // 8-digit hex for alpha
  fadeOpacity={[1, 0]}         // fade out over lifetime


  // Rendering
  appearance="circular"        // "default" | "gradient" | "circular"
  blending={2}                 // 2 = ADDITIVE (glow effect)
  intensity={40}               // brightness multiplier


  // Rotation: per-axis ranges [min, max] in radians
  rotation={[[-3.4, 6.7], [-7.6, 6.7], [-5.4, 6.4]]}
  rotationSpeed={[[-6.3, 5.9], [-5.9, 6], [-6.6, 6]]}
/>
```
Tokens:
Raw