VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece


Game Piece

A Game Piece, sometimes simply referred to as a piece, is any counter, marker, or card used in a game. Game Pieces in VASSAL are highly customizable and can have quite complex behavior. They are defined by adding Traits to a basic piece in the Piece Definer window shown at right. A list of available Traits appears to the left, and a list of Traits currently in use by the piece you’re defining appears at the right. Add a Trait by selecting it in the list of available traits and clicking the 'Add' button. Remove a Trait by selecting it and clicking the 'Remove' button.

As you define your Piece, it will appear at the top of the window. You can select the Piece and type commands for it or right-click to bring up its context menu to test it as you go.

Once added to your Piece, a Trait’s properties can be edited by selecting the Trait and clicking the Properties button, or by double-clicking on the Trait in the list.

When a Piece is drawn, the Traits are drawn in order, beginning with the Basic Piece and continuing downward. The order of Traits can be important. For example the image in a Layer trait may obscure the Basic Piece or other Layers before it in the list of Traits.

For highly specialized pieces, you may supply your own custom Java classes. The Java class must implement the GamePiece interface and most commonly extends the Decorator class. First, add the Java .class file to the module file using a Zip utility (remember to preserve the package structure: e.g. the class should go in a subdirectory within the Zip that is named for its package). Then hit the "Import" button and enter the fully-qualified name of the class (if the package name is "PathsOfGlory" and the class name is "CustomPieceMover" then enter "PathsOfGlory.CustomPieceMover"). The Trait corresponding to your class will appear in the list of available Traits and you may add it normally. See the Coding Tutorial for more details.

GamePiece


Trait Ordering and YOU

Although you can probably make it a reasonable way into designing your first VASSAL module by just loading Traits into a piece in whatever order they occur to you, eventually as your mastery grows and you begin to think of more and more ambitious ways to improve your game and module there may well come a time when your traits will seem to be interacting oddly with each other. Perhaps the trait you expected to be hidden by the Mask trait you just added isn’t disappearing? Or parts of the piece you set up to be rotatable aren’t rotating? Or parts that you set up not to rotate are rotating? Or maybe the Trigger Actions you are sending aren’t being resolved in the order you expected they would?

Well it turns out that the interactions between different traits within the same piece are substantially affected by the order those traits appear in the Game Piece’s trait list! This section will walk you through the relationships between traits, provide you with some basic "rules of thumb" for ordering your traits, and then end with a comprehensive trait ordering guide that should be a regular touchstone even when you’ve become a VASSAL master!

Draw Order and Traits

Most Traits which draw something are drawn starting from the Basic Piece and proceeding downwards, meaning that the last Layer (or Text Label, etc) in the list will be drawn overtop everything else. However there are two exceptions: Area of Effect traits, and any Layer with the Underneath when highlighted? option when the piece is currently selected. In both of these cases, the "exception" traits (Area-of-Effect or Draw-Underneath) are drawn before the Basic Piece. If more than one of these exceptions exists in a single piece, then the first to draw will be the lowest trait in the list, then the next lowest, etc — the opposite of the normal order, and all before the Basic Piece.

The chart at right illustrates the draw order for a sample set of piece traits. The two exception traits are drawn first (in bottom up order), followed by everything else (in top down order). Changing the order of the traits in this piece would change the order in which they were drawn. For example if the Text Label trait were moved up to the position directly underneath the Basic Piece, then it would be drawn right after the Basic Piece.

GamePieceDrawOrder

Traits That Control Other Traits

Some Traits, such as Can Rotate, Mask, and Restrict Commands are designed to directly control and affect other traits (without the use of Key Commands). These traits will only affect traits which appear above them in the list of traits after taking prototypes into account. Conversely each trait can only be affected/controlled/modified by traits which appear below them in the list of traits. You must think about each trait, how it affects the Game Piece, and whether it should affect, or be affected by other traits of the Game Piece. The chart at right provides some general guidance for an ordering that will frequently be the best, but it is not exhaustive — there will be special cases where you will want to deviate from it.

Example 1: if you want a Text Label to Rotate, then the Text Label trait must be above the Can Rotate trait. If you don’t want your Text Labels to rotate, then they must be below the Can Rotate trait.

Example 2: if you want the most of the visible information on your card or piece to be hidden from other players when the card is "flipped over" to its back side by a Mask trait, then all of its Layers (and any Text Labels, plus any traits that create Menu options and/or Key Commands that you don’t want to be available to other players while the card is hidden) need to be above the Mask trait. But if there’s some particular graphic Layer or Text Label that you want to be drawn even when the card is flipped over, then you’d put those traits below the Mask trait.

Example 3: Restrict Commands traits should almost always go at the very bottom of the list of traits, so that they will be able to hide/disable the traits that they specify.

GamePieceTraitOrder

Key Commands and Traits

When a Keystroke Command or a Named Command (Collectively known as Key Commands) is received by a Game Piece, the Traits are visited in a particular order to see if they listen for that Key Command, and if they do have an entry for that Key Command the appropriate part of the Trait activates. When a Key Command arrives at a Game Piece, its behaviour is identical regardless of the "origin" of that Key Command. The Key Command could have come from the player pressing a real keyboard shortcut, from the player selecting the corresponding right-click context menu command, from a Global Key Command arriving from a completely different Game Piece or from the Toolbar, from an Action Button, or from a Trigger Action trait within the piece.

The order Traits within the piece are visited is as follows:

  1. First any traits except for Trigger Action and Report Action traits are visited. This happens starting at the bottom of the list and proceeding up toward the Basic Piece trait.

  2. Then, once every trait that isn’t a Trigger Action or Report Action trait has been visited, we then visit those traits, this time starting at the top of the list just beneath the Basic Piece trait and proceeding towards the bottom.

GamePieceOrder

Advanced Trait Ordering

Traits

(in recommended order they should normally appear in a piece)

Ordering Notes

Basic Piece

(Basic Piece will always be at the top)

Layer (Rotatable)
Text Label (Rotatable)

Drawing Layers that will rotate should be above the Can Rotate and/or Can Pivot.

Can Rotate
Can Pivot
Mat Cargo

Can Rotate belongs below any drawing trait that it should rotate, but above any Can Pivot trait.

Mat Cargo similarly belongs below any drawing trait that it should cause to maintain relative facing.

Movement Trail
Layer
Mark When Moved
Text Label
Area of Effect

These drawing traits all belong above Non-Rectangular, and above Masking/Restricting Traits (see red box below). Optionally they could also move above Can Rotate if you want them to rotate/pivot; in this position they will not rotate or pivot. Traits will draw in order from the Basic Piece on down, meaning the very last drawing trait in the list will be "drawn on top of" everything else, and so forth.

Non-Rectangular

Non-Rectangular belongs below all drawable traits - otherwise their bounding box regions will be selectable even if transparent.

Delete
Replace With Other

These delete the piece & stop any further processing. Keep them above anything that needs doing first.

Note
Be aware that any Trigger Action on the same Key Command as a deleting trait will never get to execute — you will need to use a forking/chaining Trigger Action sequence to be sure any Trigger Action traits you need to have run before a deleting trait are executed.

Send to Location
Move Fixed Distance
Return to Deck
Place Marker
Clone

Movement and Piece-Placement traits normally belong above any Masking/Restricting traits (i.e. Mask, Invisible, Restrict Access, Restrict Commands).

Play Sound
Action Button
Global Hotkey
Global Key Command

"Communication" and Key Command initiating traits normally belong above Masking/Restricting traits (i.e. Mask, Invisible, Restrict Access, Restrict Commands).

Trigger Action

Trigger Action traits should normally be grouped above Report Action traits so that any changes to properties they trigger are resolved before the Report Action reports on them. (They should also normally appear above any Mask & Restrict Commands).

Report Action

Report Action traits should be grouped below Trigger Action traits (so that they report results after the Triggers process).

Set Global Property
Spreadsheet
Property Sheet
Dynamic Property

Property traits can have their values read faster (so that Vassal runs slightly faster) the lower they are in the trait list. However you’ll normally want the "setter" actions of e.g. Dynamic Properties and Set Global Property to remain above any Mask, Invisible, Restrict Access, and Restrict Commands traits that could affect them.

Mask
Invisible
Restrict Access
Restrict Commands

Masking/Restricting traits belong below any traits that they need to be able to hide, restrict, and protect.

Mask belongs above Invisible.

Does not stack

Does Not Stack functions correctly anywhere in the trait list but runs slightly faster near the bottom.

Calculated Property
Marker
Translatable Message
Mat

Calculated Property, Marker, Mat, and Translatable Message function properly anywhere, but they run slightly faster near the bottom.

Free Floating Traits

(Proper Order Varies)

Prototype

The proper location for a Prototype…​ depends on what’s in the Prototype! Note that you may sometimes decide that you need to split up large/complex Prototypes so that "the part that needs to go on top can go on top" and "the part that needs to go down below can go down below".

Sub-Menu
Menu Separator

Menu-building traits should go wherever you need them for building the right kinds of right-click context menus. Note, however, that Sub-Menu traits must always go below the traits that it should be grouping into a menu.


Comprehensive List of Piece Traits

Action Button

Area Of Effect

Basic Piece

Calculated Property

Can Pivot

Can Rotate

Clone

Delete

Does not stack

Dynamic Property

Global Hotkey

Global Key Command

Global Property, Set

Invisible

Layer

Mark When Moved

Marker

Mask

Mat

Mat Cargo

Menu Separator

Move fixed distance

Movement Trail

Non-Rectangular

Place Marker

Play Sound

Property Sheet

Prototype

Replace with Other

Report Action

Restrict Commands

Restricted Access

Send to Location

Spreadsheet

Sub-Menu

Text Label

Translatable Message

Trigger Action


Basic Piece

Every Game Piece contains a Basic Piece, which itself contains a name string and can also be assigned an image. For a truly simple piece this is all that is necessary. However for pieces that need more complex images or combinations of them, the image from the Basic Piece element can be omitted in favor of ones from e.g. Layer traits.

The Basic Piece exposes a list of Properties concerning name, location, and other common piece details. See the full Basic Piece article for details.

BasicPiece

Delete

Delete

The ability to be deleted by players during a game. When this trait’s Key Command or menu item is activated, the piece is deleted from the game.

Description: An optional description for you own use.

Command: Text for the right-click context menu item that will delete the piece. If left blank, no context menu item will appear, but the piece can still be deleted with the Key Command.

Key command: The Keystroke or Named Command that will cause the piece to be deleted.

Note
When this trait is activated the piece is deleted and therefore does not do any further processing on the Key Command. This can prevent Report Action traits from reporting the deletion, because of the order traits are processed. Such a situation can be worked around by using a Trigger Action trait to first send a Key Command to cause a Report Action and then send a second Key Command to process the delete.

Clone

The ability to be duplicated by players during a game. When this trait’s Key Command or menu item is activated, an exact copy of the piece is placed in the game at the same location.

Command: Text for the right-click context menu item that will clone the piece. If left blank, no context menu item will appear, but the piece can still be cloned with the Key Command.

Key command: The Keystroke or Named Command that will cause the piece to be duplicated.

Clone

Layer

A Layer is the most powerful way to add images to a piece. Each Layer you add can contain multiple images along with with Key Commands and/or Expressions to switch between them and activate/deactivate them. A piece can contain as many Layers as you wish. See full article for details.

Layer

Prototype

Inserts a pre-defined set of Traits defined in a Prototype Definition elsewhere. This allows you to define a set of Traits for a whole class of Pieces all in one place; likewise, by changing the Prototype later your changes will automatically apply to every piece which inherits the Prototype.

See Prototype (Trait) and Prototype (Definition) for further details.

UsePrototype

Label

Text Label

A text message drawn somewhere on or near the piece. Font sizes, colors, and position can be customized, and the text of the message can be created indirectly using the contents of Properties.

Report Action

Allows the piece to automatically report messages, state changes, and other game information to the chat log.

ReportChanges

TriggerAction

Trigger Action

Allows pieces to trigger Keystroke Commands and Named Commands. Triggers can be used to combine multiple commands into a single menu entry, place conditions on a command’s execution, create repeating loops, and more.

Global Hotkey

Allows pieces to activate a function from the Toolbar, via the Hotkey associated with the button on the Toolbar.

GlobalHotkey

ActionButton

Action Button

Allows a region of a piece to be configured to act like a button, invoking a command when a player clicks within the designated region.

Can Rotate

Gives a piece, or parts of it, the ability to rotate through a specified number of facings.

Rotate

Pivot

Can Pivot

Gives a piece, or parts of it, the ability to pivot, i.e. rotate around a point other than the center.

Invisible

Allows the piece to be hidden from opponents and other non-owning players, with a toggle to reveal it. Appears partially transparent to the owner while it is hidden, as a reminder.

The player sides who are allowed to hide the piece can be specified.

Hideable

Mask

Mask

Allows a piece to be flipped to a generic "reverse side" so that only limited information is shown to opponents and other non-owning players. The most common application is to give playing cards a generic "back side" which obscures the face of the card from players who aren’t currently entitled to see it.

The player sides who are allowed to flip the card or piece over can be specified.

Send to Location

Adds a command that moves a piece directly to another location.

SendToLocation

CounterGlobalKeyCommand

Global Key Command

Adds an action that applies a Keystroke Command or Named Command to other pieces, similar to the Global Key Command component of a Map Window. Global Key Commands are the main avenue by which pieces can prompt action by other pieces.

Move Fixed Distance

Adds a command to move a piece a fixed distance in a direction.

Translate

ReturnToDeck

Return to Deck

Adds a command to send a piece to a Deck.

Can be used to send cards to a discard pile, back to the draw pile, etc. Also useful with groups of chits or for fixed pools of counters.

Does Not Stack

Prevents the piece from combining with other pieces to form a stack, and can also be used to control whether the piece can be moved, selected, and/or band-selected by a player.

NonStacking

PropertySheet

Property Sheet

Provides a popup window from which players may set and view auxiliary information about a piece. Includes sophisticated controls for specifying single- and multi-line text notes and tick-mark boxes for depletable resources (hit points, shield levels, damage, etc.)

property sheet map

Spreadsheet

Attaches an editable informational table to a piece. Unlike a Property Sheet, it contains only plain-text fields, but can contain arbitrary numbers of rows and columns.

Spreadsheet

Marker

Place Marker

Adds a command to place another piece (of any type) at the same location as this piece. An optional additional command can then be applied to e.g. move the piece somewhere else.

Replace with Other

Adds a command that replaces this piece with a different piece.

Note
When this trait is activated the piece is deleted and therefore does not do any further processing on the Key Command. This can prevent Report Action traits from reporting the deletion, because of the order traits are processed. Such a situation can be worked around by using a Trigger Action trait to first send a Key Command to cause a Report Action and then send a second Key Command to process the delete.

Replace

NonRectangular

Non-Rectangular

Allows pieces with unconventional shapes to use their actual image boundaries for selection and dragging. In technical terms, directs the piece to ignore transparent areas of its image for purposes of selecting the piece with the mouse.

Play Sound

Adds a command that plays a specified sound when invoked.

PlaySound

MarkMoved

Mark When Moved

Allows the piece to be automatically marked with a visible image when moved in a Map Window.

Movement Trail

Pieces with this trait will leave behind a graphical trail showing the positions through which the piece has been moved.

MovementTrail

AreaOfEffect

Area Of Effect

The Area of Effect trait allows you to graphically highlight an area surrounding a gamepiece. The area is shaded with a specified color and transparency. Alternatively, you canpoint to a Map Shading component, contributing to the area that it draws.

Sub-Menu

Creates a sub-menu in the right-click context menu and groups some of the piece’s other commands into it.

SubMenu

MenuSeparator

Menu Separator

Creates a menu separator (horizontal bar) in the piece’s right-click context menu.

Restrict Commands

Hides or removes key/menu commands from the piece when certain conditions apply.

RestrictCommands

RestrictedAccess

Restricted Access

Limits control of a Piece by opponents and other non-owning players. Such players will not be able to access protected commands of the piece.

Marker

Assigns a fixed value to a named property on a piece. Analogous to creating a "constant" in programming.

PropertyMarker

DynamicProperty

Dynamic Property

Adds a named property to the piece, with a user-changeable value. Allows any number of commands to change and manipulate the value to be defined.

Calculated Property

Adds a named property to the piece, whose value is automatically calculated according to a specified formula.

CalculatedProperty

SetGlobalProperty

Set Global Property

Defines commands to change the value of a Global Property.

Mat / Mat Cargo

Allows designated smaller "cargo" pieces to be moved and optionally rotated along with a larger "mat" piece.

Mat2