Cross-Platform Game Programming with gameplay3d/Particles

Overview

The gameplay::ParticleEmitter class defines all the information needed to simulate and render a system of particles. Particle emitters can be used to represent a multitude of visual effects, such as smoke, steam, fire and explosions; and other atmospheric effects, such as rain and lightning. Once created, the emitter can be set on a gameplay::Node in order to follow an object, or it can be placed within a scene.

Creating a particle emitter

Use the ParticleEmitter::create() method to create a particle emitter.

There are 3 overloads of this function, but the one which you are likely to use most commonly is the overload for creating a particle emitter from a .particle file, which has the following function signature:

static ParticleEmitter* create (const char *url);

If you want to create a particle emitter programmatically, you can use the following overload, which creates an uninitialized ParticleEmitter. The new particle emitter can then be configured using member functions in the ParticleEmitter class.

static ParticleEmitter* create (const char *texturePath, TextureBlending textureBlending, unsigned int particleCountMax);

.particle files

The following is a commented example of a .particle file created with the "sample-particles" example project, which is a useful particle editor packaged with gameplay3d.

Given the number of fields which need completing in a .particle file, and because it is helpful to see a visual representation of the particle emitter while you are editing it, the "sample-particles" project is probably the easiest way to get started creating and configuring particle emitters.

particle smoke
{
    sprite
    {
        path = smoke.png        // A path to the image to use as this ParticleEmitter's texture.
        width = 64              // The height of the first frame of the sprite.
        height = 64             // The width of the first frame of the sprite.
        blending = ADDITIVE     // Other options are OPAQUE, TRANSPARENT AND MULTIPLIED.
        animated = false        // Specifies whether particles cycle through the sprite frames.
        looped = false          // Specifies whether sprites are set to loop,
        frameCount = 1          // The number of frames to use for the particle emitter's sprite.
        frameRandomOffset = 0   // Set to 0 for all particles to start on the first frame. Otherwise the starting frame will be a random frame not higher than this value.
        frameDuration = 0       // The duration of a single sprite frame, in milliseconds.
    }

    particleCountMax = 5000             // The number of live particles at any one time will not exceed this value.
    emissionRate = 20                   // The emission rate, measured in particles per second.
    ellipsoid = false                   // An ellipsoid particle emitter spawns particles inside a ellipsoidal domain. (Using an ellipsoidal domain
                                                  is slightly more expensive than the default cuboid domain.)
    orbitPosition = false               // Whether to rotate initial particle positions by the node's rotation matrix.
    orbitVelocity = false               // Whether to rotate initial particle velocity vectors by the node's rotation matrix.
    orbitAcceleration = false           // Whether to rotate initial particle acceleration vectors by the node's rotation matrix.
    sizeStartMin = 3.5                  // The minimum size that each particle can be at the time when it is started.
    sizeStartMax = 3.5                  // The maximum size that each particle can be at the time when it is started.
    sizeEndMin = 15                     // The minimum size that each particle can be at the end of its lifetime.
    sizeEndMax = 15                     // The maximum size that each particle can be at the end of its lifetime.
    energyMin = 4000                    // The minimum lifetime of each particle, measured in milliseconds.
    energyMax = 5000                    // The maximum lifetime of each particle, measured in milliseconds.
    colorStart = 0.5, 0.5, 0.5, 1       // The base start color of emitted particles.
    colorStartVar = 0, 0, 0, 0          // The variance of start color of emitted particles.
    colorEnd = 1, 0, 0, 0               // The base end color of emitted particles.
    colorEndVar = 0, 0, 0, 0            // The variance of end color of emitted particles.
    position = 0, 0, 0                  // The position of new particles, relative to the emitter's transform.
    positionVar = 0, 0, 0               // The position variance of new particles.
    velocity = 2.5, 5, 0                // The initial velocity of new particles.
    velocityVar = 0, 0, 0               // The initial velocity variance of new particles.
    acceleration = -10, 5, 0            // The base acceleration vector of emitted particles.
    accelerationVar = 2.5, 5, 0         // The variance allowed in the acceleration of emitted particles.
    rotationPerParticleSpeedMin = -1.5  // The minimum rotation speed (per particle).
    rotationPerParticleSpeedMax = 1.5   // The maximum rotation speed (per particle).

    editor                              // Particle editor-specific properties
    {
        cameraTranslation = -0.0200001, 4.06, 0
        cameraZoom = 0, 0, 16.8
        cameraRotation = 0, 0, 0, 0
        sizeMax = 20
        energyMax = 5000
    }
}