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.

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.