Triggers

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(What problem(s) does this not solve)
(The File Menu: updated image for Sapphire)
Line 58: Line 58:
 
==== The File Menu ====
 
==== The File Menu ====
  
[[Image:FileMenuCreateNewTrigger.jpg|200px|left|Create New Trigger]]HeroBlade's file menu has a handy ''Create'' option that provides ready access to the creation of new assets.  Simply Click on the ''Create'' option and select Trigger from the drop-down menu that appears.
+
[[Image:HeroBladeCreateMenu.png|left|Create New Trigger]]HeroBlade's file menu has a handy ''Create'' option that provides ready access to the creation of new assets.  Simply Click on the ''Create'' option and select Trigger from the drop-down menu that appears.
  
 
<br clear="all" />
 
<br clear="all" />

Revision as of 21:22, 29 October 2012

Contents

See also: Script triggers

A trigger is a predefined area in 3-dimensional space. Everything encompassed in this certain sphere of space is referred to as its "volume". This is used to trigger callbacks into script when particular events occur. A trigger keeps track of a list of targets in its volume and calls class methods and/or procedural functions when a target enters/leaves/resides/disappears within the volume.

Example:
Assume you wanted to automatically turn on a light when the character enters a room. A (client-side) trigger is ideal for this, requiring only a very simple script to toggle the light's hidden property when the trigger performs the onEnter event for character nodes. (Depending on your gameplay, you could optionally use a server-side trigger to set a state for the light to "ON" using the States System to perform the actual work.)

Rendering of a Trigger While Selected


What problem(s) does this solve

What problem(s) does this not solve

Concepts

Triggers call HSL scripts

Triggers do not have any functionality other than performing callbacks into HSL scripts when an event (see Event Types below) occurs. That means a trigger does essentially nothing without additional scripting.

Event types

Triggers perform script callbacks for the following event types:

Enter 
Enter events are triggered the first time that a node in which the trigger is interested (see Trigger Sensitivity) is first sensed inside the trigger's volume.
Reside 
Reside events are triggered for each subsequent polling in which a node, which the trigger has already registered as having entered the volume, is found still within the volume.
Leave 
Leave events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer as long as the node left the volume "normally", i.e. a character walking out of the volume. (Leave and Disappear are mutually exclusive events)
Disappear 
Disappear events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer where the node left the volume "abnormally", via TeleportPlayer or disconnect. (Disappear and Leave are mutually exclusive events)

Trigger sensitivity

Triggers are sensitive to a subset of node types as dictated by a series of flags. At least one of the sensitivity flags must be set to true for the trigger to actually do anything useful.

Usage

Triggers are conceptually simple in nature, describe a volume of space in the world and call a script when a particular event occurs. The simple concept however allows for extremely complex behaviors composed of anything a developer chooses to implement in script.

The process boils down to:

Add a Trigger to the World

The File Menu

Create New Trigger
HeroBlade's file menu has a handy Create option that provides ready access to the creation of new assets. Simply Click on the Create option and select Trigger from the drop-down menu that appears.


Asset Library

Like all assets, triggers may be added individually or as one of a group of assets.

Script

Creating a trigger dynamically from script currently requires a relatively low level understanding of how the engine handles area assets. The reference copy of Hero's Journey has a script "TriggerUtils" that implements this functionality in script, we may come up with something cleaner for clean HeroEngine.

Edit Trigger Properties

Properties Panel
Like any asset, you may select a trigger in HeroBlade and view/edit its properties in the Properties Panel.

Name

The primary use of a trigger's name (other than display in some kind of GUI) is to be used as part of a munge for the name of the function to call in the script specified for the trigger. The name need not be unique.

TriggerScript

Specifies the script to call on the Server or Client (see Execution Location below) using a munged function name based on the trigger's name plus the type of event. This is not needed if the behaviors are going to be implemented in a class methods script for a class GLOMmed onto the trigger instance.

Failure to implement the appropriate functions in the specified script for the events your trigger is configured to send will result in a script error if the function is not defined.

Events

Boolean flags dictate which events the Trigger will send.

Sensitivity

Boolean flags dictate which types of nodes are capable of triggering events.

Period

The period dictates the rate at which the trigger polls in seconds. The frequency of HeroEngine's event loop imposes an absolute limit to the period of a trigger as the trigger can not fire faster than the event pump for triggers (this is in practice 7-20ms).

For the sake of efficiency, it is best to have triggers polling no more often than is needed for them to perform properly. It should be exceedingly rare for a trigger to have a period of less than 0.25 seconds and generally 1 second is sufficient.

The volume of the trigger factors into the frequency the trigger requires to function properly, because of the way triggers track nodes in their volume and produce events based on changes to that tracking, a very narrow trigger may not produce any events for nodes passing through its volume because they are never inside the volume during the trigger's period.

Execution location

The ExistsOn enumeration dictates in which local GOM (server or client) the trigger will execute, this includes not only where the C++ code runs but also where the script callbacks are made. In other words, a server trigger calls only a server script/class method script.

As with anything on the client, client-side triggers can not be considered trustworthy for game-play applications since the client may be "hacked"


Catching Trigger Events in Script

Whenever a trigger performs a callback into script, it checks:

Method calls

See also: Class methods
CautionSign.gif These are method calls, as such you need to keep in mind that you may not GLOM multiple classes that implement them onto the same trigger.


Triggers first attempt to call the appropriate method in the class method scripts for the trigger instance. That means you may GLOM a class onto the trigger instance to receive calls for that trigger.

Enter

Enter events are triggered the first time a node, in which the trigger is interested (see Trigger Sensitivity), is first sensed inside the trigger's volume.

method TriggerEnter( triggeredBy as noderef )
 
.
Reside

Reside events are triggered for each subsequent polling in which a node, which the trigger has already registered as having entered the volume, is found still within the volume.

method TriggerReside( triggeredBy as noderef )
 
.
Leave

Leave events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer as long as the node left the volume "normally", i.e. a character walking out of the volume. (Leave and Disappear are mutually exclusive events)

method TriggerLeave( triggeredBy as noderef )
 
.
Disappear

Disappear events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer where the node left the volume "abnormally", via TeleportPlayer or disconnect. (Disappear and Leave are mutually exclusive events)

method TriggerDisappear( triggeredBy as noderef )
 
.

Function calls

Assuming none of the class method scripts for a particular trigger instance implement a method to catch a particular event, the trigger attempts to make a function call into the script specified in the trigger's script field. This call will be to function name formed by a munge of the trigger's name and the event.

In the following examples, assume the trigger is named "Foo".

Enter

Enter events are triggered the first time a node, in which the trigger is interested (see Trigger Sensitivity), is first sensed inside the trigger's volume.

function Foo_TriggerEnter( triggeredBy as noderef )
 
.
Reside

Reside events are triggered for each subsequent polling in which a node, which the trigger has already registered as having entered the volume, is found still within the volume.

function Foo_TriggerReside( triggeredBy as noderef )
 
.
Leave

Leave events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer as long as the node left the volume "normally", i.e. a character walking out of the volume. (Leave and Disappear are mutually exclusive events)

function Foo_TriggerLeave( triggeredBy as noderef )
 
.
Disappear

Disappear events are triggered during polling for any node that was present in the trigger's list of nodes that were in its volume but are no longer where the node left the volume "abnormally", via TeleportPlayer or disconnect. (Disappear and Leave are mutually exclusive events)

function Foo_TriggerDisappear( triggeredBy as noderef )
 
.

See also

Provides information on how to dissect existing triggers in an area that you may be exploring
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox