<< Click to Display Table of Contents >> Command Action |
![]() ![]() ![]() |
Show/Hide Hidden Text |
There are three things you can do in a command action:
To do any of the above, we must identify the target attribute or stock to be changed, or the target action to be triggered. Every action must have a reference to the entity it will affect. Every action is automatically created with two pre-existing references: parent, a reference to the entity that owns the action, and invoker, a reference to the entity that owns the trigger that fires the action. These references are used to access the target attribute or stock to be changed. Some actions involve other references as well, discussed below. For now, we'll use the parent reference in examples of things one can do with command actions.
1. Change the Value of an Attribute:
Continuing with our chameleon example, we will first create an action that changes the chameleon's color to red.
We start with a chameleon entity type, having an attribute color with default initial value "green".
Add an action either by right-clicking on the chameleon entity type in the model overview, or by clicking the "New Action" button on the actions tab of the chameleon inspector:
When the editor for the new action appears, set the name to "turn red", the action type to "command", and add a description.
The action now exists, and even has its own inspector and (empty) diagram, but doesn't actually do anything yet. To complete the action definition, go to the references tab of the action, and drag "color" from under the parent reference to the "turn red" diagram:
The resulting "Parent•color" node is a surrogate for the color attribute of each chameleon entity. You use a surrogate of a stock or an attribute to specify the change to that stock or attribute that you want the action to effect. The surrogate is not a reference to any chameleon or its color; instead, it is a construct that lives entirely within the action. You can see it listed on the attributes tab of the action inspector:
Right-click and choose "Edit attribute", and set the "new value" field to "red":
The action is now completely defined. When triggered (see below), this action will change its parent entity's "color" value to "red".
2. Move a value into, out of, or between stocks:
You can use flows in your action diagram to cause a transfer into our out of a stock. On the action diagram, the stock is represented by its reference. So in an action that removes mass from the chameleon (say, when it loses its tail), you first drag a reference to the chamelon's mass from the reference tab, then add an outflow to represent the loss:
There is an important difference between regular flows, and flows in actions: Regular flows represent a rate of change over time, e.g. chameleon mass is growing at 0.5 grams per day. A flow in an action is a single, instantaneous transfer: when the "lose tail" action is triggered, the chameleon suffers an immediate, one-time loss of 3 grams of mass. Thus, while units for a regular flow are generally time dependent (for example, with units of gram/day), action flows not time-dependent (with units of gram).
The same applies to transfers between stocks. You can even make transfers between stocks of different entities. For example, the action pictured below executes a transfer of money from invoking entity (the entity where the trigger is defined--see below) to the parent entity (the entity where the action is defined):
3. Trigger other actions:
A command action can trigger a second action. Triggers are discussed below, but the basic idea is that a trigger checks to see if the criteria for performing an action are met, and if they are, the action occurs. To cause a command action to trigger a second action, add a trigger to the first action's diagram (see below for how to add a trigger). Each time the first action occurs, the trigger will be evaluated and if conditions warrant, the second action will also occur.
Command actions can act on any attribute or stock of either the parent entity or the invoking entity. They can also act on any entity to which those entities have a reference. If the parent entity of an action has a reference called "employer" that points to another entity, then the action can affect not only parent.bank_balance, but also parent.employer.bank_balance. (References can be chained, so it is possible for an action to affect the subsidiary of the competitor of the holding company of the parent, so long as all the references in parent.holding company.competitor.subsidiary exist.) When one action triggers a second action, the parent of the first action is the invoker of the second.
|