Skip to Content
Quarks
DocumentationGetting Started

Getting Started

This guide will help you get up and running with three.quarks, a powerful particle system SDK for three.js.

What is three.quarks?

three.quarks is a high-performance particle system library designed specifically for three.js. It enables you to create various particle effects like fire, smoke, explosions, magic effects, and more. The library optimizes rendering through batching techniques, allowing thousands of particles to be rendered with minimal draw calls.

Prerequisites

Before you begin, make sure you have:

  • Basic knowledge of JavaScript / TypeScript
  • Familiarity with three.js
  • Node.js and npm installed (for installation via npm)

Installation

You can install three.quarks using npm:

npm install three.quarks three

Or yarn:

yarn add three.quarks three

Alternatively, you can include it directly via CDN:

<script src="https://unpkg.com/three@0.169.0/build/three.min.js"></script>
<script src="https://unpkg.com/three.quarks@0.15.7/build/three.quarks.min.js"></script>

Basic Setup

Here’s a minimal example to get you started with three.quarks:

import * as THREE from "three";
import * as QUARKS from "three.quarks";
 
// Create a three.js scene, camera, and renderer
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  75,
  window.innerWidth / window.innerHeight,
  0.1,
  1000,
);
camera.position.z = 10;
 
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
 
// Create a batched renderer for efficient particle rendering
const batchedRenderer = new QUARKS.BatchedRenderer();
scene.add(batchedRenderer);
 
// Create a particle system
const particleSystem = new QUARKS.ParticleSystem({
  // Duration of the particle system in seconds
  duration: 2,
 
  // Whether the particle system should loop
  looping: true,
 
  // Emission shape (where particles are emitted from)
  shape: new QUARKS.SphereEmitter({
    radius: 1,
    thickness: 1,
  }),
 
  // Initial particle properties
  startLife: new QUARKS.IntervalValue(1, 3),
  startSpeed: new QUARKS.ConstantValue(5),
  startSize: new QUARKS.ConstantValue(0.5),
  startColor: new QUARKS.ConstantColor(new THREE.Vector4(1, 0.5, 0.1, 1)),
 
  // Whether to use world space coordinates
  worldSpace: true,
 
  // Material for particles
  material: new THREE.MeshBasicMaterial({
    color: 0xffffff,
    transparent: true,
    blending: THREE.AdditiveBlending,
  }),
 
  // Behaviors controlling particle evolution over time
  behaviors: [
    new QUARKS.SizeOverLife(
      new QUARKS.PiecewiseBezier([[new QUARKS.Bezier(1, 0.8, 0.2, 0), 0]]),
    ),
    new QUARKS.ColorOverLife(
      new QUARKS.Gradient(
        [
          [new THREE.Vector3(1, 0.5, 0.1), 0],
          [new THREE.Vector3(0.1, 0.1, 0.1), 1],
        ],
        [
          [1, 0],
          [0, 1],
        ],
      ),
    ),
  ],
});
 
// Add the particle system to the scene
scene.add(particleSystem.emitter);
 
// Add the particle system to the batched renderer
batchedRenderer.addSystem(particleSystem);
 
// Animation loop
function animate() {
  requestAnimationFrame(animate);
 
  // Update the batched renderer
  batchedRenderer.update(0.016); // Pass delta time in seconds
 
  renderer.render(scene, camera);
}
animate();

Core Concepts

Understanding these key concepts will help you work effectively with three.quarks:

1. Particle System

The ParticleSystem class is the central component that manages particles, their emission, and their lifecycle. It contains configuration for initial particle properties and behaviors.

2. Batched Renderer

The BatchedRenderer optimizes rendering by batching similar particle systems together, reducing draw calls. Always add your particle systems to a batched renderer for better performance.

3. Emitters and Shapes

Emitters control where and how particles are spawned. three.quarks provides various emitter shapes like Point, Circle, Sphere, Cone, etc.

4. Behaviors

Behaviors control how particles evolve over time. Examples include:

  • SizeOverLife: Changes particle size based on lifetime
  • ColorOverLife: Changes particle color based on lifetime
  • ApplyForce: Applies physics forces to particles

5. Value Generators

Value generators provide dynamic values for particle properties:

  • ConstantValue: Always returns the same value
  • IntervalValue: Returns a random value between min and max
  • PiecewiseBezier: Returns values based on Bezier curves

Building Your First Effect

Let’s create a simple fire effect:

const fireEffect = new QUARKS.ParticleSystem({
  duration: 5,
  looping: true,
 
  // Emit from a cone shape
  shape: new QUARKS.ConeEmitter({
    radius: 0.5,
    angle: Math.PI / 8,
  }),
 
  // Particle properties
  startLife: new QUARKS.IntervalValue(1, 2),
  startSpeed: new QUARKS.IntervalValue(2, 4),
  startSize: new QUARKS.IntervalValue(0.8, 1.2),
  startColor: new QUARKS.ConstantColor(new THREE.Vector4(1, 0.5, 0.1, 1)),
 
  // Material with fire texture
  material: new THREE.MeshBasicMaterial({
    map: new THREE.TextureLoader().load("fire_particle.png"),
    transparent: true,
    blending: THREE.AdditiveBlending,
  }),
 
  // Behaviors
  behaviors: [
    // Size gradually increases then decreases
    new QUARKS.SizeOverLife(
      new QUARKS.PiecewiseBezier([[new QUARKS.Bezier(0.5, 1, 1, 0), 0]]),
    ),
 
    // Color changes from yellow to red to black
    new QUARKS.ColorOverLife(
      new QUARKS.Gradient(
        [
          [new THREE.Vector3(1, 0.8, 0.2), 0],
          [new THREE.Vector3(1, 0.2, 0.1), 0.5],
          [new THREE.Vector3(0.1, 0.1, 0.1), 1],
        ],
        [
          [1, 0],
          [0.8, 0.5],
          [0, 1],
        ],
      ),
    ),
 
    // Particles rise upward
    new QUARKS.ApplyForce(
      new THREE.Vector3(0, 5, 0),
      new QUARKS.ConstantValue(1),
    ),
 
    // Add turbulence for realistic fire movement
    new QUARKS.TurbulenceField(
      new THREE.Vector3(2, 2, 2),
      2,
      new THREE.Vector3(1, 2, 1),
      new THREE.Vector3(0.1, 0.1, 0.1),
    ),
  ],
});
 
// Add to scene and batched renderer
scene.add(fireEffect.emitter);
batchedRenderer.addSystem(fireEffect);

Next Steps

Now that you’ve set up your first particle system, explore these topics to deepen your understanding:

Troubleshooting

If you encounter issues:

  1. Ensure three.js and three.quarks versions are compatible
  2. Check console for errors
  3. Verify that particle systems are added to both the scene and the batched renderer
  4. Confirm you’re calling batchedRenderer.update(deltaTime) in your animation loop
  5. Make sure your material settings (transparency, blending) are appropriate for particle effects
Last updated on
HomeParticle System