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.

Description: A description of this trait, which appears in the Piece Definer list in the Editor.

Command name: 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.

Matching Properties:  The Global Key Command will only be applied to Game Pieces which match the specified Property Match Expression. Note that the properties named in the 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 or not 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.

Restrict Range:  If selected, the command will only apply to pieces located within a specified distance of this piece.

Range:   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 matching properties { type == "Infantry" } && { nation == "$nation$" } && { Rally_Active == "false" }.

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. Finally, we filter out Generals who aren't currently in play on the map (either they're in the reinforcement pool, the dead pool, or already in command of another army) by checking to make sure their CurrentZone name corresponds to one of the US or Confederate states in a string list ("Alabama, Arkansas, ...") contained in another Global Property.