Particles

Fire, smoke, sparks, dust, rain and magic are made of many small things that appear, move and fade. A Particle Effect asset describes them, and a Particle Effect component plays one at an entity.

Making an effect

New > Particle Effect makes an effect with one system that already sends particles up like a fountain and lets them fall. Double-click it to open its page, which has three panes:

• On the left, a tree of the effect’s systems. Under each system are its Emitter, its Initializers, its Behaviors and its Sub-emitters.
• In the middle, a live preview. Its bar has Frame, Restart, Play (Pause while it plays) and Stop, the count of particles alive, and a Speed slider for the preview only, which is not saved. The chosen system’s emission shape is drawn over the preview.
• On the right, the settings of what is selected in the tree.

An effect is one or more systems, each a kind of particle: a campfire might have flames, smoke and sparks. The System button above the tree adds a system, as does Add System when you right-click a system. A new system starts as the same fountain.

What a system draws

Select a system to see its settings:

• Render Mode: Billboard (flat pictures facing the camera, the usual choice), Stretched Billboard (stretched along their motion, for sparks and rain), Horizontal Billboard or Vertical Billboard (lying flat, or standing up), Mesh (a small mesh for each particle, for debris or leaves), Trail (a ribbon behind each particle) or Light (each particle is a small light, for fireflies and embers).
• Texture, for the billboards and trails, and Blend Mode: Alpha, Additive (glows that add up, for fire and magic), Premultiplied or Multiply.
• Mesh, Mesh Scale and Materials, for Mesh. The materials follow the mesh’s material slots.
• Flipbook, for the billboards: turn on Enabled to play a sheet of frames on each particle, set its Columns and Rows, and play the sheet once over each particle’s life (Over Lifetime) or at a Frame Rate.
• Trail, for Trail: how many points it keeps, how long a point takes to fade, its width at the start and the end, and its colour.
• Max Particles: the most alive at once.
• Space: World, so particles stay where they were made as the entity moves (smoke behind a car), or Local, so they move with it.
• Sort Particles: draw Alpha particles back to front, so nearer ones cover farther ones.
• Soft Particles (on by default): particles fade over Soft Distance where they meet surfaces, instead of cutting a hard line.
• Prewarm Time: seconds the system runs before it shows, so a fire is already burning when the scene opens.
• Distance: the spawn rate falls from Fewer From down to Fewest (a fraction of the rate) at its farthest, and the system is not drawn past Hidden From. A distance of 0 turns each off.

When particles appear

Select the Emitter:

• Mode: Continuous emits Spawn Rate particles a second. Burst emits Burst Count at once, every Burst Interval seconds (0 bursts once), Burst Cycles times (0 bursts without end). Continuous And Burst does both.
• Duration: seconds it emits (0 emits without end), and Looping to emit for the duration again and again.
• Emits: turn it off for a system that only receives particles from another system’s sub-emitter.

Initializers: how each particle starts

Right-click a system’s Initializers to add one:

• Position: where in the emission Shape it starts. Shapes are Point, Sphere, Hemisphere, Box, Cone, Ring, Circle and Edge; spheres, hemispheres and circles can emit from their surface only.
• Velocity: a Base Velocity, a Randomness added on each axis, a speed along the shape’s direction, and a share of the emitter’s own velocity.
• Lifetime: how long it lives, picked between a minimum and a maximum.
• Color, Size and Rotation, each also a range, and Mesh Orientation for meshes.

Behaviors: how each particle changes

Right-click a system’s Behaviors to add what acts on its particles as they live:

• Forces: Gravity, Drag, Wind, Turbulence, Vortex, Attractor and Radial Force.
• Collision, bouncing off planes, spheres and boxes, with Bounce, Friction and the share of its life a hit takes (Lifetime Loss).
• Changes over each particle’s life: Color over Lifetime, Alpha over Lifetime, Size over Lifetime, Rotation over Lifetime and Speed over Lifetime. Shape these with the curve in the settings, or for colour the gradient.

Initializers and behaviors run in order. Right-click one for Move Up, Move Down and Delete.

Sub-emitters

A system can spawn particles into another system as its own particles are born or die: sparks that burst where a firework shell dies, for example. Add a link in the system’s Sub-emitters list in the settings, then set when it fires (On Birth or On Death), the system it spawns Into, how many it spawns, and the chance it spawns at all. The new particles can start where the particle was, with part of its velocity and with its colour. Turn off Emits on the receiving system so it shows only what is spawned into it.

Playing an effect

Give an entity Add Component > Particle Effect and set its Effect. It plays at once, in the editor too. The component can also set the Mesh and Material used by a Mesh system whose effect names none, a Mesh Scale, the Light Intensity and Light Range of Light particles, and whether it is Visible.

From a script:

Luau

function Torch:onTriggerEnter(other)
    SceneParticles.of(self.entity.scene):restart(self.entity) -- a burst of sparks
end

AngelScript

void onTriggerEnter(Entity@ other)
{
    SceneParticles::of(self.scene).restart(self); // a burst of sparks
}

• play(entity) starts emitting; stop(entity) stops, and lets what is alive fade out.
• restart(entity) clears it and plays it again from the start, which fires a burst again.
• pause(entity, true) freezes it, live particles too; pause(entity, false) lets it go on.
• isPlaying(entity) is true while it emits or anything is alive.
• setEffect(entity, id) swaps the effect for the one with that asset ID (a Guid).

Each entity plays its own copy of the effect. To make a burst at a place, spawn a prefab with the effect there.