The ParticleSystemManager implements the interface IParticleSystemService. A particle system service manages a collection of particle systems. Usually ParticleSystemManagerUpdate(TimeSpan) is called in the game loop once per frame. In this method all particle systems are updated.

The use of the ParticleSystemManager is optional. Individual particle systems can also be updated manually.

The class ParticleSystem provides the base class for a particle system. It acts like a configurable container for particle parameters, particle effectors and other particle systems. To create a new particle effect a new type can be derived from ParticleSystem, but usually the class is used directly.

Each particle system can have child particle systems (see property Children) to create complex effects. For example, an explosion particle system can consist of a glow particle system, a smoke particle system and a debris particle system.

The particle system updates its simulation state when the method Update is called. This method is called automatically if the particle system is added to a particle system service or a another particle system. Reset can be called to remove all particles and set a particle system back to its initial state.

A particle system starts without any particles. To add ("emit") new particles the method AddParticles needs to be called. There are special particle effectors (called "emitters" such as the StreamEmitter) that automatically call this method.

Geometric object

Reference frame

Timing

Each particle system owns a ParticleParameterCollection which manages particle parameters. Particle parameters have a name and define properties of the particle system or of individual particles. Typical particle parameters are Position, Speed, Direction, Size, Color, Alpha, etc.

A particle parameter is called "uniform" if it provides a single value that is shared by the particle system and all particles. For example, most particle systems will have a uniform parameter "Texture" that defines which texture a particle renderer should use for the particles. All particles use the same texture.

A particle parameter is called "varying" if each particle has its own value. For example, most particle systems will have a varying parameter "Position" that stores the positions of the individual particles. (Each particle can have a unique position.)

New particle parameters are added to a particle system using the methods ParticleParameterCollectionAddUniformT(String) and ParticleParameterCollectionAddVaryingT(String). Existing parameters can be retrieved using the Get methods (for example ParticleParameterCollectionGetT(String)).

Particle parameters implement the interface IParticleParameterT, which has a property DefaultValue and a property Values. Uniform particle parameters store their value in DefaultValue and Values is null. Varying particle parameters store the values in the Values array and DefaultValue is not used. The Values array is preallocated when the particle parameter is added to the particle system. The length of the array is defined by ParticleSystemMaxNumberOfParticles. It is used as a circular buffer for the current particle values. ParticleSystemParticleStartIndex determines the index of the oldest active particle in the array. ParticleSystemNumberOfActiveParticles defines how many array elements are currently in used. When old particles die, ParticleStartIndex is increased by the particle system. NumberOfActiveParticles is increased when new particles are added.

The class ParticleParameterNames provides names for commonly used particle parameters. These names are only suggestions. (The only parameter name which is fixed is "NormalizedAge" - see below.)

Default parameters

Inheriting uniform parameters

Each particle system owns a ParticleEffectorCollection that manages objects derived from the base class ParticleEffector. In each update the particle system calls the particle effectors to do the actual work. Particle effectors can be used to create, initialize, and manipulate particles. Effectors define the behavior of a particle system.

DigitalRune Particles provides several predefined effectors: See namespace DigitalRune.Particles.Effectors and included samples.

The base class ParticleEffector provides several virtual methods, which can be overridden in derived class. See the class description of ParticleEffector for more information.

Common particle effector types

Distributions

Here are some tips for designing particles effects:

• For good performance try to decrease the number of particles. Use particles with high opacity (high alpha values) and textures that contain more structure.

• Some particle effects look a lot better if particles have a random "Lifetime".

• If several start value effectors initialize the same particle parameter, the last effector in the Effectors collection overrides the other start value effectors.

• Uniform parameters can be directly initialized by setting their DefaultValue when they are created. For example:

  C#

  Copy

  particleSystem.Parameters.AddUniform<float>(ParticleParameterNames.Lifetime).DefaultValue = 5;

  But they can also be initialized using start value effectors. For example:

  C#

  Copy

  particleSystem.Effectors.Add(new StartValueEffector<float>
  {
    Parameter = ParticleParameterNames.Lifetime,
    DefaultValue = 5,
  });

  The advantage of using start value effectors is that when the particle system is reset (using the method Reset) the start value effector will reset the uniform parameter. Without a start value effector, the uniform parameter keeps its last value and this might not be the same as the original value if the user or a particle effector has modified the parameter.

• Have a look at the Samples to see several particle effects in action.

• The class ParticleSystem implements the interface IAnimatableObject. All uniform particle parameters implement IAnimatablePropertyT. That means, all uniform parameters can be animated using DigitalRune Animation.

• Particle systems and particle effectors can be cloned (see method Clone). That means, a particle system can be configured once and then replicated as needed.

• Particle systems and particle effectors can be serialized/deserialized using the XNA IntermediateSerializer.

• The class ParticleHelper provides the extension methods GetValueT and SetValueT which can be used to retrieve values from particle parameters without differentiating between uniform or varying parameters.

• Particle effectors can read uniform particle parameters to create a time-dependent behavior. For example, a wind force effector could use a uniform parameter "WindStrength" to determine its wind force. A SingleFadeEffector could be used to animate the "WindStrength" from 0 to its maximum and back to 0.