✨ Three VFX ✨

High-performance GPU-accelerated particle system for Three.js WebGPU.

Available for React Three Fiber (R3F), and experimentally for vanilla Three.js, TresJS (Vue), and Threlte (Svelte).

Features

• 🚀 GPU Compute Shaders - All particle simulation runs on the GPU for maximum performance
• 🎨 Flexible Appearance - Sprites, custom geometry, materials, and shaders
• 🌀 Advanced Physics - Gravity, turbulence, attractors, collisions, and more
• 🎯 Multiple Emitter Shapes - Point, Box, Sphere, Cone, Disk, and Edge emitters
• 📊 Curve-based Control - Bezier curves for size, opacity, velocity, and rotation over lifetime
• 🔗 Emitter System - Decoupled emitters that can share particle systems
• ⚡ WebGPU Native - Built specifically for Three.js WebGPU renderer
• 🐢 WebGL fallback – Three VFX targets WebGPU (79% global support) but provides a CPU fallback

Quick Start

React Three Fiber

Add it to your React Three Fiber project with:

npm install r3f-vfx

import { Canvas } from '@react-three/fiber'
import { VFXParticles } from 'r3f-vfx'

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

Vanilla Three.js (Experimental)

Add it to your vanilla Three.js project with:

npm install vanilla-vfx

import { VFXParticles } from 'vanilla-vfx'

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

TresJS / Vue (Experimental)

Add it to your TresJS project with:

npm install tres-vfx

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

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

Threlte / Svelte (Experimental)

Add it to your Threlte project with:

npm install threlte-vfx

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

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

How to use

Use the debug panel to design your effect, then copy the generated code and replace it in your code.

API Reference

VFXParticles

The main particle system component.

Basic Props

Appearance Props

Physics Props

interface FrictionConfig {
  intensity: number // Drag amount
  easing?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' // Deceleration curve
}

Emitter Shape Props

Geometry Mode Props

lightingParams gives full control over PBR material properties when using lighting: 'standard' or 'physical':

interface LightingParams {
  roughness?: number          // Surface roughness (0 = mirror, 1 = matte)
  metalness?: number          // Metallic factor (0 = dielectric, 1 = metal)
  emissive?: string           // Emissive color hex string
  emissiveIntensity?: number  // Emissive brightness
  envMapIntensity?: number    // Environment map strength
  // Physical mode 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
}

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

Stretch Props

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

Turbulence Props

interface TurbulenceConfig {
  intensity: number // Turbulence strength
  frequency: number // Noise scale
  speed: number // Animation speed
}

Attractor Props

interface AttractorConfig {
  position: [x, y, z]
  strength: number // Positive = attract, negative = repel
  radius?: number // 0 = infinite range
  type?: 'point' | 'vortex'
  axis?: [x, y, z] // Vortex rotation axis
}

Collision Props

interface CollisionConfig {
  plane: { y: number } // Plane Y position
  bounce?: number // Bounce factor (0-1)
  friction?: number // Horizontal friction
  die?: boolean // Kill on collision
  sizeBasedGravity?: number // Gravity multiplier by size
}

Trail Props

Requires makio-meshline installed as a peer dependency.

interface TrailConfig {
  segments?: number // Trail resolution (default: 32)
  width?: number // Line width (default: 0.1)
  taper?: boolean | ((t: number) => number) // Width taper (default: true)
  opacity?: number | ((data: TrailOpacityData) => Node) // Opacity control (default: 1)
  length?: number // History in seconds (default: 0.5)
  showParticles?: boolean // Show particles alongside trails (default: true)
  fragmentColorFn?: (data: TrailData) => Node // Per-pixel trail coloring
}

taper controls how the trail width varies from head to tail:

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

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

// Custom JS callback: t goes 0 (head) → 1 (tail), return width multiplier
trail={{ taper: (t) => Math.sin(t * Math.PI) }} // fat middle, thin ends
trail={{ taper: (t) => Math.abs(Math.sin(t * Math.PI * 4)) }} // wavy

opacity controls trail transparency. As a number it sets global opacity. As a TSL callback it runs per-vertex in the fragment shader with full access to particle data:

// Global opacity
trail={{ opacity: 0.5 }}

// TSL callback with particle data
trail={{
  opacity: ({ alpha, trailProgress, progress, lifetime, position, velocity, size }) => {
    // Fade based on trail position and particle lifetime
    return alpha.mul(trailProgress.oneMinus()).mul(lifetime)
  }
}}

Sorting Props

When enabled, particles are sorted by distance to camera for correct alpha blending. On WebGPU this uses a GPU bitonic sort; on WebGL fallback it uses a CPU radix sort.

<VFXParticles
  sortParticles
  sortFrameInterval={2}  // Sort every other frame for better perf
  blending="normal"
/>

Rendering Props

Soft Particles Props

Curve Props

All curves use Bezier spline format:

interface CurveData {
  points: Array<{
    pos: [x, y] // Position (x: 0-1 progress, y: value)
    handleIn?: [x, y] // Bezier handle in (offset)
    handleOut?: [x, y] // Bezier handle out (offset)
  }>
}

Custom Shader Props

type NodeFunction = (data: ParticleData, defaultColor?: Node) => Node
type GeometryNodeFunction = (data: ParticleData, defaultPosition: Node) => Node

interface ParticleData {
  progress: Node // 0 → 1 over lifetime
  lifetime: Node // 1 → 0 over lifetime
  position: Node // vec3 world position
  velocity: Node // vec3 velocity
  size: Node // float size
  rotation: Node // vec3 rotation
  colorStart: Node // vec3 start color
  colorEnd: Node // vec3 end color
  color: Node // vec3 interpolated color
  intensifiedColor: Node // color × intensity
  shapeMask: Node // float alpha mask
  index: Node // particle index
}

Texture Props

interface FlipbookConfig {
  rows: number
  columns: number
}

VFXEmitter

Decoupled emitter component that links to a VFXParticles system.

<VFXParticles name="sparks" maxParticles={1000} autoStart={false} />

<group ref={playerRef}>
  <VFXEmitter
    name="sparks"
    position={[0, 1, 0]}
    emitCount={5}
    delay={0.1}
    direction={[[0, 0], [0, 0], [-1, -1]]}
    localDirection={true}
  />
</group>

Props

Ref Methods

interface VFXEmitterAPI {
  emit(): boolean // Emit at current position
  burst(count?: number): boolean // Burst emit
  start(): void // Start auto-emission
  stop(): void // Stop auto-emission
  isEmitting: boolean // Current state
  getParticleSystem(): ParticleAPI
  group: THREE.Group // The group element
}

useVFXEmitter Hook

Programmatic emitter control.

function MyComponent() {
  const { emit, burst, start, stop } = useVFXEmitter('sparks')

  const handleClick = () => {
    burst([0, 1, 0], 100, { colorStart: ['#ff0000'] })
  }

  return <mesh onClick={handleClick}>...</mesh>
}

Returns

interface UseVFXEmitterResult {
  emit(
    position?: [x, y, z],
    count?: number,
    overrides?: SpawnOverrides
  ): boolean
  burst(
    position?: [x, y, z],
    count?: number,
    overrides?: SpawnOverrides
  ): boolean
  start(): boolean
  stop(): boolean
  clear(): boolean
  isEmitting(): boolean
  getUniforms(): Record<string, { value: unknown }>
  getParticles(): ParticleAPI
}

useVFXStore

Zustand store for managing particle systems.

const store = useVFXStore()

// Access registered particle systems
const sparks = store.getParticles('sparks')
sparks?.spawn(0, 0, 0, 50)

// Store methods
store.emit('sparks', { x: 0, y: 0, z: 0, count: 20 })
store.start('sparks')
store.stop('sparks')
store.clear('sparks')

Examples

Fire Effect

<VFXParticles
  maxParticles={3000}
  size={[0.3, 0.8]}
  colorStart={['#ff6600', '#ffcc00', '#ff0000']}
  colorEnd={['#ff0000', '#330000']}
  fadeSize={[1, 0.2]}
  fadeOpacity={[1, 0]}
  gravity={[0, 0.5, 0]}
  lifetime={[0.4, 0.8]}
  direction={[
    [-0.3, 0.3],
    [0.5, 1],
    [-0.3, 0.3],
  ]}
  speed={[0.01, 0.05]}
  friction={{ intensity: 0.03, easing: 'easeOut' }}
  appearance={Appearance.GRADIENT}
  intensity={10}
/>

Sphere Burst

<VFXParticles
  maxParticles={500}
  size={[0.05, 0.1]}
  colorStart={['#00ffff', '#0088ff']}
  fadeOpacity={[1, 0]}
  lifetime={[1, 2]}
  emitterShape={EmitterShape.SPHERE}
  emitterRadius={[0.5, 1]}
  startPositionAsDirection={true}
  speed={[0.1, 0.2]}
/>

3D Geometry Particles

import { BoxGeometry } from 'three/webgpu'
;<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={Lighting.STANDARD}
/>

Turbulent Smoke

<VFXParticles
  maxParticles={300}
  size={[0.3, 0.6]}
  colorStart={['#666666', '#888888']}
  colorEnd={['#333333']}
  fadeSize={[0.5, 1.5]}
  fadeOpacity={[0.6, 0]}
  gravity={[0, 0.5, 0]}
  lifetime={[3, 5]}
  direction={[
    [-0.1, 0.1],
    [0.3, 0.5],
    [-0.1, 0.1],
  ]}
  speed={[0.02, 0.05]}
  turbulence={{
    intensity: 1.2,
    frequency: 0.8,
    speed: 0.3,
  }}
/>

Velocity Curves

<VFXParticles
  maxParticles={1000}
  velocityCurve={{
    points: [
      { pos: [0, 1], handleOut: [0.1, 0] },
      { pos: [0.5, 0.2], handleIn: [-0.1, 0], handleOut: [0.1, 0] },
      { pos: [1, 0], handleIn: [-0.1, 0] },
    ],
  }}
  speed={[0.5, 1]}
  lifetime={[2, 3]}
/>

TypeScript

Full TypeScript support with exported types:

import type {
  VFXParticlesProps,
  VFXEmitterProps,
  ParticleAPI,
  SpawnOverrides,
  CurveData,
  TurbulenceConfig,
  CollisionConfig,
  AttractorConfig,
  TrailConfig,
  TrailData,
  TrailOpacityData,
} from 'r3f-vfx'

License

MIT