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

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