quarks.r3f

React Three Fiber integration for three.quarks particle systems.

Installation

npm install quarks.r3f three.quarks

Quick Start

import { Canvas } from '@react-three/fiber'
import { QuarksProvider, ParticleSystem } from 'quarks.r3f'
import { ConeEmitter, SizeOverLife, PiecewiseBezier, Bezier, RenderMode } from 'three.quarks'

function FireEffect() {
    const shape = useMemo(() => new ConeEmitter({ angle: 0.3, radius: 0.2 }), [])
    const behaviors = useMemo(() => [
        new SizeOverLife(new PiecewiseBezier([[new Bezier(1, 0.8, 0.4, 0), 0]]))
    ], [])

    return (
        <ParticleSystem
            duration={5}
            looping
            startLife={[1, 2]}
            startSpeed={[2, 4]}
            startSize={[0.3, 0.6]}
            startColor={{ r: 1, g: 0.5, b: 0.2, a: 1 }}
            emissionOverTime={40}
            shape={shape}
            renderMode={RenderMode.BillBoard}
            behaviors={behaviors}
            position={[0, 0, 0]}
            rotation={[-Math.PI / 2, 0, 0]}
            autoPlay
        />
    )
}

function App() {
    return (
        <Canvas>
            <QuarksProvider>
                <FireEffect />
            </QuarksProvider>
        </Canvas>
    )
}

Components

<QuarksProvider>

Required wrapper component that manages the BatchedRenderer for all child particle systems.

<Canvas>
    <QuarksProvider>
        {/* All particle systems must be children of QuarksProvider */}
        <ParticleSystem ... />
    </QuarksProvider>
</Canvas>

<ParticleSystem>

Declarative particle system component with flexible prop types.

Props:

| Prop | Type | Description | |------|------|-------------| | duration | number | System duration in seconds | | looping | boolean | Whether to loop the system | | startLife | number \| [min, max] \| ValueGenerator | Particle lifetime | | startSpeed | number \| [min, max] \| ValueGenerator | Initial particle speed | | startSize | number \| [min, max] \| ValueGenerator | Initial particle size | | startColor | {r,g,b,a} \| ColorGenerator | Initial particle color | | startRotation | number \| [min, max] \| ValueGenerator | Initial rotation | | emissionOverTime | number \| [min, max] \| ValueGenerator | Particles per second | | shape | EmitterShape | Emitter shape (ConeEmitter, SphereEmitter, etc.) | | material | Material | Three.js material for particles | | renderMode | RenderMode | BillBoard, StretchedBillBoard, Mesh, Trail | | behaviors | Behavior[] | Array of particle behaviors | | uTileCount | number | Texture atlas horizontal tiles | | vTileCount | number | Texture atlas vertical tiles | | worldSpace | boolean | Emit in world space | | position | [x, y, z] | Emitter position | | rotation | [x, y, z] | Emitter rotation (Euler angles) | | scale | [x, y, z] | Emitter scale | | autoPlay | boolean | Start playing automatically (default: true) |

Ref API:

const systemRef = useRef<ParticleSystemRef>(null)

<ParticleSystem ref={systemRef} ... />

// Control methods
systemRef.current.play()
systemRef.current.pause()
systemRef.current.restart()
systemRef.current.stop()

// Access underlying objects
systemRef.current.system   // ParticleSystem instance
systemRef.current.emitter  // ParticleEmitter (Object3D)

<QuarksEffect>

Load particle effects from JSON files with React Suspense support.

import { Suspense } from 'react'
import { QuarksEffect } from 'quarks.r3f'

function MyEffect() {
    return (
        <Suspense fallback={null}>
            <QuarksEffect
                url="/effects/explosion.json"
                position={[0, 0, 0]}
                autoPlay
            />
        </Suspense>
    )
}

// Preload effects
QuarksEffect.preload('/effects/explosion.json')

Hooks

useQuarks()

Access the BatchedRenderer from context.

import { useQuarks } from 'quarks.r3f'

function MyComponent() {
    const { batchedRenderer } = useQuarks()
    // Use for advanced operations
}

useParticleSystem(props)

Imperative hook for creating particle systems.

import { useParticleSystem } from 'quarks.r3f'

function MyParticles() {
    const { system, emitter, play, pause, restart } = useParticleSystem({
        duration: 5,
        looping: true,
        startLife: [1, 2],
        // ... other props
    })

    return <primitive object={emitter} position={[0, 1, 0]} />
}

useQuarksEffect(url)

Hook for loading JSON effects with Suspense.

import { useQuarksEffect } from 'quarks.r3f'

function MyEffect() {
    const { group, systems, play, pause, restart } = useQuarksEffect('/effect.json')
    return <primitive object={group} />
}

// Preload
useQuarksEffect.preload('/effect.json')

Flexible Prop Types

Props like startLife, startSpeed, startSize, and emissionOverTime accept flexible types:

// Constant value
startLife={2}

// Random range [min, max]
startLife={[1, 3]}

// ValueGenerator from three.quarks
startLife={new IntervalValue(1, 3)}
startLife={new PiecewiseBezier([[new Bezier(1, 2, 3, 4), 0]])}

Behaviors

Use behaviors from three.quarks to animate particles over their lifetime:

import {
    SizeOverLife,
    ColorOverLife,
    SpeedOverLife,
    RotationOverLife,
    Gradient,
    PiecewiseBezier,
    Bezier,
    Vector4,
} from 'three.quarks'

const behaviors = useMemo(() => [
    // Size fades out
    new SizeOverLife(new PiecewiseBezier([[new Bezier(1, 0.8, 0.4, 0), 0]])),

    // Color gradient
    new ColorOverLife(new Gradient([
        [new Vector4(1, 0.8, 0.2, 1), 0],
        [new Vector4(1, 0.3, 0.1, 1), 0.5],
        [new Vector4(0.5, 0.1, 0.1, 0), 1],
    ])),

    // Speed decay
    new SpeedOverLife(new PiecewiseBezier([[new Bezier(1, 0.5, 0.2, 0), 0]])),
], [])

<ParticleSystem behaviors={behaviors} ... />

Emitter Shapes

import { ConeEmitter, SphereEmitter, PointEmitter } from 'three.quarks'

// Cone emitter (good for fire, fountains)
const cone = new ConeEmitter({ angle: 0.3, radius: 0.2, arc: Math.PI * 2 })

// Sphere emitter (good for explosions, magic effects)
const sphere = new SphereEmitter({ radius: 0.5, thickness: 0.2 })

// Point emitter
const point = new PointEmitter()

License

MIT