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.
tide add particlesKeep visual effects in local state, 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.
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:
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:
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.
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);
}
}
}
}Move and expire particles
Call Update once per frame, with the same elapsed time used for emission:
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:
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.
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.
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, drawing position.xy as soft discs:
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:
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:
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's HDR scene after its transparent pass and before its effects/presentation:
[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. A custom vert or frag can receive Particles.Particle as its instance parameter, including custom, and use Age, Size and Tint for lifetime effects.
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:
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 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.
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.