Particle FX

Particle effects are used to visually enhance games. You can use them to create explosions, blood splatter, trails, weather or any other effect.

Particle effects consists of a number of emitters and optional modifiers:

Emitter

An emitter is a positioned shape that emits particles uniformly distributed over the shape. The emitter contains properties that controls the particle spawning as well as the image or animation, lifespan, color, shape and velocity of the individual particles.

Modifier

A modifier affects the velocity of spawned particles to make them accelerate or slow down in a particular direction, move radially or swirl around a point. Modifiers can affect a single emitter’s particles or a particular emitter.

Creating an effect

Select New... ▸ Particle FX from the context menu in the Assets browser. Name the new particle effect file. The editor will now open the file using the Scene Editor.

The Outline pane shows the default emitter. Select the emitter to bring up its properties in the Properties pane below.

To add a new emitter to the effect, right click the root of the Outline and select Add Emitter ▸ [type] from the context menu. Note that you can change the type of the emitter in the emitter properties.

To add a new modifier, right click the location of the modifier in the Outline (the effect root or a particular emitter) and select Add Modifier, then select the modifier type.

A modifier that sits on the effect root (not childed to an emitter) affects all particles in the effect.

A modifier that is added as a child to an emitter affects only that emitter.

Previewing an effect

• Select View ▸ Play from the menu to preview the effect. You may need to zoom out the camera to see the effect properly.
• Select View ▸ Play again to pause the effect.
• Select View ▸ Stop to stop the effect. Playing it again restarts it from its initial state.

When editing an emitter or modifier the result is immediately visible in the editor, even with the effect paused:

Emitter properties

Id

Emitter identifier (used when setting render constants for specific emitters).

Position/Rotation

Transform of the emitter relative the ParticleFX component.

Play Mode

Controls how the emitter plays:

• Once stops the emitter after reaching its duration.
• Loop restarts the emitter after reaching its duration.

Size Mode

Controls how flipbook animations will be sized:

• Auto keeps the size of each flipbook animation frame to the source image.
• Manual sets the particle size according to the size property.

Emission Space

Which geometrical space the spawned particles will exist:

• World moves the particles independent of the emitter.
• Emitter moves the particles relative to the emitter.

Duration

The number of seconds the emitter should emit particles.

Start Delay

The number of seconds the emitter should wait before emitting particles.

Start Offset

The number of seconds into the particle simulation the emitter should start, or in other words how long the emitter should pre-warm the effect for.

Image

The image file (Tile source or Atlas) to use for texturing and animating the particles.

Animation

The animation from the Image file to use on the particles.

Material

The material to use for shading the particles.

Blend Mode

Available blend modes are Alpha, Add and Multiply.

Max Particle Count

How many particles originating from this emitter that can exist at the same time.

Emitter Type

The shape of the emitter

• Circle emits particles from a random location inside a circle. The particles are directed outwards from the center. The circle diameter is defined by Emitter Size X.

• 2D Cone emits particles from a random location inside a flat cone (a triangle). The particles are directed out of the top of the cone. Emitter Size X defines the width of the top and Y defines the height.

• Box emits particles from a random location inside a box. The particles are directed up along the box’ local Y-axis. Emitter Size X, Y and Z defines width, height and depth respectively. For a 2D rectangle, keep the Z size at zero.

• Sphere emits particles from a random location inside a sphere. The particles are directed outwards from the center. The sphere diameter is defined by Emitter Size X.

• Cone emits particles from a random location inside a 3D cone. The particles are directed out through the top disc of the cone. Emitter Size X defines the diameter of the top disc and Y defines the height of the cone.

Particle Orientation

How the emitted particles are oriented:

• Default sets the orientation to unit orientation
• Initial Direction keeps the initial orientation of the emitted particles.
• Movement Direction adjusts the orientation of the particles according to their velocity.

Inherit Velocity

A scale value of how much of the velocity of the emitter the particles should inherit. This value is only available when Space is set to World. The velocity of the emitter is estimated every frame.

Stretch With Velocity

Check to scale any particle stretch in the direction of movement.

Blend modes

The Blend Mode property defines how the component graphics should be blended with the graphics behind it. These are the available blend modes and how they are calculated:

Alpha

Normal blending: src.a * src.rgb + (1 - src.a) * dst.rgb

Add

Brighten the background with the color values of the corresponding pixels of the component: src.rgb + dst.rgb

Multiply

Darken the background with values of the corresponding pixels of the component: src.rgb * dst.rgb

Screen

Opposite of Multiply. Brighten background and values of the corresponding pixels of the component: src.rgb - dst.rgb * dst.rgb

Keyable emitter properties

These properties have two fields: a value and a spread. The spread is a variation which is applied randomly for each spawned particle. E.g. if the value is 50 and the spread is 3, each spawned particle will get a value between 47 and 53 (50 +/- 3).

By checking the key button, the value of the property is controlled by a curve over the duration of the emitter. To reset a keyed property, uncheck the key button.

The Curve Editor (available among the tabs in the bottom view) is used to modify the curve. Keyed properties can’t be edited in the Properties view, only in the Curve Editor. Click and drag the points and tangents to modify the shape of the curve. Double-click on the curve to add control points. To remove a control point, double click on it.

To auto-zoom the Curve Editor to display all curves, press F.

The following properties can be keyed over the play time of the emitter:

Spawn Rate

The number of particles to emit per second.

Emitter Size X/Y/Z

The dimensions of the emitter shape, see Emitter Type above.

Particle Life Time

The lifespan of each spawned particle, in seconds.

Initial Speed

The initial velocity of each spawned particle.

Initial Size

The initial size of each spawned particle. If you set Size Mode to Automatic and use a flipbook animation as image source, this property is ignored.

Initial Red/Green/Blue/Alpha

The initial color component tint values for the particles.

Initial Rotation

The initial rotation values (in degrees) for the particles.

Initial Stretch X/Y

The initial stretch values (in units) for the particles.

Initial Angular Velocity

The initial angular velocity (in degrees/second) of each spawned particle.

The following properties can be keyed over the life time of the particles:

Life Scale

The scale value over each particle’s life.

Life Red/Green/Blue/Alpha

The color component tint value over each particle’s life.

Life Rotation

The rotation value (in degrees) over each particle’s life.

Life Stretch X/Y

The stretch value (in units) over each particle’s life.

Life Angular Velocity

The angular velocity (in degrees/second) over each particle’s life.

Modifiers

There are four types of modifiers available that affect the velocity of particles:

Acceleration

Acceleration in a general direction.

Drag

Reduces the acceleration of particles proportional to the particle velocity.

Radial

Either attracts or repels particles towards/from a position.

Vortex

Affects particles in a circular or spiraling direction around its position.

Modifier properties

Position/Rotation

The transform of the modifier relative its parent.

Magnitude

The amount of effect the modifier has on the particles.

Max Distance

The maximum distance within which particles are affected at all by this modifier. Only used for Radial and Vortex.

Controlling a particle effect

To start and stop a particle effect from a script:

-- start the effect component "particles" in the current game object
particlefx.play("#particles")

-- stop the effect component "particles" in the current game object
particlefx.stop("#particles")

See the Particle FX reference documentation for more information.

Material constants

The default particle effect material has the following constants that can be changed using particlefx.set_constant() and reset using particlefx.reset_constant() (refer to the Material manual for more details):

tint

The color tint of the particle effect (vector4). The vector4 is used to represent the tint with x, y, z, and w corresponding to the red, green, blue and alpha tint. Refer to the API reference for an example.

Project configuration

The game.project file has a few project settings related to particles.