Particle emitter functions

Jump to: navigation, search



Particle Emitters are a powerful mechanism which HeroEngine developers can use to make swirling visual effects. Emitters generate animated particles, which follow a certain course for a set period of time, and then each individual particle expires. These effects can be used to animate such things as a fountain's spray, the flickering flame of a torch, a pulsing glow around a magical object, the leaves drifting down from a tree, and many other animations which add life to the world.

For detailed information about how to create particle effects, please see Creating particle effects.


In some ways, emitters can be thought of as a kind of NPC. Each one is its own node, with its own script. The emitter has its own properties such as an ID, a location, and various flags which control its behavior.

To turn an emitter on, it's a simple case of toggling its flag:


Within an emitter's script are various functions which are called each time the emitter takes certain behaviors. For example, each time the emitter fires a particle, a function is called which can trigger a sound or other activity. Functions are also called whenever a particle expires, or if a particle collides with something (like if a raindrop hits the ground).

Particle Emitter functions

On Particle Expire

This function is called when one of an emitter's particles expires due to reaching the end of its lifespan.

OnParticleExpire(position as vector3)

On Particle Emitter Fired

Each time a particle is generated, this function on the emitter is called. There are no arguments -- it is a simple trigger that a particle went out, in case that information is needed to trigger some other event such as a sound or other animation.


Collision Functions

Particles only collide with static objects -- not with characters, other particles (including anything generated by a plant emitter) or (at this time) speedtrees. They also don't collide with mirrors, though artists can work around this such as to place an invisible poly with an identifiable material name right under the mirror.

Ways that collisions could be used:

When a particle collides with something, one way to handle it might be to take the dot product of the normalized trajectory and the normal to find out the angle of the collision. Depending on this angle, different sounds could be chosen (a direct hit, a glance-off, etc.) It might also be useful to keep a list of material names in the room that the emitter's particle might hit, so that each could have a different sound. One for the particle hitting against stone, against metal, and so forth.

Note: Particle emitters use up resources, so developers must be cautious to not overuse the effect. For example, though it might be more realistic to code a script such that there was an appropriate splash effect for every raindrop falling during a storm, this would be an excessive use of emitters.

On Particle Collide

This function is called when one of an emitter's particles collides with something, if the COLLIDE_IGNORE flag isn't set.

OnParticleCollide(position as vector3, trajectory as vector3, normal as
vector3, material as string, room as string, time as float)
the exact place in the world where the particle died
not normalized, this is the difference between where the particle was during the last frame, and where it tried to go that caused it to collide.
the face normal of the poly that the particle collided with -- a normalized vector pointing in the direction that it faces. For instance, the ground plane in Clean Test Area always has the normal (0,1,0), which points up.
the artist-assigned name of the material that the particle collided with
the name of the room that the poly belongs to
the length of time, in seconds, that the particle was in existence

Particle Emitter Examples

function OnParticleExpire(position as vector3)
  ("A particle died of old age.")
function OnParticleCollide(position as vector3, trajectory as vector3,
normal as vector3, material as string, room as string, time as float)
  MsgArea("A particle collided with: ["+material+"] in room: ["+room+"]")
function setupCollideCallback()
  emitter as NodeRef of Class HBNODE = 266268511333  // or whatever the ID of the emitter is                                     
  emitter.lw_field_script = system.exec.thisscript   // The script that is to be added to the emitter
Personal tools