Manual
Manual
Trail
A Trail is a ribbon left behind its entity as it moves: a sword's swing, a bullet, a dash, a comet. This page covers making one, its fields, how it behaves while you edit, and driving it from code.
Make a trail
- Entity ▸ Effects ▸ Trail, or the same item in the Hierarchy's + menu, makes one in 3D: half a unit wide, each point lasting a second.
- Entity ▸ Effects ▸ Trail 2D makes one drawn flat among sprites, sized for a 2D camera: a quarter of a unit wide, each point lasting half a second.
- Add Component puts one on any entity, a sprite included.
A new Trail is widest at its head and tapers to nothing at its tail, white fading out along it, drawn with a soft streak over what is behind it.
The Scene view marks a Trail with a shooting star.
Trail
What it leaves
While Emitting, the entity leaves a point where it is each time it has moved Minimum Vertex Distance from the last one, and each point lasts Time seconds. The ribbon runs from the entity, its head, through the points from the newest to the oldest, its tail.
The points stay where the entity was in the world, whatever its parent does afterward: a trail behind a wheel stays on the road, not on the car. Turned off, the ribbon lets go of the entity and fades as its points go.
| Field | What it does |
|---|---|
| Emitting | Leaves points as the entity moves. Off, the trail lets go of it and fades. |
| Time | How long each point lasts, in seconds: how long the trail is behind a moving entity. |
| Minimum Vertex Distance | How far the entity moves before it leaves another point, in units. Less is smoother and costs more. |
How it looks
| Field | What it does |
|---|---|
| Width | How wide it is, in units, times Width over Trail. |
| Width over Trail | How wide it is along its length, from its head to its tail: a curve, a constant, or one picked between two for each trail. |
| Color over Trail | Its color along its length, from its head to its tail: a gradient, a color, or one picked between two. |
| Corner Vertices | How many points go round each corner it turns. 0 cuts the corner. A thin trail looks round with a few, a thick one wants more. |
| End Cap Vertices | How many points go round each of its ends. 0 leaves them flat. |
| Alignment | In 3D. View: turned to face the camera. Local: lying in its entity's XZ plane, facing its +Y, seen from either side, for tire marks on a road or a sword's swing in its plane. |
| Texture Mode | Stretch: the texture once from head to tail. Tile: again and again, once every Tile Length units. |
| Material | In 3D, a material file that draws it in place of its texture and blending, lit or not as the material says. |
| Texture | The picture it is drawn with: a soft streak (Soft Streak) until you give it one. Drop an image on the slot, or pick one with its button. |
| Blending | Alpha: over what is behind it. Additive: added to it, so it glows. Opaque: solid, the nearest drawn wherever it crosses anything, itself included, its texture cut away where less than half opaque. |
| Flat | Drawn among sprites by a 2D camera, rather than in 3D. |
| Sorting Layer, Order in Layer | Flat: where it is drawn among sprites. Order in Layer starts at −1, so a trail is drawn behind the sprite it follows. |
Width over Trail and Color over Trail are edited with the curve and gradient editors a Particle Emitter's numbers use; see Numbers that change: curves and gradients. A value picked between two is picked once for each trail.
Blended Alpha or Additive, where a trail crosses itself its later part is drawn over its earlier, as anything see-through drawn in one piece is. Its corners are drawn once, so a see-through trail is as see-through at a corner as along it, except where its pieces cross each other, as in a turn sharper than its width allows.
While you edit
A Trail is drawn while you edit the scene too: drag its entity in the Scene view and the ribbon follows, so you can tune how it looks without playing. Nothing of what it has left is saved. Every Trail starts empty as play starts and as it stops, and holds still while the game is paused.
Trails from code
A game's C# drives a Trail through world.Trails:
// ship is an entity with a Trail.static void Teleport(World world, ulong ship){ world.Trails.SetEmitting(ship, false); // lets go of the ship and fades bool on = world.Trails.IsEmitting(ship);
world.Trails.Clear(ship); // forgets every point it has left world.Trails.SetEmitting(ship, true);
world.Trails.AddPoint(ship, new Vector3(0f, 2f, 0f)); // a point of your own, in the world Vector3[] points = world.Trails.Points(ship); // the oldest first, in the world}Clear a trail when its entity jumps from one place to another, as for a teleport or a respawn, or the ribbon is drawn across the gap. Points(entity, span) reads into a span without allocating, and returns how many points there are.
A game's Rust systems take GameTrails from abyss_ffi, with emitting, set_emitting, clear, add_point and points.
A Particle Emitter's Trails module draws ribbons behind its particles the same way. A ribbon through points you place yourself is a Line.
In the Scripting API
- WorldTrails: a Trail's emitting switched, cleared, given points and read.
