Particle configuration

Below lies the description of particle configuration files (.pcfg, .pgrp)? In the following specification we adopt this convention:

.pcfg

The overall structure is:

PARTICLE "" this is at the beginning of file. There can be a name of particle in "" (but it isn't used in a game).

Following two blocks are optional (when PART_MODELS is defined then PART_TEXTURES are ignored, when none of them is defined, the particles will be billboards using color defined in COLOR):

PART_TEXTURES definition of textures which will be used by particles (they will be shown as billboards)
  PNAME "string" string contains name of texture file used for billboard (it can have extension .anim which is an animated texture or .tga which is plain texture in Targa format). This name should have local path (i.e. tactical/textures/...).
There can be any number of textures - when particle is created one random texture from this list will be attached to it.
END_OF_PART_TEXTURES end of definition of textures
 
PART_MODELS definition of models which will represent particles
  PNAME "string" string contains name of model which will represent particle (it should have extension .txt). This name should have local path (i.e. tactical/models/...).
There can be any number of models - when particle is created one random model from this list will be selected as a representation of particle.
END_OF_PART_MODELS end of definiton of models

Following block is optional:

EXT_NAMES definition of "external names"
   PNAME "EXTCOL" currently only one external name is fully supported and it is EXTCOL - it means that particles will collide with the scene
END_OF_EXT_NAMES end of definition of external names

Definition of particle:

END_TIME_MS i the time in ms which says how long will the whole particle live (not only particular particle), after this time the whole effect will end (and will be freed from memory) or if CYCLE is true it will start from beginning (but without creation of new particles, only forces, attractors, etc. will be affected)
START_TIME_MS i the time in ms which says for how long should the particle effect process when it is created. For example when you have fire you may want it to start already firing, so you set it this to some nonzero number
START_TIME_DELTA i this is multiplied by random number (0 -1) and added to START_TIME_MS
NUM_OF_PARTICLES i number of particles - there won't be more particles in this effect than this number
START_CREATION f (0 - 1) fraction of START_TIME_MS when the particles will start to be created
END_CREATION f (0 - 1) fraction of END_TIME_MS when the particles will cease to be created
when START_CREATION = END_CREATION = 0 all particles will be created at the start of the effect at once otherwise they will be uniformly created in the specified time interval
CYCLE b (TRUE, FALSE) - specifies whether the effect is unfinite or will last for END_TIME_MS miliseconds
RESPAWN b (TRUE, FALSE) - specifies whether the particular particles should be created again when they surpass their LIFE_TIME
CONTACT_COEF f (0 - 1) when 1 - the particle will always bounce when it contacts with obstruction
when 0 - the particle will always stay on obstruction when it contacts, otherwise it depends on magnitude of velocity and f whether it will bounce or stay still
HOME_INTENSITY f multiplier which is applied to a force from current possition of particle to its spawning posision
DAMPING f multiplier which is applied to a damping force
DRIFT f multiplier which is applied to a force (RND()-0.5f,RND()-0.5f,RND()-0.5f)
CLIP e (0, 1, 2) - 0 - no clipping performed
- 1 - when the particle hits bounding box it will continue on opposite side of scene
- 2 - when the particle hits bounding box it will disappear
MAXIMAL_STEP i the maximal time in ms for which particles will be processed in one frame (when zero it is unlimited)
LIFE_TIME i the time in ms which says how long will particular particle live. Then it can either cease to exist or respawn again (when RESPAWN is TRUE).
LIFE_SIGMA f sigma used in normal gaussian distribution - it can create variable life times of particles
BILLBOARD_ANGLE f radians/sec - specifies how much will billboard particles rotate (the signs specified the direction of rotation). It has sense only when particles are billboard, it is ignored when they are models.
BILLBOARD_SIGMA f sigma in normal gaussian distribution - how much will BILLBOARD_ANGLE vary for each particular particle.
START_POSITION e f1 f2 f3
               f4 f5 f6
               f7 f8 f9
specifies how the emitor of particles appears - the particles are uniformly generated in specified space
e emitor is
0 point, (f1, f2, f3) is the position of emitor
1 box, (f1, f2, f3) - start position (f4, f5, f6) - opposite corner of box
2 line, (f1, f2, f3) - start position, (f3, f4, f5) - vector
3 rectangle, (f1, f2, f3) - start position,
(f4, f5, f6) - vector 1,
(f7, f8, f9) - vector 2
4 emitor is sphere, (f1, f2, f3) - center, f4 - inner radius, f5 - outer radius, particles are generated in space between inner and outer radius
5 cylinder, (f1, f2, f3) - center, (f4, f5, f6) - vector from center, f7 - inner radius, f8 - outer radius
6 cone, (f1, f2, f3) - center, (f4, f5, f6) - vector from center, f7 - inner radius, f8 - outer radius
7 blob, (f1, f2, f3) is the position of emitor, f4 is sigma used in normal gaussian distribution, the particle will be thus generated at position, (f1+NormRand(f4), f2+NormRand(f4), f3+NormRand(f4))
8 lightning (it's a special type useful mainly for effects of firing)
(f1, f2, f3) - start position
(f4, f5, f6) - end position
f7 - number of lightning points - depends also on distance between start and end position (distance in meters is multiplied by f7 and 2 are added)
f8 - variation in lightning points (f8*RND() is added to number of lightning points
f9 - distance of lightning point from line between start and end points (NormRand(1)*y9 in meters)
START_VELOCITY e f1 f2 f3
               f4 f5 f6
               f7 f8 f9
specifies the emitor of velocity vector (cm/s), e, etc... is the same as above
START_ANGVELOCITY e f1 f2 f3
                  f4 f5 f6
                  f7 f8 f9
specifies the emitor of angular velocity vector (cm/s), e, etc... is the same as above. It has sense only when particles are models, it is ignored when they are billboards.
BOUNDBOX f1 f2 f3 f4 f5 f6 bounding box of whole particle effect (the effect shouldn't get out of this box - it's used for speeding up graphics; particle aren't drawn when bounding box isn't seen)
f1 - x min, f2 - y min, f3 - z min, f4 - x max, f5 - y max, f6 - z max

After these definitions of particles there can be any number of following blocks (all of them are optional):

ATTRACTOR attractor will influence all particles, below is the definition of this attractor
  START_TIME f (0 - 1) fraction of END_TIME_MS when the attractor will start to influence particles, it will be at START_POSITION and will have START_INTENSITY intensity in this instant
  END_TIME f (0 - 1) fraction of END_TIME_MS when the attractor will cease to influence particles, it will be at END_POSITION and will have END_INTENSITY intensity in this instant
  START_POS f1 f2 f3 position (f1, f2, f3) of attractor at START_TIME
  END_POS f1 f2 f3 position (f1, f2, f3) of attractor at END_TIME
  START_INTENSITY f intensity of attractor at START_TIME, the force which will be applied to all particles is computed in this way: |position of attractor - position of particle| * intensity (where |x| is normed x); it means that depending on sign of intensity it will attract or repel the particles
  END_INTENSITY f intensity of attractor at END_TIME
the attractor will linearly move from START_POS to END_POS and its intensity will linearly change from START_INTENSITY to END_INTENSITY in its time frame
please note that when START_TIME and END_TIME are almost same number the attractor needn't be created at all and thus won't influence the particles - it will depend on frame rate
END_OF_ATTRACTOR end of definition of attractor
... number of attractors isn't limited

FORCE force will be applied to all particles, below is the definition of this force
  START_TIME f (0 - 1) fraction of END_TIME_MS when the force will start to take effect on particles, it will be START_VECTOR in this instant
  END_TIME f (0 - 1) fraction of END_TIME_MS when the force will cease to take effect on particles, it will be END_VECTOR in this instant
  START_VECTOR f1 f2 f3 force (f1, f2, f3) (1kg cm /sec^2) will be applied at START_TIME
  END_VECTOR f1 f2 f3 force (f1, f2, f3) (1kg cm /sec^2) will be applied at END_TIME
the force will linearly interpolate from START_VECTOR to END_VECTOR in its time frame
please note that when START_TIME and END_TIME are almost same number this force needn't be applied - it will depend on frame rate
END_OF_FORCE end of definition of force
... number of forces isn't limited

COLOR color will be changed in all particles, below is the definition of color change
  START_TIME f (0 - 1) fraction of LIFE_TIME when the color change will start to take effect on particles
  END_TIME f (0 - 1) fraction of LIFE_TIME when the color change will cease to take effect on particles
  MIN_START_COLORA f1 f2 f3 f4 (0 - 1) color red(f1), green(f2), blue(f3) and alpha(f4) will be applied to a particle (as for alpha - 0 means fully transparent, 1 solid). Some number will be chosen on "line" connecting MIN_START_COLOR and MAX_START_COLOR and the particle will be set to a color in between those 2 colors according to selected number. This number will not change for the whole life of particle (it will also influence other possible color blocks) so that color transition between two possible blocks will be smoth. The particle will have this color when at START_TIME fraction of its LIFE_TIME and the color will slowly change to something (depending on generated number) between MIN_END_COLORA and MAX_END_COLORA when the time will progress. It will be set to it when reaching END_TIME fraction of its LIFE_TIME. Everything is linear here.
  MIN_END_COLORA f1 f2 f3 f4 (0 - 1) see above for explanation
  MAX_START_COLORA f1 f2 f3 f4 0 - 1) see above for explanation
  MAX_END_COLORA f1 f2 f3 f4 (0 - 1) see above for explanation
END_OF_COLOR end of definition of color
... number of colors isn't limited but their time spans shouldn't overlap (in that case the first color will be chosen and applied to particle)

SIZE size of particles will change, below is the definition of size change
  START_TIME f (0 - 1) fraction of LIFE_TIME when the size change will start to take effect on particles
  END_TIME f (0 - 1) fraction of LIFE_TIME when the size change will cease to take effect on particles
  MIN_START_SIZE f similar to color (see above) change, it's simpler that the size is one number instead of four. The generated number is different from generated number for color change but it is also valid for the whole life of particle.
  MIN_END_SIZE f see above for explanation
  MAX_START_SIZE f see above for explanation
  MAX_END_SIZE f see above for explanation
END_OF_SIZE end of definition of size
... number of sizes isn't limited but their time spans shouldn't overlap (in that case the first size will be chosen and applied to particle)

COLPLANE particles will collide with plane, it's definition lies below
  NORMAL f1 f2 f3 normal (f1, f2, f3) of collision plane
  DISTANCE f distance d in definition of plane in normal form (ax+by+cz+d = 0)
  FRICTION f specifies how much (in term of length) will the particle bounce
  RESILIENCE f specifies how much (in term of height) will the particle bounce
  CUTOFF f when nonzero specifies when friction will not be applied
END_OF_COLPLANE end of definition of collision plane

COLSPHERE particles will collide with sphere, it's definition lies below
  POSITION f1 f2 f3 center (f1, f2, f3) of collision sphere
  RADIUS f radius of collision sphere
  FRICTION f same as at the collision plane
  RESILIENCE f same as at the collision plane
  CUTOFF f same as at the collision plane
END_OF_COLSPHERE end of definition of collision sphere

END_OF_PARTICLE this is at the end of file and means end of definition of particle

.pgrp

The overall structure is:
#!TXT#PARTICLEGR# this has to be at the beginning of file
PARTICLEGR "" there is a definition of particle group after the header. There can be a name of particle in "" (but it isn't used in a game).
MAXIMAL_STEP i the maximal time in ms for which particles will be processed in one frame (when zero it is unlimited)
PARTICLE_GROUP start of definition of one particle in particle group
  NAME "path" string is the name of particle effect (extension .pcfg) which will be in a group
  START_TIME i this particle effect will start to be played after i ms
  TRANSF_MATRIX f1 f2 f3 f4 f5
                f6 f7 f8 f9 f10
                f11 f12 f13 f14
                f15 f16
transformation matrix which is applied to particle effect (it's optional). The matrix looks like this
| f1  f2  f3  f4  |
| f5  f6  f7  f8  |
| f9  f10 f11 f12 |
| f13 f14 f15 f16 |

(so (f13, f14, f15) is usually a translation)
  END_OF_PARTICLE_GROUP end of definition of one particle in particle group
... there can be any number of particle effects in particle group
END_OF_PARTICLEGR this is at the end of file and means end of definition of particle group

Prev: Specification of Animation Next: none Up: Home