effect

effect (function, var number, VECTOR* pos, VECTOR* vel);

effect_local (function, var number, VECTOR* pos, VECTOR* vel);

This instruction can be used to create a swarm of little moving bitmap particles, to create rocket trails, explosions, laser beams, photon torpedoes, rain, snowstorms, tornadoes or the like. The pos vector gives the starting position of the swarm, number gives the number of particles, vel gives either the initial speed or the initial beam length, and the function defines the behavior of each particle The function must be defined before. It is called permanently during the lifespan of each single particle and can change the position, speed, color, size, and bitmap of the particle through the my pointer, the same way as with normal entities. It can even create new 'children' particles. Thus you have the flexibility to use particle effects of every description.


	Particle effect		Beam effect

Parameters:

function	particle function; runs every frame
number	number of particles to create
pos	position of the particle emitter
vel	initial speed vector or beam length

Remarks:

The particles are not created immediately after calling this function, but at the start of the next render cycle.
When executed by a client in a multiplayer environment, effect_local creates a local particle effect which is only visible on the client. Executed on the server, effect creates a global particle effect, which will executed on all clients separately. In a single player environment, both instructions behave identically.
You can have many thousands of particles, so the particle function should be as fast and as short as possible. wait() instructions can not be used in a particle function. Local variables can be used, but are not preserved between frames.
For speed reasons, particles are two dimensional (they have no angles) and do not perform collision detection. If you need angles or collision detection, use ent_create for creating a swarm of sprites.
If the effect_local instruction was performed by an entity, the particle functions can access this entity through the you pointer. This way, the particle effect can use the entity parameters and skills.

Speed:

Medium

Example (C-Script):

// helper function: sets the vector to random direction and length
function vec_randomize (&vec, range)
{
   vec[0] = random(1) - 0.5;
   vec[1] = random(1) - 0.5;
   vec[2] = random(1) - 0.5;
   vec_normalize(vec,random(range));
}

// helper function: fades out a particle
function part_alphafade()
{
   my.alpha -= 2*time_step;
   if (my.alpha <= 0) { my.lifespan = 0; }
}

// particle function: generates a fading explosion into vel direction
function effect_explo()
{
   vec_randomize(temp,10);
   vec_add(my.vel_x, temp);
   my.alpha = 25 + random(25);
   my.bmap = scatter_map;
   my.flare = on;
   my.bright = on;
   my.move = on;
   my.function = part_alphafade; // change to a shorter, faster function
}

...
vec_scale(normal,10); // produce an explosion into the normal direction
effect(effect_explo,1000,my.x,normal);

Example (lite-C):

// helper function: sets the vector to random direction and length
function vec_randomize (var* vec, var range)
{
   vec[0] = random(1) - 0.5;
   vec[1] = random(1) - 0.5;
   vec[2] = random(1) - 0.5;
   vec_normalize(vec,random(range));
}

// helper function: fades out a particle
function part_alphafade(PARTICLE *p)
{
   p.alpha -= 2*time_step;
   if (p.alpha <= 0) p.lifespan = 0;
}

// particle function: generates a fading explosion into vel direction
function effect_explo(PARTICLE *p)
{
   var temp[3];
   vec_randomize(temp,10);
   vec_add (p.vel_x, temp);
   p.alpha = 25 + random(25);
   p.bmap = scatter_map;
   p.flags |= (BRIGHT | MOVE);
   p.event = part_alphafade; // change to a shorter, faster function
}

...
vec_scale(normal,10); // produce an explosion into the normal direction
effect(effect_explo,1000,my.x,normal);