ParticleArray: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "_this" to "_this")
(Table updated: Column for "since" and first column is zero-based index now)
Line 33: Line 33:
]</code>
]</code>
{| class="wikitable sortable"
{| class="wikitable sortable"
! # !! parameter name !! Type !! Description
! Index !! parameter name !! Type !! Description !! Since
|-
|-
| 1 || shapeName || Render || [[String]] or [[Array]] format [p3dPath, n<sup>th</sup>, index, count, loop]:
| 0 || shapeName || Render || [[String]] or [[Array]] format [p3dPath, n<sup>th</sup>, index, count, loop]:
* p3dPath: [[String]]
* p3dPath: [[String]]
* n<sup>th</sup>: [[Number]]
* n<sup>th</sup>: [[Number]]
Line 41: Line 41:
* count: [[Number]]
* count: [[Number]]
* loop: [[Number]]
* loop: [[Number]]
|
|-
|-
| 2 || animationName || {{n/a}} || [[String]] - obsolete parameter that was meant to play .rtm anims, will throw "Skeletal animation not supported for particles" rpt error if not empty
| 1 || animationName || {{n/a}} || [[String]] - obsolete parameter that was meant to play .rtm anims, will throw "Skeletal animation not supported for particles" rpt error if not empty ||
|-
|-
| 3 || type || Render || [[String]] - "Billboard" or "SpaceObject"
| 2 || type || Render || [[String]] - "Billboard" or "SpaceObject" ||
|-
|-
| 4 || timerPeriod || Script || [[Number]] - In seconds.
| 3 || timerPeriod || Script || [[Number]] - In seconds. ||
|-
|-
| 5 || lifetime || Physical || [[Number]] - In seconds.
| 4 || lifetime || Physical || [[Number]] - In seconds. ||
|-
|-
| 6 || position || Physical || [[Array]] format [[Position]]
| 5 || position || Physical || [[Array]] format [[Position]] ||
|-
|-
| 7 || moveVelocity || Physical || [[Array]] format [[velocity]]
| 6 || moveVelocity || Physical || [[Array]] format [[velocity]] ||
|-
|-
| 8 || rotationVelocity || Physical || [[Number]] - rotations per second
| 7 || rotationVelocity || Physical || [[Number]] - rotations per second ||
|-
|-
| 9 || weight || Physical || [[Number]] - weight of the particle (kg)
| 8 || weight || Physical || [[Number]] - weight of the particle (kg) ||
|-
|-
| 10 || volume || Physical || [[Number]] - volume of the particle in m<sup>3</sup>
| 9 || volume || Physical || [[Number]] - volume of the particle in m<sup>3</sup> ||
|-
|-
| 11 || rubbing || Physical || [[Number]] - Determines how particles blown by winds (include downwash by helicopters).
| 10 || rubbing || Physical || [[Number]] - Determines how particles blown by winds (include downwash by helicopters). ||
|-
|-
| 12 || size || Render || [[Array]] of [[Number]]s - particle size along its ''lifetime'', in meter
| 11 || size || Render || [[Array]] of [[Number]]s - particle size along its ''lifetime'', in meter ||
|-
|-
| 13 || color || Render || [[Array]] of [[Array]]s format [[Color|Color (RGBA)]]
| 12 || color || Render || [[Array]] of [[Array]]s format [[Color|Color (RGBA)]] ||
|-
|-
| 14 || animationPhase || Render || [[Array]] of [[Number]]s - phase of the animation in time. In other words, the play speed of the selected frames for the Number of Frames to Play above.  The higher the number, the faster it plays through the animation frames. Note that if the Number of Frames to Play above is set to 1, this will have no visible effect.
| 13 || animationPhase || Render || [[Array]] of [[Number]]s - phase of the animation in time. In other words, the play speed of the selected frames for the Number of Frames to Play above.  The higher the number, the faster it plays through the animation frames. Note that if the Number of Frames to Play above is set to 1, this will have no visible effect. ||
|-
|-
| 15 || randomDirectionPeriod || Random || [[Number]] - In seconds.
| 14 || randomDirectionPeriod || Random || [[Number]] - In seconds. ||
|-
|-
| 16 || randomDirectionIntensity || Random || [[Number]] - How particles change its velocity every once in ''randomDirectionPeriod'' seconds, in meters'''?'''
| 15 || randomDirectionIntensity || Random || [[Number]] - How particles change its velocity every once in ''randomDirectionPeriod'' seconds, in meters'''?''' ||
|-
|-
| 17 || onTimer || Script || [[String]] - path to the script to be executed on timer. Variable [[Magic Variables#this|_this]] contains particle position. <code>[[private]] _particlePosition = [[Magic Variables#this|_this]];</code>
| 16 || onTimer || Script || [[String]] - path to the script to be executed on timer. Variable [[Magic Variables#this|_this]] contains particle position. <code>[[private]] _particlePosition = [[Magic Variables#this|_this]];</code> ||
|-
|-
| 18 || beforeDestroy || Script || [[String]] - code executed right before particle's destruction. <code>[[private]] _particlePosition = [[Magic Variables#this_2|this]];</code>
| 17 || beforeDestroy || Script || [[String]] - code executed right before particle's destruction. <code>[[private]] _particlePosition = [[Magic Variables#this_2|this]];</code> ||
|-
|-
| 19 || object || Physical || [[Object]] - If this parameter isn't [[objNull]], the particle source will be attached to the object. The source will stop to generate its particles when the distahce between the object and the source is further than [[getObjectViewDistance|Object View Distance]].
| 18 || object || Physical || [[Object]] - If this parameter isn't [[objNull]], the particle source will be attached to the object. The source will stop to generate its particles when the distahce between the object and the source is further than [[getObjectViewDistance|Object View Distance]]. ||
|-
|-
| 20 || angle || Physical || [[Number]] - ('''Optional''', default 0) determines the particle's starting angle '''in radian'''. [[pi]] = 180°. {{Since|||y}}
| 19 || angle || Physical || [[Number]] - ('''Optional''', default 0) determines the particle's starting angle '''in radian'''. [[pi]] = 180°. || <center>{{Icon|Unknown}}</center>
|-
|-
| 21 || onSurface || Physical || [[Boolean]] - ('''Optional''', default [[false]]) Bounce the particles when hit the surface if [[true]]. If ''circleRadius'' > 0, placing of particle on (water) surface on start of its existence. Circle radius is defined by command [[setParticleCircle]]. {{Since|arma3|0.74|y}}
| 20 || onSurface || Physical || [[Boolean]] - ('''Optional''', default [[false]]) Bounce the particles when hit the surface if [[true]]. If ''circleRadius'' > 0, placing of particle on (water) surface on start of its existence. Circle radius is defined by command [[setParticleCircle]]. || {{GVI|arma3|0.74}}
|-
|-
| 22 || bounceOnSurface || Physical || [[Number]] - ('''Optional''', default -1) coef of bounce in collision with ground, 0..1 for collisions, -1 to disable collision. Should be used soberly as it has a significant impact on performance. {{Since|arma3|0.74|y}}
| 21 || bounceOnSurface || Physical || [[Number]] - ('''Optional''', default -1) coef of bounce in collision with ground, 0..1 for collisions, -1 to disable collision. Should be used soberly as it has a significant impact on performance. || {{GVI|arma3|0.74}}
|-
|-
| 23 || emissiveColor || Render || [[Array]] of [[Array]]s format [[Color|Color (RGBA)]] - ('''Optional''', default {{Inline code|[&nbsp;]}}'''?''') Sets emissivity of the particle ('''RGB0'''). Works as lighting of particles, so must be combined with correctly set particle color. Values need to be higher than just 0-1 to have a real effect (f.e. 100 times the RGB color values). Last parameter has no meaning for now. {{Since|arma3|1.08|y}}
| 22 || emissiveColor || Render || [[Array]] of [[Array]]s format [[Color|Color (RGBA)]] - ('''Optional''', default {{Inline code|[&nbsp;]}}'''?''') Sets emissivity of the particle ('''RGB0'''). Works as lighting of particles, so must be combined with correctly set particle color. Values need to be higher than just 0-1 to have a real effect (f.e. 100 times the RGB color values). Last parameter has no meaning for now. || {{GVI|arma3|1.08}}
|-
|-
| 24 || vectorDir || Physical || [[Array]] format [[vectorDir]]'''?''' - ('''Optional''') Sets the default direction for '''SpaceObject''' particles. {{Since|arma3|1.92|y}}
| 23 || vectorDir || Physical || [[Array]] format [[vectorDir]]'''?''' - ('''Optional''') Sets the default direction for '''SpaceObject''' particles. || {{GVI|arma3|1.92}}
|}
|}



Revision as of 17:30, 25 February 2021

Particle is a lightweight for performance effect system that is to be used for emulate dusts, fires, explosions, and/or anything. Every explosions, dusts, fires and most of in-game 3D effects are made in this system.
Particles can be generated by script commands like drop, so you can also do emulate them easily.


Format

[ shapeName, animationName, type, timerPeriod, lifeTime, position, moveVelocity, rotationVelocity, weight, volume, rubbing, size, color, animationPhase, randomDirectionPeriod, randomDirectionIntensity, onTimer, beforeDestroy, object, angle, // Template:Since onSurface, // Template:Since bounceOnSurface, // Template:Since emissiveColor, // Template:Since vectorDir // Template:Since ]

Index parameter name Type Description Since
0 shapeName Render String or Array format [p3dPath, nth, index, count, loop]:
1 animationName N/A String - obsolete parameter that was meant to play .rtm anims, will throw "Skeletal animation not supported for particles" rpt error if not empty
2 type Render String - "Billboard" or "SpaceObject"
3 timerPeriod Script Number - In seconds.
4 lifetime Physical Number - In seconds.
5 position Physical Array format Position
6 moveVelocity Physical Array format velocity
7 rotationVelocity Physical Number - rotations per second
8 weight Physical Number - weight of the particle (kg)
9 volume Physical Number - volume of the particle in m3
10 rubbing Physical Number - Determines how particles blown by winds (include downwash by helicopters).
11 size Render Array of Numbers - particle size along its lifetime, in meter
12 color Render Array of Arrays format Color (RGBA)
13 animationPhase Render Array of Numbers - phase of the animation in time. In other words, the play speed of the selected frames for the Number of Frames to Play above. The higher the number, the faster it plays through the animation frames. Note that if the Number of Frames to Play above is set to 1, this will have no visible effect.
14 randomDirectionPeriod Random Number - In seconds.
15 randomDirectionIntensity Random Number - How particles change its velocity every once in randomDirectionPeriod seconds, in meters?
16 onTimer Script String - path to the script to be executed on timer. Variable _this contains particle position. private _particlePosition = _this;
17 beforeDestroy Script String - code executed right before particle's destruction. private _particlePosition = this;
18 object Physical Object - If this parameter isn't objNull, the particle source will be attached to the object. The source will stop to generate its particles when the distahce between the object and the source is further than Object View Distance.
19 angle Physical Number - (Optional, default 0) determines the particle's starting angle in radian. pi = 180°.
Unknown
20 onSurface Physical Boolean - (Optional, default false) Bounce the particles when hit the surface if true. If circleRadius > 0, placing of particle on (water) surface on start of its existence. Circle radius is defined by command setParticleCircle. Arma 3 logo black.png0.74
21 bounceOnSurface Physical Number - (Optional, default -1) coef of bounce in collision with ground, 0..1 for collisions, -1 to disable collision. Should be used soberly as it has a significant impact on performance. Arma 3 logo black.png0.74
22 emissiveColor Render Array of Arrays format Color (RGBA) - (Optional, default [ ]?) Sets emissivity of the particle (RGB0). Works as lighting of particles, so must be combined with correctly set particle color. Values need to be higher than just 0-1 to have a real effect (f.e. 100 times the RGB color values). Last parameter has no meaning for now. Arma 3 logo black.png1.08
23 vectorDir Physical Array format vectorDir? - (Optional) Sets the default direction for SpaceObject particles. Arma 3 logo black.png1.92

Parameters

Global parameters

ArmA particle texture

ShapeName - Name of the shape associated with the particle.

In ArmA, the ShapeName is defined as an array. This should be the particle shape name, followed by three integers.
Example: ["\Ca\Data\ParticleEffects\FireAndSmokeAnim\SmokeAnim.p3d", 8, 5, 0]
1. Anim Divisor (1 for a 1x1, 8 for a 8x8, etc)
2. Anim Starting Row
3. Number of Frames to Play (speed controlled by animation phase below)
In this shot of "\Ca\Data\ParticleEffects\FireAndSmokeAnim\SmokeAnim.p3d", note the following:
The image used for this particle effect is 8X8 effect frames. This means you need to use 8 as your Anim Divisor. Overwise, the game will either draw too much of the image used, or too little. This is highly visible in most situations.
The Anim Starting Row picks the coresponding superimposed number in the image above. 0 picks the first smoke effect, 1 picks the second smoke effect, 2 picks the first fire effect, etc.
The setting for the Number of Number of Frames to Play should, in most cases, be the number of effects available to the animation. If you go over this (for example, selecting 9 in this 8X8 tile), it will start playing the animation frames of the next effect down. If there is nothing below to grab, it will draw a blank for that frame. If 1 is used, it will only play the first frame of the selected row.
If you want to find out of how many rows a datasource consists use ["...", 1, 0, 1] to see the full picture as a particle.
Arma2 particle texture

In Arma 2 (and OA), the method for determining how many frames to play has changed.

Example 1:

["\Ca\Data\ParticleEffects\Universal\Universal", 16, 10, 32, 1]
1. Anim Divisor (for the new Universal particle model it is 16 since the texture file is 16x16)
2. Anim Starting Row (starting a 0)
3. Number of Frames to play (Starting with 1 and not 0)
4. Animation Loop (0 = no loop, 1 = loop (default if left blank is 1))
Example 1 above (a fire burning) will start the animation in row 10, will play from frames 1 to 32, and will loop.


Also in Arma 2 and OA, To achieve a single frame of animation that is not the first column of a row, use the third numerical value as a column selection instead of indicating how many frames to play.

Example 2:

["\Ca\Data\ParticleEffects\Universal\Universal", 16, 12, 9, 0]
1. Anim Divisor (for the new Universal particle model it is 16 since the texture file is 16x16)
2. Anim Starting Row (starting at 0)
3. Column Selection (Starting with 1 and not 0)
4. Animation Loop (0 = no loop, 1 = loop (default if left blank is 1))
Additional Step: You must also set the AnimationPhase value (described in render parameters) to a large number (such as 1000) if you only want to play a single frame. The reason for this is that the game engine does not only play a single frame, it actually begins at the first frame in the row and cycles to the desired frame. If a small AnimationPhase number is used then you can actualy see the animation cycle through the all the frames (1-9). A large number makes this imperceptible and only the desired frame appears to be displayed.
Arma3 particle texture (Universal)
Example 2 above (exploding rock dust) will start the animation in row 12, will only play frame 9, and will not loop.


AnimationName - Has to be a String, but it is obsolete. Used to play .rtm anims, if not empty, it will throw "Skeletal animation not supported for particles" rpt error

Type - Type of particle (either "Billboard" or "SpaceObject").

TimerPeriod - The period of calling the "OnTimer" event (in sec).

LifeTime - Life time of the particle (in sec).

Physical parameters

Position -' Either 3D coordinate (x, y, z) or name of the selection - in this case the Object property must be set.

MoveVelocity - 3D vector (x, y, z) which describes the velocity vector of the particle direction and speed in m/s.

RotationVelocity - Float number which determines number of rotations in one second.

Weight - Weight of the particle (kg).

Volume - Volume of the particle (m^3).

Rubbing - Float number without dimension which determines the impact of the density of the environment on this particle. 0 - no impact (vacuum).

Angle - Float number which determines starting angle of the particle.

OnSurface - Boolean. Placing of particle on (water) surface on start of it is existence, default value is true, works only if circleRadius > 0. Circle radius is defined by command setParticleCircle. Works since Arma 3 v. 0.74.

BounceOnSurface - Coef of speed's loosing in collision with ground, 0-1 for collisions, -1 disable collision. Default value -1. Should be used soberly, it has significant impact on performance. Works since Arma 3 v. 0.74.

Arma3 particle texture (Universal_02)

Render parameters

Note: All these values are set as arrays to show their development in time.

If you set the array [1, 2] as a size, then at the beginning the size of the particle will be 1 and at the end of the life time of the particle its size will be 2.

The rest of the values during the life time will be linearly interpolated.


Size - Size of the particle in time to render (m).

Color - Colour of the particle in time to render (RGBA).

EmissiveColor - Sets emissivity of the particle (RGB0). Works as lighting of particles, so must be combined with correctly set particle color. Last parameter has no meaning for now.

AnimationPhase - Phase of the animation in time. In other words, the play speed of the selected frames for the Number of Frames to Play above. The higher the number, the faster it plays through the animation frames. Note that if the Number of Frames to Play above is set to 1, this will have no visible effect.

Random parameters

RandomDirectionPeriod - Period of change of the velocity vector (s).

RandomDirectionIntensity - Each MoveVelocity component will be changed with random value from interval <0, RandomDirectionIntensity>.

OnTimer - Name of the script to run every period determined by TimerPeriod property.

Position of the particle is stored in "this" variable.

BeforeDestroy - Name of the script to run right before destroying the particle.

Position of the particle is stored in "this" variable.

Object - Object to bind this particle to.


Example

For several examples of the kind of effects that can be accomplished via particles, see ParticleTemplates.

Thunderbolt

Create thunderbolt on logic named logic1:

private _pos = [position logic1 select 0,position logic1 select 1, 10];
drop ["blesk1", "", "Billboard", 0.01, 0.2, _pos, [0,0,0], 0, 1, 1, 0, [20 + random 20], [[1,1,1,1], [1,1,1,0.7]], [1,0], 0, 0, "", "", ""];

Mass grave Flies

// SCRIPT FOR GENERATING FLIES AROUND MASS GRAVE

// FIXED PARAMS
private _source = "#particlesource" createVehicleLocal getPos (_this select 0);
_source setParticleParams [
/* Sprite */			["\ca\characters2\OTHER\FLY.p3d",1,0,1,0], // File,Ntieth,Index,Count,Loop
/* Animation */			"",
/* Type */				"spaceObject",
/* TimerPer */			1,
/* Lifetime */			4,
/* Position */			[0,0,0],
/* MoveVelocity */		[0,0,0.5],
/* Simulation */		1,1.30,1,0, // rotationVel, weight, volume, rubbing
/* Scale */				[0.03,0.03,0.03,0],
/* Color */				[[1,1,1,1],[1,1,1,1]],
/* AnimSpeed */			[1.5,0.5],
/* randDirPeriod */		0.01,
/* randDirIntensity */	0.08,
/* onTimerScript */		"",
/* DestroyScript */		"",
/* object */			_this,
/* Angle */             0,
/* onSurface */         true,
/* bounceOnSurface */   0.5,
/* emissiveColor */     [[0,0,0,0]]];

// RANDOM / TOLERANCE PARAMS
_source setParticleRandom [
/* LifeTime */			2,
/* Position */			[2,2,0.25],
/* MoveVelocity */		[0,0,0],
/* rotationVel */		1,
/* Scale */				0.02,
/* Color */				[0,0,0,0.1],
/* randDirPeriod */		0.01,
/* randDirIntensity */	0.03,
/* Angle */				10];

_source setDropInterval 0.003;
private _soundSource = createSoundSource ["Sound_Flies", getPos (_this select 0), [], 0];


Tutorials