Package VASSAL.counters

Interface GamePiece

All Superinterfaces:
PropertySource
All Known Subinterfaces:
EditablePiece, TranslatablePiece
All Known Implementing Classes:
ActionButton, AreaOfEffect, BasicPiece, CalculatedProperty, Clone, CounterGlobalKeyCommand, Deck, Decorator, Delete, Deselect, DynamicProperty, Embellishment, Embellishment0, Footprint, FreeRotator, GlobalHotKey, Hideable, Immobilized, Labeler, Marker, MenuSeparator, MovementMarkable, NonRectangular, Obscurable, Pivot, PlaceMarker, PlaySound, PropertySheet, Replace, ReportState, RestrictCommands, Restricted, ReturnToDeck, SendToLocation, SetGlobalProperty, 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 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