three.quarks ✨

three.quarks is a high-performance particle system and visual effects library for three.js, written in TypeScript.

Create stunning real-time VFX for games, interactive experiences, and web applications with an intuitive API and powerful visual editor.

🎮 Try the Demo

▶️ Launch Live Demo - See three.quarks in action with interactive examples!

🔗 Quick Links

🚀 Why three.quarks?

• ⚡ High Performance - Optimized batch rendering minimizes draw calls
• 🎮 Unity Compatible - Import particle systems from Unity's Shuriken system
• 🎨 Visual Editor - Design effects visually with three.quarks-editor
• 🔧 Flexible - Extensible plugin system for custom behaviors and emitters
• ✅ Production Ready - Used in games and interactive applications

📦 Installation

npm install three.quarks

⚡ Quick Start

import * as THREE from 'three';
import {
    BatchedRenderer,
    ParticleSystem,
    ConstantValue,
    IntervalValue,
    ConstantColor,
    PointEmitter,
    RenderMode
} from 'three.quarks';

// 1. Create the batch renderer (manages all particle systems)
const batchRenderer = new BatchedRenderer();
scene.add(batchRenderer);

// 2. Define your particle system
const particles = new ParticleSystem({
    duration: 2,
    looping: true,
    startLife: new IntervalValue(1, 2),
    startSpeed: new ConstantValue(5),
    startSize: new IntervalValue(0.1, 0.3),
    startColor: new ConstantColor(new THREE.Vector4(1, 1, 1, 1)),
    maxParticle: 100,
    emissionOverTime: new ConstantValue(20),
    shape: new PointEmitter(),
    material: new THREE.MeshBasicMaterial({
        map: yourTexture,
        transparent: true
    }),
    renderMode: RenderMode.BillBoard
});

// 3. Add to scene and renderer
scene.add(particles.emitter);
batchRenderer.addSystem(particles);

// 4. Update in your animation loop
function animate() {
    const delta = clock.getDelta();
    batchRenderer.update(delta);
    renderer.render(scene, camera);
    requestAnimationFrame(animate);
}

📂 Loading VFX from JSON

Export effects from the visual editor and load them at runtime:

import { QuarksLoader, QuarksUtil, BatchedRenderer } from 'three.quarks';

const batchRenderer = new BatchedRenderer();
const loader = new QuarksLoader();

loader.load('effects/explosion.json', (effect) => {
    QuarksUtil.addToBatchRenderer(effect, batchRenderer);
    scene.add(effect);
});

scene.add(batchRenderer);

Playing Multiple Instances

// Clone and play the effect multiple times
const instance = loadedEffect.clone();
scene.add(instance);

QuarksUtil.addToBatchRenderer(instance, batchRenderer);
QuarksUtil.setAutoDestroy(instance, true); // Auto-cleanup when finished
QuarksUtil.play(instance);

✨ Features

🎬 Renderers

• Billboard - Camera-facing sprites
• Stretched Billboard - Velocity-aligned sprites
• Mesh - 3D geometry particles
• Trail - Ribbon trails behind particles

📐 Emitter Shapes

• Point, Sphere, Hemisphere, Cone, Circle
• Mesh Surface - Emit from 3D model surfaces
• Grid - Structured emission patterns

🎭 Behaviors

• Color over lifetime
• Size over lifetime
• Rotation over lifetime
• Force fields
• Orbital motion
• Texture animation
• Sub-emitters
• Custom behaviors via plugin system

🎨 Materials

• MeshBasicMaterial (unlit)
• MeshStandardMaterial (PBR)
• Configurable blending modes
• Texture atlas support

🧪 Examples

Browse the examples folder or run locally:

npm install
npm run build
npm run examples

📦 Packages

This project is a monorepo with modular packages:

🛠️ Editor

• three.quarks-editor - Visual editor for creating and previewing particle effects with real-time preview and JSON export

📚 Resources

• Change Log
• Contributing Guide
• Development Guide
• Code of Conduct
• CodeSandbox Example
• React Three Fiber Example

🗺️ Roadmap

• 🔲 WebGPU rendering support
• 🔲 WebAssembly particle simulation
• 🔲 Node-based scriptable particle systems
• 🔲 Cross-platform native plugins

📄 License

MIT