Particle System Reference

File:Titans-icon.png Planetary Annihilation Titans & Classic Particle Effect System Reference

Work in progress, go here.

Overview of how the system works: (mental notes) Each effect, (called a particle system), is defined as a list of particle emitters. Each emitter can control things like the color, velocity, drag, and lifetime of the particles they spawn. Emitter is an entity that spawns particles over time. Properties that you define for your emitter either apply directly to the way the emitter produces particles, or they apply to the particles that are spawned. You can think of this as the emitter defining various properties over time, and then the moment a particle is spawned, it inherits a snapshot of those values.

Glossary

// Particle System
{
    "emitters": [{
        "spec" : {<particle properties>},
        <emitter properties>
    }],
    "color": <global color multiplier>
}

Particle System

The group of particle emitters.

Field Name	Field Type (default value) - Description
emitters	array ( [] ) The list of emitter objects in the system.
color	color ( [1.0, 1.0, 1.0, 1.0] ) A system wide color multiplier. Value is RGBA linear float color values in a JSON array.

Emitter System

Defines the position and movement behavior of particles.

Field Name	Field Type (default value) - Description
spec	object ( ) The particle spec definition.
type	string ( "POSITION" ) Defines the shape of the particle spawn positions, and how the offset* keys are interpreted. Valid types are "POSITION", "SPHEROID", "SHELL", "EMITTER", "CYLINDER_X", "CYLINDER_Y", and "CYLINDER_Z"
linkIndex	number ( -1.0 ) Used when the type is set to "EMITTER" to define the emitter to attach to.
offsetX offsetY offsetZ	emitter time curve ( 0.0 ) Define the starting spawn position for the particles in emitter space. The shape of the emitter space depends on the type field.
offsetRangetX offsetRangetY offsetRangetZ	emitter time curve ( 0.0 ) Define the starting spawn position range in which a particle can randomly deviate from offsetX, offsetY, and offsetZ.
offsetAllowNegZ	bool ( true ) Allow particles to spawn with an initial positiong with a negative Z in emitter space, otherwise flip Z to a positive position. Useful for explosions on the ground so that particles travel only up.
velocityX velocityY velocityZ	emitter time curve ( 0.0 ) Initial velocity direction in emitter space. This is for indicating direction only, so if you increase any of these the actual speed of the particle will not change, only the direction.
velocityRangeX velocityRangeY velocityRangeZ	emitter time curve ( 0.0 ) Initial velocity direction range in which a particle can randomly deviate from velocityX, velocityY, and velocityZ.
useRadialVelocityDir	bool ( false ) Use the starting location as a normalized vector in addition to the velocity direction values.
useShapeVelocityDir	bool ( false ) Use the starting position on the shape from the emitter's type in addition to the velocity direction values.
velocity	emitter time curve ( 1.0 ) Initial particle velocity along velocity direction vector at spawn.
velocityRange	emitter time curve ( 0.0 ) Initial particle velocity range +/- velocity.
inheritedVelocity	emitter time curve ( 0.0 ) Add the system’s velocity multiplied by this value to the initial particle velocity.
gravity	emitter time curve ( 0.0 ) Particle gravity over the emitter lifetime. Always in world space towards the center of the planet. Affects all particles in the emitter. Value is in world units per second with negative numbers going towards the planet center.
accelX accelY accelZ	emitter time curve ( 0.0 ) Particle acceleration over the emitter lifetime in emitter space. Affects all particles in the emitter. These values are absolute acceleration values and not normalized like velocity. (May have odd results with world space particles.)
drag	emitter time curve ( 0.0 ) Particle velocity multiplier over the emitter lifetime. Affects all particles in the emitter. Note: a drag of 1.0 is no drag, a drag of 0.0 turns drag off which is the same thing. A real drag of 0.0 would disable all movement. Drag values greater than 1.0 will cause particles to accelerate.
sizeX sizeY	emitter time curve ( 1.0 ) Defines the particle size in world units.
sizeRangeX sizeRangeY	emitter time curve ( 0.0 ) Defines the particle size range in world units.
sizeRandomFlip sizeRandomFlipX sizeRandomFlipY	bool ( false ) Defines if the particle’s size can be negated on one or both axis. The result is it randomly chooses how the texture is flipped on particle spawn. Helps randomize the appearance of a particle especially if the texture used has a strong pattern.
sizeSquareAspect	bool ( false ) Force particles to be square. Defaults to true if no sizeY is defined.
sizeConstantAspect	bool ( false ) Force particles to have a constant sizeX:sizeY ratio when using sizeRangeX. Defaults to true if no sizeRangeY is defined.
rotation	emitter time curve ( 0.0 ) Defines the initial particle rotation orientation. Value is in radians (about 6.2832 is one full rotation).
rotationRange	emitter time curve ( 0.0 ) Defines the initial particle rotation orientation range, +/- the initial rotation. Value is in radians (about 3.1416 encompasses the entire possible rotation range).
rotationRate	emitter time curve ( 0.0 ) Defines the particle rotation rate on spawned. Value is in radians per second (about 6.2832 will cause a particle to rotate one full rotation over a second).
rotationRateRange	emitter time curve ( 0.0 ) Defines the particle rotation rate range on spawn +/- the rotationRate. Value is in radians per second.
snapToSurface	bool ( false ) Option to snap particle’s spawn position to the ground mesh surface. Takes the offset location and traces towards the center of the planet. If particle offset is underground will snap to the surface. Will always snap to the highest point on the land. Does not test against units, only the planet surface mesh. **THIS IS EXPENSIVE, USE ONLY WHEN NEEDED!**
snapToSurfaceOffset	emitter time curve ( 0.0 ) Particle spawn distance from the ground surface when using snapToSurface. Is always in a direction away from the planet center, not the surface normal.
alignVelocityToSurface	bool ( false ) Align velocity directions when using snapToSurface to make Z up from the planet center and -Y away from the emitter along the ground (specifically perpendicular from the direction to the planet center).
red green blue alpha	emitter time curve ( 1.0 ) Particle initial color multiplier in linear float color. Set at the time of each particle’s spawn.
rgb	emitter time rgb curve ( [0.0, 1.0, [255, 255, 255]] ) Particle initial color multiplier in sRGB binary color form with a brightness.
useArmyColor	number ( 0 ) Use the system color multiplier (0), the primary team color (1), or secondary team color (2) for this emitter.
rampV	emitter time curve ( 0.0 ) Defines the initial V of the UV of the ramp texture in particle shaders that use it. Otherwise used in string particles to define texture repeat distance in world units.
rampRangeV	emitter time curve ( 0.0 ) Defines the initial V range of the UV of the ramp texture +/- the rampV in particle shaders that use it. Otherwise used in string particles to define the texture repeat distance +/- the rampV in world units.
rampOffsetV	bool ( false ) Randomly offset the texture on string particles.
lifetime	emitter time curve ( 1.0 ) Defines initial particle lifetime in seconds.
lifetimeRange	emitter time curve ( 0.0 ) Defines initial particle lifetime range +/- the particle lifetime.
emitterLifetime	number ( 1.0 ) Defines the emitter lifetime in seconds. This the length of time a looping emitter will repeat or how long a non-looping emitter will live before ceasing to emit particles. Particles will finish out their own lifetime after the emitterLifetime ends or a looping particle emitter is turned off.
delay	number ( 0.0 ) Defines a delay in seconds before an emitter lifetime begins the first time. Note: if all of a particle system’s emitters are delayed the particle system may shut down before anything spawns.
delayRange	number ( 0.0 ) Defines a delay range in seconds +/- the delay before an emitter lifetime begins the first time.
bLoop	bool ( true ) Defines if an emitter should loop or happen only once.
loopCount	number ( 0 ) Defines how many times an emitter should loop before ending if bLoop is true. A value of 0 loops indefinitely, a value of 1 has the same behavior as bLoop set to false.
startLoop	number ( 0.0 ) The emitter time in seconds at which each loop of the emitter should restart the lifetime at. Note: can be a negative value.
endLoop	number ( 0.0 ) The emitter time in seconds at which each loop of the emitter should end before restarting the lifetime. A value of 0.0, a negative value, or a value greater than the emitterLifetime will use the emitterLifetime instead.
startDistance	number ( 0.0 ) Disables emitter if camera is closer than this distance.
endDistance	number ( 1.0 ) Disables emitter if camera is further than this distance.
useWorldSpace	bool ( false ) Use world space instead of emitter space for particle position updates. Allows particles to be “left behind” on a moving emitter.
useArcLengthSpace	bool ( false ) Transform particle positions into arc length space. Effectively wraps positions around the planet surface.
interpolateSpawn	bool ( true ) Interpolate the position of world space particles on moving particle systems. Spreads the particles across the current and previous particle system positions to keep smooth position distributions.
killOnDeactivate	bool ( false ) Immediately remove all particles in the emitter if the particle system is disabled. Mainly used on looping effects in the game. Does not kill particles when the emitter lifetime ends.
emissionBursts	bursts ( 0 ) Define bursts of particles over the emitter’s lifetime.
emissionRate	emitter time curve ( 20.0 ) Define the number of particles per second to spawn. Defaults to 0.0 if emissionBursts is defined.
maxParticles	number ( <dynamic> ) Max number of live particles allowed in the emitter at one time. This is not a running total, but a current living count limit. If left undefined it is generally “smart”; it tries to determine the max number based on emit rate and particle lifetime.