Particle events

Last update: v1.9.0 - See also: Particle system overview

Particle events allow to spawn another particle effect, a sound, a decal, whatever you like, when something special happens on a given particle, such as when it is born, dies, collides with the physical world, or when a specific condition happens inside a script.

Overview

Every layer has its own set of events.
To access the particle events panel, unroll the layer you want to see, and select its 'Events' node.

The event list will appear inside the node properties panel. By default, there are no events.

Empty event panel. By default, there are no events.	Click on the 'Create' button to create new events	Choose an action from the 'EventAction' dropdown	Right click on the event for additional options.

1- EventName

Name of the event. This is the name that will be published to scripts and to custom C++ event handlers.

2- EventMode

Determines the event trigger strategy. can be one of the following:

1- TriggerAlways : There can be an unlimited number of trigger-always events

2- TriggerOnce : There can be at most 32 trigger-once events.

NOTE: in the current editor version, this is ignored, and defaults to 'TriggerAlways'

3- EventAction

Action to be triggered by the event. The editor automatically fills the dropdown with all the actions of this type it knows about.

Users can create custom actions by inheriting from the CActionFactory / CActionInstance classes in the C++ SDK

Note that you do not have to trigger an external Fx file, you can add local layers in the 'LayerGroups' folder, and they will appear in the 'EventAction' list

Manually triggering events

This feature is not in the current version, but will be released soon:

Scripts can manipulate events through the 'Trigger' member functions:

EventName.trigger(condition);

For example, imagine we just created a custom event named 'BelowGround', that is supposed to be triggered whenever a particle goes below a horizontal plane at y = 0.

To trigger this event, we would write:

BelowGround.trigger(Position.y < 0);

This will trigger the 'BelowGround' event whenever the particle 'y' position is below 0.
This means the event will be triggered each frame as long as the particle stays below y = 0.

you can add additional computations to handle this more gracefully. For example, if you want to kill the original particle after triggering the event, you can do:

int shouldTrigger = Position.y < 0;
BelowGround.trigger(shouldTrigger); // will trigger the event if 'Position.y < 0'
kill(shouldTrigger);                // will kill the particle if 'Position.y < 0'

if you want an enter/leave behavior, you can do that using a persistent particle field that will store the enter/leave state:

• create a new particle field named, for example 'IsInsideTrigger', of type 'int'
• create a new event named, for example, 'EnterTrigger'
• create a new event named, for example, 'LeaveTrigger'
• create a new shape named, 'TriggerShape', that will be used as a trigger
• initialize to 0 in the spawn script
• in the evolve script, write:

int wasInsideTrigger = IsInsideTrigger;
IsInsideTrigger = TriggerShape.contains(Position);

EnterTrigger.trigger(IsInsideTrigger && !wasInsideTrigger);
LeaveTrigger.trigger(!IsInsideTrigger && wasInsideTrigger);

Builtin events

There are a few special events that are automatically triggered by the popcorn runtime, and some evolvers, if they are found in the event list:

Event name	When is it triggered?	Who triggers it?	Typical use
OnSpawn	each time a particle is spawned.	Popcorn runtime	To chain effects, or play a sound when a particle spawns.
OnDeath	when the particle dies.	Popcorn runtime	To chain effects (ex: fireworks)
OnCollide	when a collision occurs	Physics or collision evolvers when WorldInteractionMode != None	To play a "hit" effect when a particle collides, play a sound, spawn a decal, etc...