EmitterObject

Parent DisplayObject
Library display.*
Revision Release 2024.3703
Keywords EmitterObject
See also display.newEmitter()
EmitterObject:start()
EmitterObject:stop()
EmitterObject:pause()

Overview

This object is used to display particle effects.

See the display.newEmitter() documentation for details about creating a new emitter.

Note

To modify the appearance of an emitter object, specific parameters can be set/modified directly as properties of the object — see the properties section below for a list of valid emitter properties.

Functions

(Inherits methods from DisplayObject)

Properties

(Inherits properties from DisplayObject)

Emitter — General

These properties relate to general emitter behavior.

Property Description
state String value (read-only) which indicates the playing state of the emitter. Values include "playing", "stopped", or "paused", based on the result of the emitter functions listed above.
textureFileName String indicating the file (image) used for emitted particles. This file can not be changed dynamically following creation of the emitter via display.newEmitter().
maxParticles Number which limits the amount of particles that can be emitted at any given time. Excessively high values may impact performance on some devices. This is a read-only property.
angle Number indicating the angle, in degrees, of particle emission. Note that this value must be adjusted by -90 (degrees) to account for Solar2D's coordinate system (0 degrees pointing directly up) — for example, if you want the particles to be emitted directly upward, set this to -90.
angleVariance Number indicating the variance on the angle of particle emission (angle).
emitterType Number indicating the emitter type. Set this to 0 for a point/line/field emitter — sometimes referred to as a "gravity" type emitter — or 1 for a radial emitter. For each type, additional unique properties apply as indicated in the following sections.
absolutePosition Boolean or GroupObject indicating how the generated particles should behave in relation to the emitter. If true, all particles are independent of the emitter. If the emitter orientation/angle changes, all particles will continue their transformations independently. If false, particles will move relative to the emitter if its orientation/angle changes. If set to GroupObject particles will transform following the specified parent group. For example, if set to the background group and the whole background is moved, particles will move with the background. The group must be in the parent chain of the emitter. If the emitter is removed from the group, this setting will change to true. Group can only be assigned after emitter is created.
duration Number indicating the duration in seconds for which the emitter should emit particles. A value of -1 indicates endless emission.

Emitter — Point/Line/Field

These properties are intended for emitters where particles should originate from a point, line, or rectangular field relative to the origin. For this emitter type, the emitterType property should be set to 0.

Property Description
speed Number indicating the speed at which the particles should be emitted.
speedVariance Number indicating the variance on the particle emission speed (speed).
sourcePositionVariancex Number which extends the horizontal range of particle emission outward from the emitter's origin.
sourcePositionVariancey Number which extends the vertical range of particle emission outward from the emitter's origin.
gravityx Number for the implied particle gravity along the x axis.
gravityy Number for the implied particle gravity along the y axis.
radialAcceleration Number which, when positive, causes particles to accelerate radially outward from the emitter's origin. When negative, produces an inward acceleration toward the origin.
radialAccelVariance Number indicating the variance on radial acceleration (radialAcceleration).
tangentialAcceleration Number indicating the tangential acceleration of particles relative to the emitter's origin.
tangentialAccelVariance Number indicating the variance on tangential acceleration (tangentialAcceleration).

Emitter — Radial

These properties are intended for emitters where particles should originate in a radial orientation relative to the origin. For this emitter type, the emitterType property should be set to 1.

Property Description
maxRadius Number indicating the maximum radius outward from the emitter's origin at which particles may originate.
maxRadiusVariance Number indicating the variance on the maximum emission radius (maxRadius).
minRadius Number indicating the minimum radius outward from the emitter's origin at which particles may originate.
minRadiusVariance Number indicating the variance on the minimum emission radius (minRadius).
rotatePerSecond Number indicating the radial rotation of particles in degrees per second.
rotatePerSecondVariance Number indicating the variance on the radial rotation of particles (rotatePerSecond).

Particles — General

These properties control general per-particle behavior.

Property Description
particleLifespan Number indicating the lifespan of an individual particle in seconds. After this duration, the particle will automatically be removed from the screen.
particleLifespanVariance Number indicating the variance on an individual particle's lifespan (particleLifespan).
startParticleSize Number indicating the initial size of each particle.
startParticleSizeVariance Number indicating the variance on the initial size of each particle (startParticleSize).
finishParticleSize Number indicating the ending size of each particle.
finishParticleSizeVariance Number indicating the variance on the ending size of each particle (finishParticleSize).
rotationStart Number indicating the initial rotation of the particle.
rotationStartVariance Number indicating the variance on the initial rotation of the particle (rotationStart).
rotationEnd Number indicating the ending rotation of the particle.
rotationEndVariance Number indicating the variance on the ending rotation of the particle (rotationEnd).

Particles — Color/Alpha

These properties control the starting and ending color channel values of individual particles.

Property Description
startColorRed Number for each particle's initial red color channel value. Valid range is 0 to 1.
startColorGreen Number for each particle's initial green color channel value. Valid range is 0 to 1.
startColorBlue Number for each particle's initial blue color channel value. Valid range is 0 to 1.
startColorAlpha Number for each particle's initial alpha channel value. Valid range is 0 to 1.
startColorVarianceRed Number for the variance on each particle's initial red color channel value (startColorRed). Valid range is 0 to 1.
startColorVarianceGreen Number for the variance on each particle's initial green color channel value (startColorGreen). Valid range is 0 to 1.
startColorVarianceBlue Number for the variance on each particle's initial blue color channel value (startColorBlue). Valid range is 0 to 1.
startColorVarianceAlpha Number for the variance on each particle's initial alpha channel value (startColorAlpha). Valid range is 0 to 1.
finishColorRed Number for each particle's ending red color channel value. Valid range is 0 to 1.
finishColorGreen Number for each particle's ending green color channel value. Valid range is 0 to 1.
finishColorBlue Number for each particle's ending blue color channel value. Valid range is 0 to 1.
finishColorAlpha Number for each particle's ending alpha channel value. Valid range is 0 to 1.
finishColorVarianceRed Number for the variance on each particle's ending red color channel value (finishColorRed). Valid range is 0 to 1.
finishColorVarianceGreen Number for the variance on each particle's ending green color channel value (finishColorGreen). Valid range is 0 to 1.
finishColorVarianceBlue Number for the variance on each particle's ending blue color channel value (finishColorBlue). Valid range is 0 to 1.
finishColorVarianceAlpha Number for the variance on each particle's ending alpha channel value (finishColorAlpha). Valid range is 0 to 1.

Particles — Blend Modes

These properties allow you to control how the source and destination factors are used in the blending calculation of particles. They follow the blend factors discussed in the OpenGL-ES 2 specification.

Property Description
blendFuncSource Number indicating the source color written by the fragment shader. When specifying this property for your emitter, enter the value from the list below, not the string name of the blend operation.
blendFuncDestination Number indicating the destination color from the image in the framebuffer. When specifying this property for your emitter, enter the value from the list below, not the string name of the blend operation.

Value Blend Operation
0 GL_ZERO
1 GL_ONE
774 GL_DST_COLOR
775 GL_ONE_MINUS_DST_COLOR
770 GL_SRC_ALPHA
771 GL_ONE_MINUS_SRC_ALPHA
772 GL_DST_ALPHA
773 GL_ONE_MINUS_DST_ALPHA
776 GL_SRC_ALPHA_SATURATE
768 GL_SRC_COLOR
769 GL_ONE_MINUS_SRC_COLOR