VASSAL Reference Manual

Basic Piece

The simplest game piece consists of an image and a name.

The image is optional, or different pieces can share the same image, but you should always either give each Basic Piece a unique name or add a Basic Name trait to provide one.

Simple piece images can be created from scratch within Vassal using Game Piece Image Definitions, but you will usually get a better result by loading images sourced from existing artwork or created with specialist graphics software.

To give a piece more complex behaviors, you can add more Traits to it in the Piece Definer dialog. For example, you could omit or remove the image from the Basic Piece and instead add a Layer trait to allow the piece to use multiple images.

Name:

Choose a unique name for this Game Piece.

Image:

Click on the Add button to select an image for this Game Piece and to load it into the module.

Click on the Clear button to remove the selected image from this Game Piece.

Click on the drop-down menu to select an image that has already been loaded into the module in a previous editing session. Note that newly selected images do not appear in the drop-down list until the module has been saved and re-loaded.

BasicPiece A Basic Piece containing an image and a name.

BasicPiece2 Choosing an image that has already been loaded into the module.

Back to Trait List

The following Properties are defined in a Basic Piece, meaning that any trait in the piece can refer to them:

  • BasicName contains the name of Basic Piece trait. Can be overridden by adding a Basic Name trait to the piece.

  • PieceName contains the full name of the piece, including any additional strings added by e.g. Layer or Text Label traits (Note the distinction from the use of $pieceName$ with lowercase p inside the Text Label trait and in a Map’s movement report fields — those are similar but separate uses specific to those situations. The general-purpose property for a piece’s traits to use to get the piece’s own full name, as well as for Property Match Expressions selecting for target pieces in a Global Key Command, is PieceName with the capital P).

  • PlayerSide contains the side of the current player, as specified in the Definition of Player Sides

  • LocationName contains the name of the current location, as determined by the local grid. If the piece is in a Zone in a Multi-Zone Grid, then whether LocationName returns the name of the Zone or a Region within the Zone’s grid depends on the configuration of the Zone.

  • CurrentMap contains the name of the current Map Window

  • CurrentBoard contains the name of the current Board

  • CurrentZone contains the name of the current Zone

  • CurrentX contains the current map X coordinate

  • CurrentY contains the current map Y coordinate

  • DeckName contains the name of the Deck if the piece is currently stacked in one.

  • DeckPosition contains the position of a piece within a Deck (top = 1) if the piece is currently stacked in one, or 0 otherwise.

  • Selected contains true when the piece has been selected with the mouse

  • PieceId contains a string that uniquely defines the source of the piece. All pieces sourced from the same Game Piece Palette slot will have the same PieceId string.

  • PieceUID contains a string that uniquely defines a piece. No two pieces will ever have the same PieceUID string. PieceUID’s are re-allocated when a game is refreshed and so cannot be guaranteed to link pieces long-term and should only be used for short-term comparisons.

  • UniqueID contains a string that uniquely defines a piece. No two pieces will ever have the same UniqueID string. UniqueID’s ARE maintained across a Game Refresh and can be used for long-term comparisons between pieces.

  • DrawingMouseover contains true when a Mouseover Stack Viewer is currently being drawn, and contains false otherwise.

  • DrawingMouseoverIndex contains 2 when a Mouseover Stack Viewer is currently being drawn, and contains 1 otherwise. This can be used, e.g., in the Follows Expression field of a Layer trait to draw a different image for the Mouseover than is normally used when drawing the piece on the map.

  • StackPos contains the position of the piece within the piece’s current Stack, 1 being the top. If the piece is a Non-stacking piece, StackPos will return 1.

  • StackSize contains the number of pieces in the piece’s current Stack. If the piece is a Non-stacking piece, StackSize will return 1.

The following Properties are defined after a piece is moved, either manually by drag-and-drop movement or by a Send To Location trait:

  • OldLocationName contains the name of the previous location, as determined by the local grid

  • OldMap contains the name of the previous Map Window

  • OldBoard contains the name of the previous Board

  • OldZone contains the name of the previous Zone

  • OldX contains the previous map X coordinate

  • OldY contains the previous map Y coordinate

  • OldDeckName contains the name of any deck the piece was in before its last move (will be an empty string if piece wasn’t in a deck)

  • OldMat contains the previous Mat, if this is a Mat Cargo piece.

  • OldMatID contains the previous Mat ID, if this is a Mat Cargo piece.

  • OldMatPieceName contains the previous Mat’s Piece Name

  • OldMatBasicName contains the previous Mat’s Basic Name

The following Properties are defined after the player has selected something from the piece’s right-click context menu:

  • ClickedX contains the X location on current map where right-click took place.

  • ClickedY contains the Y location on current map where right-click took place.