GamePiece

From VASSAL
Jump to: navigation, search

VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece


Game Piece

GamePiece.png
A Game 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.   A list of available traits appears to the left, and a list of traits 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 pushing the 'Add' button.   Remove a trait by selecting it and pushing 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 popup menu to test it as you go.

Once added to your piece, a trait's properties can be edited by selecting the trait and pushing the 'Properties' button, or by double-clicking on the trait.

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

For highly specialized pieces, you may supply your own 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).  Then hit the "Import" button and enter the fully-qualified name of the class.  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 Order

The order of traits is significant. Each trait is only affected by traits that are below it in the expanded list of traits after taking prototypes into account.

For example, if you want Text Labels to Rotate, then the Text Label trait must be above the Rotation trait. If you don't want your Text Labels to rotate, then they must be below the Rotation trait. You need to think about each trait, how it affects the counter, and whether it should affect, or be affected by, other traits that affect the counter.


Keystrokes and Traits

When a keystroke enters a piece, the traits are visited in a particular order to see if they're interested in that keystroke, and if they are interested, they execute.

When a keystroke enters a piece, the behaviour is identical irrespective of the origin of that keystroke. The keystroke could have come from the player, from a global key command, from an action button, or from a trigger within the piece.

The order traits are visited is as follows.

  • First all non-triggers are visited. This happens starting at the bottom of the list going up.
  • After all the non-triggers are visited, then all triggers are visited, starting at the top of the list of triggers going downwards.

Piece Traits

Basic Piece

A simple piece drawn from an image.

Delete

The ability to be deleted by players during a game.   Specify the name of the corresponding menu item and the keyboard shortcut.

Delete.png


Clone

The ability to be duplicated by players during a game.   Specify the name of the corresponding menu item and the keyboard shortcut.

Clone.png

Layer

A sequence of images with key commands to loop through them.

Prototype

Insert a pre-defined set of traits defined in a prototype elsewhere.

Label

A plain text label drawn somewhere on the piece.

Invisible

The ability to be hidden to non-owning players.

Mask

The ability to show only limited information to non-owning players.

Send to Location

Defines a command to automatically send a piece to a pre-defined location.

Global Key Command

Applies a command to to other pieces.

Move Fixed Distance

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

Return to Deck

Defines a command to automatically send a piece to a Deck.

Does Not Stack

Prevents the piece from combining with other pieces in a stack.

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

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.

Place Marker

Defines a keyboard command that places another piece on top of this piece.

Replace with Other

Defines a keyboard command that replaces this piece with a different piece.

Can Rotate

Defines ability to rotate through a specified number of facings.

Can Pivot

Defines ability to pivot a piece, i.e. rotate around a point other than the center.

Non-Rectangular

Directs a piece to ignore image transparency for purposes of selecting a piece with the mouse.

Play Sound

Adds a command that plays a specified sound when invoked.

Mark When Moved

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

Movement Trail

Draws the recent movement path of the piece as a trail of points.

Area Of Effect

Highlights a specified radius around a piece.

Sub-Menu

Creates a sub-menu in the right-click drop-down menu.

Restrict Commands

Hides or removes keyboard/menu commands when certain conditions apply.

Restricted Access

Limit control of a piece from non-owning players.

Report Action

Allows the piece to automatically report state changes to the chat text area.

Trigger Action

Allows you to trigger keyboard actions with other keyboard actions, combining multiple keystrokes into a single menu entry.

Global Hotkey

Allows you to trigger toolbar  actions, via the hotkey associated with the button in the toolbar.

Action Button

Allows you to specify a region of a piece that acts like a button, invoking an action when a player clicks within the region with the mouse.

Marker

Assigns a fixed value to a named property on a piece.

Dynamic Property

Assigns a user-changeable value to a named property on a piece.

Set Global Property

Defines commands to change the value of a Global Property.