Package VASSAL.counters

Interface GamePiece

All Superinterfaces:

Auditable, PropertySource

All Known Subinterfaces:

EditablePiece, TranslatablePiece

All Known Implementing Classes:

ActionButton, AreaOfEffect, Attachment, BasicName, BasicPiece, BorderOutline, CalculatedProperty, Clone, Comment, CounterGlobalKeyCommand, Deck, Decorator, Delete, Deselect, DynamicProperty, Embellishment, Embellishment0, Footprint, FreeRotator, GlobalHotKey, Hideable, Immobilized, Labeler, Marker, Mat, MatCargo, MenuSeparator, MovementMarkable, MultiLocationCommand, NonRectangular, Obscurable, Pivot, PlaceMarker, PlaySound, PropertySheet, Replace, ReportState, RestrictCommands, Restricted, ReturnToDeck, SendToLocation, SetGlobalProperty, SetPieceProperty, Stack, SubMenu, TableInfo, TranslatableMessage, Translate, TriggerAction, UsePrototype

public interface GamePiece
extends PropertySource

Interface to deal with the behaviors of a physical component of the game, or a Trait of one. Although from the name you might think that anything implementing this would be "a whole piece" (and perhaps in Elder Times that was true), a GamePiece is in fact implemented NOT ONLY by all of the three "basic" piece types: BasicPiece, Stack, or Deck; BUT ALSO it is implemented by all of the Traits (Decorator classes) that form the subcomponents of a full "piece" as we would know it on the game board.

When a GamePiece method of a Trait (Decorator) is called, the Trait first attempts to service the method call, and then normally (though not always, as in the case of "draw" calls to pieces with Invisible/Hideable or Mask/Obscurable traits) calls the same method for the next trait inward from it in the Decorator stack for the overall piece, and so on in turn until the "innermost" piece (normally a BasicPiece) has its method called.
Methods:
getType() - gets type information fixed throughout game
getState() - gets state information changeable during gameplay
setState(java.lang.String) - sets state information changeable during gameplay
setProperty(java.lang.Object, java.lang.Object) - sets other properties, *possibly* game-related, about a piece.
getProperty(java.lang.Object) - gets other properties, *possibly* game-related, about a piece.

draw(java.awt.Graphics, int, int, java.awt.Component, double) - tells this piece or part-of-piece to draw itself
keyEvent(javax.swing.KeyStroke) - gives this piece or Trait a chance to process key events. This is the main way for a GamePiece to receive "events".

getName() - the plain English name of the piece
getLocalizedName() - the localized name of the piece
getMap() and setMap(VASSAL.build.module.Map) - Each GamePiece belongs to a single Map
getPosition() and setPosition(java.awt.Point) - position on the map
getParent() and setParent(VASSAL.counters.Stack) - deals with membership in a Stack
boundingBox() - bounding box
getShape() - shape
getId() and setId(java.lang.String) - each piece has a unique ID

See Also:
extends PropertySource
extended by EditablePiece, TranslatablePiece

Method Summary

Modifier and Type	Method	Description
Rectangle	boundingBox()
default Command	checkTrueMoved()
void	draw(Graphics g, int x, int y, Component obs, double zoom)	Draw this GamePiece
default Command	finishMove(Command c, boolean afterburner, boolean findmat)
default Command	finishMove(Command c, boolean afterburner, boolean findmat, boolean markMoved)
String	getId()	Each GamePiece must have a unique String identifier
String	getLocalizedName()	And the translated name for this piece
Map	getMap()
String	getName()	The plain English name for this piece
Stack	getParent()
Point	getPosition()
Object	getProperty(Object key)	Properties can be associated with a piece -- many may be game-specific, but others are standard, such as the LocationName property exposed by BasicPiece -- and can be read through this interface.
Shape	getShape()
String	getState()
String	getType()
Command	keyEvent(KeyStroke stroke)	The primary way for the piece or trait to receive events.
default Command	prepareMove(Command c, boolean mark_moved)
void	setId(String id)	Each GamePiece must have a unique String identifier
void	setMap(Map map)
void	setParent(Stack s)
void	setPosition(Point p)
void	setProperty(Object key, Object val)	Properties can be associated with a piece -- many may be game-specific, but others are standard, such as the LocationName property exposed by BasicPiece -- and can be set through this interface.
void	setState(String newState)

Methods inherited from interface VASSAL.script.expression.Auditable

getComponentName, getComponentTypeName

Methods inherited from interface VASSAL.build.module.properties.PropertySource

getLocalizedProperty

Method Details

setMap

void setMap(Map map)

Parameters:

map - Each GamePiece belongs to a single Map

getMap

Map getMap()

Returns:

Each GamePiece belongs to a single Map

draw

void draw(Graphics g,
 int x,
 int y,
 Component obs,
 double zoom)

Draw this GamePiece

Parameters:

g - target Graphics object

x - x-location of the center of the piece

y - y-location of the center of the piece

obs - the Component on which this piece is being drawn

zoom - the scaling factor.

getPosition

Point getPosition()

Returns:

the location of this piece on its owning Map

setPosition

void setPosition(Point p)

Parameters:

p - Sets the location of this piece on its Map

boundingBox

Rectangle boundingBox()

Returns:

The area which this GamePiece occupies when drawn at the point (0,0)

getShape

Shape getShape()

Returns:

The shape of the piece from the user's viewpoint. This defines the area in which the user must click to select or move the piece, for example. Like boundingBox(), it assumes the position is (0,0) -- which to be clear is normally aligned with the CENTER of the piece image -- and must be translated to the actual location where the piece is being drawn. For most ordinary pieces, the shape returned here will simply be equivalent to the bounding box, but see NonRectangular.

getParent

Stack getParent()

Returns:

the Stack to which this piece belongs, or null if it doesn't belong to a stack.

setParent

void setParent(Stack s)

Parameters:

s - sets the Stack to which this piece belongs.

keyEvent

Command keyEvent(KeyStroke stroke)

The primary way for the piece or trait to receive events. KeyStroke events are forward to this method if they are received while the piece is selected (or as the result of e.g. a Global Key Command being sent to the piece). The class implementing GamePiece can respond in any way it likes. Actual key presses by the player, selected items from the right-click Context Menu, keystrokes "applied on move" by a Map that the piece has just moved on, and Global Key Commands all send KeyStrokes (and NamedKeyStrokes) which are passed to pieces and traits through this interface.

Returns:

a Command that, when executed, will make all changes to the game state (maps, pieces, other pieces, etc) to duplicate what the piece did in response to this event on another machine. Often a ChangePiece command, but for example if this keystroke caused the piece/trait to decide to fire off a Global Key Command, then the Command returned would include the entire results of that, appended as subcommands.

See Also:

• ForwardToKeyBuffer

getName

String getName()

The plain English name for this piece

getLocalizedName

String getLocalizedName()

And the translated name for this piece

getId

String getId()

Each GamePiece must have a unique String identifier

Returns:

unique ID for this piece

See Also:

• GameState.getNewPieceId()

setId

void setId(String id)

Each GamePiece must have a unique String identifier

Parameters:

id - sets unique ID for this piece

See Also:

• GameState.getNewPieceId()

getType

String getType()

Returns:

The "type information" of a piece or trait is information that does not change during the course of a game. Image file names, context menu strings, etc., all should be reflected in the type. The type information is returned serialized string form, ready to be decoded by a SequenceEncoder#decode.

See Also:

• BasicCommandEncoder

getState

String getState()

Returns:

The "state information" is game state information that can change during the course of a game. State information is saved when the game is saved and is transferred between players on the server. For example, the relative order of pieces in a stack is state information, but whether the stack is expanded is not.

setState

void setState(String newState)

Parameters:

newState - New state information serialized in string form, ready to be passed to a SequenceEncoder#decode. The "state information" is game state information that can change during the course of a game. State information is saved when the game is saved and is transferred between players on the server. For example, the relative order of pieces in a stack is state information, but whether the stack is expanded is not.

setProperty

void setProperty(Object key,
 Object val)

Properties can be associated with a piece -- many may be game-specific, but others are standard, such as the LocationName property exposed by BasicPiece -- and can be set through this interface. The properties may or may not need to be encoded in the piece's getState() method. Properties include the value of e.g. Marker Traits, DynamicProperty Traits, and so forth.

NOTE: Properties outside the piece, however, CANNOT be set by this method (e.g. Global Properties), even though they can be read by getProperty(java.lang.Object) -- in this the two methods are not perfect mirrors.

Parameters:

key - String key of property to be changed

val - Object containing new value of the property

getProperty

Object getProperty(Object key)

Properties can be associated with a piece -- many may be game-specific, but others are standard, such as the LocationName property exposed by BasicPiece -- and can be read through this interface. The properties may or may not need to be encoded in the piece's getState() method. Properties include the value of e.g. Marker Traits, DynamicProperty Traits, and so forth. Furthermore they include the values of any visible "Global Property" in a Vassal module, whether at the module level, map level, or zone level -- but these "higher level" properties, coming from "outside the piece", CANNOT be written to by the setProperty(java.lang.Object, java.lang.Object) method even though they can be read by this method -- in this sense the two methods are NOT perfect mirrors.

When using this interface a piece's own properties are preferred to those of "Global Properties", and those in turn are searched Zone-first then Map, then Module. This method implements the PropertySource interface, which allows Global Properties to be read by other types of object than GamePieces.

Specified by:

getProperty in interface PropertySource

Parameters:

key - String key of property to be returned

Returns:

Object containing new value of the specified property

prepareMove

default Command prepareMove(Command c,
 boolean mark_moved)

checkTrueMoved

default Command checkTrueMoved()

finishMove

default Command finishMove(Command c,
 boolean afterburner,
 boolean findmat)

finishMove

default Command finishMove(Command c,
 boolean afterburner,
 boolean findmat,
 boolean markMoved)