Skip to main content

​
Overview

The particle system allows you to create and manage particle effects with customizable emission patterns, physics simulation, and rendering. Particles automatically face the camera using billboarding.

​
ParticleEmitter

The ParticleEmitter class manages particle spawning, updates, and rendering.

​
Constructor

​
ParticleEmitter
constructor
Creates a new particle emitter.Parameters:
  • maxParticles - Maximum number of particles the emitter can handle (default: 100)

​
Core Methods

​
initialize
void
Allocates buffers and shader state necessary for particle simulation. Called automatically when added to a scene.
​
render
void
Renders all active particles with billboarding logic.Parameters:
  • dt - Delta time since last frame
  • commandBuffer - Command buffer for rendering
  • updatePipeline - Whether to update the pipeline (default: false)
​
update
void
Updates particle lifetimes, spawns new particles, and applies forces.Parameters:
  • window - The window context for updates

​
Configuration Methods

​
setEmissionType
void
Sets the type of particle emission pattern.Parameters:
  • type - Emission type (ParticleEmissionType::Fountain or ParticleEmissionType::Ambient)
​
setDirection
void
Sets the direction in which particles are emitted.Parameters:
  • dir - Direction vector
​
setSpawnRadius
void
Sets the radius around the emitter from which particles are spawned.Parameters:
  • radius - Spawn radius
​
setSpawnRate
void
Sets how many particles are spawned per second.Parameters:
  • particlesPerSecond - Number of particles to spawn per second (float or int)
​
setParticleSettings
void
Sets the settings for particle behavior and appearance.Parameters:
  • particleSettings - ParticleSettings structure

​
Emission Control

​
emitOnce
void
Emits particles once, then stops.
​
emitContinuously
void
Emits particles continuously at the configured spawn rate.
​
startEmission
void
Starts emitting particles.
​
stopEmission
void
Stops emitting particles.
​
emitBurst
void
Emits a burst of particles immediately.Parameters:
  • count - Number of particles to emit in the burst

​
Appearance Methods

​
attachTexture
void
Binds a sprite texture that will be used for each particle.Parameters:
  • tex - Texture to use for particles
​
setColor
void
Sets a tint color that modulates the particle sprite.Parameters:
  • newColor - Color tint
​
enableTexture
void
Enables the use of a texture for particles.
​
disableTexture
void
Disables the use of a texture for particles.

​
Transform Methods

​
setPosition
void
Sets the emitter position.Parameters:
  • newPosition - New position in 3D space
​
move
void
Moves the emitter by a delta.Parameters:
  • deltaPosition - Position offset to apply
​
getPosition
Position3d
Returns the current emitter position.

​
Properties

​
settings
ParticleSettings
The settings used for particle behavior and appearance.

​
ParticleEmissionType

​
ParticleEmissionType
enum
Describes how particles are emitted:
  • Fountain - Particles emit in a directional cone (good for fountains, fire, smoke)
  • Ambient - Particles emit uniformly in all directions (good for snow, rain, ambient effects)

​
ParticleSettings

Structure containing all particle behavior parameters.
​
minLifetime
float
default:"1.0f"
Minimum lifetime of a particle in seconds.
​
maxLifetime
float
default:"3.0f"
Maximum lifetime of a particle in seconds.
​
minSize
float
default:"0.02f"
Minimum size of a particle.
​
maxSize
float
default:"0.01f"
Maximum size of a particle.
​
fadeSpeed
float
default:"0.5f"
Speed at which particles fade out.
​
gravity
float
default:"-9.81f"
Gravitational force applied to particles (negative for downward).
​
spread
float
default:"1.0f"
Spread of particles from the emitter (angular variation).
​
speedVariation
float
default:"1.0f"
Speed variation of particles (how much the speed is randomized).

​
Particle

Structure representing a single particle in the system.
​
position
Position3d
The position of the particle in 3D space.
​
velocity
Magnitude3d
The velocity of the particle in 3D space.
​
color
Color
The color of the particle.
​
life
float
The current life of the particle in seconds.
​
maxLife
float
The maximum life of the particle in seconds.
​
size
float
The scale of the particle.
​
active
bool
Whether the particle is active or not.

​
Example Usage

// Create a fountain particle emitter
ParticleEmitter fountain(200);
fountain.setPosition({0.0f, 0.0f, 0.0f});
fountain.setEmissionType(ParticleEmissionType::Fountain);
fountain.setDirection({0.0f, 1.0f, 0.0f});
fountain.setSpawnRadius(0.5f);
fountain.setSpawnRate(20.0f);

// Configure particle settings
ParticleSettings settings;
settings.minLifetime = 1.0f;
settings.maxLifetime = 3.0f;
settings.minSize = 0.05f;
settings.maxSize = 0.1f;
settings.fadeSpeed = 0.5f;
settings.gravity = -9.81f;
settings.spread = 1.0f;
settings.speedVariation = 0.5f;
fountain.setParticleSettings(settings);

// Attach a texture
Texture particleTexture = Texture::fromResourceName("ParticleSprite");
fountain.attachTexture(particleTexture);
fountain.enableTexture();

// Add to scene
scene.addObject(&fountain);

// Create a snow effect
ParticleEmitter snow(500);
snow.setPosition({0.0f, 20.0f, 0.0f});
snow.setEmissionType(ParticleEmissionType::Ambient);
snow.setSpawnRadius(10.0f);
snow.setSpawnRate(50.0f);

ParticleSettings snowSettings;
snowSettings.minLifetime = 5.0f;
snowSettings.maxLifetime = 8.0f;
snowSettings.minSize = 0.03f;
snowSettings.maxSize = 0.06f;
snowSettings.gravity = -2.0f;
snowSettings.speedVariation = 0.3f;
snow.setParticleSettings(snowSettings);
snow.setColor(Color::white());

scene.addObject(&snow);

// Emit a burst (explosion effect)
ParticleEmitter explosion(100);
explosion.setPosition({5.0f, 0.0f, 0.0f});
explosion.emitBurst(100);
scene.addObject(&explosion);

// Create rain streaks
ParticleEmitter rain(300);
Texture rainStreak = Texture::createRainStreak(64, 256);
rain.attachTexture(rainStreak);
rain.enableTexture();
rain.setEmissionType(ParticleEmissionType::Ambient);
rain.setDirection({0.0f, -1.0f, 0.2f});

ParticleSettings rainSettings;
rainSettings.gravity = -30.0f;
rainSettings.minSize = 0.02f;
rainSettings.maxSize = 0.04f;
rain.setParticleSettings(rainSettings);

scene.addObject(&rain);

Build docs developers (and LLMs) love

Get started for freeTalk to us