Updated Wiki: Using Tranquillity

Using Tranquillity

Using Tranquillity is easy; most tasks can be achieved in a couple of lines of code. The demo project included with the source showcases more advanced scenarios including AppHub’s fire, smoke and explosion samples.

Particle Manager

All particle properties, behavior and drawing are managed by Tranquillity’s ParticleManager. ParticleManager is aDrawableGameComponent that can simply be added to your Game’s component collection.

   1:  ParticleManager particleManager;

   2:   

   3:  ...

   4:   

   5:  public Game1()

   6:  {

   7:      ...

   8:   

   9:      particleManager = newParticleManager(this);

  10:      Components.Add(particleManager);

  11:   

  12:      ...

  13:  }

Particle Systems

A ParticleSystem defines a group of particles that share a texture representation. There are two base particle system types in Tranquillity:

• StaticParticleSystem: All particles in this system have static properties. Once a particle is added to this system type, it cannot move, grow, change color, etc. Although particles can be added and removed to/from this system on the fly, it is ideal for static allocation of particles.
• DynamicParticleSystem: A dynamic particle system contains particles that can have a velocity, rotation, lifespan and can be affected by various affectors.

Creating and registering a particle system

To create a system, specify the maximum capacity and the texture to be used for this system in theLoadContent method. For example, create a dynamic particle system:

   1:  DynamicParticleSystem particleSystem = newDynamicParticleSystem(1000, texture);

The texture can be either an image or a 1x1 pixel, which can be generated on the fly:

   1:  Texture2D pixel = newTexture2D(GraphicsDevice, 1, 1);

   2:  pixel.SetData<Color>(newColor[1] { Color.White });

Add the system to the particle manager:

   1:  particleManager.AddParticleSystem(particleSystem);

Optionally, a custom BlendState can be specified:

   1:  particleManager.AddParticleSystem(particleSystem, BlendState.Additive);

Particles

The overloaded AddParticle method can be used to add particles to any system. TheRandomHelper class can be used to randomize the generation of particles. For example:

   1:  particleSystem.AddParticle(
            RandomHelper.Vector3Between(Vector3.Up, Vector3.Down),
            RandomHelper.Color(),
            RandomHelper.NormalizedVector3(),
            RandomHelper.Float(),
            TimeSpan.FromSeconds(RandomHelper.IntBetween(1, 3))
       );

Use the RemoveAt method to remove a particle at the given index.

Particle Emitters

Emission of particles can be automated using a particle emitter. To create a custom particle emitter, implement theIParticleEmitter interface:

   1:  publicclassCustomParticleEmitter : IParticleEmitter 

Implementing the Update method will allow the emitter to automatically emit particles in the particle system it is added to. TheEmit method can be used to emit particles manually.

An emitter can be added to any dynamic particle system:

   1:  particleManager.AddEmitter(newCustomParticleEmitter());

Particle Affectors

A particle affector can affect one or more properties of all particles in a system. There are three default affectors in Tranquillity that use the particle’s age as the time factor:

• Decelerate: Slows a particle down to a complete stop towards the end of its lifespan. This affectors affects only particle that have a velocity.
• Fadeout: Reduces the alpha of a particle until it becomes completely transparent towards the end of its lifespan.
• Shrink: Reduces the size of a particle until it disappears completely invisible towards the end of its lifespan.

To create a custom particle affectors, implement the IParticleAffector interface:

   1:  publicclassCustomParticleAffector : IParticleAffector

Implementing the Affect method will the affector to access the properties of the parameter particle.

An affector can be added to any dynamic particle system:

   1:  particleManager.AddAffector(newCustomParticleAffector());