Particle System Reference

Planetary Annihilation Particle Effect System Reference

https://docs.google.com/document/d/1MP3SM9a4-mFDLp31Fibom9Mxf-pBCzFANLz4D5fLnkA/edit?usp=sharing

The following needs to be cleaned up or deleted by dom ;-)

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.

Particle Spec

Particle specification.

Field Name	Field Type (default value): Description
shader	string ( "particle_add" ) Defines the shader effect used to draw the particle.
shape	string ( "rectangle" ) Defines what kind of particle shape is used. Possible values are "rectangle", "string", "beam", "pointlight", and "mesh"
facing	string ( "camera" ) Defines how the particle shape is drawn. Possible values are "camera", "velocity", "emitterX", "emitterY", "emitterZ", "axialX", "axialY", and "axialZ"
useInitialVelocityDir	bool ( false ) Defines if velocity facing particles should use their initial velocity direction over the entire lifetime of the particle or the current velocity direction.
useRandomDir	bool ( false ) Defines if velocity facing particles should use a random direction for their facing instead of the velocity direction.
size sizeX sizeY	particle time curve ( 1.0 ) Defines the size scale over the life of a particle. The X and Y can be defined separately, or if sizeX is defined by itself the value will be applied to both X and Y. The value size is shorthand for sizeX, but will be ignored if sizeX is defined.
red green blue alpha	particle time curve ( 1.0 ) Defines the linear float color multiplier over the life of a particle.
rgb	particle time rgb curve ( [0.0, 1.0, [255, 255, 255]] ) Color multiplier in sRGB binary color form with a brightness.
baseTexture	string ( "/pa/effects/textures/particles/default_particle.papa" ) Defines the base texture used for the particle.
rampTexture	string ( "/pa/effects/textures/particles/uncompressed/no_ramp.papa" ) Defines the ramp texture used for the particle for shaders that use it.
flipBookColumns	number ( 0.0 ) Defines number of columns in flip book.
flipBookRows	number ( 0.0 ) Defines number of rows in flip book.
flipBookFrames	number ( 0 ) Defines number of frames in flip book. Defaults to flipBookColums * flipBookRows.
flipBookRandomStart	bool ( false ) Defines if the flip book should start on a random frame or always the first frame. Useful for looping flip book textures to reduce repetition or for non animation flip books.
frameCurve	particle time curve ( 0.0 ) Defines the flipbook animation timing. Is used as frameCurve * flipBookFrames, so 0.0 and 1.0 would both be the first frame.
cameraPush	particle time curve ( 0.0 ) Pushes particles towards the camera.
rotationRateMult	particle time curve ( 1.0 ) Adjust the rotation rate over the particle’s lifetime by a multiplier. Can be used to speed up or slow down a particle’s rotation rate.
polyAdjustCenter	particle time curve ( 0.0 ) Pushes the particle’s pivot along the Y axis.
beamSegmentLength	float ( 0.0 ) Defines number of points in beam particles by distance to target / segment length.
panRate	particle time curve ( 0.0 ) Defines the texture pan rate on beams.
dataChannelFormat	string ( "Position" ) Defines the data format for particles. Basically controls what properties of the particle are passed on to the GPU for optimisation purposes. Generally smart if not defined. Possible values are "Position", "PositionWithAlpha", "PositionAndColor", "PositionColorAndAlignVector", and "PositionColorAndFlipbook"
papa	string ( ) Used for mesh particles.
materialProperties	material block ( {} ) Used for mesh particles.