Particle emitter instruction reference


The return value of ig3d_GetParticle_emitterInfo_s_s and the second string parameter of ig3d_SetParticle_emitterInfo_2s
are a bit complicated, this section covers this.
The string has multiple lines, the first line is the name of the particle emitter and the second line is the name of the .emt emitter settings file
used by the emitter. It may seem stupid to provide a settings file when all settings can be directly made, but it is very useful for game scripting,
where you just pick predefined emitter settings for things you reuse, like fire, snow etc.
The third line contains the position of the emitter in [x, y, z] coords.
The fourth line contains the orientation of the emitter in euler angles [xa, ya, za].
The other lines make up the actual behaviour of the emitter.
The behaviour of an emitter's particles is controlled by instructions.
The instructions are organized in a line-delimited list with one line for each instruction.
An instruction has the following syntax: [setting]=[value_1, ..., value_n]
The types and amounts of values for a setting vary from setting to setting.
Here is a sample instruction:
life=2.3
This sets the life time of each particle emitted by the emitter to 2.3 seconds. (It has only one value).

Here is a list of all supported settings and their associated value types :
model=local file string
amount=Integer
emission rate=Real
life=Real
area=Real
velocity=Real, Real, Real
speed=Real
weight=Real
move=Boolean, Real
explode=Boolean, Real
fade=Real
lux=Boolean
texture=local file string
num_textures=Integer
anim=Boolean, Real
size=Real
size variance=Real
size max=Real
rotate=Boolean, Real
scale=Boolean, Real
plane=Boolean, Real, Real, Real
destroy=Boolean

First of all, particle emitters can either emit 3-dimensional models or 2D-billboards.
Nearly all settings apply to billboarded particles.
Only a few of the settings apply to 3D particles.
By default a particle emitter is a billboarded particle emitter. By assigning it a valid .wtf model (using "model" setting), you turn it into a 3D model emitter.
We start covering the settings that both types have in common:
"model":
If the value is a valid relative path to a WTF model inside the iGame3D directory, this will be used as the model for particles of this emitter. That turns the emitter into a 3D model emitter. If the model does not exist or the value is empty, this will turn the emitter into a billboard particle emitter.
"amount" and "emission rate":
When an emitter is started, it will emit particles at a specified rate and stop after a specified amount of particles have been emitted.
This amount is simply set using the "amount" setting and naturally takes one integer.
The value used by the "emission rate" setting is not really a rate, it is the time interval in seconds between emission of consecutive particles. For example 0.1 to emit a particle every tenth of a second.
If this interval is set to 0, the full amount of particles will be emitted at once when the emitter starts.
An amount of -1 means that the emitter will not stop emitting particles after a fixed amount of emitted particles. It will keep emitting at the specified rate until the emitter is told to stop.
Setting amount to -1 and emission rate to 0 is illegal. It would mean "Emit an infinite amount of particles at once". No particles will be emitted if you try that combination.
"life":
This is the time to live of each particle. (in seconds).

"area":
Particles will be randomly placed within the given distance around the emitter. area=0 means that all particles will spawn exactly at the position of the emitter.
"velocity":
The emitter might be part of a moving object. To represent that you can apply a default velocity to each particle that gets emitted as well. This is a vector. Since the velocity is likely to change in-game, you will probably control the emitter velocity from a script rather than with this setting.
"speed":
The value of "speed" controls how fast particles move (in case "move" is activated).

"weight":
This has different meanings for 2D and 3D particles.
2D: To apply a downwards motion to particles (to simulate gravity), you can enter a typically small value for "weight". Something like 0.01 or even smaller should do. Works well for snow etc.
3D: The value sets the mass of the 3D particle. The lower the mass, the more it will be effected by movements. 1.0 is default.
"move":
If the first value of "move" is set to true, then the emitted particles will move into the direction the emitter is pointing at the speed specified using "speed" setting. The second parameter adds some randomness to this direction. It is the maximal angle (in degrees) that the actual direction is allowed to vary from the desired direction. A value of 0 means no variation and a value of 180 means totally random direction.

"explode":
If the first value of "explode" is true then this will emit particles in a random direction at a speed specified by the second value. (Unlike "move" it does not use the "speed" setting). NOTE: You can achieve the same effect "explode" offers by using "move" with variance angle 180 and setting the "speed".

Settings for 2D billboarded particles only


"fade":
Nearing the end of its lifetime a particle can be be faded out by reducing its alpha value with time until it is completely invisible. For example if you set "life" to 3.0 and "fade" to 0.5, then a particle will start fading out 2.5 seconds after it was created and is completely invisible at its time of death (3.0). The value of "fade" is the duration of this fading.

"lux":
If the value of "lux" is true, then the particles will ignore lighting. This is useful for particles that emit light themselves, for example fire.
"texture":
This sets the texture image used by the particles. The value should be the file name of a PNG image local to the iGame3D directory.
"num_textures":
You might have multiple textures inside one image (WAD image) where certain parts of the image make up each texture. For example four 128x128 textures can be inside a 256x256 image. The values for num_textures tell how many textures are in the horizontal and how many textures are in the vertical. Default values are 1,1. In our example it would be 2,2. For each particle a random texture of these will be picked.

"anim":
If the first value of "anim" is true, then the texture of the particles will be animated. That means if you use a WAD image as discribed in "num_textures", the texture will alternate through all textures in the image at a certain speed. The time between the change of textures is specified in the second value here. It will start with the top-left image and go line-wise to the bottom-right image.
"size":
This sets the size of the particle squares.
"size variance":
A random number within the range of 0 and the value of "size variance" will be added or subtracted from the size of each emitted particle. For example if "size" is set to 1.0 and "size variance" is 0.25, then the emitted particles' sizes will range from 0.75 to 1.25.
"size max":
This can be used to specify a maximum size for particles that scale up using the "scale" setting set to true. They simply won't grow beyond the size you provide here.
"rotate":
If the first value of "rotate" is true, the particles will rotate around the axis from the emitter to where the emitter points. The second value is the speed of this rotation. It will be this value multiplied by 90 degrees per second. Use a non-zero value in the "area" setting to actually see some rotation happening, because particles that spawn at the center of rotation make no sense.
"scale":
If the first value of "scale" is true, the particles will be scaled with time. This can be used for many things including smoke and fire. The second value sets what factor of the original size will be reached after one second. A value of 2 for example means that the particle will double its size in one second.
"plane":
If the first value of "plane" is true then the particles will no longer be billboarded. Instead they will get the orientation specified by the values 2 to 4. (three floats that make up the xa, ya, za angles). You could create flat water surface particles with "plane=true,90,0,0" for example.

Settings for 3D model particles only

NOTE: You can preview the motion of the 3D particles in game-mode only since they use physics and interact with the scene and that is only available in game-mode.
"destroy":
If the value of "destroy" is true, particles will be cleared once they collide with something.

Some additional hints:
You can combine those "move", "scale", "rotate" and "explode" effects, but not all combinations make sense, see yourself. A lot can be done with these emitters. If one emitter cannot achieve the desired effect you might want to use multiple emitters that are able to create the effect you have in mind.
Particle settings are saved to .emt files. When you create a particle emitter entity, you assign it an .emt file to take the data from.
You are encouraged to check out some .emt files to get some idea of particle settings and also see the what ig3d_GetParticle_emitterInfo_s_s returns.