Tutorial 5 - The Emitter

In this tutorial we will look at the Emitter, which is used to emit particles.

Load the Tutorial 5 project and open up Game1.cs.

Emitting particles using the Emitter

Every DPSF particle system has an Emitter property.  The Emitter can be used to automatically emit particles from the particle system; the other option you have to emit particles is to directly call the particle system's AddParticle() or AddParticles() functions.

The Emitter's ParticlesPerSecond property is used to determine what rate the Emitter should emit particles at.  If the Emitter's EmitParticlesAutomatically property is true then the emitter will emit particles forever at the specified rate until the EmitParticlesAutomatically property is set to false.  For example, the following code could be placed in the particle system's LoadParticleSystem() function to have the particle system emit 100 particles per second forever until it is explicitly turned off.

       // Turn the Emitter on to constantly emit 100 Particles Per Second

       Emitter.EmitParticlesAutomatically = true;

       Emitter.ParticlesPerSecond = 100;

If you want to emit a burst of particles, you can set the Emitter's BurstParticles property to emit a specific number of particles.  Similarly, if you want to emit a burst of particles for a certain amount of time (instead of a certain amount of particles), you can set the Emitter's BurstTime property to the number of seconds that you want it to emit particles for.  Both the BurstParticles and BurstTime properties will emit particles at the rate corresponding to the ParticlesPerSecond property.  However, BurstParticles and BurstTime will only emit particles if the EmitParticlesAutomatically property is set to false, since if it is true the particle system will be emitting the particles at the specified rate anyways.  If both the BurstParticles and BurstTime properties are set, the Emitter will first emit particles until the BurstTime property reaches zero, and then it will continue to emit particles until the BurstParticles property reaches zero.

Near the very bottom of Game1.cs, Tutorial 5 shows how to set the release a burst of particles when the X and C keys are pressed during the simulation (the EmitParticlesAutomatically is set to false when loading the particles system):

       // If the X Key was just pressed

    if (KeyWasJustPressed(Keys.X))

     {

           // Emit 50 particles

           mcMyParticleSystem.Emitter.BurstParticles = 50;

       }

       // If the C Key was just pressed

    if (KeyWasJustPressed(Keys.C))

     {

           // Emit particles for 2 seconds

           mcMyParticleSystem.Emitter.BurstTime = 2.0f;

     }

You may also check the Emitter's BurstParticles property to see how many particles is still has left to emit, and similarly you may check the BurstTime property to see how much longer it will emit particles for.

To disable the Emitter from emitting any particles, you can set the Emitter's Enabled property to false.  When the Enabled property is false the Emitter will never emit any particles, but the Emitter's Position, Rotation, and Pivot Point information (described below) will still be updated each frame.

Emitter's Position, Rotation, and Pivot Point

The particle system's Emitter has built-in position and orientation data.  The Emitter.PositionData property allows you to specify the Emitter's Position, Velocity, and Acceleration.  The Emitter's Position and Velocity will be updated according to the Acceleration each time the particle system's Update() function is called.

The code near the bottom of Game1.cs shows how to toggle the Emitter's Velocity on and off when the V key is pressed:

       // If the V Key was just pressed

    if (KeyWasJustPressed(Keys.V))

     {

           // If the Emitter is not moving

          if (mcMyParticleSystem.Emitter.PositionData.Velocity == Vector3.Zero)

           {

                 // Make the Emitter move

                 mcMyParticleSystem.Emitter.PositionData.Velocity = new Vector3(50, 0, 0);

           }

          // Else the Emitter is moving already

          else

           {

                 // So stop the Emitter's movement

                 mcMyParticleSystem.Emitter.PositionData.Velocity = Vector3.Zero;

           }

       }

You will likely want to first turn the Emitter on to emit particles automatically by pressing the E key.  This will make it easier to see the Emitter's movement.  The Emitter may be returned to its default position by pressing the W key.

Similarly the Emitter has an Emitter.OrientationData property that can be used to specify the Emitter's Orientation, Rotational Velocity, and Rotational Acceleration.  The tutorial also shows how to toggle the Emitter's Rotational Velocity on and off when the B key is pressed:

       // If the B Key was just pressed

    if (KeyWasJustPressed(Keys.B))

     {

           // If the Emitter is not rotating

          if (mcMyParticleSystem.Emitter.OrientationData.RotationalVelocity == Vector3.Zero)

           {

                 // Make the Emitter rotate

                 mcMyParticleSystem.Emitter.OrientationData.RotationalVelocity = new Vector3(0, 0, MathHelper.Pi);

           }

          // Else the Emitter is rotating already

          else

           {

                 // So stop the Emitter's rotations

                 mcMyParticleSystem.Emitter.OrientationData.RotationalVelocity = Vector3.Zero;

           }

       }

Again, you will want to have the Emitter emitting particles automatically by pressing the E key so that it is easy to see the effect that rotating the Emitter has on the particles.

The Emitter can also be rotated around an arbitrary Pivot Point (some point in 3D space) using the Emitter.PivotPointData property.  It allows you to set the PivotPoint that the Emitter should rotate around, as well as the PivotRotationalVelocity and PivotRotationalAcceleration to control how fast it rotates around the Pivot Point.  The tutorial shows how to toggle the Emitter's Pivot Rotational Acceleration on and off when the N key is pressed:

       // If the N Key was just pressed

    if (KeyWasJustPressed(Keys.N))

     {

           // Specify the Pivot Point that the Emitter should rotate around

           mcMyParticleSystem.Emitter.PivotPointData.PivotPoint = new Vector3(0, 75, 0);

          // If the Emitter is not rotating around the Pivot Point

          if (mcMyParticleSystem.Emitter.PivotPointData.PivotRotationalAcceleration == Vector3.Zero)

           {

                 // Make it Accelerate around the Pivot Point

                 mcMyParticleSystem.Emitter.PivotPointData.PivotRotationalAcceleration = new Vector3(0, 0, 0.1f);

           }

          // Else the Emitter is rotating around the Pivot Point already

          else

           {

                 // So stop the Emitter from rotating around the Pivot Point

                 mcMyParticleSystem.Emitter.PivotPointData.PivotRotationalVelocity = Vector3.Zero;

                 mcMyParticleSystem.Emitter.PivotPointData.PivotRotationalAcceleration = Vector3.Zero;

           }

       }

If you wanted the Emitter to rotate around another object, you could specify the Emitter's Pivot Point each frame to be the position of the object to rotate around.  By default rotating the Emitter around a Pivot Point will affect both the Emitter's Position and Rotation.  If you wanted it to only affect the Emitter's Position you could specify to not rotate the Emitter's Orientation by setting the RotateOrientationToo property to false:

       mcMyParticleSystem.Emitter.PivotPointData.RotateOrientationToo = false;

Emitting particles according to the Emitter's Position and Orientation

In this tutorial you may have noticed that moving and rotating the Emitter affects where the particles are emitted from, and the direction they are emitted in.  During the simulation you can use the Home / End, Delete / Page Down, and Insert / Page Up keys to move the Emitter's Position along the X, Y, and Z axis.  You can also use the I / K, J / L, and U / O keys to rotate the emitter around the X, Y, and Z axis.

This behaviour is defined by the Particle Initialization Function.  Open up MyParticleSystem.cs and locate the InitializeParticleProperties() function.  In this function you should see the line:

       cParticle.Position = Emitter.PositionData.Position;

This line specifies that new particles should be emitted from the Emitter's Position.  If you don't want the particles to be released from the Position of the Emitter, you could specify an absolute value for the particle's Position, such as Vector3(0, 50, 0).

Also in that Particle Initialization Function you should see the line:

       cParticle.Velocity = Vector3.Transform(cParticle.Velocity, Emitter.OrientationData.Orientation);

This line specifies that the direction the particle should be traveling in should be adjusted according to the Emitter's Orientation.  If you don't want the particle's Velocity direction to be based upon the Emitter's Orientation, simply comment out or remove this line from the Particle Initialization Function.

If you are using the InitialProperties object to initialize the particles, as described in Tutorial 2, and do not want the new particle's Position to be based on the Emitter's Position, you may set the InitialProperties.PositionIsAffectedByEmittersPosition property to false.  Similarly, if you don't want the particle's Velocity direction to be adjusted according to the Emitter's Orientation, you may set the InitialProperties.VelocityIsAffectedByEmittersOrientation property to false.

Remarks

Play around with changing the Emitter's ParticlesPerSecond property during the simulation (using the + / - keys) and pressing X and C to release bursts of particles to help see the difference between BurstParticles and BurstTime.