VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Global Key Command

Global Key Command

This Trait adds an action that applies a key command to other pieces, similar to the Global Key Command component of a Map Window. Global Key Commands are the main avenue by which Pieces can prompt action by other Pieces. As such, they are very powerful, but they do come at the price of some performance lag, as each time one is issued Vassal must generally check it against every piece on the board.


A short description of this trait for your own reference.

Menu command:

Name of the right-click context menu item. If left blank, no context menu item will appear.

Key command:

A Key Command or Named Key Command that initiates the action. For example a keyboard shortcut which, when typed with this piece selected will cause the Global Key Command to be issued. This is not, however, the command that will be issued to the other pieces (see next field).

Global Key Command:

The Key Command or Named Key Command that will be applied to other Pieces (and potentially this piece as well). As with all Key Commands, this can either be an actual keyboard shortcut like Ctrl+F, or a Named Key Command such as FireForwardPhasers. Other pieces which have that same shortcut or Named Key Command filled in as the Key Command for one or more of their Traits will have those traits activated.

Pre-select (Fast Match):

New from VASSAL 3.5, the 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. Essentially these run limited but much faster comparisons, to screen out some of the potentially hundreds of pieces needing to be checked for each Global Key Command. Fast Match expressions are optional in that the same comparisons can always be run in the standard "Additional matching expression" field. Judicious use of them, however, can improve the performance of a Global Key Command by 25-33%.

See the FastMatch.html 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 the Global Key Command will be applied to pieces in a Deck. Options are All pieces, No pieces, or Fixed number of pieces. If Fixed number of pieces is selected, a field appears to allow entry of the number of Pieces in the Deck to affect, starting at the top of the Deck. Thus, selecting 1 for the fixed number would cause only the top card or piece in a Deck to be affected. As of VASSAL 3.6, an Expression can be used. Note that such an expression will be evaluated once at the beginning of the global key command (not each time a candidate piece is being checked).

Restrict Range:

If selected, the command will only apply to pieces located within a specified distance of this piece.Properties.html


Only others pieces within this distance, inclusive, of this piece will have the command applied to them. If the pieces are on a board with a Hex Grid or Rectangular Grid, then the distance is in units of the grid. Otherwise, the distance is measured in screen pixels.

Fixed Range:

If selected, then the range is specified as a fixed number. If unselected, then the range will be given by the value of the named property.

Range Property:

The name of a Property that contains the range to use when Fixed Range is not selected.

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.

EXAMPLE 1 (see upper right):

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 (see below):

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.