ParticleEmitter

View source
Entity → ceramic.ParticleEmitter (Class)
Implements: tracker.Observable, Component

A powerful and flexible particle emitter system for creating visual effects.

ParticleEmitter manages the creation, animation, and recycling of particles to create effects like fire, smoke, explosions, rain, snow, and more. The emitter can be attached as a component to any Visual entity.

Features:

  • Continuous or burst emission modes
  • Full control over particle properties and their evolution over time
  • Efficient particle pooling and recycling
  • Support for custom particle visuals
  • Deterministic random generation with seeding
  • Launch modes: circular (angle-based) or square (velocity-based)

Particle properties that can be animated over lifetime:

  • Position, velocity, acceleration, and drag
  • Scale, rotation, and angular velocity
  • Color and alpha transparency
  • Custom ranges for randomization
// Create a fire effect
var fire = new ParticleEmitter();
fire.launchMode = CIRCLE;
fire.launchAngle(-90, -90);
fire.speedStart(100, 150);
fire.lifespan(0.5, 1.0);
fire.scaleStart(0.5, 1.0);
fire.scaleEnd(0.1, 0.2);
fire.colorStart(Color.YELLOW, Color.ORANGE);
fire.colorEnd(Color.RED);
fire.alphaEnd(0);
fire.emitContinuously(0.05);
myVisual.component('particles', fire);

// Create an explosion
var explosion = new ParticleEmitter();
explosion.speedStart(200, 400);
explosion.lifespan(0.3, 0.6);
explosion.scaleEnd(2.0);
explosion.alphaEnd(0);
explosion.explode(50); // Emit 50 particles at once
See: ParticleItem The individual particle data structure, Particles For managing multiple emitters, ParticlesLaunchMode For launch mode options

Instance Members

observedDirty: Bool

Default is false, automatically set to true when any of this instance's observable variables has changed.

entity: Visual

The visual entity this emitter is attached to when used as a component. Particles will be added as children of this visual.

visual: Visual

The visual that particles are added to as children. Can be set directly or automatically assigned when used as a component. If null, particles won't be displayed.

status: Anonymous

Determines whether the emitter is currently emitting particles or not

paused: Bool

Determines whether the emitter is currently paused. It is totally safe to directly toggle this.

interval: Float

How often a particle is emitted, if currently emitting. Can be modified at the middle of an emission safely;

launchMode: Anonymous

How particles should be launched. If CIRCLE (default), particles will use launchAngle and speed. Otherwise, particles will just use velocityX and velocityY.

keepScaleRatio: Bool

Keep the scale ratio of the particle. Uses the scaleX value for reference.

visualScaleActive: Bool

Apply particle scale to underlying visual or not.

visualColorActive: Bool

Apply particle color to underlying visual or not.

visualPositionActive: Bool

Apply particle position (x & y) to underlying visual or not.

visualRotationActive: Bool

Apply particle angle to underlying visual rotation or not.

visualAlphaActive: Bool

Apply particle alpha to underlying visual or not.

width: Float

The width of the emission area. If not defined (-1), will use visual's width bound to this ParticleEmitter object, if any

height: Float

The height of the emission area. If not defined (-1), will use visual's height bound to this ParticleEmitter object, if any

The x position of the emission, relative to particles parent (if any)

The y position of the emission, relative to particles parent (if any)

maxVelocityX: Float

If you are using acceleration, you can use maxVelocity with it to cap the speed automatically (very useful!).

maxVelocityY: Float

If you are using acceleration, you can use maxVelocity with it to cap the speed automatically (very useful!).

velocityActive: Bool

Enable or disable the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityStartMinX: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityStartMinY: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityStartMaxX: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityStartMaxY: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityEndMinX: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityEndMinY: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityEndMaxX: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

velocityEndMaxY: Float

Sets the velocity range of particles launched from this emitter. Only used with SQUARE.

speedStartMin: Float

Set the speed range of particles launched from this emitter. Only used with CIRCLE.

speedStartMax: Float

Set the speed range of particles launched from this emitter. Only used with CIRCLE.

speedEndMin: Float

Set the speed range of particles launched from this emitter. Only used with CIRCLE.

speedEndMax: Float

Set the speed range of particles launched from this emitter. Only used with CIRCLE.

maxAngularVelocity: Float

Use in conjunction with angularAcceleration for fluid spin speed control.

angularAccelerationActive: Bool

Enable or disable the angular acceleration range of particles launched from this emitter.

angularAccelerationStartMin: Float

Set the angular acceleration range of particles launched from this emitter.

angularAccelerationStartMax: Float

Set the angular acceleration range of particles launched from this emitter.

angularDragActive: Bool

Enable or disable the angular drag range of particles launched from this emitter.

angularDragStartMin: Float

Set the angular drag range of particles launched from this emitter.

angularDragStartMax: Float

Set the angular drag range of particles launched from this emitter.

angularVelocityActive: Bool

Enable or disable the angular velocity range of particles launched from this emitter.

angularVelocityStartMin: Float

The angular velocity range of particles launched from this emitter.

angularVelocityStartMax: Float

The angular velocity range of particles launched from this emitter.

angularVelocityEndMin: Float

The angular velocity range of particles launched from this emitter.

angularVelocityEndMax: Float

The angular velocity range of particles launched from this emitter.

angleActive: Bool

Enable or disable the angle range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

angleStartMin: Float

The angle range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

angleStartMax: Float

The angle range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

angleEndMin: Float

The angle range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

angleEndMax: Float

The angle range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

ignoreAngularVelocity: Bool

Set this if you want to specify the beginning and ending value of angle, instead of using angularVelocity (or angularAcceleration).

launchAngleActive: Bool

Enable or disable the angle range at which particles will be launched from this emitter. Ignored unless launchMode is set to CIRCLE.

launchAngleMin: Float

The angle range at which particles will be launched from this emitter. Ignored unless launchMode is set to CIRCLE.

launchAngleMax: Float

The angle range at which particles will be launched from this emitter. Ignored unless launchMode is set to CIRCLE.

lifespanActive: Bool

Enable or disable the life, or duration, range of particles launched from this emitter.

lifespanMin: Float

The life, or duration, range of particles launched from this emitter.

lifespanMax: Float

The life, or duration, range of particles launched from this emitter.

scaleActive: Bool

Enable or disable scale range of particles launched from this emitter.

scaleStartMinX: Float

Sets scale range of particles launched from this emitter.

scaleStartMinY: Float

Sets scale range of particles launched from this emitter.

scaleStartMaxX: Float

Sets scale range of particles launched from this emitter.

scaleStartMaxY: Float

Sets scale range of particles launched from this emitter.

scaleEndMinX: Float

Sets scale range of particles launched from this emitter.

scaleEndMinY: Float

Sets scale range of particles launched from this emitter.

scaleEndMaxX: Float

Sets scale range of particles launched from this emitter.

scaleEndMaxY: Float

Sets scale range of particles launched from this emitter.

alphaActive: Bool

Enable or disable alpha range of particles launched from this emitter.

alphaStartMin: Float

Sets alpha range of particles launched from this emitter.

alphaStartMax: Float

Sets alpha range of particles launched from this emitter.

alphaEndMin: Float

Sets alpha range of particles launched from this emitter.

alphaEndMax: Float

Sets alpha range of particles launched from this emitter.

colorActive: Bool

Enable or disable color range of particles launched from this emitter.

colorStartMin: Color

Sets color range of particles launched from this emitter.

colorStartMax: Color

Sets color range of particles launched from this emitter.

colorEndMin: Color

Sets color range of particles launched from this emitter.

colorEndMax: Color

Sets color range of particles launched from this emitter.

dragActive: Bool

Enable or disable X and Y drag component of particles launched from this emitter.

dragStartMinX: Float

Sets X and Y drag component of particles launched from this emitter.

dragStartMinY: Float

Sets X and Y drag component of particles launched from this emitter.

dragStartMaxX: Float

Sets X and Y drag component of particles launched from this emitter.

dragStartMaxY: Float

Sets X and Y drag component of particles launched from this emitter.

dragEndMinX: Float

Sets X and Y drag component of particles launched from this emitter.

dragEndMinY: Float

Sets X and Y drag component of particles launched from this emitter.

dragEndMaxX: Float

Sets X and Y drag component of particles launched from this emitter.

dragEndMaxY: Float

Sets X and Y drag component of particles launched from this emitter.

accelerationActive: Bool

Enable or disable the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationStartMinX: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationStartMinY: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationStartMaxX: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationStartMaxY: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationEndMinX: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationEndMinY: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationEndMaxX: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

accelerationEndMaxY: Float

Sets the acceleration range of particles launched from this emitter. Set acceleration y-values to give particles gravity.

seed: Float

A random seed used to generated particles. Provide a custom seed to reproduce same chain of particles.

initializerName: String
size(width: Float, height: Float): Void

The width and height of the emission area. If not defined (-1), will use visual's width and height bound to this ParticleEmitter object, if any

Name Type
width Float
height Float
pos(x: Float, y: Float): Void

The x and y position of the emission, relative to particles parent (if any)

Name Type
x Float
y Float
maxVelocity(maxVelocityX: Float, maxVelocityY: Float): Void

If you are using acceleration, you can use maxVelocity with it to cap the speed automatically (very useful!).

Name Type
maxVelocityX Float
maxVelocityY Float
velocityStart(startMinX: Float, startMinY: Float, ?startMaxX: Float, ?startMaxY: Float): Void

Sets the velocity starting range of particles launched from this emitter. Only used with SQUARE.

Name Type Default
startMinX Float
startMinY Float
startMaxX Float (optional)
startMaxY Float (optional)
velocityEnd(endMinX: Float, endMinY: Float, ?endMaxX: Float, ?endMaxY: Float): Void

Sets the velocity ending range of particles launched from this emitter. Only used with SQUARE.

Name Type Default
endMinX Float
endMinY Float
endMaxX Float (optional)
endMaxY Float (optional)
speedStart(startMin: Float, ?startMax: Float): Void

Set the speed starting range of particles launched from this emitter. Only used with CIRCLE.

Name Type Default
startMin Float
startMax Float (optional)
speedEnd(endMin: Float, ?endMax: Float): Void

Set the speed ending range of particles launched from this emitter. Only used with CIRCLE.

Name Type Default
endMin Float
endMax Float (optional)
angularAcceleration(startMin: Float, startMax: Float): Void

Set the angular acceleration range of particles launched from this emitter.

Name Type
startMin Float
startMax Float
angularDrag(startMin: Float, startMax: Float): Void

Set the angular drag range of particles launched from this emitter.

Name Type
startMin Float
startMax Float
angularVelocityStart(startMin: Float, ?startMax: Float): Void

The angular velocity starting range of particles launched from this emitter.

Name Type Default
startMin Float
startMax Float (optional)
angularVelocityEnd(endMin: Float, ?endMax: Float): Void

The angular velocity ending range of particles launched from this emitter.

Name Type Default
endMin Float
endMax Float (optional)
angleStart(startMin: Float, ?startMax: Float): Void

The angle starting range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

Name Type Default
startMin Float
startMax Float (optional)
angleEnd(endMin: Float, ?endMax: Float): Void

The angle ending range of particles launched from this emitter. angleEndMin and angleEndMax are ignored unless ignoreAngularVelocity is set to true.

Name Type Default
endMin Float
endMax Float (optional)
launchAngle(min: Float, max: Float): Void

The angle range at which particles will be launched from this emitter. Ignored unless launchMode is set to CIRCLE.

Name Type
min Float
max Float
lifespan(min: Float, max: Float): Void

The life, or duration, range of particles launched from this emitter.

Name Type
min Float
max Float
scaleStart(startMinX: Float, startMinY: Float, ?startMaxX: Float, ?startMaxY: Float): Void

Sets scale starting range of particles launched from this emitter.

Name Type Default
startMinX Float
startMinY Float
startMaxX Float (optional)
startMaxY Float (optional)
scaleEnd(endMinX: Float, endMinY: Float, ?endMaxX: Float, ?endMaxY: Float): Void

Sets scale ending range of particles launched from this emitter.

Name Type Default
endMinX Float
endMinY Float
endMaxX Float (optional)
endMaxY Float (optional)
accelerationStart(startMinX: Float, startMinY: Float, ?startMaxX: Float, ?startMaxY: Float): Void

Sets acceleration starting range of particles launched from this emitter.

Name Type Default
startMinX Float
startMinY Float
startMaxX Float (optional)
startMaxY Float (optional)
accelerationEnd(endMinX: Float, endMinY: Float, ?endMaxX: Float, ?endMaxY: Float): Void

Sets acceleration ending range of particles launched from this emitter.

Name Type Default
endMinX Float
endMinY Float
endMaxX Float (optional)
endMaxY Float (optional)
dragStart(startMinX: Float, startMinY: Float, ?startMaxX: Float, ?startMaxY: Float): Void

Sets drag starting range of particles launched from this emitter.

Name Type Default
startMinX Float
startMinY Float
startMaxX Float (optional)
startMaxY Float (optional)
dragEnd(endMinX: Float, endMinY: Float, ?endMaxX: Float, ?endMaxY: Float): Void

Sets drag ending range of particles launched from this emitter.

Name Type Default
endMinX Float
endMinY Float
endMaxX Float (optional)
endMaxY Float (optional)
colorStart(startMin: Color, ?startMax: Color): Void

Sets color starting range of particles launched from this emitter.

Name Type Default
startMin Color
startMax Color (optional)
colorEnd(endMin: Color, ?endMax: Color): Void

Sets color ending range of particles launched from this emitter.

Name Type Default
endMin Color
endMax Color (optional)
alphaStart(startMin: Float, ?startMax: Float): Void

Sets alpha starting range of particles launched from this emitter.

Name Type Default
startMin Float
startMax Float (optional)
alphaEnd(endMin: Float, ?endMax: Float): Void

Sets alpha ending range of particles launched from this emitter.

Name Type Default
endMin Float
endMax Float (optional)
invalidateStatus(): Void
getCustomParticleVisual(existingVisual: Visual): Visual

Custom particle visual creation callback.

Use this to emit custom visuals as particles. The callback receives an existing visual (if being recycled) and should return a visual to use for the particle.

Alternative approach: Create a subclass and override getParticleVisual().

Name Type Description
existingVisual Visual A recycled visual if available, null otherwise
Returns Description
Visual The visual to use for the particle * haxe emitter.getCustomParticleVisual = (existing) -> { if (existing != null) return existing; var sprite = new Quad(); sprite.texture = sparkTexture; sprite.anchor(0.5, 0.5); return sprite; };
destroy(): Void

Destroys the emitter and cleans up resources.

If the emitter has no associated visual (not attached as component), all active particle visuals without parents are also destroyed. This prevents memory leaks from orphaned particles.

emitContinuously(?interval: Float = 0.1, ?quantity: Int = -1): Void

Starts emitting particles continuously at regular intervals.

Creates a stream of particles over time. Useful for effects like:

  • Fire, smoke, steam
  • Rain, snow, falling leaves
  • Fountains, waterfalls
  • Magic sparkles, energy beams
Name Type Default Description
interval Float 0.1 Time between particle emissions in seconds. Examples: 0.1 = 10 particles/second, 0.01 = 100 particles/second. Set to 0 or less to stop emission.
quantity Int -1 Total particles to emit before stopping. -1 = infinite (default), 0 = stop immediately, positive = emit that many then stop. * haxe // Continuous smoke emitter.emitContinuously(0.05); // 20 particles per second, forever * // Limited burst emitter.emitContinuously(0.1, 50); // 10/second, stop after 50
explode(quantity: Int): Void

Emits a burst of particles all at once.

Creates an instant explosion of particles. Useful for effects like:

  • Explosions, impacts, hits
  • Confetti, fireworks
  • Debris, shrapnel
  • Death/spawn effects

All particles are created at the same moment but with randomized properties according to the configured ranges.

Name Type Description
quantity Int Number of particles to emit instantly. Must be 1 or greater, does nothing if less. * haxe // Explosion effect emitter.explode(100); * // Small puff of smoke emitter.explode(10);
stop(): Void

Stops particle emission immediately.

Existing particles continue to animate until their lifespan ends. The emitter status changes from EMITTING to SPREADING (if particles remain) or IDLE (if no particles are active).

Safe to call even if not currently emitting.

emitParticle(): Void

Emits a single particle with randomized properties.

This method:

  1. Gets a particle from the pool
  2. Randomizes properties within configured ranges
  3. Initializes position, velocity, and other attributes
  4. Triggers the emitParticle event

Can be called directly for custom emission patterns beyond the built-in continuous and burst modes.

// Emit particles in a custom pattern
for (i in 0...5) {
    emitter.x = i * 50;
    emitter.emitParticle();
}
new(): Void

Creates a new ParticleEmitter instance.

The emitter starts in IDLE status and must be activated using either emitContinuously() for streams or explode() for bursts. Default settings create white 5x5 pixel particles.

Private Members

unobservedStatus: Anonymous
degToRad(deg: Float): Float
Name Type
deg Float
Returns
Float
interpolateColor(a: Color, b: Color, percent: Float): Color
Name Type
a Color
b Color
percent Float
Returns
Color
velocityFromAngle(angle: Float, speed: Float, result: Point): Void
Name Type
angle Float
speed Float
result Point
computeVelocity(velocity: Float, acceleration: Float, drag: Float, max: Float, elapsed: Float): Float

A tween-like function that takes a starting velocity and some other factors and returns an altered velocity.

Name Type Description
velocity Float Any component of velocity (e.g. 20).
acceleration Float Rate at which the velocity is changing.
drag Float This is how much the velocity changes if acceleration is not set.
max Float An absolute value cap for the velocity (0 for no cap).
elapsed Float The amount of time passed in to the latest update cycle
Returns Description
Float The altered velocity value.
emitObservedDirty(instance: ParticleEmitter, fromSerializedField: Bool): Void

Event when any observable value as changed on this instance.

Name Type
instance ParticleEmitter
fromSerializedField Bool
emitEmitParticle(particle: ParticleItem): Void

Emitted when a new particle is launched. Useful for applying custom initialization or effects to particles.

Name Type Description
particle ParticleItem The particle that was just emitted
emitStatusChange(current: Anonymous, previous: Anonymous): Void

Event when status field changes.

Name Type
current Anonymous
previous Anonymous
bindAsComponent(): Void

Called when this emitter is bound as a component to a visual. Currently empty but can be overridden for custom initialization.

update(delta: Float): Void

Updates the emitter and all active particles.

Called automatically by the game loop. Handles:

  • Continuous particle emission timing
  • Particle position, velocity, and property updates
  • Particle lifecycle and recycling
  • Status updates (IDLE, EMITTING, SPREADING)
Name Type Description
delta Float Time elapsed since last update in seconds
emitContinuousParticlesIfNeeded(delta: Float): Void

Emits particles based on continuous emission settings.

Accumulates time and emits particles when the interval threshold is reached. Handles quantity countdown and automatic stopping.

Name Type Description
delta Float Time elapsed since last update in seconds
updateParticle(particle: ParticleItem, delta: Float): Void

Updates a single particle's properties and visual.

Handles:

  • Age progression and lifespan checking
  • Property interpolation (velocity, scale, color, etc.)
  • Physics simulation (acceleration, drag, max velocity)
  • Visual synchronization if enabled

Properties are interpolated linearly over the particle's lifetime when start and end values differ.

Name Type Description
particle ParticleItem The particle to update
delta Float Time elapsed since last update in seconds
createParticleItem(): ParticleItem

Creates a new ParticleItem instance.

Override this method in a subclass to use custom ParticleItem implementations with additional properties or behavior.

Returns Description
ParticleItem A new ParticleItem instance * haxe override function createParticleItem():ParticleItem { return new CustomParticleItem(); }
getParticle(): ParticleItem

Gets a particle from the pool or creates a new one.

Implements object pooling for performance:

  1. Tries to reuse a recycled particle
  2. Creates new particle if pool is empty
  3. Assigns or recycles visual
  4. Adds to active particles list
Returns Description
ParticleItem An active particle ready for initialization
getParticleVisual(existingVisual: Visual): Visual

Gets or creates a visual for a particle.

Default implementation creates a 5x5 white quad centered at anchor point. Override this method or use getCustomParticleVisual callback to provide custom visuals like sprites, shapes, or complex graphics.

Name Type Description
existingVisual Visual A recycled visual if available, null for new particles
Returns Description
Visual Visual to use for the particle * haxe override function getParticleVisual(existingVisual:Visual):Visual { if (existingVisual != null) { existingVisual.active = true; return existingVisual; } var sprite = new Quad(); sprite.texture = particleTexture; sprite.anchor(0.5, 0.5); return sprite; }
recycleParticle(particle: ParticleItem): Void

Recycles a particle back to the pool.

Removes particle from active list, recycles its visual, and adds to recycled pool for later reuse. If the visual was destroyed, nullifies the reference.

Name Type Description
particle ParticleItem The particle to recycle
recycleParticleVisual(visualToRecycle: Visual): Void

Recycles a particle's visual for later reuse.

Default implementation simply deactivates the visual. Override to perform custom cleanup like resetting animations, clearing filters, or releasing resources.

Name Type Description
visualToRecycle Visual The visual to recycle
randomBetweenFloats(a: Float, b: Float): Float
Name Type
a Float
b Float
Returns
Float
randomBetweenColors(a: Color, b: Color): Color
Name Type
a Color
b Color
Returns
Color
setEntity(entity: Entity): Void
Name Type
entity Entity
getEntity(): Entity
Returns
Entity

Metadata

Name Parameters
:build tracker.macros.ObservableMacro.build()
:autoBuild tracker.macros.ObservableMacro.build()
:build ceramic.macros.ComponentMacro.build()
:autoBuild ceramic.macros.ComponentMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()