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 a DrawableGameComponent that can simply be added to your Game’s component collection.

   1:  ParticleManager particleManager;
   3:  ...
   5:  public Game1()
   6:  {
   7:      ...
   9:      particleManager = new ParticleManager(this);
  10:      Components.Add(particleManager);
  12:      ...
  13:  }

The ParticleManager needs to know how your world is being viewed. Use the SetMatrices method to set the view and projection matrices.

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 the LoadContent method. For example, create a dynamic particle system:

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

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

       1:  Texture2D pixel = new Texture2D(GraphicsDevice, 1, 1);
       2:  pixel.SetData<Color>(new Color[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);


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

       1:  particleSystem.AddParticle(
                RandomHelper.Vector3Between(Vector3.Up, Vector3.Down),
                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 the IParticleEmitter interface:

       1:  public class CustomParticleEmitter : IParticleEmitter 

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

    An emitter can be added to any dynamic particle system:

       1:  particleSystem.AddEmitter(new CustomParticleEmitter());

    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 particles 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 towards the end of its lifespan.

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

       1:  public class CustomParticleAffector : IParticleAffector

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

    An affector can be added to any dynamic particle system:

       1:  particleSystem.AddAffector(new CustomParticleAffector());
  • Last edited Dec 27, 2011 at 12:07 AM by AlexYakobovich, version 27


    No comments yet.