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.

While editing a Piece, a number of keyboard shortcuts are available, including Alt+Right to jump to the list of your Piece’s current traits, Alt+Left to jump to the list of available traits, and Space as a substitute for double-clicking a Trait in either list. Typing a character in either list will jump to the next entry that starts with the typed character.

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:

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

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

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.