VASSAL Reference ManualHome > Module > Game Piece Palette > 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. |
![]() |
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
Traits That Control Other Traits
Key Commands and Traits
|
Basic PieceEvery 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. |
![]() |
![]() |
DeleteThe 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.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. Keyboard Command: The Key Command or Named Key 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. |
CloneThe 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. Keyboard Command: The Key Command or Named Key Command that will cause the piece to be duplicated. |
![]() |
![]() |
|
PrototypeInserts 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. |
![]() |
![]() |
Text LabelA 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.See full article for details. |
Report ActionAllows the piece to automatically report messages, state changes, and other game information to the chat log.See full article for details. |
![]() |
![]() |
Trigger ActionAllows pieces to trigger Key Commands and Named Key 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.See full article for details. |
Global HotkeyAllows pieces to activate a function from the Toolbar, via
the Hotkey associated with the button on the Toolbar.See full article for details. |
![]() |
![]() |
Action ButtonAllows a region of a piece to be configured to act like a
button, invoking a command when a player clicks within the designated region.See full article for details. |
Can RotateGives a piece, or parts of it, the ability to rotate through a specified number of facings.See full article for details. |
![]() |
![]() |
Can PivotGives a piece, or parts of it, the ability to pivot, i.e. rotate around a point other than the center.See full article for details. |
InvisibleAllows 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. See full article for details. |
![]() |
![]() |
MaskAllows 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. See full article for details. |
Send to LocationAdds a command that moves a piece directly to another location.See full article for details. |
![]() |
![]() |
Global Key CommandAdds an action that applies a Key Command or Named Key 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.See full article for details. |
Move Fixed DistanceAdds a command to move a piece a fixed distance in a
direction.See full article for details. |
![]() |
![]() |
Return to DeckAdds 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. See full article for details. |
Does Not StackPrevents 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.See full article for details. |
![]() |
![]() |
Property SheetProvides 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.)See full article for details. ![]() |
SpreadsheetAttaches 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.See full article for details. |
![]() |
![]() |
Place MarkerAdds 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.See full article for details. |
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. See full article for details. |
![]() |
![]() |
Non-RectangularAllows 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.See full article for details. |
Play Sound
Adds a command that plays a specified sound when invoked.See full article for details. |
![]() |
![]() |
Mark When MovedAllows the piece to be automatically marked with a visible image when moved in a Map Window.See full article for details. |
Movement Trail
Pieces with this trait will leave behind a graphical trail showing the positions through which the piece has been moved.See full article for details. |
![]() |
![]() |
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.See full article for details. |
Sub-MenuCreates a sub-menu in the right-click context menu and groups some of the piece's other commands into it.See full article for details. |
![]() |
![]() |
Menu SeparatorCreates a menu separator (horizontal bar) in the piece's right-click context menu.See full article for details. |
Restrict CommandsHides or removes key/menu commands from the piece when certain conditions apply.See full article for details. |
![]() |
![]() |
Restricted AccessLimits control of a Piece by opponents and other non-owning players. Such players will not be able to access protected commands of the piece.See full article for details. |
Marker
Assigns a fixed value to a named property on a piece. Analogous to creating a "constant" in programming.See full article for details. |
![]() |