This wiki is archived from 2021-09-05

Particle System Reference: Difference between revisions

From Planetary Annihilation: TITANS and Classic PA Wiki
Jump to navigation Jump to search
mNo edit summary
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  [[Category:Modding]]
  [[Category:Modding]]


= [[File:Titans-icon.png|50px]] Planetary Annihilation Titans & Classic Particle Effect System Reference =
= Planetary Annihilation Particle Effect System Reference =


Work in progress, go [https://wiki.palobby.com/wiki/Particle_System here].
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:
Overview of how the system works:
Line 10: Line 13:
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.
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.
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 =
= Glossary =
Line 40: Line 42:
! style="text-align: left" | Field Name
! style="text-align: left" | Field Name
! style="text-align: left" | Field Type (default value) - Description
! style="text-align: left" | Field Type (default value) - Description
{{template:pfx_spec_row | spec | object | | The particle spec definition. }}
{{template:pfx_spec_row | spec | object | {} | The particle spec definition. }}
{{template:pfx_spec_row | type | string | "POSITION" | Defines the shape of the particle spawn positions, and how the <code>offset*</code> keys are interpreted.<br/>Valid types are <code>"POSITION"</code>, <code>"SPHEROID"</code>, <code>"SHELL"</code>, <code>"EMITTER"</code>, <code>"CYLINDER_X"</code>, <code>"CYLINDER_Y"</code>, and <code>"CYLINDER_Z"</code>}}
{{template:pfx_spec_row | type | string | "POSITION" | Defines the shape of the particle spawn positions, and how the <code>offset*</code> keys are interpreted.<br/>Valid types are <code>"POSITION"</code>, <code>"SPHEROID"</code>, <code>"SHELL"</code>, <code>"EMITTER"</code>, <code>"CYLINDER_X"</code>, <code>"CYLINDER_Y"</code>, and <code>"CYLINDER_Z"</code>}}
{{template:pfx_spec_row | linkIndex | number | -1.0 | Used when the <code>type</code> is set to <code>"EMITTER"</code> to define the emitter to attach to. }}
{{template:pfx_spec_row | linkIndex | number | -1.0 | Used when the <code>type</code> is set to <code>"EMITTER"</code> to define the emitter to attach to. }}
Line 51: Line 53:
{{template:pfx_spec_row | useShapeVelocityDir  | bool | false | Use the starting position on the shape from the emitter's type in addition to the velocity direction values. }}
{{template:pfx_spec_row | useShapeVelocityDir  | bool | false | Use the starting position on the shape from the emitter's type in addition to the velocity direction values. }}
{{template:pfx_spec_row | velocity            | emitter time curve | 1.0 |  Initial particle velocity along velocity direction vector at spawn. }}
{{template:pfx_spec_row | velocity            | emitter time curve | 1.0 |  Initial particle velocity along velocity direction vector at spawn. }}
{{template:pfx_spec_row | velocityRange            | emitter time curve | 0.0 | Initial particle velocity range +/- velocity. }}
{{template:pfx_spec_row | velocityRange            | emitter time curve | 0.0 | Initial particle velocity range +/- velocity. }}
{{template:pfx_spec_row | inheritedVelocity        | emitter time curve | 0.0 | Add the system’s velocity multiplied by this value to the initial particle velocity.}}
{{template:pfx_spec_row | inheritedVelocity        | emitter time curve | 0.0 | Add the system’s velocity multiplied by this value to the initial particle velocity.}}
Line 100: Line 99:
Particle specification.
Particle specification.


{| class="wikitable" style="width:100%; background:white"
{| class="wikitable" style="width:100%"
|-  
|-  
! style="width:100px;text-align: left" | Field Name
! style="width:100px;text-align: left" | Field Name

Latest revision as of 10:58, 9 September 2021


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.