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
   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
   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

 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)
   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, yo u can also specify particle modifiers so that the particles are not always flying into the same dire ction and look the same. There are 3 different functions, for modifying the default particle addemit modifier(), for modifying all existing particles addglobalmodifier(), and for modifying the attribut es for each particle individually addlocalmodifier(). The local modifiers are the most often used mo difier. Parameters are:

 modifier type - once,impulse or range - modifies the particle one time, periodeically 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 delaymin to a high value 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
   delaymin - Minimum time before another particle is emitted
   delaymax - Maximum time before another particle is emitted
   nrofparticles - Number of particles to release at once
   firstinfront - Tells whether particles drawn after the first particle should draw on top or below the first
   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.
   emissionoffset - How far away from the emitter (or the level if attachposition=false) to emit particles. Format: {x,y,z}
 particle
   lifetime - Time (in seconds) before a particle is hidden
   image - Image to use for the particle
   mode - Drawing mode of the image. (0 = add, 1 = replace, 2 = subtract) See changeimgmode
   alpha - Alpha transparency of a particle (0 = invisible, 1 = opaque)
   zoom - Zoomfactor of a particle
   angle - Angle the particle should move at
   zangle - Height angle of the particle
   speed - How many pixels the particle should move (every .05 seconds)
   rotation - How much to rotate the image
   spin - How many times the particle should spin before it is destroyed
   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 - Unknown (format is {float,float,float})
     Parameters:
     First - Affects distance east
     Second - Affects distance south
     Third - Affects distance north
 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 affects all particles the emitter emits
 addmod() - Used in conjunction with addlocalmodifier, same parameters except no parameters 1-3
 emit() - Begin emitting particles
 maxparticles - Maximum number of particles that can exist at once
 currentparticlecount - Current number of particles that exist
 emittedparticles - Total number of particles that have been emitted
 autorotation - Unknown (boolean)
 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