---
title: Particles
description: Create particle effects in Tide code with bounded emitters, custom
  spawn and update functions, and instanced 2D sprites or 3D billboards.
source_url: https://tide-engine.dev/packages/particles
source_file: docs/packages/particles.md
source_revision: 36904d8e07dd044bd665de823e6b8022ed4f4248
source_worktree: modified
documentation_sha256: ea38a553efadfaf8a016c33e947825b8c4d3d2005abcf32eb4f4a64094909e97
documentation_scope: Website source checkout; not matched to an installed Tide
  release. Check tide version and the project toolchain.
---

<a id="particles"></a>

# Particles

`particles`, in namespace `Particles`, supplies reusable particle storage, emission, lifetime updates and drawing. Effects are ordinary Tide functions: write how a particle starts, how it moves and what it looks like. People and agents can edit the same source, with normal completion, error messages, version control and hot reload.

```sh
tide add particles
```

Keep visual effects in [local state](https://tide-engine.dev/game/local-state.md), usually an `Emitter` field of a local singleton or a local field attached to an entity. Each emitter owns an ordinary `List<Particle>`, a random generator and its fractional emission count. There is no entity per particle and no global effect manager.

<a id="write-an-effect"></a>

## Write an effect

An initializer receives a new particle and its emitter's random generator. It can use ordinary math, conditions, helper functions and captured values to choose a shape, velocity, lifetime and appearance:

```csharp
void Spark(mut Particles.Particle particle, mut Random random)
{
    float2 direction = random.NextFloat2Direction();
    float speed = random.NextFloat(1, 3);
    particle.velocity = float3(direction * speed, 0);
    particle.lifetime = random.NextFloat(0.4, 0.9);
    particle.size = float2(0.08);
    particle.endSize = float2(0);
    particle.color = Color(1, 0.75, 0.2);
    particle.endColor = Color(1, 0.3, 0.1, 0);
}

local singleton Effects
{
    Particles.Emitter sparks;
}
```

`Particles.Burst(effects.sparks, 40, Spark)` emits immediately. `Particles.Emit(effects.sparks, 80, dt, Spark)` emits 80 per second, carrying fractional counts between calls. Both return the number actually added. Call emission once for each interval you want it to cover.

For an effect at a particular place, capture that place in a lambda:

```csharp
void SparkAt(mut Particles.Particle particle, mut Random random, float3 position)
{
    Spark(particle, random);
    particle.position = position;
}

Particles.Burst(effects.sparks, 40,
    (mut Particles.Particle particle, mut Random random) => SparkAt(particle, random, hitPosition));
```

The initializer runs for each new particle. Changing its code or the parameters it captures affects later emissions; existing particles retain the values already stored in them.

The example combines a continuous fountain, smoke with a custom movement function and bursts at the pointer. Stop flow to let the existing particles finish, change the emission rate, or clear both emitters. Its source is the complete effect.

**Sparks and smoke in code** ([Run example](https://tide-engine.dev/examples/particles/?stats))

```tide
using Particles;

settings { title = "Particles: effects written in code"; }

local scene Main;

local singleton Effects
{
    Emitter sparks;
    Emitter smoke;
    Particles.Renderer renderer;
    float rate = 70;
    bool flowing = true;
}

// An effect is a function: this one chooses the newborn spark's values.
void Spark(mut Particle particle, mut Random random)
{
    float2 direction = random.NextFloat2Direction();
    float speed = random.NextFloat(0.8, 2.5);
    particle.position = float3(0, 0.15, 0);
    particle.velocity = float3(direction * speed + float2(0, 1.7), 0);
    particle.lifetime = random.NextFloat(0.55, 1.15);
    particle.size = float2(0.07, 0.11);
    particle.color = Color(0.98, 0.75, 0.14);
    particle.endColor = Color(0.98, 0.3, 0.08, 0);
    particle.rotation = random.NextFloat(Math.TAU);
    particle.angularVelocity = random.NextFloat(-5, 5);
}

void Puff(mut Particle particle, mut Random random)
{
    float x = random.NextFloat(-0.18, 0.18);
    float rise = random.NextFloat(0.6, 0.9);
    particle.position = float3(x, 0.2, 0);
    particle.velocity = float3(x * 0.4, rise, 0);
    particle.lifetime = random.NextFloat(1.5, 2.3);
    particle.size = float2(0.35);
    particle.endSize = float2(1.1);
    particle.color = Color(0.18, 0.83, 0.75, 0.38);
    particle.endColor = Color(0.3, 0.45, 0.5, 0);
    particle.custom.x = random.NextFloat(Math.TAU);
}

// Custom movement uses ordinary code too. The package manages age and expiry.
void Drift(mut Particle particle, float dt)
{
    Particles.Integrate(particle, dt, acceleration: float3(0, 0.2, 0), drag: 0.2);
    particle.position.x += Math.Sin(particle.age * 4 + particle.custom.x) * dt * 0.18;
}

void SparkAt(mut Particle particle, mut Random random, float3 position)
{
    Spark(particle, random);
    particle.position = position;
}

void BurstAt(mut Emitter emitter, float3 position)
{
    Particles.Burst(emitter, 70,
        (mut Particle particle, mut Random random) => SparkAt(particle, random, position));
}

view Show(mut Effects effects, Devices devices)
{
    float dt = Math.Min(Frame.dt, 0.05);
    Particles.Update(effects.sparks, dt, acceleration: float3(0, -4, 0), drag: 0.5);
    Particles.Update(effects.smoke, dt, Drift);
    if (effects.flowing)
    {
        Particles.Emit(effects.sparks, effects.rate, dt, Spark);
        Particles.Emit(effects.smoke, effects.rate * 0.25, dt, Puff);
    }

    Draw.Clear(Color(0.086, 0.086, 0.094));
    Draw.SetCamera(float2(0, 0.75), 2.7);
    float panelTop = Screen.height - 140;
    float2 pointer = Screen.Flip(devices.pointer.position);
    if (devices.pointer.press.down && pointer.y > 64 && pointer.y < panelTop)
        BurstAt(effects.sparks, float3(Draw.ScreenToWorld(pointer), 0));

    Particles.DrawSprites(effects.renderer, effects.smoke.particles);
    Particles.DrawSprites(effects.renderer, effects.sparks.particles, Blend.Add);

    Draw.SetScreen();
    Draw.Text($"{effects.sparks.particles.count + effects.smoke.particles.count} particles", float2(16, 14), 18, Color.white);
    Draw.Text("Click above the controls for a burst", float2(16, 40), 13, Color(0.64, 0.64, 0.68));
    GUI.SetTheme(GUITheme { radius = 6 });
    // Keep the host's stats corner clear below the controls.
    GUILayout.Area(Rect(12, panelTop, Screen.width - 24, 88))
    {
        GUILayout.Slider("Rate", effects.rate, 0, 200);
        GUILayout.Horizontal()
        {
            if (GUILayout.Button(effects.flowing ? "Stop flow" : "Start flow")) effects.flowing = !effects.flowing;
            if (GUILayout.Button("Burst")) BurstAt(effects.sparks, float3(0, 0.15, 0));
            if (GUILayout.Button("Clear"))
            {
                Particles.Clear(effects.sparks);
                Particles.Clear(effects.smoke);
            }
        }
    }
}
```



<a id="move-and-expire-particles"></a>

## Move and expire particles

Call `Update` once per frame, with the same elapsed time used for emission:

```csharp
float dt = Math.Min(Frame.dt, 0.05);
Particles.Update(effects.sparks, dt, acceleration: float3(0, -4, 0), drag: 0.8);
Particles.Emit(effects.sparks, 80, dt, Spark);
```

Updating before emission leaves new particles at age zero for their first draw. `Frame.dt` is the frame's real length; the clamp above is the game's choice to avoid a large leap after a stall. Zero, negative or nonfinite time does not advance the effect.

The standard update advances age, removes particles that have reached their lifetime, applies acceleration and drag, moves position and advances rotation. A custom update replaces the movement part, while the package still advances age and removes expired particles:

```csharp
void Drift(mut Particles.Particle particle, float dt)
{
    Particles.Integrate(particle, dt, acceleration: float3(0, 0.4, 0), drag: 0.3);
    particle.position.x += Math.Sin(particle.age * 5 + particle.custom.x) * dt * 0.2;
}

Particles.Update(effects.smoke, dt, Drift);
```

This is also where a game can implement attraction, visual bounces, noise or motion along a path. `custom` is a `float4` for effect-specific values such as a phase, a starting height or a sprite-frame index. The particle list is public, so game code can inspect or change it directly.

<a id="particle-data"></a>

## Particle data

| Field | Meaning |
|---|---|
| `position`, `velocity` | `float3` position and units per second; use `z = 0` for 2D |
| `age`, `lifetime` | Seconds lived and total lifetime; lifetime defaults to 1 |
| `size`, `endSize` | `float2` width and height at birth and death; defaults are `(0.1, 0.1)` and `(0, 0)` |
| `color`, `endColor` | Color at birth and death; defaults are white and transparent white |
| `rotation`, `angularVelocity` | Radians and radians per second |
| `custom` | Four numbers for the game's own effect code |

`Age(particle)` returns normalized lifetime progress, from 0 to 1. `Size(particle)` interpolates the size endpoints and keeps the result nonnegative. `Tint(particle)` blends alpha-weighted colors, so fading to a transparent endpoint keeps the visible hue instead of darkening it. Changing those endpoints changes the remaining appearance of a live particle. For another curve, calculate it in your own update or shader with ordinary functions such as `Math.SmoothStep`.

<a id="draw-in-2d-or-3d"></a>

## Draw in 2D or 3D

Keep a `Particles.Renderer` in local state alongside the emitters. It reuses the quad geometry and rendering lists. `DrawSprites` uses the current [2D camera or screen coordinates](https://tide-engine.dev/game/cameras.md), drawing `position.xy` as soft discs:

```csharp
Particles.DrawSprites(effects.renderer, effects.smoke.particles);
Particles.DrawSprites(effects.renderer, effects.sparks.particles, Blend.Add);
```

An optional texture between the particle list and blend mode draws full textured quads instead. `size` and `endSize` are the full width and height in the current drawing units, with rotation around the center. Positive 2D rotation turns from `+x` toward `+y`: counterclockwise under a world camera, clockwise in top-left screen coordinates. Texture coordinate `(0, 0)` stays at the top left in both modes:

```csharp
Particles.DrawSprites(effects.renderer, effects.leaves.particles, leafTexture);
```

For 3D, supply the position and rotation of the camera already selected for drawing. Each quad faces that camera; its size is in world units, and positive rotation turns from camera-right toward camera-up. The helper tests against opaque geometry's depth without writing depth itself, so draw opaque objects first:

```csharp
Draw.SetCamera(eye, cameraRotation, 50deg);
Particles.DrawBillboards(effects.renderer, effects.smoke.particles, eye, cameraRotation);
Particles.DrawBillboards(effects.renderer, effects.sparks.particles, eye, cameraRotation,
                 Blend.Add, sort: false);
```

`DrawBillboards` sorts the particles back to front by camera-forward distance unless `sort: false` is supplied. Particle positions must be world-space positions, with no additional `Draw.Transform` around the draw: inherited transforms are not part of the sort key. Sorting belongs to that draw only; overlapping transparent effects in separate calls are not sorted together. The particle simulation list keeps its order. Additive effects can usually skip sorting.

The texture overload places its texture after `cameraRotation`. Both drawing functions also have an overload with a `RenderTarget` first. For example, draw into [Render3D](https://tide-engine.dev/packages/render3d.md)'s HDR scene after its transparent pass and before its effects/presentation:

```csharp
[After(Render3D.Stages.Transparent), Before(Render3D.Stages.PostPrepare)]
view DrawSmoke(mut Effects effects, Render3D.Renderer scene)
{
    if (!scene.enabled || !scene.ready) return;
    Particles.DrawBillboards(scene.hdr, effects.renderer, effects.smoke.particles,
                     scene.camera.position, scene.camera.rotation);
}
```

The helpers restore the destination's previous blend, depth and culling settings. To use another shader or draw a mesh per particle, use the ordinary list with [`Draw.Instanced`](https://tide-engine.dev/game/shaders.md#instances-from-a-list). A custom vert or frag can receive `Particles.Particle` as its instance parameter, including `custom`, and use `Age`, `Size` and `Tint` for lifetime effects.

<a id="capacity-seeds-and-timing"></a>

## Capacity, seeds and timing

`emitter.capacity` defaults to 4,096 and is clamped to zero through 1,048,576 when used. Reducing it trims the end of the existing list on the next add, burst or valid emission/update. When an emitter is full, new emissions are dropped, without running their initializers. Emission never accumulates a burst of missed whole particles to release later. Its fractional count survives a pause. `Clear(emitter)` removes its particles and fractional emission count; seed it explicitly when a repeatable effect is useful:

```csharp
Particles.Clear(effects.sparks);
effects.sparks.random = Random(42);
```

The same seed, callbacks and sequence of updates and emissions reproduce the same CPU values. Different frame lengths need not produce the same trajectory. Local particles are outside match snapshots, rollback, hashes and network transfers. Use [local handlers](https://tide-engine.dev/game/events.md#local-handlers) to start visual effects from match events; keep damage and gameplay collision in match code.

`Add(emitter, particle)` adds a fully authored particle and returns whether it was accepted. Invalid particles, including nonfinite fields, negative age or age at/past lifetime, are rejected; `Update` also removes particles made invalid by direct edits or a callback. `Clear` keeps the random generator's current sequence. Survivors keep their relative order, but particles have no stable handle: removal compacts the list, so retain game-specific identity in your own data when needed.

<a id="current-scope"></a>

## Current scope

Simulation runs on the CPU, with instanced drawing on the GPU. There is no compute-shader simulation, built-in physics collision, ribbon/trail topology, effect-file format or editor graph. Spawn shapes, forces and lifetime curves are functions in your game; custom shaders can use the particle fields directly.
