VASSAL Reference Manual


Attachment

This Trait adds an action that creates a lasting "attachment" to other pieces, allowing several special functions:

(1) The piece will be able to issue Global Key Commands to attached pieces using the very fast and efficient "Current Attachments" location filter. A piece that needs to repeatedly communicate with the same piece(s) every time can thus use an Attachment to make the commands process very quickly, overcoming the normal performance lag of Global Key Commands.

(2) The piece will be able to access the properties of any of the pieces that the Attachment trait is bound to through the various versions of the GetAttachProperty function.

(3) The piece will be able to directly read the properties of one of the pieces that the Attachment trait is bound to through a simple syntax. For cases where a single piece is bound to a particular Attachment trait, this can be quite useful in reading its properties quickly and easily. If a group of multiple pieces is attached with one Attachment trait, properties will be read from an undetermined single piece from among the attached pieces. See Attachment Name, below, for an explanation of how to read a property from the attached piece.

(4) For Dynamic Properties of an attached piece, the value of the properties can also be set by this piece, by using a Set Piece Property trait with the Current Attachments fastmatch option.

(5) If the attached-to piece also has an Attachment trait that shares the same Attachment Name, then mutual attachments between pieces can also be formed.

(6) Attachments are also allowed to be made from a piece to itself (`Allow attachments to self'). This allows you to create a group of pieces that are all equivalently attached to all other pieces in the group and can all issue the same Attachment related commands. By default, this option is disabled, which creates an assymetric Attachment group, where one piece is the 'driver' that sends commands to an attached set of pieces, but they cannot necessarily send commands back.

NOTES:
  • The property <AttachmentName>_AttachCount can be used to find out how many pieces are currently attached via this trait. For example if the Attachment Name were "Sibling" then the property Sibling_AttachCount would hold the attachment count.

  • A Global Key Command sent to "Current Attachments" will execute very quickly

  • Pieces can attach to themselves, but only if the Allow attachment to self option is enabled.

  • While a single piece can contain one or more Attachment traits, all of an individual piece’s Attachment traits should have different names (no single piece should have two Attachment traits with the same name).

  • Two pieces, each with an Attachment trait sharing the same Attachment Name can form a mutual attachment

  • Pieces which are deleted from the game are automatically removed as attachments.

  • The GetAttachProperty function can be used in expressions to read the values of Dynamic Properties on attached pieces. See the section on the GetProperty functions for more information.

  • A Set Attachment Property trait can be used to change the values of Dynamic Properties on attached pieces.

Attachment Name:

The name for this Attachment trait. This name can be used by the piece to read properties from attached pieces. For example if the Attachment name were Sibling, then the property Sibling_LocationName would contain the LocationName property of the first currently attached piece.

Description:

A short description of this trait for your own reference.

Auto-attach to all pieces with identical attachment name:

If selected, the piece will automatically attach itself to other pieces which have an Attachment trait with an identical attachment name; this can be used to easily and quickly attach pieces together. When selected, none of the advanced options for attaching and detaching pieces will be displayed. When this option not selected, the advanced options for attaching and detaching pieces will be shown.

Allow attachment to self:

If selected, the attachment is allowed to attach to this piece (i.e., itself) if conditions are otherwise met. If not selected, the Attachment will never attach to itself in any circumstances.

Note
This has implications when using the GetAttachProperty function - The function can potentially select the current piece to read the property from.
Before adding attachments:

Determines whether existing attachments are cleared before adding new attachments.

Clear existing attachments first

If this option is selected, then whenever the key command to attach pieces executes, all existing attachments are first cleared before adding any pieces that match the command.

Leave existing attachments alone

If this option is selected, then adding attachments will never detach pieces — meaning that executing the attach key command a second or subsequent time will only potentially add attachments, never remove any.

When another piece attaches to this one using this attachment’s name

Determines what happens when another piece with an Attachment trait sharing the same Attachment Name attaches to this piece. Can be used to create two-way and multi-way attachments.

No additional action

Nothing additional happens. This is the default setting, and useful for creating "one-way" attachments.

Attach to that piece

This piece adds that piece to its list of attachments—​in other words a mutual attachment is formed. This setting is useful for creating mutual or "two-way" attachments.

Attach to that piece along with all pieces it has attached to

This piece adds that piece to its list of attachments. This piece also adds to its attachment every other piece that the new piece has attached (using an Attachment trait with the same Attachment Name). This setting is useful for creating "multi-way" attachments. NOTE: it will also normally result in the piece being attached to itself, unless the Allow attachment to self box is unchecked.

Menu command to attach pieces:

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

Key command to attach pieces:

A Key Command or Named Key Command that initiates attachment of pieces.

Pre-select (Fast Match):

Fast Match selections can be used to improve the performance of "slow" piece filters.

See the Fast Match page for full details on Fast Matches.

Additional matching expression:

If further refinement of which target pieces should be attached is needed, or if you do not wish to use Fast Match pre-selections, an Additional Matching Expression can be used. Only Game Pieces which match the specified Property Match Expression will become attached. Note that the properties named in this expression are evaluated against the properties of the target pieces, not the properties of the piece creating the Attachment. 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 attach it. 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.

Within a Deck, apply to:

Select how the Attachment 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 attached. An Expression can be used. Note that such an expression will be evaluated once at the beginning of the attachment (not each time a candidate piece is being checked).

Restrict Range:

If selected, the command will only attach pieces located within a specified distance of this piece.

Range:

Only others pieces within this distance, inclusive, of this piece will be attached. 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.

When clearing our attachment to another piece

Determines what happens when the Clear Matching or Clear All key command is used to remove one of our existing attachments.

No additional action

Nothing additional happens. This is the default setting.

Remove that piece’s attachment to this one as well

Severs the other piece’s attachment to this one as well (assuming it has one from an Attachment trait with the same Attachment Name)

Menu command to clear all outgoing attachments:

Name of the right-click context menu item to clear ALL current attachments (by this individual Attachment trait). If left blank, no context menu item will appear.

Key command to clear all outgoing attachments:

A Key Command or Named Key Command that initiates the clearing of ALL current attachments (by this individual Attachment trait).

Menu command to clear matching attachments:

Name of the right-click context menu item to clear current attachments that match an expression. Only pieces attached by this Attachment trait will be affected.

Key command to clear matching attachments:

A Key Command or Named Key Command that initiates the clearing of current attachments that match an expression. Only pieces attached by this Attachment trait will be affected.

Property match expression for clearing attachments:

An expression determining which current attachments will be cleared when the above key command is executed. See Additional matching expression, above, for further information on how these expressions work.

Attachment