Particle Engine
Introduction
The particle engine in Graal v4 is an extension of the SHOWIMG feature. With the command "showimg" scripts can display graphics, text, polygons and even animations on the screen. That command is mainly meant for client-side effects, but can also partially used on the serverside, and they can also be made visible on other player's screens. Graphics or texts displayed using this command will be called SHOWIMGs in this paper.
Each SHOWIMG can be used as emitter for particles. That way all kind of scripts can use the new particle engine - just display a SHOWIMG and set the attributes of the SHOWIMG so that the particle emitter is activated and is emitting particles. A particle can be seen as an independent graphic object that is put at the position of the emitter once it is emitted, then travelling over the screen, and disappearing once its lifetime is over or it is outside the allowed screen bounds. Actually a particle is itself a SHOWIMG and can so be used for any kind of graphical effect, and can theoretically even be used as emitter for other particles.
The reason for using a particle engine is speed: theoretically all graphical effects could be done by using scripts which call commands to display graphics or text. But often such effects contain several hundreds or even thousands of graphics, which must be moved and animated several times each second. If there are many objects using scripted particle effects that can slow down the game quite a lot. That's why it is possible in Graal v4 to use a built-in particle engine with many possible options to influence the look and behaviour of the particles so that most graphics effects can be displayed using that engine.
Create a SHOWIMG
To use the particle engine, you first need a SHOWIMG as emitter:
with (findimg(200)) {
x = player.x;
y = player.y;
}
The function findimg(index) is searching for an existing SHOWIMG with the index of 200 and then using that for setting the other attributes, otherwise it is automatically creating a new SHOWIMG with index 200 for the current object (npc, or player if its a weapon/gui-script). Afterwards it is setting the position of the SHOWIMG to position of the player.
Configure emitter and particle
Once the SHOWIMG is setup, you need to configure the emitter and the default attributes of the particle that should be emitted:
with (findimg(200)) {
x = player.x;
y = player.y;
emitter.attribute = value;
emitter.particle.attribute = value;
}
Possible attribute names are (you can run "Graal4.exe -listscriptfunctions" to get the latest list of script functions):
TParticleEmitter (TGraalVar):
attachposition - boolean - says if the particle is moved with the emitter (true), or can fly freely (false)
autorotation - boolean - for making the particle heading into the direction it flies (rotation=angle)
checkbelowterrain - boolean - destroys the particles if they are below the terrain height (or zero on flat maps)
clippingbox - {xd1,yd1,zd1, xd2,yd2,zd2} - defines a box, if particles leave this box then they are destroyed
cliptoscreen - boolean - automatically resizes the clipping box to the visible area
continueafterdestroy - boolean
delaymin - float - minimum delay till the next automatic emission (>= 0.05 seconds)
delaymax - float - maximum delay till the next automatic emission
emissionoffset - {xd,yd,zd} - by default {0,0,0}, says at which position the particles should be emitted, relative to the current emitter position
emitautomatically - boolean - enables or disabled the automatic emission of particles after delaymin/delaymax time
firstinfront - boolean - says if the first emitted particle should be displayed in front (true by default)
maxparticles - integer - can be used to limit the total particle count
nrofparticles - integer - specifies how many particles are emitted at once
particle - object (read only) - defines the default attributes of the next emitted particle
wraptoclippingbox - boolean - if a particle leaves on one side, it appears on the other side (use with "cliptoscreen" option)
dropemitter - TParticleEmitter - works exactly like the emitter itself and are used for emitting particles once a particle drops on the ground (rain drops) or the lifetime is over (for fireworks)
dropwateremitter - TParticleEmitter - see dropemitter
TParticle (TGraalVar):
angle - float - the movement angle of the particle (horizontally on the (x,y) plane)
lifetime - float - in seconds, the particle will be destroyed when the lifetime is over
movementvector - string - says in which direction the particles moves, this is a combination of angle and zangle
speed - float - tiles per second
spin - float - automatic rotation of the particle (radiants each second)
zangle - float - the vertical movement angle - says if the particles goes up or down
Particle attributes that are the same like for a SHOWIMG:
alpha - float - transparency
ani - string - a gani file (use "projectile.actor" for changing the attributes)
blue - float - blue color value (0-1)
code - string - the old representation as 'font@style@text'
dimension - integer - polygon dimension (2 or 3)
dir - integer - animation direction
emitter - object (read only) - for specifying the attributes of a sub-emitter
font - string - text font name
green - float - green color value (0-1)
image - string - image filename
layer - integer - 4 or higher for particle which move in screen coordinates, below 4 for level coordinates
mode - integer - the image drawing mode (0 - add, 1 - transparent, 2 - subtract, 3 - daynight)
playerlook - boolean - if the animation should take it's head, body, sword, shield and attr[] from the owner (playerlook), set this to false if you want to set the images yourself by changing showimg.actor.head etc.
polygon - object - array of coordinates for displaying a 2 or 3 dimensional polygon
red - float - red color value (0-1)
rotation - float - defines in which direction the particle graphics is facing
stretchx - float - horizontal particle graphics stretch factor (default 1)
stretchy - float - vertical particle graphics stretch factor (default 1)
style - string - text style (e.g. "b" for bold text)
text - string - a text that should be displayed on the SHOWIMG position
zoom - float - zoom factor of the particle graphics or text
Add particle modifiers
Once you have setup the SHOWIMG and specified the attributes of the emitter and default particle, you can also specify particle modifiers so that the particles are not always flying into the same direction and look the same. There are 3 different functions, for modifying the default particle addemitmodifier(), for modifying all existing particles addglobalmodifier(), and for modifying the attributes for each particle individually addlocalmodifier(). The local modifiers are the most often used modifier. Parameters are:
modifier type - once,impulse or range - modifies the particle one time, periodically or only in the given time range rangemin - seconds, minimum delay until first modification or start of modification range (if modifier is "range") rangemax - seconds, maximum delay until first modification or end of modification range (if modifier is "range") variable - x,y,z,movex,movey,movez,angle,zangle,speed,rotation,spin,stretchx,stretchy,red,green,blue,alpha or zoom variable modification type - replace,add or multiply (if modifier type is "range" then only "replace" and "add" are valid) valuemin - range start of the random value or first value to set/add (if modifier is "range") valuemax - range end of the random value or last value to set/add (if modifier is "range")
Those 3 functions addemitmodifier(), addglobalmodifier() and addlocalmodifier() are returning a modifier object which can be used to attach more variable modifications to the same impulse:
with (addlocalmodifier("impulse",1,2,"angle","replace",0,pi)) {
addmod("zoom","add",0.1,0.2);
}
This example is modifying the angle each 1-2 seconds, and at the same time it is zooming the particle so that it grows bigger. If you don't need to have the two modifiers act at the same moment, then you could have called addlocalmodifier("impulse",1,2,"zoom","add",0.1,0.2) which looks quite the same, but is not guaranteed to happen at the same moment like the first modifier. Most of the time you don't need the addmod-function though.
Manually emitting particles
If you have done the things mentioned in the previous steps, then the particle emitter is automatically emitting particles after the time specified with delaymin and delaymax. If you don't want that particles are automatically emitted, then set emitautomatically to false and call emitter.emit() directly.
Controlling the particle emitter
You can modify the particle emitter at any time by using the "with (findimg(index))" construct again as mentioned in "Create a SHOWIMG" chapter. To change the position where the particles are emitted you can just change the position of the SHOWIMG, e.g. moving it to the player position so that the particles are always emitted where the player stands.
It can also be interesting to watch the number of particles that the emitter has emitted, you can read the variables "currentparticlecount" and "emittedparticles" for that:
TParticleEmitter (TGraalVar): currentparticlecount - integer (read only) - for watching how many particles exist emittedparticles - integer (read only) - for seeing how many particles have been emitted in total
Reference
emitter
attachposition - Tells whether or not x/y position of particles is relative to the position of the emitter. Also tells if particles should move when the emitter is moved.
autorotation - Must be ture for making the particle heading into the direction it flies (rotation=angle)
checkbelowterrain - If true, the particle will be destroyed if it falls below the terrain height (0 for flat GMaps)
clippingbox - Format of {x1,y1,z1,x2,y2,z2}, particles that leave this box will be destroyed
cliptoscreen - boolean - automatically resizes the clipping box to the visible area
continueafterdestroy - boolean
currentparticlecount - Current number of particles that exist
delaymin - Minimum time before another particle is emitted
delaymax - Maximum time before another particle is emitted
emissionoffset - How far away from the emitter (or the level if attachposition=false) to emit particles. Format: {x,y,z}
emittedparticles - Total number of particles that have been emitted
firstinfront - Tells whether particles drawn after the first particle should draw on top or below the first
maxparticles - Maximum number of particles that can exist at once
nrofparticles - Number of particles to release at once
isfrozen - Boolean, stops all particles if true
wraptoclippingbox - boolean - if a particle leaves on one side, it appears on the other side (use with "cliptoscreen" option)
dropemitter - TParticleEmitter - works exactly like the emitter itself and are used for emitting particles once a particle drops on the ground (rain drops) or the lifetime is over (for fireworks)
dropwateremitter - TParticleEmitter - see dropemitter
particle
lifetime - Time (in seconds) before a particle is destroyed
image - Image to use for the particle
mode - Drawing mode of the image. (0 = add, 1 = replace, 2 = subtract, 3 = daynight) See changeimgmode
alpha - Alpha transparency of a particle (0 = invisible, 1 = opaque)
zoom - Zoomfactor of a particle
angle - Movement angle for the particle (for x/y)
zangle - Up/down movement angle for the particle
speed - How many tiles or pixels the particle should move (depends on if its in a level or on the GUI)
rotation - Angle for rotating the image (set autorotation=true to automatically set rotation=angle)
spin - How much the image should be rotated each second, can be postive and negative
stretchx - How much to stretch the particle image horizontally
stretchy - How much to stretch the particle image vertically
red, green, blue - Used to change color of particle
dimension - Polygon dimension (2 or 3)
movementvector - Format is {float,float,float}, a combination of x, y and z
Emitter functions:
addlocalmodifier("string",float,float,"string","string",float,float)
Parameters:
First - Tells when to do an action
once - Do it once
range - Do the action during the range of time param2-param3
impulse - Do it randomly
Second - Tells the minimum time to wait before doing an action (except for 'range')
Third - Tells the maximum time to wait before doing an action (except for 'range')
Fourth - Tells what action to perform
Everything under "particle" except for the following can be changed: image , text, ani, font, movementvector, style
x - x position of the particle
y - y position of the particle
z - z position of the particle
movex - How far the particle should move horizontally in its lifetime
movey - How far the particle should move vertically in its lifetime
movez - How far the particle should move above the ground in its lifetime
Fifth - Tells what to do with parameters 6 and 7
add - Add the amount (use negatives to subtract)
replace - Set a new amount
multiply - Multiply the amount (use negatives to divide)
Sixth - Minimum amount
Seventh - Maximum amount
addglobalmodifier() - Same as addlocalmodifier, except it affects all particles at once
addemitmodifier() - Same as addlocalmodifier, except it only affects emitter.particle
addmod() - Used in conjunction with addlocalmodifier, same parameters except no parameters 1-3
emit() - Do one emission
removemodifiers() - Remove modifiers set
removeparticles() - Remove particles
Examples
with (findimg(200)) {
emitter.nrofparticles = 1;
emitter.particle.image = "block.png";
}
with (findimg(200)) {
// Chimney
// Emitter attributes
layer = 2;
emitter.delaymin = 0.1;
emitter.delaymax = 0.2;
emitter.nrofparticles = 1;
// Basic particle attributes
emitter.particle.lifetime = 3;
emitter.particle.image = "g4_particle_smoke.png";
emitter.particle.mode = 1; // alpha transparent
emitter.particle.alpha = 0.8;
emitter.particle.zoom = 1;
// Movement
emitter.particle.angle = pi / 2;
emitter.particle.speed = 8;
emitter.addglobalmodifier("impulse", 0.2, 0.2, "spin", "multiply", 0.9, 0.9);
emitter.addlocalmodifier("once", 0, 0, "angle", "add", -0.2, 0.2);
emitter.addlocalmodifier("once", 0, 0, "rotation", "replace", 0, 2*pi);
emitter.addlocalmodifier("range", 1, 3, "alpha", "replace", 0.8, 0);
emitter.addlocalmodifier("range", 0, 3, "zoom", "add", 0.25, 0.25);
emitter.addlocalmodifier("range", 0, 0.5, "speed", "replace", 12, 4);
emitter.addlocalmodifier("range", 0.5, 3, "speed", "replace", 4, 1.5);
emitter.addlocalmodifier("once", 0, 0, "spin", "replace", 2, 4);
}
Useful articles
Creation/Dev/Script/Client/TParticleEmitter