VASSAL Reference Manual


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

Returns the current Attachment count of the last defined Attachment trait.

BasicName

The basic name of the piece.

BoardOfCommand

Contains the Board Name of the last selected Multi-Location Command.

cannotMove

"true" if this piece cannot move at all (note spelling).

ClickedX

Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).

ClickedY

Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).

CloneId

All pieces Cloned from the same piece (including the original piece) will have the same unique value for CloneId.

CurrentBoard

Current Board name or "" if not on a map.

CurrentMap

Current Map name or "" if not on a map.

CurrentMat

If the piece is Cargo loaded on a Mat, then the name of the Mat, otherwise ""

CurrentMatBasicName

If the piece is Cargo loaded on a Mat, then the BasicName of the Mat piece, otherwise ""

CurrentMatBoard

If the piece is Cargo loaded on a Mat, then the CurrentBoard of the Mat, otherwise ""

CurrentMatID

If the piece is Cargo loaded on a Mat, then the unique identifying ID string of the Mat, otherwise ""

CurrentMatLocationName

If the piece is Cargo loaded on a Mat, then the LocationName of the Mat, otherwise ""

CurrentMatMap

If the piece is Cargo loaded on a Mat, then the CurrentMap of the Mat, otherwise ""

CurrentMatOffsetX

If the piece is Cargo loaded on a Mat, then the difference between the CurrentX of this piece and of the Mat, otherwise ""

CurrentMatOffsetY

If the piece is Cargo loaded on a Mat, then the difference between the CurrentY of this piece and of the Mat, otherwise ""

CurrentMatPieceName

If the piece is Cargo loaded on a Mat, then the PieceName of the Mat piece, otherwise ""

CurrentMatProp0
CurrentMatProp1
…​
CurrentMatProp9

If the piece is Cargo loaded on a Mat, then the value of exact same named property in the Mat piece, otherwise ""

CurrentMatX

If the piece is Cargo loaded on a Mat, then the CurrentX of the Mat, otherwise ""

CurrentMatY

If the piece is Cargo loaded on a Mat, then the CurrentY of the Mat, otherwise ""

CurrentMatZone

If the piece is Cargo loaded on a Mat, then the CurrentZone of the Mat, otherwise ""

CurrentX

Current X-coordinate of the piece.

CurrentY

Current Y-coordinate of the piece.

CurrentZone

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

Current Deck name if stacked in a Deck, or "" if not in a Deck.

DeckPosition

Current position of the piece (top = 1) if stacked in a Deck, or "" if not in a Deck.

DrawingMouseover

"true" when a Mouseover Stack Viewer is currently being drawn, "false" otherwise.

DrawingMouseoverIndex

2 when a Mouseover Stack Viewer is currently being drawn, 1 otherwise.

IgnoreGrid

"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

"true" if this piece cannot be moved by drag and drop.

Invisible

"true" if this piece is invisible to the current player. May be false or "" if the piece is not invisible.

InvisibleToOthers

"true" if this piece is invisible to other players. May be false or "" if the piece is not invisible.

IsCargo

Will always be "true" for a Cargo piece, "" otherwise. Use CurrentMat to check if a Cargo piece is currently loaded on a Mat.

LocationName

Name of the piece’s current location, as determined by the map’s Zone (if any) and grid settings.

LocationOfCommand

Contains the Location Name of the last selected Multi-Location Command.

MapOfCommand

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

"true" if this piece has moved since the last time its movement history was cleared.

NoStack

"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

"true" if this piece is masked from the current player. May be false or "" if the piece is not masked.

ObscuredToOthers

"true" if this piece is masked from other players. May be false or "" if the piece is not masked.

OldBoard

Board name prior to most recent movement.

OldDeckName

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

Location name prior to most recent movement.

OldMap

Map name prior to most recent movement.

OldMat

Mat name prior to most recent movement.

OldMatBasicName

Mat BasicName prior to most recent movement.

OldMatID

MatID prior to most recent movement.

OldMatOffsetX

MatOffsetX prior to most recent movement.

OldMatOffsetY

MatOffsetY prior to most recent movement.

OldMatPieceName

MatPieceName prior to most recent movement.

OldX

X coordinate prior to most recent movement.

OldY

Y coordinate prior to most recent movement.

OldZone

Zone name prior to most recent movement.

ParentID

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

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

Full piece name including both Basic Name and all additional strings provided by traits.

PieceUID

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

"true" if there are restrictions as to who can access this piece.

RestrictedMovement

"true" if non-owning players are resticted from moving the current piece.

Selected

"true" if the piece is currently selected.

StackPos

The position of the piece in its current Stack. Returns 1 if not stacked.

StackSize

Number of pieces in the Stack this piece is stacked in. Returns 1 if not stacked.

UniqueID

A string that uniquely identifies an individual piece and is guaranteed to never change, even if a game is refreshed.

ZoneOfCommand

Contains the Zone Name of the last selected Multi-Location Command.

Properties dependent on the data in the trait
Property Trait Description

<propertyName>

The value of the properties defined by the 3 types of property traits can be accessed directly using their defined Property Name.

<traitname>_Active

"true" if the Area of Effect with the name <traitname> is currently active.

<traitname>_AttachCount

The current Attachment count for the Attachment trait <traitname>.

<rotatename>_Facing

The current facing number (1, 2, etc.) for the Can Rotate trait <rotatename>.

<rotatename>_Degrees

The current degrees of rotation for the Can Rotate trait <name>.

<layername>_Active

"true" if the Layer <layername> is currently active.

<layername>_Image

The image name of the currently active layer for Layer <layername>.

<layername>_Level

The level number of the currently active layer for Layer <layername>.

<layername>_Name

The level name of the currently active layer for Layer <layername>.

<property_name>

The value of each property on the Property Sheet can be accessed via the property name recorded in the trait.

<Property Name>

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>

The value of a Translatable Message can be referenced using the Property name defined in the trait.

<Property Name>

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

Module

The 2 letter language code for the language selected by the current player.

CurrentLanguageName

Module

The name of the language seleted by the current player.

ModuleDescription

Module

The Module description text from the main Game Module component.

ModuleName

Module

The Module name text from the main Game Module component.

ModuleOther1

Module

The Additional Module Info 1 text from the main Game Module component.

ModuleOther2

Module

The Additional Module Info 2 text from the main Game Module component.

ModuleVersion

Module

The Module version text from the main Game Module component.

PlayerId

Module

The Player Id string for the current player, as defined in Global Options

PlayerName

Module

The Player Name of the current player

PlayerSide

Module

The Side taken by the current player if Sides have been defined in the module

VassalVersionCreated

Module

The version number of Vassal that was used to create the current module.

VassalVersionRuning

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>

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>

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>

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>

Module

Returns the value of a Loop Index property defined in an Action Button.

<propertyname>

Module

Returns the value of a Custom Preference defined within the Global Options component.

<dicename>_result

Module

Returns the list of dice rolled during the last die roll of the Dice Button <diceName>.

<dicename>_total

Module

Returns the number of dice that where kept from the last die roll of the Dice Button <diceName>.

<dicename>_keep

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>

Module

Returns the value a Scenatio Property defined within a Scenario Properties Option Tab component.

<propertyname>

Module

Returns the current value of the Turn Counter Level named <propertyname>.

<propertyname>

Module

Returns the current value of the Turn List Level named <propertyname>.