Arma 3: Particle Effects

Intro

Please be aware of our Arma 3 modding license: http://community.bistudio.com/wiki/Arma_3_Modding_License

Related links

Definition of an effect in a script:

• ParticleArray
• ParticleTemplates

Definition of effect

There are two ways how to define particle effect in Arma 3 - script and config. Pros and cons of config defined effects:

• difficult editing (every change in any parameter requires restart of the game)
• posibility to change the effect outside of the effect's definition is limited
• more parameters (some advanced parameters are present only in config)
• better performance (this is not true for each effect)
• calling of an effect can be used in a specific engine-supported parameter

Technology of scripted effects is older and the documentation is already present on wiki (see Related links).

Config

Each complex effect (CE) is created by part-effects (PE) (defined in CfgCloudlets) and light (defined in CfgLights).

Definition of complex effect

Class of effect is defined directly in configFile and consists of classes that link PE (or light) to the parent effect.

class Example
{
    simulation = "particles";   //type of simulation - particles or light
    type = "Default";           //name of PE's class defined in CfgCloudlets or light's class defined in CfgLights
    position[] = {0, 0, 0};     //position related to the default position or memorypoint
    lifeTime = 0.05;            //life time of emitter

    qualityLevel = -1;          //effect is used when the particle quality option is -> -1 everytime, 0 low, 1 normal, 2 high
    start = 1;                  //is used only if the lifeTime parameter is defined, if value is changed from negative to positive then the effect is triggered
    enabled = 1;                //1 effect is enabled, -1 effect is disabled
};

Parameters simulation, type, qualityLevel, enabled are used everytime. Using of other parameters depends on calling of the effect (see Calling of effect).

Definition of part-effect

Class of PE must be in configFile class CfgCloudlets.

class Default
{
    interval = "0.5 * speedSize + 0.5";      //interval of particle's creation
    circleRadius = 0;			     //radius around emitter where particles are created
    circleVelocity[] = {0, 0, 0};	     //direction and speed of movement of particle's circle
    particleShape = \A3\data_f\ParticleEffects\Universal\Universal;		//path and name of file
    particleFSNtieth = 16;		     //coef; size of one particle's texture in pixels = 2048/coef
    particleFSIndex = 12;		     //index of start line on texture
    particleFSFrameCount = 8;		     //count of pictures in animation (starts on first picture in defined line - particleFSIndex)
    particleFSLoop = 1;		             //loop of animation (0 - false, 1 - true)
    angle = 0;				     //angle of particle
    angleVar = 0;			     //variability in angle of particle

    animationName = "";
    particleType = "Billboard";	             //type of animation (Billboard (2D), Spaceobject (3D))
    timerPeriod = 1;			     //interval of timer (how often is called script defined in parameter onTimerScript)
    lifeTime = 1;			     //life time of particle in seconds
    moveVelocity[] = {0, 0, 0};	             //direction and speed of movement of particle [x,z,y]
    rotationVelocity = 0;		     //direction and speed of rotation of particle [x,z,y]
    weight = 1;			             //weight of particle (kg)
    volume = 1;			             //volume of particle (m3)
    rubbing = 0.05;			     //how much is particle affected by wind/air resistance
    size[] = {1,1};			     //size of particle during the life
    color[] = {{1,1,1,1},{1,1,1,0}};	     //color of particle during the life (r,g,b,a)
    animationSpeed[] = {1};		     //speed of animation (number of animation cycles in 1s)
    randomDirectionPeriod = 0;		     //interval of random speed change
    randomDirectionIntensity = 0;	     //intensity of random speed change
    onTimerScript = "";		             //script triggered by timer (in variable "this" is stored position of particle)
    beforeDestroyScript = "";		     //script triggered before destroying of particle (in variable "this" is stored position of particle)
    lifeTimeVar = 0;			     //variability in lifetime of particle
    positionVar[] = {0, 0, 0};		     //variability in position of particle (each part of vector has it's own variability)
    positionVarConst[] = {0, 0, 0};	     //variability in position of particle (variablity of all parts of vector is the same)
    moveVelocityVar[] = {0, 0, 0};	     //variability in direction and speed of particle (each part of vector has it's own variability)
    moveVelocityVarConst[] = {0, 0, 0};      //variability in direction and speed of particle (variablity of all parts of vector is the same)
    rotationVelocityVar = 0;		     //variability in rotation of particle
    sizeVar = 0;			     //variability in size of particle
    colorVar[] = {0, 0, 0, 0};		     //variability in color of particle
    randomDirectionPeriodVar = 0;	     //variability in interval of random speed change
    randomDirectionIntensityVar = 0;	     //variability in intensity of random speed change
    sizeCoef = 1;                            //size of particle = size parameter value * this coef
    colorCoef[]={1,1,1,1};                   //size of particle = color parameter value * this coef
    animationSpeedCoef = 1;                  //size of particle = animationSpeed parameter value * this coef

    destroyOnWaterSurface = 0;               //particle can exist - only underwater (-1), only above the water (1), everywhere (0)
    destroyOnWaterSurfaceOffset = 0;         //offset of water surface in destroyOnWaterSurface parameter
    onSurface = true;                        //placing of particle on (water) surface on start of it's existence
    keepOnSurface = false;                   //true for particle is stay on water surface - see notes bellow
    surfaceOffset = 0;                       //offset of water surface in keepOnSurface parameter
    bounceOnSurface = 0.6;                   //coef of speed's loosing in collision with ground, 0-1 for collisions, -1 disable collision
    bounceOnSurfaceVar = 0.0;                //variability in speed's loosing in collision with ground
    postEffects = "IEDMineFlame";            //effect triggered before destroying of particle
    particleEffects = "ExplosionShardsFire"; //emitter of effect defined in this parameter is attached to each particle
};

Notes:

• MoveVelocity parameter affects only initial phase of movement of a particle. Movement in later phase is affected by air resistance, wind and collisions.
• Ascent/descent of a particle is affected by ratio bewteeen particle's density (weight/volume) and density of air (it's 1.275 kg/m3 in Arma).
• Parameters ending with "Coef" are used only in some effects, see Calling of effect.
• Only 3D particles (particleType = "SpaceObject") can use materials.
• You can use single frame in middle of line on texture as texture of particle. Just set particleFSLoop = 0 and animationSpeed[] = {1000}, then paremeter particleFSFrameCount is number of frame in given line.

Calling of effect

There are two ways how to call a particle effect defined in config. You can use script or one of the engine-provided config parameters. Using of a config parameter (if there is one you can use) is usually recommended, because of better performance and an efficient use of engine-provided variables in PE definitions (see the list bellow).

Script

There is script command setParticleClass. This command can use only a class of PE.
Example:

_source01 = "#particlesource" createVehicleLocal _pos01;
_source01 setParticleClass "ObjectDestructionFire1Smallx";
_source01 attachto [_object,[0,0,0]];

Config parameters

These engine-provided parameters have already set conditions for using of particle effect. For example parameter for exhaust effect is triggered when the engine of vehicle is running. Each parameter has engine-provided variables which can be used in some parts of definition of particle effect.

For more info see List of config parameters.