## 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.

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%.

  by location?

    If this box is checked, potential target pieces will be pre-filtered based on their locations.

    Select By:

      Selects the type of Location-based filtering that will be done on target pieces.

      Current Stack or Deck - Only pieces in the same Stack or Deck as the issuing piece will be checked. This type of filtering, when applicable, is very fast.

      Current Map - Only pieces on the same Map as the piece issuing the Global Key Command will be checked.

      Current Zone - Only pieces in the same Zone (and therefore Map) as the piece issuing the Global Key Command will be checked.

      Current Location - Only pieces in the same Location (i.e. LocationName property the same) as the piece issuing the Global Key Command will be checked.

      Specific Map - Only sends to pieces that are on the Map matching the supplied expression. The expression is evaluated against the properties of the source piece, i.e. the piece issuing the Global Key Command, but then the result of the expression is compared to the Map of potential target pieces to determine if they are valid targets.

      Specific Zone - Only sends to pieces that are in the Zone matching the supplied expression (an optional Map expression can be supplied as well). The expressions are evaluated against the properties of the source piece, i.e. the piece issuing the Global Key Command, but then the results of the expressions are compared to the CurrentZone (and optionally CurrentMap) of potential target pieces to determine if they are valid targets.

      Specific Location - Only sends to pieces that are in the Location matching the supplied expression (an optional Map expression can be supplied as well). The expressions are evaluated against the properties of the source piece, i.e. the piece issuing the Global Key Command, but then the results of the expressions are compared to the LocationName (and optionally CurrentMap) of potential target pieces to determine if they are valid targets.

      Specific X,Y Position - Only sends to pieces that are at the X,Y location matching the supplied expressions (optional Map and Board expressions can be supplied as well). The expressions are evaluated against the properties of the source piece, i.e. the piece issuing the Global Key Command, but then the results of the expressions are compared to the CurrentX and CurrentY (and optionally CurrentMap and CurrentBoard) of potential target pieces to determine if they are valid targets.

  by property?

    If this box is checked, a single property of the target will be checked to determine if it is a valid target. This search will be performed more quickly than a similar search in the Additional Matching Expression field.

    Property Name

      Can be a simple string containing the name of a property in potential target pieces to be checked, or an expression to be evaluated against the source piece (the piece issuing the Global Key Command). The result of evaluating the expression is then used to find a property name in the potential target piece.

    Comparison

      The type of comparison to be done with the value of the property specified above. Can be equals, not-equals, greater, greater-or-equal, less than, less-than-or-equal, or can be matches or non-matches a regular expression.

    Property Value

      Can be a simple string or number containing a specific value which will be compared to the value of the property specified above, or an expression to be evaluated against the source piece (the piece issuing the Global Key Command). The result of evaluating the expression is then used as the value to be compared against the property specified above using the comparison specified above.

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 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.Properties.html

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 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.