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.

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 Basic Piece defines properties related to a piece’s name, location, side, and whether it’s selected.

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

  • 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.

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

  • The Dynamic Property trait allows you to define your own changeable 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 Invisible trait sets a property when the piece is invisible.

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

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

Property

Trait

Description

BasicName

Basic Piece

The basic name of the piece.

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).

CurrentBoard

Basic Piece

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

CurrentMap

Basic Piece

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

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.

IgnoreGrid

Does not stack

"true" if this piece ignores the map grid when moving.

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.

InvisibleToOthers

Invisible

"true" if this piece is invisible to other players.

LocationName

Basic Piece

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

Moved

Mark When Moved

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

NoStack

Does not stack

"true" if this piece cannot stack with other pieces.

Obscured

Mask

"true" if this piece is masked from the current player.

ObscuredToOthers

Mask

"true" if this piece is masked from other players.

OldBoard

Basic Piece

Board name prior to most recent movement.

OldLocationName

Basic Piece

Location name prior to most recent movement.

OldMap

Basic Piece

Map name 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.

PieceName

Basic Piece

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

playerSide

Basic Piece

Side of the current player (not the side of the piece).

Restricted

Restricted Access

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

Selected

Basic Piece

"true" if the piece is currently selected.

<property_name>

PropertySheet

The value of each property on the Property Sheet can be accessed via the property 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>.

_<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>.

<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.

_<deckname>__numPieces

Deck (Map level property)

Number of pieces/"cards" in the Deck <deckname>.

<deckname>__<expression_name>_

Deck (Map level property)

The number of pieces/"cards" for which the named expression evaluates to true in the Deck <deckname>.