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`