<< Click to Display Table of Contents >> Navigation:  Defining a Model > Triggers

Triggers

 

Every action must have a trigger that specifies whether and when the action occurs. A trigger may be created in the same entity where the action is defined, or in a different entity. The entity where the action is defined is called the parent of the action, the entity where the trigger is defined is called the invoker of the action. Thus it is possible and even common for a single entity to be both the invoker and the parent of an action.

 

To create a trigger, either drag a trigger node onto the diagram of the invoking entity and then right click to edit,

 

 

or use the New Trigger button on the actions tab of the inspector for the invoking entity,

 

 

or drag an action onto a diagram, which will automatically create a new trigger for that action.

 

 

Right-click the new trigger to edit. You will be asked to provide the following:

 

 

A name for the trigger. You can name the trigger after the action, as shown here, or give it any other descriptive name.

 

 

 

The sequence number sets the order of priority in case more than one trigger is set to occur at the same time.

 

Period Start triggers occur at the beginning of the time slice; Period End triggers occur at the end of the time slice after other calculations have been done. Set this to "Never" to disable a trigger. Note: Triggers for Allocate and Market actions must be set to "Period Start".

 

In the "Trigger If:" field, set the conditions that must be met for the triggered action to occur.

 

 

 

Specify the action that will be performed. When the action and trigger are not defined in the same entity, you will need to use a reference to identify the action. See "Who triggers whom?" below.

 

 

The description field is a place for any notes or related information.

 

 

 

 

As shown in the description field in the image above, this trigger is checked every time slice, at the start of the period. If the chameleon's temperature is over 100 and the color is anything other than red, the "Turn Red" action will be invoked, which will set the chameleon's "color" attribute to "red".

 

Who triggers whom? What to write in "Action to Invoke"

 

The most crucial aspect of defining a trigger is making sure the correct entity's action is being invoked. The invoker entity (the entity that owns the trigger) must have a defined relationship to the entity that owns the triggered action.

 

There are three situations to consider:

 

1.The parent and invoker are the same entity. In other words, the action is defined in the same entity as the trigger, and both show up on the actions tab of the same inspector. In this simplest case, you can specify the Action to Invoke simply by writing the name of the action, as with the "turn red" example above where the trigger and action are owned by the same chameleon entity.

 

2.The parent and invoker are different entities. In this case, the Action to Invoke field must include a reference to the owner of the action. If your "boy" entity is going to make his girlfriend blush, then the boy entity must have a reference called "girlfriend" to a specific girl. Girl entities must have a "turn red" action defined. The trigger defined in the boy entity will then list "girlfriend.turn red" in the Action to Invoke field.
 
Note that this applies even if both entities are of the same type. If each platypus entity has a reference to a second platypus called "mate", then a platypus that wants to make its mate blush must list "mate.turn red" in the Action to Invoke field of the trigger. If it just says, "turn red", then each platypus will be making itself blush.

 

3.The invoker is an action. In other words, you are chaining actions so one trigger invokes an action, which includes a trigger that invokes a second action. For example, if each phoenix entity has both a self-delete action called "death" and a create action called "rebirth", the trigger for "rebirth" should be defined inside the "death" action so a new phoenix can be created just as the old one dies. In this case, the owner of the trigger is the action called "death". The owner of the action to be invoked is the phoenix--that is, the parent of the death action. So, the trigger for rebirth should list "parent.rebirth" as the Action to Invoke.

 

Fine print: If you are using chains of references to trigger an action, such as writing mother.brother.son.BakeCookies for an entity to invoke its cousin's tendency to produce cookies, you may not send that chain through an action other than the one you mean to invoke. The first action that is encountered in the sequence of references will be invoked. If your trigger is owned by an action, the first action found outside of that invoking action will be the one that is triggered.

 

Multiple Triggers for the Same Action

 

You may create more than one trigger for a single action. The triggers can even be defined in entities of different types -- for example, lions, cheetahs and wild dogs all might have triggers for the action that results in a particular gazelle being eaten. However, any variables that are used in the trigger must be defined in all the different invoking types. If this is not so, an error will result and the model will not run.