VASSAL Reference Manual

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

Home > Module > Map > Global Key Command > Fast Match

Fast Match (Global Key Command pre-select)

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

Note	From VASSAL 3.7, all Location-based Fast-match options have been optimised and are now lightning fast. For best performance, always use a Location Fast-match (if possible).

You should aim to choose Fast-match conditions that exclude as many pieces as possible from the not Fast-match condtion checking.

Note	The Current options for Location Fast-match are only available for use in Counter Global Key Commands.

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. (Counter GKC only).

Current Map - Only pieces on the same Map as the piece issuing the Global Key Command will be checked. (Counter GKC only).

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

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. (Counter GKC only).

Current Mat & Cargo - If this piece is a Mat, or if it is a Mat Cargo piece that is currently on a Mat, then the Mat itself and all of its current Cargo will be checked. (Counter GKC only).

Current Attachments - Only pieces attached by an Attachment trait on this piece will be checked. (Counter GKC only).

You can optionally add an expression that evaluates to an Attachment name and only pieces attached using that name will be checked. If the Attachment name field is left blank, then all pieces attached by any Attachment trait on this piece will be checked.

You can also optionally add a Basic Name or Attachment Index to further refine the selection. A Basic Name will only match attached pieces that have the specified Basic Name. An integer Attachment index will return the nth attached piece for a given Attachment name. The first piece attached using an Attachment names is index 1, the second index 2 etc.

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.