VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Set Piece Property

Set Piece Property

This trait allows a Game Piece to change the value of an existing Dynamic Property in one or more other pieces which match a provided expression and fast-match context.

SetPieceProperty

Description:: A brief description of this trait for reference in the editor (not used during play).
Property Name:: An Expression that defines the name of the property to be set. A specific Dynamic Property can simply be listed by name, but it is possible to compute the name of the Dynamic Property to be changed based on other properties of this piece, e.g. { "Resources" + GetProperty("Side") }. In this case when the property Side holds the value "Allied" then the Dynamic Property to be set will be ResourcesAllied.

Note	The Dynamic Property trait must exist on the target pieces. This trait does not 'create' new Dynamic Properties.

Over-ride numeric constraints in target properties:

If left unticked, then the Set Property Piece trait will use whatever (if any) numeric constraints have been specified in the Dynamic Properties that it updates. If ticked, then the following 4 options appear and allow you to ignore or override any numeric constraints in the target property.

Is numeric:

If true, then changes to the value of the property by this trait will be restricted to integer values. If left unticked, then the following 3 options do not appear and this trait will set exactly the value specified.

Minimum value:

Numeric values will be restricted to no less than this number when changed by this trait.

Maximum value:

Numeric values will be restricted to no more than this number when changed by this trait.

Wrap:

If true, then when incrementing this numeric property, values will wrap around from the maximum to the minimum and vice versa.

Pre-select (Fast Match):

Fast match expressions help filter which pieces will have their property/properties set. See Fast Match for details.

Additional matching expression:

If further refinement of which target pieces should have their property/properties set is needed, or if you do not wish to use Fast Match pre-selections, an Additional Matching Expression can be used. Properties will only be set on 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 Set Piece Property.

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 apply the property change.

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 property change 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. As of VASSAL 3.6, an Expression can be used. Note that such an expression will be evaluated once at the beginning of the property set operation (not each time a candidate piece is being checked).

Restrict Range:

If selected, the property change 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 property change 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.

Key commands:

Adds any number of commands for this piece, each of which will change the value of the designated property in the specified way.

For each Key Command:

Menu command:

Right-click context menu text for the command, or leave blank to display no context menu item.

Key command:

Keystroke or Named Command which will activate this change.

Type:

Select the way in which this command will change the property:

Set value directly: Set the property directly to the value of the Expression entered in the New Value field. The properties AttachmentName and AttachmentIndex are available in this context.
Increment numeric value: Increment the value of the property by the value of the Expression entered in the Increment by field. To "decrement" the value, simple increment by a negative number.
Prompt user: Pop up a dialog and ask the user for a new value for the property. They will be prompted for a new value using the text prompt entered in the Prompt field.

Prompt user to select from list: Similar to Prompt User but displays a list of items to select from in a drop-down menu. The items in the list can be generated dynamically by Expressions. If some items evaluate to a blank string, then those items are only purged from the menu if the Purge Blanks option in Global Options is selected; otherwise the blank options appear.

Note

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 Set Piece Property
If you want to use a property in this piece in an expression here, then use $property$. All $…$ property references will be evaluated against this piece before the final expression is evaluated using properties from the target piece. E.g., Incrementing a property using the expression {$p1$ + p2} will add the value of the p1 property from this piece, plus the value of the p2 property from the target piece.