Triggers
The Triggers Page is a tool page in the World Editor. It can be found under the Object tab.
A trigger node is used to detect when some object has entered or exited a specific volume of space. The engine defines three different shapes for a trigger volume: a box, a cylinder, and a sphere. The trigger nodes in a world are activated and deactivated by calling the World::ActivateTriggers() function. The old and new positions of an object are typically passed to this function to determine whether the line segment connecting them has intersected any trigger volumes.
When a trigger is activated, the engine takes the following steps.
- If the trigger node itself has a controller, then that controller is activated.
- If the trigger object specifies an activation connector key and there is a node connected to the trigger through a connector having that key, then:
- If that node has a controller, then that controller is activated.
- Otherwise, the immediate subnodes of that node are examined, and every controller belonging to that set of subnodes is activated.
If the activated controller is a script controller that is configured to handle controller activation events (which is the default), then the script is executed.
On the first frame after a trigger node is activated, if it no longer intersects any line segments passed to the World::ActivateTriggers() function, then it becomes deactivated. When a trigger node is deactivated, it takes the following steps, similar to the activation process.
- If the trigger node itself has a controller, then that controller is deactivated.
- If the trigger object specifies a deactivation connector key and there is a node connected to the trigger through a connector having that key, then:
- If that node has a controller, then that controller is deactivated.
- Otherwise, the immediate subnodes of that node are examined, and every controller belonging to that set of subnodes is deactivated.
If the deactivated controller is a script controller that is configured to handle controller deactivation events, then the script is executed. A script does not handle deactivation events by default, so it has to be configured as such by double-clicking on the script name in the Script Editor and checking the Handles controller deactivate event box.
A single script can handle both activate and deactivate events if both boxes are checked in the script settings. In this case, different paths of execution can be followed by using the Controller Activate Event and Controller Deactivate Event methods to determine which type of event actually caused the script to run.
Trigger Settings
A trigger node can be configured under the Trigger tab in the Node Info window. The specific settings are described in the following table.
|
Setting |
Description |
|
Disabled after activation |
The trigger node is disabled immediately after the first time it is activated so that it is activated only once. (It's possible to explicitly re-enable the trigger later.) |
|
Continuously activated |
The trigger is activated for each frame during which an object is inside it instead of waiting for the object to leave and re-enter. |
|
Activation connector key |
An optional connector key specifying a link to the node that receives the activation event when the trigger is activated. This is used only if the trigger node itself does not have a controller. |
|
Deactivation connector key |
An optional connector key specifying a link to the node that receives the deactivation event when the trigger is deactivated. This is used only if the trigger node itself does not have a controller. |