Emitters

Emitters are a fundamental component of the three.quarks particle system. They define where and how particles are spawned into the scene. The library provides various emitter shapes to create different emission patterns for your particle effects.

Overview

In three.quarks, an emitter is represented by the ParticleEmitter class, which is a node in the three.js scene graph. Each emitter is associated with a specific particle system and has an emission shape that determines the spatial distribution of generated particles.

Emitter Shapes

The emission shape controls the volume or surface from which particles originate. The shape affects both the initial position and, in most cases, the initial velocity direction of particles.

Available Emitter Shapes

three.quarks provides the following emitter shapes:

Shape	Description
Point	Emits particles from a single point
Circle	Emits particles from a circle in 2D space
Sphere	Emits particles from a spherical volume
Cone	Emits particles from a cone volume with directional velocity
Rectangle	Emits particles from a rectangular surface
Grid	Emits particles from a grid of points
Hemisphere	Emits particles from a hemisphere surface
Donut	Emits particles from a torus (donut) shape
Mesh Surface	Emits particles from the surface of a 3D mesh

Using Emitters

An emitter is automatically created when you create a particle system. You specify the emission shape in the ParticleSystem constructor:


// Create a particle system with a sphere emitter
const particleSystem = new ParticleSystem({
  shape: new SphereEmitter({
    radius: 2,
    thickness: 1,
    arc: Math.PI * 2,
  }),
  // Other particle system properties...
});
 
// Add the emitter to the scene
scene.add(particleSystem.emitter);

Emitter Modes

Many emitter shapes support different emission modes that control how particles are distributed over time:

Mode	Description
`EmitterMode.Random`	Particles are emitted randomly within the shape (default)
`EmitterMode.Loop`	Emission point moves in a repeating pattern
`EmitterMode.PingPong`	Emission point moves back and forth
`EmitterMode.Burst`	All particles are emitted at once from points distributed across the shape

Detailed Emitter Shape Configuration

PointEmitter

The simplest emitter that emits particles from a single point.


new PointEmitter();

Particles emitted from a PointEmitter will have random initial velocity directions.

SphereEmitter

Emits particles from within a spherical volume or from its surface.


new SphereEmitter({
  radius: 2, // Radius of the sphere
  thickness: 1, // 0 = surface only, 1 = full volume
  arc: Math.PI * 2, // Emission arc angle (in radians)
  mode: EmitterMode.Random,
  spread: 0, // Used with Loop/PingPong modes
  speed: new ConstantValue(1), // Speed of emission point movement
});

ConeEmitter

Emits particles in a cone shape with directional velocity.


new ConeEmitter({
  radius: 1, // Radius of the cone base
  angle: Math.PI / 6, // Half-angle of the cone (in radians)
  thickness: 1, // 0 = surface only, 1 = full volume
  arc: Math.PI * 2, // Emission arc angle (in radians)
  mode: EmitterMode.Random,
  spread: 0,
  speed: new ConstantValue(1),
});

CircleEmitter

Emits particles from within a circular area or from its edge.


new CircleEmitter({
  radius: 2, // Radius of the circle
  thickness: 1, // 0 = edge only, 1 = full area
  arc: Math.PI * 2, // Emission arc angle (in radians)
  mode: EmitterMode.Random,
  spread: 0,
  speed: new ConstantValue(1),
});

RectangleEmitter

Emits particles from a rectangular surface or its perimeter.


new RectangleEmitter({
  width: 2, // Width of the rectangle
  height: 2, // Height of the rectangle
  thickness: 1, // 0 = perimeter only, 1 = full area
  mode: EmitterMode.Random,
  spread: 0,
  speed: new ConstantValue(1),
});

GridEmitter

Emits particles from a grid of points.


new GridEmitter({
  width: 4, // Width of the grid
  height: 4, // Height of the grid
  column: 5, // Number of columns
  row: 5, // Number of rows
});

HemisphereEmitter

Emits particles from a hemisphere surface or volume.


new HemisphereEmitter({
  radius: 2, // Radius of the hemisphere
  thickness: 1, // 0 = surface only, 1 = full volume
  arc: Math.PI * 2, // Emission arc angle (in radians)
  mode: EmitterMode.Random,
  spread: 0,
  speed: new ConstantValue(1),
});

DonutEmitter

Emits particles from a torus (donut) shape.


new DonutEmitter({
  radius: 2, // Main radius of the donut
  donutRadius: 0.5, // Radius of the donut tube
  thickness: 1, // 0 = surface only, 1 = full volume
  arc: Math.PI * 2, // Emission arc angle (in radians)
  mode: EmitterMode.Random,
  spread: 0,
  speed: new ConstantValue(1),
});

MeshSurfaceEmitter

Emits particles from the surface of a 3D mesh.


// First create a mesh geometry
const geometry = new TorusKnotGeometry(1, 0.3, 100, 16);
 
// Create the emitter using the geometry
new MeshSurfaceEmitter(geometry);

This emitter is particularly useful for creating effects that follow the shape of complex 3D models.

Emission Bursts

In addition to continuous emission, you can create bursts of particles at specific times:


const particleSystem = new ParticleSystem({
  // ... other settings
  emissionBursts: [
    {
      time: 0, // Time in seconds when the burst occurs
      count: new ConstantValue(20), // Number of particles to emit
      cycle: 1, // Number of times to repeat the burst
      interval: 0.1, // Interval between cycles
      probability: 1, // Probability of the burst occurring
    },
    {
      time: 1,
      count: new ConstantValue(10),
      cycle: 1,
      interval: 0.1,
      probability: 0.5,
    },
  ],
});

Properties controlling emission rate

The rate at which particles are emitted is controlled by:

emissionOverTime: Controls how many particles are emitted per second
emissionOverDistance: Controls how many particles are emitted per unit of distance the emitter moves


const particleSystem = new ParticleSystem({
  // ... other settings
  emissionOverTime: new ConstantValue(10), // 10 particles per second
  emissionOverDistance: new ConstantValue(5), // 5 particles per unit of distance
});

You can use value generators to create dynamic emission rates:


// Variable emission rate that peaks in the middle
const particleSystem = new ParticleSystem({
  // ... other settings
  emissionOverTime: new PiecewiseBezier([[new Bezier(0, 10, 10, 0), 0]]),
});

Positioning and Transforming Emitters

Since the emitter is a node in the three.js scene graph, you can position, rotate, and scale it like any other object:


// Position the emitter
particleSystem.emitter.position.set(0, 5, 0);
 
// Rotate the emitter
particleSystem.emitter.rotation.set(0, Math.PI / 2, 0);
 
// Scale the emitter
particleSystem.emitter.scale.set(2, 2, 2);

You can also add an emitter as a child of another object to make it follow that object:


const character = new Object3D();
character.add(particleSystem.emitter);

World Space vs. Local Space

The worldSpace property of the particle system determines whether particles are simulated in world space or local space:

worldSpace: true: Particles continue moving independently of the emitter’s position and rotation.
worldSpace: false: Particles move relative to the emitter, following it as it moves.


// Particles will move independently of the emitter
const particleSystem = new ParticleSystem({
  // ... other settings
  worldSpace: true,
});
 
// Particles will follow the emitter
const particleSystem = new ParticleSystem({
  // ... other settings
  worldSpace: false,
});

Example: Fountain Effect

Here’s a complete example of creating a fountain effect using a cone emitter:


const fountainSystem = new ParticleSystem({
  duration: 5,
  looping: true,
 
  // Emit from a cone shape pointing upward
  shape: new ConeEmitter({
    radius: 0.5,
    angle: Math.PI / 12, // Narrow angle for upward spray
    thickness: 0.2, // Mostly emit from near the center
    arc: Math.PI * 2, // Full circular emission
  }),
 
  // Emission settings
  emissionOverTime: new ConstantValue(100),
 
  // Initial particle properties
  startLife: new IntervalValue(2, 3),
  startSpeed: new IntervalValue(10, 15),
  startSize: new ConstantValue(0.2),
  startColor: new ConstantColor(new Vector4(0.5, 0.7, 1.0, 1.0)),
 
  // Rendering settings
  worldSpace: true,
  material: new MeshBasicMaterial({
    map: waterDropletTexture,
    transparent: true,
    blending: AdditiveBlending,
  }),
 
  // Behaviors controlling how particles evolve
  behaviors: [
    // Apply gravity to make particles fall down
    new ApplyForce(new Vector3(0, -9.8, 0), new ConstantValue(1)),
 
    // Fade out at the end of life
    new ColorOverLife(
      new Gradient(
        [
          [new Vector3(0.5, 0.7, 1.0), 0],
          [new Vector3(0.5, 0.7, 1.0), 0.8],
          [new Vector3(0.5, 0.7, 1.0), 1],
        ],
        [
          [1, 0],
          [1, 0.8],
          [0, 1],
        ],
      ),
    ),
 
    // Slight size variation over life
    new SizeOverLife(new PiecewiseBezier([[new Bezier(1, 1.2, 0.8, 0), 0]])),
  ],
});
 
// Position the fountain
fountainSystem.emitter.position.set(0, 0, 0);
 
// Add to scene and batched renderer
scene.add(fountainSystem.emitter);
batchedRenderer.addSystem(fountainSystem);

Next Steps

Learn about Particle System Configuration for more options
Explore various Behaviors to control how particles evolve over time
Discover Value Generators for creating dynamic particle properties
See detailed documentation for each Emitter Shape