tiramisu/particle_emitter

Particle Emitter module - GPU-accelerated particle effects system.

Provides a declarative builder API for creating particle effects like fire, smoke, explosions, trails, and environmental effects. Particles are rendered efficiently using Three.js Points with automatic lifetime management.

Core Concepts

Particle Emitter: Configuration for spawning particles continuously
Builder Pattern: Chainable functions with sensible defaults
Validated Construction: Result types catch invalid parameters
GPU Rendering: Efficient rendering using Three.js Points geometry
Automatic Lifecycle: Particles fade out and are recycled automatically

Quick Example

import tiramisu/particle_emitter
import tiramisu/scene
import vec/vec3

// Fire effect
let assert Ok(fire) =
  particle_emitter.new()
  |> particle_emitter.rate(100.0)             // 100 particles/sec
  |> particle_emitter.lifetime(2.0)           // 2 second lifetime
  |> particle_emitter.velocity(vec3.Vec3(0.0, 5.0, 0.0))  // Upward
  |> particle_emitter.velocity_variance(vec3.Vec3(2.0, 1.0, 2.0))
  |> particle_emitter.color(0xffff00)         // Yellow
  |> particle_emitter.fade_to(0xff0000)       // Fade to red
  |> particle_emitter.size(0.3)
  |> particle_emitter.gravity(-0.5)           // Rise (negative gravity)
  |> particle_emitter.build()

scene.ParticleEmitter(
  id: "campfire",
  emitter: fire,
  transform: transform.at(position: vec3.Vec3(0.0, 0.0, 0.0)),
)

Particle Parameters

rate: Particles spawned per second (must be > 0)
lifetime: How long each particle lives in seconds (must be > 0)
velocity: Base velocity vector for new particles
velocity_variance: Random variance added per axis (creates spread)
size: Base particle size (must be > 0)
size_variance: Random size variance (must be >= 0)
color: Start color as hex (0x000000 to 0xffffff)
color_end: Optional end color for fade effect
gravity_scale: Gravity multiplier (1.0 = normal, 0.0 = no gravity, negative = rise)
max_particles: Maximum simultaneous particles (must be > 0)

Effect Examples

Smoke Trail

particle_emitter.new()
|> particle_emitter.rate(30.0)
|> particle_emitter.lifetime(3.0)
|> particle_emitter.velocity(vec3.Vec3(0.0, 2.0, 0.0))
|> particle_emitter.velocity_variance(vec3.Vec3(0.5, 0.5, 0.5))
|> particle_emitter.color(0x888888)
|> particle_emitter.fade_to(0x000000)
|> particle_emitter.size(0.5)
|> particle_emitter.gravity(0.0)  // No gravity
|> particle_emitter.build()

Explosion

particle_emitter.new()
|> particle_emitter.rate(500.0)  // Burst!
|> particle_emitter.lifetime(1.0)
|> particle_emitter.velocity(vec3.Vec3(0.0, 0.0, 0.0))
|> particle_emitter.velocity_variance(vec3.Vec3(10.0, 10.0, 10.0))  // Radial
|> particle_emitter.color(0xffa500)
|> particle_emitter.fade_to(0x000000)
|> particle_emitter.gravity(1.0)
|> particle_emitter.build()

Sparkles

particle_emitter.new()
|> particle_emitter.rate(50.0)
|> particle_emitter.lifetime(0.5)
|> particle_emitter.velocity(vec3.Vec3(0.0, 1.0, 0.0))
|> particle_emitter.velocity_variance(vec3.Vec3(2.0, 2.0, 2.0))
|> particle_emitter.color(0xffff00)
|> particle_emitter.size(0.1)
|> particle_emitter.gravity(0.5)
|> particle_emitter.build()

Types

ParticleEmitter

opaque </>

Particle emitter configuration for creating particle effects.

Particle emitters spawn particles over time with configurable properties. Particles are rendered efficiently using Three.js Points with automatic lifetime management, velocity integration, and color fading.

Example

let assert Ok(emitter) = scene.particle_emitter(
  rate: 50.0,
  lifetime: 2.0,
  velocity: vec3.Vec3(0.0, 5.0, 0.0),
  velocity_variance: vec3.Vec3(2.0, 1.0, 2.0),
  size: 0.1,
  size_variance: 0.05,
  color: 0xffff00,
  color_end: option.Some(0xff0000),
  gravity_scale: 1.0,
  max_particles: 1000,
)

pub opaque type ParticleEmitter

ParticleEmitterBuilder

opaque </>

Builder for particle emitter with sensible defaults.

Start with new_particle_emitter(), chain setter methods, then call build_emitter().

Example

let emitter = scene.new_particle_emitter()
  |> scene.emitter_rate(100.0)
  |> scene.emitter_lifetime(2.0)
  |> scene.emitter_velocity(vec3.Vec3(0.0, 5.0, 0.0))
  |> scene.emitter_color(0xffff00)
  |> scene.emitter_fade_to(0xff0000)
  |> scene.build_emitter()

pub opaque type ParticleEmitterBuilder

ParticleError

</>

pub type ParticleError {
  NegativeRate(Float)
  NegativeLifetime(Float)
  NegativeSize(Float)
  NegativeSizeVariance(Float)
  OutOfBoundsColor(Int)
  OutOfBoundsColorEnd(Int)
  NegativeMaxParticles(Int)
}

Constructors

```
NegativeRate(Float)
```
```
NegativeLifetime(Float)
```
```
NegativeSize(Float)
```
```
NegativeSizeVariance(Float)
```
```
OutOfBoundsColor(Int)
```
```
OutOfBoundsColorEnd(Int)
```
```
NegativeMaxParticles(Int)
```

Values

build

</>

pub fn build(
  builder: ParticleEmitterBuilder,
) -> Result(ParticleEmitter, ParticleError)

Build the particle emitter from the builder (validates parameters).

color

</>

pub fn color(
  builder: ParticleEmitterBuilder,
  color: Int,
) -> ParticleEmitterBuilder

Set the start color for particles.

fade_to

</>

pub fn fade_to(
  builder: ParticleEmitterBuilder,
  color: Int,
) -> ParticleEmitterBuilder

Set the end color for particles (for fading effect).

gravity

</>

pub fn gravity(
  builder: ParticleEmitterBuilder,
  scale: Float,
) -> ParticleEmitterBuilder

Set gravity multiplier (1.0 = normal, 0.0 = no gravity).

lifetime

</>

pub fn lifetime(
  builder: ParticleEmitterBuilder,
  lifetime: Float,
) -> ParticleEmitterBuilder

Set how long particles live (in seconds).

max_particles

</>

pub fn max_particles(
  builder: ParticleEmitterBuilder,
  max: Int,
) -> ParticleEmitterBuilder

Set maximum number of active particles.

new

</>

pub fn new() -> ParticleEmitterBuilder

Create a new particle emitter builder with default values.

Defaults:

rate: 50.0 particles/sec
lifetime: 1.0 seconds
velocity: upward (0, 2, 0)
velocity_variance: (1, 1, 1)
size: 0.1
size_variance: 0.05
color: white (0xffffff)
color_end: None
gravity_scale: 1.0
max_particles: 1000

rate

</>

pub fn rate(
  builder: ParticleEmitterBuilder,
  rate: Float,
) -> ParticleEmitterBuilder

Set the emission rate (particles per second).

size

</>

pub fn size(
  builder: ParticleEmitterBuilder,
  size: Float,
) -> ParticleEmitterBuilder

Set the base particle size.

size_variance

</>

pub fn size_variance(
  builder: ParticleEmitterBuilder,
  variance: Float,
) -> ParticleEmitterBuilder

Set random variance added to size.

velocity

</>

pub fn velocity(
  builder: ParticleEmitterBuilder,
  velocity: vec3.Vec3(Float),
) -> ParticleEmitterBuilder

Set the base velocity for new particles.

velocity_variance

</>

pub fn velocity_variance(
  builder: ParticleEmitterBuilder,
  variance: vec3.Vec3(Float),
) -> ParticleEmitterBuilder

Set random variance added to velocity (per axis).