## VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Properties

### Properties

A Property is like a variable in programming: it has a value which can be referenced by including its name in Expressions, Message Formats and other similar fields. Most types of Property have their values change through the course of the game. Some Properties can have their values set by commands provided in Game Pieces themselves; others have their values set by the system and cannot be changed from within the module.

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components. You can add your own new properties to a Game Piece explicitly by adding Dynamic Property traits to create values which can be changed during the course of the game and Marker traits for properties whose values will remain constant. System-defined properties are also added implicitly when other traits are added (see below). Global Properties can also be defined for a Zone, a Map or for the entire module. If a referenced Property name is not defined in a Game Piece, the VASSAL looks for the value in the Zone containing the piece, then in the Map containing the piece, then in the module.

Properties can be matched using Expressions like name == value for an exact match, name != value for a non-match, or name =~ value for a regular expression match. For properties that return a numeric value (e.g. the level in a Layer) you can use <, <=, >, and >=. You can combine expressions using && for logical AND and || for a logical OR.

Note

Properties associated with specific traits (e.g. Obscured) have a value of true or false if that trait exists in the piece, but will have a value of "" if that trait does not exist. So when using these traits in expression, you should always test if the value is true, or not true, never test for false:
`{property == true}`
`{property != true}`
Do not use
`{! property}`
in cases like these as this will generate an error if the property does not have a value.

Components that use properties

- Any Message Format defined in a Game Piece will substitute values for the properties defined on that Game Piece.

- The Global Key Command component uses properties to determine which pieces will respond to the command.

- The Game Piece Layers component uses properties to determine relative ordering when drawing pieces on the map.

- The Trigger Action trait uses properties to determine when to fire a Key Command or Named Key Command .

- The Text Label trait substitutes properties when setting the text of the label.

- A Zone uses properties to specify a Zone Highlighter.

Properties defined by Game Pieces

- The Area of Effect defines a property that returns the current visibity (on or off) of the highlight.

- The Basic Piece defines properties related to a piece’s name, location, side, and whether it’s selected.

- The Clone trait sets a property in all pieces Cloned from the same piece that links them together.

- The Dynamic Property trait allows you to define your own changeable properties.

- The Invisible trait sets a property when the piece is invisible.

- The Layer trait defines properties related to the state of that Layer.

- The Marker trait allows you to define your own static properties.

- The Mark When Moved trait sets a property when a piece has moved.

- The Mask trait sets a property when the piece is masked.

- The Place Marker trait sets a property in the created marker piece that links back to the piece that created it.

- The Property Sheet trait exposes a set of user-editable properties.

- The Rotate trait defines properties related to the current facing of the piece.

- The Text Label trait returns the value of the label as a property.

Properties defined by other components

- The Global Property component defines properties for a Zone, Map or the module.

- The Global Options component allows you to tie property values to preferences settings.

- The results of a roll by a Dice Button is exposed as a property

- A Deck component exposes the number of cards remaining as a Map-level property.

#### Handy Combined List of VASSAL-defined Properties for Game Pieces

##### Fixed Property Names

Property | Trait | Description
--- | --- | ---
AttachCount | Attachment | Returns the current Attachment count of the last defined Attachment trait.
BasicName | Basic Piece or Basic Name | The basic name of the piece.
BoardOfCommand | Multi-Location Command | Contains the Board Name of the last selected Multi-Location Command.
cannotMove | Does not stack | "true" if this piece cannot move at all (note spelling).
ClickedX | Basic Piece | Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
ClickedY | Basic Piece | Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
CloneId | Clone | All pieces Cloned from the same piece (including the original piece) will have the same unique value for CloneId.
CurrentBoard | Basic Piece | Current Board name or "" if not on a map.
CurrentMap | Basic Piece | Current Map name or "" if not on a map.
CurrentMat | Cargo | If the piece is Cargo loaded on a Mat, then the name of the Mat, otherwise ""
CurrentMatBasicName | Cargo | If the piece is Cargo loaded on a Mat, then the BasicName of the Mat piece, otherwise ""
CurrentMatBoard | Cargo | If the piece is Cargo loaded on a Mat, then the CurrentBoard of the Mat, otherwise ""
CurrentMatID | Cargo | If the piece is Cargo loaded on a Mat, then the unique identifying ID string of the Mat, otherwise ""
CurrentMatLocationName | Cargo | If the piece is Cargo loaded on a Mat, then the LocationName of the Mat, otherwise ""
CurrentMatMap | Cargo | If the piece is Cargo loaded on a Mat, then the CurrentMap of the Mat, otherwise ""
CurrentMatOffsetX | Cargo | If the piece is Cargo loaded on a Mat, then the difference between the CurrentX of this piece and of the Mat, otherwise ""
CurrentMatOffsetY | Cargo | If the piece is Cargo loaded on a Mat, then the difference between the CurrentY of this piece and of the Mat, otherwise ""
CurrentMatPieceName | Cargo | If the piece is Cargo loaded on a Mat, then the PieceName of the Mat piece, otherwise ""
CurrentMatProp0 CurrentMatProp1 …​ CurrentMatProp9 | Cargo | If the piece is Cargo loaded on a Mat, then the value of exact same named property in the Mat piece, otherwise ""
CurrentMatX | Cargo | If the piece is Cargo loaded on a Mat, then the CurrentX of the Mat, otherwise ""
CurrentMatY | Cargo | If the piece is Cargo loaded on a Mat, then the CurrentY of the Mat, otherwise ""
CurrentMatZone | Cargo | If the piece is Cargo loaded on a Mat, then the CurrentZone of the Mat, otherwise ""
CurrentX | Basic Piece | Current X-coordinate of the piece.
CurrentY | Basic Piece | Current Y-coordinate of the piece.
CurrentZone | Basic Piece | Current Zone name if the current map has a multi-zoned grid, or "" if the piece is not in any zone, or not on a map.
DeckName | Basic Piece | Current Deck name if stacked in a Deck, or "" if not in a Deck.
DeckPosition | Basic Piece | Current position of the piece (top = 1) if stacked in a Deck, or "" if not in a Deck.
DrawingMouseover | Basic Piece | "true" when a Mouseover Stack Viewer is currently being drawn, "false" otherwise.
DrawingMouseoverIndex | Basic Piece | 2 when a Mouseover Stack Viewer is currently being drawn, 1 otherwise.
IgnoreGrid | Does not stack Cargo | "true" if this piece ignores the map grid when moving. Note that a Cargo trait in a piece currently loaded onto a Mat will force the IgnoreGrid property to be "true".
Immobile | Does not stack | "true" if this piece cannot be moved by drag and drop.
Invisible | Invisible | "true" if this piece is invisible to the current player. May be false or "" if the piece is not invisible.
InvisibleToOthers | Invisible | "true" if this piece is invisible to other players. May be false or "" if the piece is not invisible.
IsCargo | Cargo | Will always be "true" for a Cargo piece, "" otherwise. Use CurrentMat to check if a Cargo piece is currently loaded on a Mat.
LocationName | Basic Piece | Name of the piece’s current location, as determined by the map’s Zone (if any) and grid settings.
LocationOfCommand | Multi-Location Command | Contains the Location Name of the last selected Multi-Location Command.
MapOfCommand | Multi-Location Command | Contains the Map Name of the last selected Multi-Location Command.
MatID | Mat | A string uniquely identifying a particular Mat, even if it shares the same Mat Name with another trait containing a Mat.
MatName | Mat | The name of the Mat.
MatNumCargo | Mat | The number of pieces of Cargo currently loaded on the Mat.
Moved | Mark When Moved Movement Trail | "true" if this piece has moved since the last time its movement history was cleared.
NoStack | Does not stack Mat | "true" if this piece cannot stack with other pieces. Note that the Mat trait forces a piece to be Non-Stacking as it is required for Mats to function correctly.
Obscured | Mask | "true" if this piece is masked from the current player. May be false or "" if the piece is not masked.
ObscuredToOthers | Mask | "true" if this piece is masked from other players. May be false or "" if the piece is not masked.
OldBoard | Basic Piece | Board name prior to most recent movement.
OldDeckName | Basic Piece | Name of any Deck the piece was in before its last move (will be an empty string if piece wasn’t in a deck)
OldLocationName | Basic Piece | Location name prior to most recent movement.
OldMap | Basic Piece | Map name prior to most recent movement.
OldMat | Cargo | Mat name prior to most recent movement.
OldMatBasicName | Cargo | Mat BasicName prior to most recent movement.
OldMatID | Cargo | MatID prior to most recent movement.
OldMatOffsetX | Cargo | MatOffsetX prior to most recent movement.
OldMatOffsetY | Cargo | MatOffsetY prior to most recent movement.
OldMatPieceName | Cargo | MatPieceName prior to most recent movement.
OldX | Basic Piece | X coordinate prior to most recent movement.
OldY | Basic Piece | Y coordinate prior to most recent movement.
OldZone | Basic Piece | Zone name prior to most recent movement.
ParentID | Place Marker | The UniqueID of the piece that placed this piece using the Place Marker trait. Can be used to communicate back to the parent piece.
PieceId | Basic Piece | A string that uniquely identifies the source of a piece (e.g. A Game Piece Palette entry, an At-Start Stack or Definition, or a Place Marker or Replace definition). All pieces created from the same source will have the same PieceId.
PieceName | Basic Piece | Full piece name including both Basic Name and all additional strings provided by traits.
PieceUID | Basic Piece | A string that uniquely identifies an individual piece. No two pieces will ever have the same PieceUID. A new PieceUID is allocated when a game is Refreshed. See UniqueID for a Uniquely identifying property that is guaranteed to never change.
Restricted | Restricted Access | "true" if there are restrictions as to who can access this piece.
RestrictedMovement | Restricted Access | "true" if non-owning players are resticted from moving the current piece.
Selected | Basic Piece | "true" if the piece is currently selected.
StackPos | Basic Piece | The position of the piece in its current Stack. Returns 1 if not stacked.
StackSize | Basic Piece | Number of pieces in the Stack this piece is stacked in. Returns 1 if not stacked.
UniqueID | Basic Piece | A string that uniquely identifies an individual piece and is guaranteed to never change, even if a game is refreshed.
ZoneOfCommand | Multi-Location Command | Contains the Zone Name of the last selected Multi-Location Command.

##### Properties dependent on the data in the trait

Property | Trait | Description
--- | --- | ---
<propertyName> | Calculated Property Dynamic Property Marker | The value of the properties defined by the 3 types of property traits can be accessed directly using their defined Property Name.
<traitname>_Active | Area of Effect | "true" if the Area of Effect with the name <traitname> is currently active.
<traitname>_AttachCount | Attachment | The current Attachment count for the Attachment trait <traitname>.
<rotatename>_Facing | Can Rotate | The current facing number (1, 2, etc.) for the Can Rotate trait <rotatename>.
<rotatename>_Degrees | Can Rotate | The current degrees of rotation for the Can Rotate trait <name>.
<layername>_Active | Layer | "true" if the Layer <layername> is currently active.
<layername>_Image | Layer | The image name of the currently active layer for Layer <layername>.
<layername>_Level | Layer | The level number of the currently active layer for Layer <layername>.
<layername>_Name | Layer | The level name of the currently active layer for Layer <layername>.
<property_name> | PropertySheet | The value of each property on the Property Sheet can be accessed via the property name recorded in the trait.
<Property Name> | Text Label | If the "Property Name" field in the trait is filled out, then a property with that name will be filled with the current value of the Text Label trait’s Text field.
<Property Name> | Translatable Message | The value of a Translatable Message can be referenced using the Property name defined in the trait.
<Property Name> | Trigger Action | The value of a Loop Index Property defined in a Trigger Action can be referenced using the Property name defined in the trait.

##### Fixed named properties provided by VASSAL that can be accessed by traits

Property | Component | Global Property Level | Description
--- | --- | --- | ---
CurrentLanguage | Game Module | Module | The 2 letter language code for the language selected by the current player.
CurrentLanguageName | Game Module | Module | The name of the language seleted by the current player.
ModuleDescription | Game Module | Module | The Module description text from the main Game Module component.
ModuleName | Game Module | Module | The Module name text from the main Game Module component.
ModuleOther1 | Game Module | Module | The Additional Module Info 1 text from the main Game Module component.
ModuleOther2 | Game Module | Module | The Additional Module Info 2 text from the main Game Module component.
ModuleVersion | Game Module | Module | The Module version text from the main Game Module component.
PlayerId | Game Module | Module | The Player Id string for the current player, as defined in Global Options
PlayerName | Game Module | Module | The Player Name of the current player
PlayerSide | Game Module | Module | The Side taken by the current player if Sides have been defined in the module
VassalVersionCreated | Game Module | Module | The version number of Vassal that was used to create the current module.
VassalVersionRuning | Game Module | Module | The version number of Vassal that is currently running.

##### Property names provided by VASSAL Components that can be accessed by traits, but are dependent on the module

Property | Component | Global Property Level | Description
--- | --- | --- | ---
<propertyname> | Global Property | Zone | Global Properties defined within a Zone can be referenced directly by the property name by pieces that are inside that Zone. To reference a Global Property in a different zone, use the GetZoneProperty function.
<propertyname> | Global Property | Map | Global Properties defined within a Map can be referenced directly by the property name by pieces that are reside on that Map. To reference a Global Property in a different map, use the GetMapProperty function.
<propertyname> | Global Property | Module | Global Properties defined within the top-level Game Module can be referenced directly by the property name by any pieces in the game.
<propertyname> | Action Button | Module | Returns the value of a Loop Index property defined in an Action Button.
<propertyname> | Custom Preference | Module | Returns the value of a Custom Preference defined within the Global Options component.
<dicename>_result | Dice Button | Module | Returns the list of dice rolled during the last die roll of the Dice Button <diceName>.
<dicename>_total | Dice Button | Module | Returns the number of dice that where kept from the last die roll of the Dice Button <diceName>.
<dicename>_keep | Dice Button | Module | Returns the numeric total of the last die roll of the Dice Button <diceName>.
<deckname>_numPieces | Map | Map | Returns the number of pieces/"cards" in the Deck <deckname>.
<deckname>_<expression_name> | Map | Map | Returns the number of pieces/"cards" for which the named expression evaluates to true in the Deck <deckname>.
<mapname>_isVisible | Map | Map | Returns the True if the Map named <mapname> is currenly visible.
<propertyname> | Scenario Property | Module | Returns the value a Scenatio Property defined within a Scenario Properties Option Tab component.
<propertyname> | Turn Counter | Module | Returns the current value of the Turn Counter Level named <propertyname>.
<propertyname> | Turn Counter | Module | Returns the current value of the Turn List Level named <propertyname>.