Particles

Entity → Visual → ceramic.Particles (Class)

A visual container that manages a particle emitter with convenient automatic emission modes.

Particles extends Visual to provide a high-level wrapper around ParticleEmitter, adding features like automatic continuous emission and timed burst intervals. This makes it easier to create self-contained particle effects that can be added to the scene and configured with minimal code.

The class is generic, allowing use of custom ParticleEmitter subclasses for specialized particle behaviors.

Key features:

Automatic continuous emission with autoEmit
Automatic burst intervals with autoExplodeInterval
Forwards all emitter properties with emitter* prefix
Lifecycle management - destroying particles destroys the emitter

// Create auto-emitting smoke
var smoke = new Particles();
smoke.autoEmit = true;
smoke.emitterInterval = 0.05;
smoke.emitterLifespan(0.5, 1.0);
smoke.emitterSpeedStart(50, 100);
smoke.emitterAlphaEnd(0);
scene.add(smoke);

// Create periodic explosions
var explosions = new Particles();
explosions.autoExplodeInterval = 2.0; // Every 2 seconds
explosions.autoExplodeQuantity = 50;
explosions.emitterSpeedStart(100, 300);
scene.add(explosions);

// Use custom emitter
var custom = new Particles(new MyCustomEmitter());

See: ParticleEmitter The underlying emitter being managed, ParticleItem Individual particle data

Instance Members

emitter: ceramic.Particles.T

The particle emitter managed by this visual.

Can be accessed directly for advanced configuration or to call methods like explode() and emitParticle(). Most common properties are also exposed with emitter* prefix.

autoEmit: Bool

Whether to automatically emit particles continuously.

When set to true, starts continuous emission using emitterInterval. When set to false, stops emission (existing particles continue).

Default: false

particles.emitterInterval = 0.1; // Configure interval first
particles.autoEmit = true; // Start emitting

autoExplodeInterval: Float

Interval in seconds between automatic burst emissions.

When set to a positive value, triggers burst emissions of autoExplodeQuantity particles at regular intervals. Set to -1 to disable automatic bursts.

Default: -1 (disabled)

// Burst 30 particles every 1.5 seconds
particles.autoExplodeQuantity = 30;
particles.autoExplodeInterval = 1.5;

autoExplodeQuantity: Int

Number of particles to emit in each automatic burst.

Used with autoExplodeInterval to create periodic bursts. Only takes effect when autoExplodeInterval is positive.

Default: 64

See: autoExplodeInterval

emitterPaused: Bool

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

emitterInterval: Float

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

emitterLaunchMode: Anonymous

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

emitterVisualScaleActive: Bool

Apply particle scale to underlying visual or not.

emitterKeepScaleRatio: Bool

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

emitterVisualColorActive: Bool

Apply particle color to underlying visual or not.

emitterVisualAlphaActive: Bool

Apply particle alpha to underlying visual or not.

emitterVisualPositionActive: Bool

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

emitterVisualRotationActive: Bool

Apply particle angle to underlying visual rotation or not.

emitterWidth: Float

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

emitterHeight: Float

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

emitterX: Float

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

emitterY: Float

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

emitterVelocityActive: Bool

Enable or disable the velocity range of particles launched from this #if cs (cast emitter:ParticleEmitter) #else emitter #end. Only used with SQUARE.

emitterMaxVelocityX: Float

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

emitterMaxVelocityY: Float

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

emitterVelocityStartMinX: Float