VASSAL Reference Manual
Global Key Commands
Global Key Command (or GKCs) are a fundamental aspect of VASSAL and are used in many places in a Vassal module.
GKCs select a group of pieces according to supplied criteria and then apply a Key Command to each of the selected pieces. This allows a set of actions to be performed on multiple pieces at once.
There are 5 different kinds of GKCs:
-
Module GKCs are defined in the top level Module component and are initiated by an associated Toolbar button and can affect any piece in the current game.
-
Map GKCs are defined in a Map and are initiated by an associated Toolbar button and can affect any piece on the Map they are defined on.
-
Startup GKCs are defined in the top level Module component and are initiated when a new game is started or loaded and can affect any piece in the current game.
-
Deck GKCs are defined in a Deck and are initiated by a right-click menu item on the Deck, and can affect any piece currently residing in the Deck the are defined in..
-
Counter GKCs are a piece trait that can be included in any Piece definition. They are initiated by a Menu Command or Key Command on the piece and can affect any piece in the current game.
The action of all types of GKCs follows the same pattern:
-
Replace any $$ variables in the Additional matching expression with property values from the component or trait that is running the GKC.
-
Select a group of piece (not components) based on the Fastmatch selection criteria and/or the Additional matching expression.
-
For each piece selected, in order, set any Dynamic Properties specified in the Set Dynamic Properties in target pieces field, then apply the specified Global Key Command.
-
After completion, generate a report in the Chat Window if a Report format has been specified.
|
Note
|
The order of the pieces selected by a GKC is not defined and cannot be depended upon not to change in future versions of VASSAL. The Key Command applied to each piece will completely finish executing, plus any of the further actions the piece initaites as a result of the Key Command, before the next piece is processed. |
The different types of GKCs share a lot of functionality in common. The next section describes all the attributes that are shared by more than one type of GKCs.
Common Global Key Command attributes
| Field | Used By | Description | ||
|---|---|---|---|---|
Description |
An optional description of the action (for distinguishing between multiple similar commands in the Editor window). |
|||
Button Text |
Text to appear on Toolbar Button |
|||
Tooltip text |
Mouse-over hint text for the Toolbar button. |
|||
Button icon |
Icon for the Toolbar button. |
|||
Hotkey |
Keyboard shortcut or Named Key Command for the Toolbar button. This is the key command that will initiate the Global Key Command, not the one that will be sent to the matching pieces |
|||
Toolbar button can be disabled by a property |
If this box is checked, you will be able to enable/disable the Toolbar Button by changing the value of a Global Property. See also: Toolbar Configuration |
|||
Global Property to disable this button when "true" |
The name of a Global Property that will control when this Toolbar Button is enabled or disabled. If the property contains the string true, the button will be disabled; if it contains any other value the button will be enabled. |
|||
Button Icon when disabled |
If you select an alternative icon here, then that icon will be used when the button is currently disabled. If you leave the icon empty, then the normal icon, if any, will stay in place. Any button text for the toolbar button will be greyed out when the button is disabled, regardless of your choice in this field. |
|||
Menu Command |
Name of the right-click context menu item for Deck and counter GKCs. If left blank, no context menu item will appear. |
|||
Global Key Command |
The key command or Named Key Command that will be sent and applied to the selected pieces. |
|||
Pre-select (Fast Match) |
Fast Match selections can be used to improve the performance of "slow" Global Key Commands by pre-matching the location and/or a single property value of the target piece. All Location-based Fast Match options use indexes maintained by VASSAL to provide extremely fast access to pieces. The Property-based matches are less efficient, but can help improve performance if the Additional match expression is complex. Fast Match expressions are optional in that the same comparisons can always be run in the standard "Additional matching expression" field, however, substantial performance improvements can be achieved by judicious use of Fast Match options. Wherever possible, specify a Location-based Fast Match that will minimise the number of pieces selected. Then, try and specify a Property Fast Match on the property that will eliminate as many pieces as possible from those remaining. Adding a Property-based Fast Match that matches most of the pieces will have little or no effect. See the Fast Match page for full details on Fast Matches. |
|||
Additional matching Expression |
If further refinement of which target pieces should receive the Global Key Command is needed, or if you do not wish to use Fast Match pre-selections, an Additional Matching Expression can be used. The Global Key Command will only be applied to Game Pieces which match the specified Property Match Expression. Note that the properties named in this expression are evaluated against the properties of the target pieces, not the properties of the piece issuing the Global Key Command. For example if you provided the expression { CurrentZone == "Europe" }, that would use the CurrentZone property of each potential target piece (checking if it is "Europe") to determine whether to apply the Global Key Command. If you want to compare a property in the target pieces against the value of a property in this piece, then use $property$. All $…$ property references will be evaluated against this piece before testing against other pieces. Note that this will often mean the expression needs to be put inside of quotation marks if the property in question is a string value. For example if the expression provided is { CurrentZone == "$CurrentZone$" } then the CurrentZone of each potential target piece will be checked against $CurrentZone$ which will read the CurrentZone of the issuing piece (see also example below). |
|||
Within a Deck, apply to |
Select how this command applies to pieces that are currently stacked in a Deck.
|
|||
Suppress individual reports |
If selected, then any reports (whether auto-reporting or Report Action traits) by the affected Pieces will be disabled throughout the processing of this Global Key Command. You may wish to use a Report Action trait on this piece to provide a summary message in their place. |
|||
Suppress individual sounds |
If selected, then any sounds generated by Play Sound traits on any affected pieces will be suppressed during the processing of this Global Key Command. |
|||
Report format |
A Message Format that will be echoed to the chat area when the button is clicked or the hotkey pressed. |
|||
Set Dynamic Properties in target pieces |
Allows you to set the values of the named Dynamic Properties that exist in pieces that are selected by this GKC. Property names used in the Expression will be replaced by the value of those properties in the matched pieces. You can use $$ variables to replace values in the expression from the source GKC. This will be values from the issuing piece for a Counter GKC, the owning Map for a Map or Deck GKC or the Game Module for a Module or Startup GKC. The values are set into the new marker before the Global Key Command is applied to the piece. This means the values are set even if the Global Key Command is not recognized by the matched pieces. You can specify a dummy Global Key Command in order to just set the Dynamic Properties in the target pieces without taking other actions.
See Passing values to pieces for more detailed information on using this feature. |
EXAMPLE 1
Example 1
A leader counter and infantry counters both have Marker traits to specify their nationality and type.
A Layer trait represents the rallied state of an infantry counter, uses Ctrl+A to activate the Layer, and uses Rally as the name.
A Global Key Command on the leader counter can select and rally all infantry counters within two hexes of the same nationality that are not rallied by checking the boxes for Restrict Range and Fixed Range, specifying Range of 2 and additional matching properties { type == "Infantry" } && { nation == "$nation$" } && { Rally_Active == "false" }.
Or, as in the example shown in the dialog box, the type=="Infantry" check can be made faster by moving it out of the additional matching expression and into the Fast Match, by checking by Property?, and putting the expression { "type" } for the property name and {"Infantry"} for the property value.
Likewise, the effects can be restricted to pieces on the main map by checking the by Location? box selecting Specific Map, and putting {"Main Map"} in the Map field.
If instead you wanted to match pieces on the same map as the issuing piece, you could select Current Map instead.
EXAMPLE 2
Example 2
An Army unit that may stack with multiple generals can be given a command to "Put Senior General In Command" with the shortcut key command Alt+Ctrl+R.
When the menu item or shortcut key are activated, this trait sends the Named Key Command CheckRANKS to the pieces representing generals who might be put in command.
Eligible generals are found by checking first if they have a property Rank which is > 0, since only generals have ranks.
Next their Side property ("Union" or "Confederate") is compared to a Global Property ActiveSide so that we don’t accidentally put Ulysses Grant in command of the Confederate army. Notice that the Rank check uses the Fast Match comparison to eliminate all pieces that don’t have ranks (all the non-generals) very quickly; the same comparison (Rank > 0) could be included in the Additional Matching Expression, for convenience, but it would not run as quickly.
Module Global Key Commands
A Module GKC has an associated toolbar button that is added to the main module toolbar and can select pieces from any Map in the game.
Use a Module GKC when you want to process pieces across more than one Map, or where you want the toolbar button to be in the main Toolbar, or a Toolbar Menu on the main Toolbar.
Module GKC Example:
Module Global Key Command example
Map Global Key Commands
A Map GKC has an associated toolbar button that is added to the toolbar associated with the Map it is defined on and by default, will only select pieces from that Map.
Map GKCs have an additional option Apply counters to this map only which can be disabled to make them act like a Module GKC and select pieces from all Maps in the game.
Use a Map GKC when you want the toolbar button to appear in the Map Toolbar, or on a Toolbar Menu on the Map toolbar.
Map GKC Example:
Map Global Key Command example
Startup Global Key Commands
Startup GKCs are run automatically when a game is started or loaded. They can be used to display message on game startup, or do New Game initialization tasks.
Otherwise, it works as a standard Global Key Command, but has no associated toolbar, unless the Global Hotkey mode is enabled.
Unlike other Global Key Commands, a Startup HKC can be confuigured to send a Global Hotkey (to affect toolbar buttons and Decks) rather than a Global Key Command (which affects pieces). See the second example below.
|
Note
|
Any Startup GKCs configured are guaranteed to run in the order they are defined in the module. |
Startup GKC example 1:
At the start of each fresh game, set the Dynamic Property PreGame on each piece in the game to false and send each piece the AutoExec Key Command.
The When to Apply option controls exactly when the Startup GKC runs:
| Option | Description | ||
|---|---|---|---|
On First Game Launch/Load Of Session |
Run every time the module starts up, regardless of whether it is to begin a new game or to load and continue an existing one. |
||
On Every Game Launch/Load Of Session |
Run every time a game is launched or loaded during the session. |
||
At Start Of Every Fresh Game Only |
Run only when a new game is starting. If the game is saved and later restored, or is being exchanged back and forth in log form, the key command will not fire on subsequent loads.
|
||
At Start of Fresh Game or Player Join/Side-Change |
Run only when a new game is starting OR a new player joins or a player changes sides. |
Startup GKC example 2:
Send a Global Hotkey on startup.
The What to Apply field allows selection of Global Key Command mode (affects pieces) or Global Hotkey mode (affects toolbar buttons and decks).
Deck Global Key Commands
Deck GKCs are a cut-down version that can only select pieces in the Deck the Deck GKC is defined in.
Deck GKCs do not have a Fast Match option, just a Matching expression field which works in the same way as the Additional matching expression of the other types.
The Affects field is cut-down version of the Affects in Deck field of the other types, allowing either All pieces, or a limited number of pieces to be affected.
Deck GKC Example:
Sent Ctrl-M to the first piece in the Deck which is not a "Blockade" piece.
Counter Global Key Commands
The Counter version of Global Key Command is a trait that can be added to a Game Piece.
The main Examples above are Counter GKCs.