ParticleEmitter

namespace Griff.Scenes;

public sealed class ParticleEmitter : Component, IDrawable

Sprays small fading quads: smoke, sparks, dust, explosions. Particles live in world space, so a moving emitter leaves a trail. Call Burst from a script for one-off effects, or use BurstOnStart with DestroyWhenFinished in a prefab and spawn it.

Live particles aren’t saved, so rewinding during play clears them.

This is a component: its saved properties are on its component page.

Properties

AnimateFrames

public bool AnimateFrames { get; set; }

With Frames: each particle shows them in order, one after another across its life, instead of one picked at birth.

BurstOnStart

public int BurstOnStart { get; set; }

Particles emitted at once when the game first runs this emitter (e.g. for an explosion prefab).

Columns

public int Columns { get; set; }

For sprite sheets: frames across the image, as on a Sprite. 1 for a single image.

DestroyWhenFinished

public bool DestroyWhenFinished { get; set; }

Removes the entity once it has stopped emitting and its last particle is gone.

Direction

public float Direction { get; set; }

Degrees: 0 is right, 90 is up. The entity’s rotation is added.

Emitting

public bool Emitting { get; set; }

While set, emits Rate particles per second.

EndColor

public Color EndColor { get; set; }

Each particle’s color at the end of its life, blending from StartColor; a clear one fades it out.

EndSize

public float EndSize { get; set; }

Width and height in world units at the end of its life.

Frame

public int Frame { get; set; }

Which frame of the sheet each particle shows, counting left to right, top to bottom from 0. Frames takes over when it’s set.

FrameList

public IReadOnlyList<int> FrameList { get; }

The frames Frames names, in order; empty when it names none.

Frames

public string? Frames { get; set; }

Frames to use instead of Frame, written like an Animation clip’s: 0-1 is frames 0 and 1, 3-4, 7 is 3, 4 and 7, and 3-0 runs backward. Each particle picks one at random as it’s born (from the game’s random, so a rewound or networked game repeats), or with AnimateFrames steps through them.

GravityScale

public float GravityScale { get; set; }

Multiplier on world gravity; 0 floats, 1 falls like a body.

Image

public string? Image { get; set; }

Image for each particle, relative to Assets. Without one, particles are solid squares.

IsFinished

public bool IsFinished { get; }

True once there’s nothing left to show: the start burst has happened, the emitter isn’t emitting continuously, and every particle has died.

Lifetime

public float Lifetime { get; set; }

Seconds each particle lives.

MaxParticles

public int MaxParticles { get; set; }

The oldest particles make room for new ones beyond this many.

Order

public int Order { get; set; }

Higher draws on top, like Order.

Particles

public IReadOnlyList<Particle> Particles { get; }

The live particles, oldest first.

Rate

public float Rate { get; set; }

Particles per second while Emitting.

Rows

public int Rows { get; set; }

For sprite sheets: frames down the image.

Speed

public float Speed { get; set; }

Starting speed in world units per second.

SpeedVariation

public float SpeedVariation { get; set; }

How much each particle’s speed may differ, from 0 (all the same) to 1 (anywhere from 0 to double).

Spread

public float Spread { get; set; }

Width of the spray in degrees around Direction; 360 sprays every way.

StartColor

public Color StartColor { get; set; }

Each particle’s color when it’s made.

StartSize

public float StartSize { get; set; }

Width and height in world units at birth.

Methods

Advance

public void Advance(float seconds, Vector2 gravity)

Ages and moves particles and emits new ones. Called by the game every frame.

Burst

public void Burst(int count)

Emits count particles right away.

Clear

public void Clear()

Removes every live particle.

ColorAt

public Color ColorAt(float progress)

The color of a particle at progress through its life.

FrameOf

public int FrameOf(Particle particle, float progress)

The frame a particle shows at progress through its life.

FrameRect

public Vector4 FrameRect(int frame)

The part of the image to show for frame: (u, v, width, height) in 0–1 image space, as FrameRect.

ParseFrames

public static int[] ParseFrames(string? text)

Reads frames written like Frames; entries that don’t make sense are skipped.

ParticleDraws

public IEnumerable<SpriteDraw> ParticleDraws()

One quad per live particle, in world space at the emitter’s depth, where they are now.

ParticleDraws

public IEnumerable<SpriteDraw> ParticleDraws(StepBlend blend)

One quad per live particle, in world space at the emitter’s depth, in a frame drawn as blend says: each between where it was and is (and how old it was and is), if they moved in the last step.

SizeAt

public float SizeAt(float progress)

The size of a particle at progress through its life.