VASSAL Reference Manual
Home > Module > Game Piece Palette > Game Piece > Trigger Action
Trigger Action Trait
Trigger Action is a multi-purpose trait which is used to activate one or more other traits of the same piece. You can use it to combine commands into one, to automatically fire commands in response to other commands (including Global Key Commands) when certain conditions apply, or to fire off multiple commands at a time.
When combining multiple Trigger Actions and key commands into sophisticated behaviors, the principles of Trait Order should be reviewed. When a Keystroke or Named Command is received by a Game Piece (whether by an actual key being pressed by the player or from a Trigger Action trait), the Traits are visited in a particular order to see if they listen for that Key Command, and if they do have an entry for that Key Command the appropriate part of the Trait activates.
The order Traits within the piece are visited is as follows:
First any traits except for Trigger Action and Report Action traits are visited. This happens starting at the bottom of the list and proceeding up toward the Basic Piece trait.
Then, once every trait that isn’t a Trigger Action or Report Action trait has been visited, we then visit those traits, this time starting at the top of the list just beneath the Basic Piece trait and proceeding towards the bottom.
- Description:
-
A brief description of the trait which will appear in the Piece Definer window for the piece or prototype. Particularly useful in distinguishing multiple Trigger Action traits from one another.
- Trigger when properties match:
-
If not left blank, the trait will only generate new key commands if the piece matches this Property Expression.
- Menu Command:
-
Adds an item to the piece’s right-click context menu that will fire the triggered commands (provided the property expression is matched).
- Key command:
-
A Keystroke or Named Command corresponding to the menu item. The only functional difference between entering a command here and entering it in the Watch for these Keystrokes field below is that if a regular keyboard shortcut is entered here it will appear alongside the Menu Command text above in the right-click context menu item for this trait as the shortcut for that item. Apart from that, use of this field is interchangeable with the Watch for these Keystrokes field.
- Watch for these Key Commands:
-
When any of these Keystrokes and/or Named Commands is detected, fires the keystrokes listed below (in Perform these Keystrokes), provided the property expression (if any) is matched.
Key commands can be detected, for example, when one of the other traits on the piece is activated by the player pressing that trait’s keyboard shortcut or selecting the corresponding item from the right-click context menu. Key commands can also be detected when sent from elsewhere via a Global Key Command or when chained from another Trigger Action trait on this piece, allowing you to set up complex chaining and forking behaviors. Click the Add button to add additional fields to accomodate more keystrokes. To remove unwanted keystrokes, simply blank the lines — extra lines will be removed next time you open the trait’s properties.
- Perform these Key Commands:
-
The Keystrokes and/or Named Commands to invoke for this piece whenever one of the above key commands (in the Perform these Keystrokes and/or Keyboard Command fields) is observed, provided that the property expression (if any) is matched. Click the Add button to add additional fields to accomodate more keystrokes. To remove unwanted keystrokes, simply blank the lines — extra lines will be removed next time you open the trait’s properties.
- Repeat this set of Key Commands (Loop):
-
If checked, allows you to define logic for a "loop" to generate the specified key commands multiple times. Otherwise, the listed key commands are triggered once each.
- Type of loop:
-
lets you configure your loop.
Repeat fixed number of times This loop option allows you to repeat the set of key strokes a specified number times.
Repeat while condition is true This loop option allows you to repeat the set of key strokes while a Property Expression remains true. If the expression initially evaluates as false, the key strokes will not be issued at all (compare with the until condition below).
Repeat until condition is true This loop option allows you to repeat the set of key strokes until a Property Expression becomes true. The key commands will be issued at least once before the expression is checked for the first time.
- Loop how many times:
-
An Expression that defines how many times to generate the set of key commands (for a fixed loop).
- Loop while/until condition is true:
-
Enter the Property Expression that controls how long to keep looping (for a while or until loop).
- Perform this Key Command once before looping starts:
-
For all loop types, enter an optional Keystroke or Named Command that will be performed once before the looping process commences.
- Perform this Key Command once after looping complete:
-
For all loop types, enter an optional Keystroke or Named Command that will be performed once after the looping process finishes.
- Create a loop index property:
-
For all loop types, allows you to create a Property whose value will change as the looping process proceeds.
- Index property name:
-
The name of the property that will be created.
- Index property start value:
-
An Expression that sets the value of the index property prior to looping commencing. The expression must evaluate to a whole number.
- Index property increment value:
-
An Expression that defines how much will be added to the Index Property at the start of each loop. The expression must evaluate to a whole number.
Example #1: Your module’s main Map has an entry in its field for Key Command to apply to all units ending movement on this map (the last field on the Map’s properties configuration dialog) which is configured to send the Named Command "MovedOnMap" to every piece that moves. Your piece then uses a Trigger Action trait that watches for the MovedOnMap Named Command. It checks to make sure the piece has actually changed locations (as opposed to simply being adjusted in its space), and if the piece has truly changed locations then it fires two additional key commands: one will lower a count of its piece type for the region it has just left, and the second will increase the count of its piece type in the region in which it has just arrived.
Example #2: A piece has a Layer to track action points and a Move Fixed Distance trait to move it forward. The Move Fixed Distance trait can be assigned a Named Command such as MoveForward) with no command name (so that it does not appear in the right-click context menu). Then a Trigger Action trait with the command Move and the keystroke Ctrl+M can trigger both the Move command and decrease the action points layer by one.
Example #3: A piece has separate Layer traits for hit points and for a "critically wounded" status for when the hit points are less than 2. A Trigger Action trait can watch for the keystrokes that affect the hit-point layer and respond by activating the wounded layer by matching the property expression for when the hit points are < 2 and the wound level is not active.
Example #4: A trait that is activated whenever any of a whole list of types of piece are due to be placed on the map. It performs a looping function to look for a piece of the appropriate type in a prioritized list of places to find them (e.g. "in the force pool", "in the reserve", "in the dead pool", etc.), and stops when it either places a piece successfully or when it runs out of places to look.
