Particle events

From PopcornFX
Revision as of 10:45, 28 January 2021 by JBilalte (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
! IMPORTANT ! This is a PopcornFX v1 page. PopcornFX v2 documentation can be found here

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.

Particle events

Events 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.

Events node

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

empty events panel creating a new event selecting the event target additional options
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

layer groups

Events 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:


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

Events 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...