|! IMPORTANT ! This is a PopcornFX v1 page. PopcornFX v2 documentation can be found here|
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.
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
|Right click on the event for|
- 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:
TriggerAlways: There can be an unlimited number of trigger-always events
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
This feature is not in the current version, but will be released soon:
Scripts can manipulate events through the 'Trigger' member functions:
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);
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|
||each time a particle is spawned.||Popcorn runtime||To chain effects, or play a sound when a particle spawns.|
||when the particle dies.||Popcorn runtime||To chain effects (ex: fireworks)|
||when a collision occurs||Physics or collision evolvers
|To play a "hit" effect when a particle collides, play a sound, spawn a decal, etc...|