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.
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. |
|
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. |
|
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:
|
|
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) |
Drawing Layers that will rotate should be above the Can Rotate and/or Can Pivot. |
||
Can Rotate |
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 |
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 |
These delete the piece & stop any further processing. Keep them above anything that needs doing first.
|
||
Send to Location |
Movement and Piece-Placement traits normally belong above any Masking/Restricting traits (i.e. Mask, Invisible, Restrict Access, Restrict Commands). |
||
Play Sound |
"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 |
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 |
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 |
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-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. |
List of Piece Traits
| Trait | Description |
|---|---|
Create a clickable button on a piece that issues a Key Command when clicked. |
|
Display a shaded area around a piece. |
|
Create groups of 'Attached' counters that can easily interact with each other. |
|
Specify a primary name for a piece that over-rides the Basic Piece name. |
|
Set the Base name and image for a piece. |
|
Specify a colored border around a piece that will appear under specified conditions. |
|
Create a named Property whose value is calculated by a formula. |
|
Allows a piece to be rotated around an off-center position. |
|
Allows a piece to be rotated around its center. |
|
Creates a duplicate of a piece. |
|
Creates a comment line in the Piece Definer display. |
|
Deletes the piece from the current game. |
|
Provides options to limit stacking, selection and movement of a piece. |
|
Remove a piece, or all pieces, from the current piece selection. |
|
Create a named Property that can be changed. |
|
Issue a Hotkey to activate game Components. |
|
Issue a Key Command to activate multiple pieces. |
|
Hide a piece from other players by making it invisible. |
|
Add additional images to a piece that can be turned on and off. |
|
Automatically highlight a piece whenever it moves. |
|
Add a named Property with a fixed value. |
|
Hide the identity of a piece from other players. |
|
Create a piece that can carry other pieces around on it. |
|
Create a pieces that can be carried on a Mat. |
|
Add a separator to the drop-down menu that is generated when you right-click on a piece. |
|
Move a piece a set distance on aMap from its starting point. |
|
Show a visible history of piece movements. |
|
Generate multiple menu commands based on Map Zone or Region names. |
|
Specifiy a non-rectangular shape for a piece that will be used as the selection border. |
|
Place a newly created piece. |
|
Play a sound. |
|
Maintain a set of independent values for a piece. |
|
Include traits from a pre-defined template piece. |
|
Replace a piece with a new, different piece. |
|
Display a message in the Chat Window when a Key Command is seen. |
|
Dynamically restrict traits from being activated by right-click menu commands or from other traits or Global Key Commands. |
|
Restrict access to a piece to specified users. |
|
Send a piece to another location. |
|
Set a value in a Global property. |
|
Set a value in a Dynamic Property in selected pieces. |
|
Maintain a spreadsheet of values in a piece. |
|
Organise right-click Menu Commands into a sub-menu. |
|
Display text on a piece. |
|
Specify a text message that can be translated and displayed in the players' local language. |
|
Specify a sequence of Key Commands that can be issued in order. |