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.

See the combined GlobalKeyCommands.html page for full details of Global Key Commands.

EXAMPLE 1:

CounterGlobalKeyCommand

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:

CounterGlobalKeyCommand

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.