# Particle

Particle
Particles are lightweight objects which are not synchronized in a network game. This means that on the one hand you can create huge amounts of particles without slowing down the game too much but on the other hand there are only limited options for control of particle behaviour. If the particles are not sufficient for a given effect you have in mind, you can always use true objects instead.
If a particle is defined in a ocd group, any object definition located in the same group is ignored. This used to be a way to allow loading of placeholder options in the old graphics system which didn't support particles.
Particles are not stored in savegames and are designed for temporary visual effects only.
Particle Components (ocd)

Particle.txt
  Particle properties.
Graphics.png
  Particle graphics.
  The particle definition can also contain the known components of object definitions for describing the particle (e.g. Title.png, DescDE/US.txt, etc.)

Particle.txt
This component contains the properties of the particle - as DefCore.txt does for object definitions.

Section [Particle]
Value
Data type
Description
Name
String (max. 30 chars)
Name of the particle definition. This name is also used to refer to this particle type in scripts. For multi-language display in the menu system you should use the Names.txt component.
MaxCount
Integer
Maximum number of instances of this particle type. See instance control.
MinLifetime
Integer
Only for smoke particles: lower limit for the lifetime, which ranges from MinLifetime to MaxLifetime.
MaxLifetime
Integer
Only for smoke particles: upper limit for the lifetime, which ranges from MinLifetime to MaxLifetime.
InitFn
String (max. 30 chars)
Identifier for the function used to initialize the particle. For valid functions see section particle functions.
ExecFn
String (max. 30 chars)
Identifier for the function used to execute the particle each frame. For valid functions see section particle functions.
DrawFn
String (max. 30 chars)
Identifier for the function used to draw the particle. For valid functions see section drawing functions.
CollisionFn
String (max. 30 chars)
Identifier for the function called upon collision with the landscape. Also see collision checking.
Face
6 integers
Target rectangle for the graphics within Graphics.png. See particle graphics.
YOff
Integer
Upper spatial limit for the particle. At this limit the particles will be deleted as if the landscape would end here. Only StdExec.
Delay
Integer
Delay between two animation phases. If Delay = 0 one randomly chosen phase is permanently displayed.
Repeats
Integer
Number of animation runs until the particle is destroyed.
Reverse
Integer
0 or 1. If 1 every seconds animation is played backwards.
FadeOutLen
Integer
If specified, this number of animation phases is truncated from the end and reserved for a death animation which is displayed after all repetitions of the standard animation.
FadeOutDelay
Integer
Delay between two animation phases of the death animation.
RByV
Integer
0 to 3. 0 for no particle rotation. If 1 the particle will be aligned to its direction of travel; the particle's up-side will be in front. If 2 the speed parameters only determine rotation; the particle will not move. If 3 a random rotation is applied.
GravityAcc
Integer
Effects of gravity. At 0 the particle is not affected by gravity, at 100 it is fully affected. Negative values are also possible.
WindDrift
Integer
Horizontal drift by wind. Same as the material property of the same name.
VertexCount
Integer
0 or 1. If 1, collision detection is done.
VertexY
Integer
Y offset of the collision checking point in percent. Also see collision detection.
Additive
Integer
0 or 1. If 1, the particle is drawn additively.
AlphaFade
Integer
0 to 40. Rate of fade out per FadeDelay. A fully faded particle is removed.
FadeDelay
Integer
The default is 1.
Parallaxity
2 Integer
Parallaxity in x and y directions. 0 is locked with the viewport; 100 is default (locked with the landscape).
Attach
Integer
0 or 1. If 1 the particle is moving relative to its target object's position.

Properties
Each particle has a position (x, y), horizontal and vertical impulse (xdir and ydir), life time (life), and two extra parameters (a and b). These are initialized by script and then processed by the particle functions. For more information see particle functions and drawing functions.
Graphics
The coordinates for the source rectangle within Graphics.png of a particle are comparable to the Face entry in an object's ActMap. The coordinates only specify the first animation phase. All following animation phases should be located on the right (with smoke also below) of the initial phase. The animation length is then automatically determined from the image size. For the drawing offset you should usually specify half the particle size. An offset 0/0 would cause the particle graphics to be drawn below actual particle position.
If Delay = 0, a random animation phase is chosen on startup and maintained. The particle will exist until is falls out of the landscape.
Particle Amounts
For each particle type a maximum count is defined which is then also adjusted by the configuration setting for effect levels in the graphics options. As soon as half of the maximum amount of particles is created, new particles are only created based on random selected and the closer you get to the maximum value, the smaller the chance of new particle generation. This ensures a smooth approach to the actual limit.
Collision Detection
Particles can collide with the landscape. This is not very exact, however. Fast moving particles might pass through very thin layers of solid materials. If you need more precision, you should use objects instead.
Collision detection is only done in StdExec (i.e. not with smoke particles). For valid functions see particle functions. Collision detection is done at the particle center and only if VertexCount is specified. The point of detection can be shifted using VertexY. The specified values are in percent of the particle size, meaning VertexY=100 would check at the bottom of the particle. The visual size specified in Face doesn't affect this.
Particle Functions
The behaviour of particles can be controlled by predefined particle functions. These are executed for initialization, then at each fram, and in case of collision with the landscape.

StdExec
  Standard function ExecFn for almost all particle types. The particle runs through an animation defined by Face, Delay, Repeats, Reverse, FadeOutLen, and FadeOutDelay and is then destroyed. The extra parameter defines the size of the particle in 1/10 pixels. b defines color modulation; if b = 0 no modulation is applied. aa as well as b are not modified by this function and will preserve the initial values. Also, the particle moves according to xdir and ydir while ydir is affected by gravity if GravityAcc is enabled.
StdInit
  Standard function for InitFn to be used with StdExec.
Bounce
  Collision function: the particle will bounce back into the exact opposite direction.
BounceY
  Collision function: the particle will bounce back vertically.
Stop
  Collision function: the particle will stop.
Die
  Collision function: the particle will be destroyed.
SmokeExec
  Hard coded processing function for smoke particles. a is puff size; b is color modulation. Smoke graphics must be defined in 4 x 4 animation phases in Graphics.png of which the one on the lower right is used only rarely. The other animation phases are used evenly. Smoke always rises continuously until it collides with the landscape. If the life time has passed, the smoke particle fades out until it is deleted.
SmokeInit
  Hard coded initialization function for smoke to be used in conjunction with SmokeExec.

Drawing Functions
Functions that can be assigned to DrawFn.

Std
  Standard function for most particles except smoke. The particle is drawn at position x/y with size a/5 x a/5 and color modulated with b.
Smoke
  Drawing function for smoke.

Control
External control of particles is very limited and only allows creation, global offset, and global removal. This is necessary as particles are not synchronized on computers throughout a network game and any deviation in particle handling would cause sync loss. Particles are created using CreateParticle.
Sven2
2002-04