Manual
Manual
Particle Emitter
A Particle Emitter sends out particles: fire, smoke, sparks, dust, debris. Each particle lives a while, moves, and is drawn as a small picture facing the camera, as a ribbon, or as a mesh. This page covers making an emitter, every section and module of its Inspector, the curves and gradients its numbers can follow, collisions, sub-emitters, trails of particles, the preview in the Scene view, and playing emitters from code.
Make an emitter
- Entity ▸ Effects ▸ Particle Emitter, or the same item in the Hierarchy's + menu, makes an emitter sending white particles up out of a cone, in 3D.
- Entity ▸ Effects ▸ Particle Emitter 2D makes one drawn flat among sprites, sized for a 2D camera: smaller particles, slower and shorter-lived, from a smaller cone.
- Add Component puts one on any entity.
A new emitter plays five-second cycles, looping. It sends out ten particles a second at five units a second, each a unit across, living five seconds, a thousand at most.
The Scene view marks an emitter with a sparkle, and a click on it picks the entity. While it is picked, its shape is drawn in its entity's space and scale, and its dots drag the shape's size: a cone's radius and angle, a sphere's radius, a box's sides, a circle's arc, an edge's ends. Each drag is one Ctrl+Z. A picked emitter also plays in the Scene view while you edit; see Preview in the Scene view.
Particles are moved by the engine on the CPU, which suits effects of up to tens of thousands of particles.
Particle Emitter
The emitter's section in the Inspector is in parts, each a heading that folds: Main, Emission and Shape; a module for each thing that changes over a particle's life; Sub Emitters; and Renderer. A module's heading has a box: ticking it puts the module on the emitter, starting as such a module usually starts, and clearing it takes the module off. An emitter pays nothing for a module that is off.
Many of the emitter's numbers have a ▾ at the right end of their row, which chooses what kind of number they are: one value, one picked between two, or a curve. See Numbers that change: curves and gradients.
The Collision, External Forces, Sub Emitter and Trails modules have sections of their own further down: Collisions, Moved by force fields, Sub-emitters and Trails of particles.
Main
| Field | What it does |
|---|---|
| Duration | How long one cycle is, in seconds. |
| Looping | Starts another cycle as one ends, until the emitter is stopped. |
| Prewarm | Starts as if a whole cycle had gone by already, so a looping fire is burning from its first frame. Looping emitters only. |
| Start Delay | How long it waits before sending anything out, in seconds. |
| Start Lifetime | How long a particle lives, in seconds. |
| Start Speed | How fast a particle goes out, in units a second. |
| Start Size | How big a particle is across, in units. |
| 3D Start Size | Gives the size along X, Y and Z apart, as Start Size X, Y and Z: a square X wide and Y tall, so a texture that is not square is not squashed. Only a mesh has a depth along Z. |
| Start Rotation | How far a particle is turned on its face, in degrees. |
| 3D Start Rotation | Shown while particles are drawn as a mesh: turns it about X and Y as well as Z. |
| Start Color | The color a particle starts with, and how opaque. |
| Gravity Modifier | How much gravity pulls particles down: 1 is 9.81 units a second every second, along the world's −Y. |
| Simulation Space | Local: particles go where the emitter goes, as the flame of a carried torch. World: they stay where they came out, as the smoke behind a car. |
| Simulation Speed | How fast the emitter's time runs: 1 as the game's does. |
| Max Particles | The most it has out at once. Past it, none is sent out until one goes. |
| Play On Awake | Plays as play starts, or as the emitter is spawned while the game plays. |
The numbers a particle starts with (its lifetime, speed, size, rotation, color and gravity) are read along the emitter's cycle as each particle is sent out, so a curve over them changes what later particles start as.
Ticking a 3D box changes nothing at first: a size's axes start as the size is, and a turn's axes start unturned.
Emission
| Field | What it does |
|---|---|
| Rate over Time | How many particles it sends out a second. |
| Rate over Distance | How many it sends out for every unit the emitter moves: a trail behind something moving. |
| Bursts | Particles sent out at once, at times through each cycle. |
Bursts is a list, a line for each burst: its Time from the cycle's start in seconds, its Count, how many Cycles it repeats (1 once, 0 for as long as the cycle goes on, shown as ∞), and the Interval between repeats. The + at the right of the row adds a burst of 30 at the cycle's start, and the × on a line takes it away.
Shape
Shape is where particles come from and which way they go, in the emitter's own space. Up is the entity's +Y. Pick a shape from the list, and its fields show under it:
| Shape | Its fields | Sends particles |
|---|---|---|
| Cone | Angle 25, Radius 1, Thickness 1 | From a disc, outward and up, as from a nozzle. Angle is how far from straight up it opens at its rim, in degrees. |
| Sphere | Radius 1, Thickness 1 | Outward from a ball. |
| Hemisphere | Radius 1, Thickness 1 | Outward from a ball's upper half. |
| Box | Width 1, Height 1, Depth 1 | Up, from inside a box. |
| Circle | Radius 1, Thickness 1, Arc 360 | Outward from the middle of a disc in the XY plane. Arc is how much of the way round, in degrees from +X toward +Y. |
| Edge | Length 2 | Up, from a line along X. |
Thickness is how much of the shape sends particles, in from its surface or rim: 1 all of it, 0 its surface alone. Randomize Direction turns each particle's way out toward a random one: 0 not at all, 1 all the way.
An emitter drawn flat has every shape in its XY plane, where a 2D game is: a cone is a fan, a sphere a circle, a hemisphere its upper half, and a box a rectangle.
Velocity over Lifetime and Force over Lifetime
Velocity over Lifetime adds a speed to each particle along X, Y and Z, in units a second. Force over Lifetime speeds each particle up along them, in units a second every second. Each axis is a number of any kind, read along the particle's life. Space says whose axes they are: the emitter's (Local) or the world's (World).
Color over Lifetime
Color is the particle's color over its life, multiplying its Start Color. It starts as a gradient from white to clear, so particles fade out.
Size over Lifetime
Size multiplies the particle's start size over its life. It starts as a curve from 1 down to 0, so particles shrink away. Separate Axes gives X, Y and Z apart.
Rotation over Lifetime
Angular Velocity is how fast a particle turns on its face, in degrees a second. It starts at 45. Separate Axes, shown while particles are drawn as a mesh, gives the turn about X, Y and Z apart.
Noise
Noise moves particles about along a smooth field that drifts, as smoke and fire are moved. Particles near each other move alike.
| Field | What it does |
|---|---|
| Strength | The most it moves a particle each second, in units. |
| Frequency | How fine it is: how many times it changes way across a unit. |
| Scroll Speed | How fast the field drifts. |
Texture Sheet Animation
The emitter's texture cut into a grid of tiles, each particle showing one tile at a time: flames, smoke and explosions drawn frame by frame, or a different picture for each particle.
| Field | What it does |
|---|---|
| Tiles X, Tiles Y | How many tiles across and down. It starts at two by two. |
| Animation | Whole Sheet: every tile, a row at a time from the top left. Single Row: the tiles of the row named by Row, 0 the top one. Random Row: the tiles of one row, picked for each particle. |
| Time Mode | Lifetime: through the tiles over each particle's life. FPS: at so many frames a second from its birth, round and round, however long it lives. |
| Frame over Time | Lifetime: how far through its tiles a particle is over its life, 0 at the first, 1 at the end of the last. It starts as a straight rise. |
| Frames per Second | FPS: how many tiles a second. |
| Start Frame | The tile a particle starts on, counted from the first. |
| Cycles | Lifetime: how many times a particle goes through its tiles over its life. |
Renderer
How particles are drawn.
| Field | What it does |
|---|---|
| Render Mode | Billboard: a square facing the camera. Stretched: drawn out along the way it goes, for sparks, rain and streaks. Horizontal Billboard: lying flat, facing up, for ripples and scorch marks. Vertical Billboard: upright, turned toward the camera about the up axis only. Mesh: each particle a copy of a mesh. |
| Mesh | Mesh mode: the mesh each particle is. Drop a model on the slot for its first mesh, or pick one of the engine's built-in meshes or a model's with the button. None draws nothing. |
| Speed Scale, Length Scale | Stretched: a particle is drawn as long as its height times Length Scale, plus its speed times Speed Scale. |
| Material | In 3D, a material file the particles are drawn with in place of their texture and blending. |
| Texture | The picture each particle is drawn with: a soft white dot (Soft Dot) until you give it one. Drop an image on the slot, or pick one of the engine's shapes or the project's images with its button. |
| Blending | Alpha: over what is behind, as far as each is opaque (smoke, dust). Additive: added to what is behind, so particles glow where they overlap (fire, sparks, magic). Opaque: solid, the nearest drawn wherever particles cross, cut away where the texture is less than half opaque (debris, leaves). |
| Trail Texture, Trail Material | With the Trails module on, what trails are drawn with; see Trails of particles. |
| Flat | Drawn among sprites by a 2D camera, rather than in 3D facing the camera. |
| Sorting Layer, Order in Layer | Flat: where the particles are drawn among sprites, as a sprite's are (see Sprites). A higher order is drawn over a lower one. |
A Material is a .mat file. A material of the standard surface draws particles lit or unlit, textured and blended as its alpha mode says, as it draws a mesh. A material running your game's own shader is handed what a mesh's fragment shader is handed, and its output is blended premultiplied: it says how opaque each pixel is, and adds light where it gives no opacity, unless its Transparency says otherwise. With a material, Texture and Blending are hidden. A flat emitter has no Material, since a 2D camera draws none. See Meshes and materials and Shaders.
A Mesh particle is sized along all three axes and turned about all three, lit by its mesh's own normals, and shows its texture, or its tile of a sheet, by the mesh's UVs: debris, shards, leaves, coins.
Numbers that change: curves and gradients
A number with a ▾ at its right is one of four kinds, picked from that menu:
| Kind | What it is |
|---|---|
| Constant | The same for every particle. |
| Random Between Two Constants | Picked for each particle, evenly, between the two values its row shows. |
| Curve | A value along a curve. |
| Random Between Two Curves | Picked for each particle between two curves, where it stays as it follows them. |
A color with a ▾ is the same four kinds, with colors and gradients: Color, Random Between Two Colors, Gradient and Random Between Two Gradients. Two colors and two gradients are mixed in linear light.
A curve or a gradient goes along a particle's life for a value that changes over its life, and along the emitter's cycle for a value a particle starts with. Changing the kind keeps what it can: a constant becomes a flat curve, two values a curve rising from the least to the most, a curve its starting value.
The curve editor
The row shows the curve small. Click it to open the curve editor under the row, or above it where the screen ends.
- The grid goes across the particle's life, or the cycle, and up from its Bottom to its Top, both typed or dragged. Changing them changes the curve's values and keeps its shape: a curve from 0 to 1 given a bottom of 4.2 and a top of 10.2 goes from 4.2 to 10.2. Fit puts the grid round the curve as it is. The grid's lines are labeled with their values.
- A key is picked by pressing it. Dragged a few pixels, it moves with the pointer, kept between the keys on either side and inside the grid, and Ctrl keeps it to the grid's lines. A picked key shows its handles: drag one to tilt the curve as it leaves or reaches the key, and to set how far the curve keeps to that tilt.
- The key's line, under the grid, types its time and value, picks how its handles are worked out, and deletes it. Auto is smooth and never overshoots the keys either side; Free Smooth, Flat and Broken (its two handles apart) follow the handles; Linear goes straight to the next key; Constant holds its value until the next key.
- Double-click the grid to add a key. Right-click a key for its modes and Delete Key, or anywhere else for Add Key. Delete deletes the picked key.
- Flat, Rise, Fall, Ease and Hump replace the curve with that shape between the grid's bottom and top.
For Random Between Two Curves, Least and Most choose which of the two you edit, and the area between them is shaded.
The gradient editor
A gradient opens the same way. A mark under each key shows its color. Click a mark to open its color in the Inspector's color picker, or drag it to move the key. Click the gradient itself to add a key of the color there, and right-click a mark to remove it. The line under the gradient holds the picked key's color, its time and a delete button, and Delete deletes it too.
Collisions
With the Collision module on, particles meet surfaces and bounce off them. Its Mode says what they meet:
- Planes: every Particle Plane in the scene.
- World: the scene's colliders, through a physics package.
In either mode, each frame a particle's move is followed from where it was to where it went, as a ball as wide as the particle times Radius Scale, and the first surface it reaches is where it stops:
| Field | What it does |
|---|---|
| Dampen | How much of all its speed it loses as it meets a surface: 0 none, 1 all. |
| Bounce | How much of what it was moving into the surface it is sent back with: 0 stops it, 1 sends it back as fast as it came. It starts at 1. |
| Lifetime Loss | How much of its life it loses as it meets a surface: 0 none, 1 all. |
| Min Kill Speed | A particle left slower than this, in units a second, goes at once. |
| Max Kill Speed | A particle left faster than this goes at once. |
| Radius Scale | How wide a particle is as it meets a surface, times its size: 1 is half its size each way. |
Dampen, Bounce and Lifetime Loss are numbers of any kind, read along each particle's life.
Meeting the world's colliders
In World mode, two more rows appear. Collides With names the layers whose colliders particles meet. Collide With names the physics package: Auto, followed by the package it finds, meets Physics 2D's colliders for an emitter drawn flat and Physics 3D's for one that is not. You can also name a package, and one named but not installed is shown as such and met by nothing.
The physics packages keep worlds of their own in step with the scene while you edit it, never stepped, so particles meet the scene's colliders in the Scene view as they will while the game plays. See Bodies and colliders and Physics 3D bodies.
Particle Plane
A Particle Plane is a surface particles meet in Planes mode, without any physics package. Entity ▸ Effects ▸ Particle Plane makes one.
| Field | What it does |
|---|---|
| Size | How big it is along its entity's X and Z, in units, times its entity's scale. It starts at 10 by 10. |
| Infinite | Goes on for ever, whatever its size. |
The plane is its entity's XZ plane, facing its +Y. It is met from either side. Every emitter whose Collision module is in Planes mode meets every plane in the scene, and an entity switched off is met by none. Turned on its edge in the XY plane, a plane is a line that flat particles meet.
The Scene view marks a plane with a rectangle icon, and draws it and the way it faces while it is picked.
Moved by force fields
With the External Forces module on, the Particle Force Fields a particle passes through push, pull, swirl and slow it. Multiplier is how strongly they act, and Influenced By names the layers whose fields act on this emitter. An emitter without the module is moved by no field.
Sub-emitters
A sub-emitter is an emitter that plays at what another emitter's particles do: a firework's trail, a splash where rain lands, sparks where a shot dies. It is an ordinary Particle Emitter on an entity under the other, with the Sub Emitter module on. It belongs to the nearest emitter above it, and never plays of its own accord: not as play starts, nor when your code plays it.
The Sub Emitter module
| Field | What it does |
|---|---|
| Trigger | What the parent's particles do to fire it. Birth: as each is sent out, a cycle that follows the particle for as long as it lives, sending out by its rate over time and over distance. Collision: as one meets something, one cycle where it met it. Death: as one's life ends, one cycle where it ended. |
| Emit Probability | How often a trigger fires it: 1 every time, 0.5 half the time. |
| Inherit | Ticks for Color, Size, Rotation and Lifetime: its particles start with the particle's color and size multiplying theirs, its turn added to theirs, and its lifetime multiplying theirs. |
| Inherit Velocity | How much of the particle's velocity its particles start with, added to their own. |
Each firing plays a cycle of the sub-emitter from its start, its shape where the particle is, turned and sized as its own entity is. A Collision or Death cycle plays once whatever Looping says, so most such sub-emitters are a burst at their start. While the module is on, Play On Awake and Prewarm are hidden.
The Sub Emitters list
Every emitter has a Sub Emitters part listing its sub-emitters, each by its trigger and its name; a click picks it. Add Sub Emitter makes one under the emitter for the trigger you pick, starting as such a one usually does: a trail along the particle's way for Birth, a splash up off what it met for Collision, and a burst every way for Death. Its particles are in the world, and it is flat and smaller under a flat emitter.
Picked in the Scene view, a sub-emitter plays its whole effect, from the emitter at its top. Your code finds an emitter's sub-emitters with world.Particles.SubEmitters(entity).
Trails of particles
With the Trails module on, ribbons are drawn with the particles. Its Mode says how:
- Particle: each particle leaves a trail of where it has been.
- Ribbon: one ribbon goes through the particles, from the newest to the oldest.
| Field | What it does |
|---|---|
| Ratio | Particle: the share of particles that leave a trail, from 0 to 1. |
| Lifetime | Particle: how long each point of a trail lasts, as a share of its particle's lifetime. It starts at 0.25. |
| Minimum Vertex Distance | Particle: how far a particle goes before its trail gets another point, in units. Less is smoother and costs more. |
| Die with Particles | Particle: a trail goes as its particle dies. Off, it fades out after it as its points do. |
| Ribbon Count | Ribbon: how many ribbons there are, each particle on one of them in turn. |
| Texture Mode | Stretch: the texture once from head to tail. Tile: again and again, once every Tile Length units. |
| Size Affects | Width: a trail is as wide as its particle, times Width over Trail. Lifetime: a trail's points last longer on a bigger particle. |
| Inherit Particle Color | A trail is its particle's color, times its own. |
| Color over Lifetime | The trail's color over its particle's life. |
| Width over Trail | How wide it is from its head to its tail. It starts narrowing from 1 to 0. |
| Color over Trail | Its color from its head to its tail. It starts fading from white to clear. |
Trails have a texture of their own, Trail Texture in the Renderer part: a soft streak (Soft Streak) until you give it one. In 3D they can have a Trail Material too. Either can be Same as Particles, the emitter's own. In 3D a trail turns to face the camera about the way it goes. Flat, it lies among sprites at its emitter's sorting layer and order, just under its own particles.
The ribbons are drawn the same way as a Trail component's, which leaves one ribbon behind a moving entity.
Preview in the Scene view
While you edit the game, the emitters on the picked entities, and on every entity under them, play in the Scene view. Each plays from its start whatever Play On Awake says, so an effect made of several emitters is seen together as you build it, and changes as you change its Inspector.
An overlay in the Scene view's bottom right corner controls the preview:
| Control | What it does |
|---|---|
| Play / Pause | Holds the particles where they are, or lets them play on. An effect that has played out plays again from its start. |
| Restart | Starts them again from nothing, playing. |
| Stop | Takes every particle away and holds them at their start, for Play to play them from. |
| Playback Time | How long they have played, held while paused. |
| Particles | How many are out. |
Nothing of the preview is saved. As play starts, the game's own particles begin afresh, as its emitters say.
Emitters from code
While the game plays, an emitter plays on its own if Play On Awake is ticked, and every particle goes as play stops. A game's C# plays, stops and emits through world.Particles:
// fire is an entity with a Particle Emitter.static void Drive(World world, ulong fire){ world.Particles.Play(fire); // starts a cycle, unless one is going on world.Particles.Stop(fire); // sends no more out; those out live out their lives world.Particles.Stop(fire, clear: true); // and takes them all away at once world.Particles.Emit(fire, 20); // twenty at once, playing or not, as far as Max Particles allows
ParticleState state = world.Particles.StateOf(fire); // as of the last frame if (!state.Playing && state.Count == 0) { // it has played out }}What you ask is done on the next frame the game plays, in the order you asked. The calls are safe from any system.
This plugin bursts sparks from every entity with a Sparks component when the player presses Jump, an action of the game's input settings (see Actions):
using Abyss.Core;using MyGame;
[assembly: AbyssPlugin<SparksPlugin>]
namespace MyGame;
[AbyssComponent]public partial struct Sparks{ public int Count = 20;}
public sealed class SparksPlugin : IPlugin{ public void Build(Schedule schedule) { World world = schedule.World; ComponentType<Sparks> sparks = world.Component<Sparks>();
schedule.Add("Sparks", [sparks.Read()], context => { if (!context.Input.Pressed(Actions.Player.Jump)) { return; }
foreach (Chunk chunk in context.Chunks) { ReadOnlySpan<Sparks> each = chunk.GetReadOnlySpan<Sparks>(0); ReadOnlySpan<ulong> entities = chunk.Entities; for (int row = 0; row < entities.Length; row++) { world.Particles.Emit(entities[row], each[row].Count); } } }); }}Read the particles
world.Particles.Read(entity) returns the emitter's particles as of the last frame, each a Particle in the world's space: its Position, its Velocity in units a second, its Age and Lifetime in seconds, its Size along X, Y and Z, and its Color, linear, with alpha. To read without allocating, pass a span: Read(entity, span) fills it and returns how many particles there are, which may be more than it holds.
From Rust
A game's Rust systems take GameParticles from abyss_ffi, which does the same through play, stop, emit and state:
use abyss_ffi::GameParticles;
use bevy_ecs::prelude::*;
#[derive(Component)]
struct Lit;
fn ignite(particles: GameParticles, lit: Query<Entity, Added<Lit>>) {
for entity in &lit {
particles.play(entity);
}
}See Rust in a game for adding Rust systems.
Colliders from another physics package
Particles meet a physics package's colliders through a registration any package can make, as Physics 2D and Physics 3D do. world.Particles.RegisterColliders(id, name, flat, cast, context) registers a native function the engine calls once a frame for each emitter in World mode, with every particle's move, its radius and the layers asked about, to write what each met first. The contract has its own version, WorldParticles.CollidersVersion, apart from the engine's. world.Particles.Colliders lists the packages registered. See WorldParticles for the function's signature.
In the Scripting API
- WorldParticles: emitters played, stopped, emitted from and read.
- Particle and ParticleState: one particle, and how an emitter was as of the last frame.
- ParticleSubEmitter and SubEmitterTrigger: an emitter's sub-emitters and what fires them.
- ParticleColliderProvider, ParticleCast and ParticleHit: a physics package's colliders, as particles meet them.
