Class BasicPiece

java.lang.Object
VASSAL.search.AbstractImageFinder
VASSAL.counters.BasicPiece
All Implemented Interfaces:
PropertyNameSource, PropertySource, EditablePiece, GamePiece, PropertyExporter, StateMergeable, TranslatablePiece, PersistentPropertyContainer, Auditable, ImageSearchTarget
public class BasicPiece extends AbstractImageFinder implements TranslatablePiece, StateMergeable, PropertyNameSource, PersistentPropertyContainer, PropertyExporter
Basic class for representing a physical component of the game. Can be e.g. a counter, a card, or an overlay. Note like traits, BasicPiece implements GamePiece (via TranslatablePiece), but UNLIKE traits it is NOT a Decorator, and thus must be treated specially.

  • Field Details

  • Constructor Details

    • BasicPiece

      public BasicPiece()

    • BasicPiece

      public BasicPiece(String type)
      creates a BasicPiece by passing complete type information
      Parameters:
      type - serialized type information (data about the piece which does not change during the course of a game) ready to be processed by a SequenceEncoder.Decoder

  • Method Details

    • mySetType

      public void mySetType(String type)
      Sets the type information for this piece. See Decorator.myGetType()
      Specified by:
      mySetType in interface EditablePiece
      Parameters:
      type - a serialized configuration string to set the "type information" of this piece, which is information that doesn't change during the course of a single game (e.g. Image Files, Context Menu strings, etc). Typically ready to be processed e.g. by SequenceEncoder.decode()

    • getType

      public String getType()
      Specified by:
      getType in interface GamePiece
      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:

    • setMap

      public void setMap(Map map)
      Specified by:
      setMap in interface GamePiece
      Parameters:
      map - Each GamePiece belongs to a single Map

    • getMap

      public Map getMap()
      Specified by:
      getMap in interface GamePiece
      Returns:
      Each GamePiece belongs to a single Map

    • getProperty

      public 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. A request to getProperty() that reaches the BasicPiece will have already checked for such a property key being available from any outer Decorator/Trait in the stack. Upon reaching BasicPiece, the search hierarchy for a matching property now becomes: (1) Specific named properties supported by BasicPiece. These include BASIC_NAME, PIECE_NAME, LOCATION_NAME, CURRENT_MAP, CURRENT_BOARD, CURRENT_ZONE, CURRENT_X, CURRENT_Y. (2) "Scratchpad" properties - see setProperty(java.lang.Object, java.lang.Object) for full details, but these are highly temporary properties intended to remain valid only during the execution of a single key command. (3) Persistent properties - see setPersistentProperty(java.lang.Object, java.lang.Object) for full details, but they are stored in the piece and "game state robust" - saved during save/load, and propagated to other players' clients in a multiplayer game. (4) The values of any visible "Global Property" in a Vassal module, checking the Zone level first, then the map level, and finally the module level.

      Thus, 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.
      Specified by:
      getProperty in interface GamePiece
      Specified by:
      getProperty in interface PropertySource
      Parameters:
      key - String key of property to be returned
      Returns:
      Object containing new value of the specified property

    • getPublicProperty

      public Object getPublicProperty(Object key)
      Properties (see getProperty(java.lang.Object)) visible in a masked (see Obscurable) piece, even when the piece is masked.
      Parameters:
      key - String key of property to be returned.

    • getLocalizedProperty

      public Object getLocalizedProperty(Object key)
      Returns the localized text for a specified property if a translation is available, otherwise the non-localized version. Searches the same hierarchy of properties as getProperty(java.lang.Object).
      Specified by:
      getLocalizedProperty in interface PropertySource
      Parameters:
      key - String key of property to be returned
      Returns:
      localized text of property, if available, otherwise non-localized value

    • getLocalizedPublicProperty

      public Object getLocalizedPublicProperty(Object key)
      Returns the localized text for a specified property if a translation is available, otherwise the non-localized version, but in both cases accounting for the unit's visibility (i.e. Mask/Obscurable Traits). Searches the same hierarchy of properties as getProperty(java.lang.Object).
      Parameters:
      key - String key of property to be returned
      Returns:
      Returns localized text of property, if available, otherwise non-localized value, accounting for Mask status.

    • setProperty

      public 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. A setProperty() call which reaches BasicPiece will already have passed through all of the outer Decorator/Traits on the way in without finding one able to match the property.

      NOTE: Properties outside the piece 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. This method ALSO does not set persistent properties (they can only be set by an explicit call to setPersistentProperty(java.lang.Object, java.lang.Object)).

      BasicPiece does, however contain a "scratchpad" for temporary properties, and for any call to this method that does not match a known property (which is, currently, ANY call which reaches this method here in BasicPiece), a scratchpad property will be set. Scratchpad properties are NOT saved when the game is saved, and NO arrangement is made to pass their values to other players' machines. Thus they should only be used internally for highly temporary values during the execution of a single key command. Their one other use is to store the piece's Unique ID -- and although this value is obviously used over periods of time much longer than a single key command, this is possible because the value is immutable and is refreshed to the same value whenever the piece is re-created e.g. when loading a save.
      Specified by:
      setProperty in interface GamePiece
      Parameters:
      key - String key of property to be changed
      val - Object containing new value of the property

    • setPersistentProperty

      public Command setPersistentProperty(Object key, Object newValue)
      Setting a persistent property writes a property value into the piece (creating a new entry in the piece's persistent property table if the specified key does not yet exist in it). Persistent properties are game-state-robust: they are saved/restored with saved games, and are passed via Command to other players' clients in a multiplayer game. The persistent property value can then be read from the piece via e.g. getProperty(java.lang.Object). When reading back properties out of a piece, the piece's built-in properties are checked first, then scratchpad properties (see setProperty(java.lang.Object, java.lang.Object)), then external properties such as Global Properties. If only persistentProperties are to be searched, use getPersistentProperty(java.lang.Object) instead.

      In practical terms, setPersistentProperty is used mainly to implement the "Old" properties of BasicPiece (e.g. "OldLocationName", "OldZone", "OldMap", "OldBoard", "OldX", "OldY"). A Persistent Property is indeed nearly identical with DynamicProperty in storage/retrieval characteristics, and simply lacks the in-module interface for setting values, etc. Module Designers are thus recommended to stick with Dynamic Property traits for these functions.
      Specified by:
      setPersistentProperty in interface PersistentPropertyContainer
      Parameters:
      key - String key naming the persistent property to be set. If a corresponding persistent property does not exist it will be created.
      newValue - New value for the persistent property
      Returns:
      a Command object which, when passed to another player's client via logfile, server, or saved game, will allow the result of the "set" operation to be replicated.

    • getPersistentProperty

      public Object getPersistentProperty(Object key)
      Specified by:
      getPersistentProperty in interface PersistentPropertyContainer
      Parameters:
      key - String key naming the persistent property whose value is to be returned.
      Returns:
      the current value of a persistent property, or null if it doesn't exist.

    • prefsValue

      protected Object prefsValue(String s)
      Parameters:
      s - Name of a module preference to be read
      Returns:
      Value of the preference

    • draw

      public void draw(Graphics g, int x, int y, Component obs, double zoom)
      Draws the BasicPiece's image, if it has been set
      Specified by:
      draw in interface 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.

    • getKeyCommands

      protected KeyCommand[] getKeyCommands()
      Returns:
      the set of key commands that will populate the a BasicPiece's right-click menu. This will normally be an empty array in the present age of the world, but the ability to contain a clone and delete command is retained for compatibility with Modules Of Ancient Times. In the case of BasicPiece, this method also keeps track of whether move up/down/to-top/to-bottom commands are enabled. This method is chained from "outer" Decorator components of a larger logical game piece, in the process of generating the complete list of key commands to build the right-click menu -- this process is originated by calling getKeyCommands() on the piece's outermost Decorator/Trait.

    • getPosition

      public Point getPosition()
      Specified by:
      getPosition in interface GamePiece
      Returns:
      piece's position on its map.

    • setPosition

      public void setPosition(Point p)
      Specified by:
      setPosition in interface GamePiece
      Parameters:
      p - Sets the location of this piece on its Map

    • getParent

      public Stack getParent()
      Specified by:
      getParent in interface GamePiece
      Returns:
      the parent Stack of which this piece is a member, or null if not a member of any Stack

    • setParent

      public void setParent(Stack s)
      Specified by:
      setParent in interface GamePiece
      Parameters:
      s - sets the Stack to which this piece belongs.

    • boundingBox

      public Rectangle boundingBox()
      Specified by:
      boundingBox in interface GamePiece
      Returns:
      bounding box rectangle for BasicPiece's image, if an image has been specified.

    • getShape

      public Shape getShape()
      Specified by:
      getShape in interface GamePiece
      Returns:
      the Shape of this piece, for purposes of selecting it by clicking on it with the mouse. In the case of BasicPiece, this is equivalent to the boundingBox of the BasicPiece image, if one exists. Note that the shape should be defined in reference to the piece's location, which is ordinarily the center of the basic image.

      For pieces that need a non-rectangular click volume, add a NonRectangular trait.

    • equals

      public boolean equals(GamePiece c)
      Parameters:
      c - GamePiece to check if equal to this one
      Returns:
      Equality check with specified game piece

    • getRealName

      public String getRealName()
      Returns:
      the name of this BasicPiece. This is the name typed by the module designer in the configuration box for the BasicPiece.

    • getName

      public String getName()
      Description copied from interface: GamePiece
      The plain English name for this piece
      Specified by:
      getName in interface GamePiece
      Returns:
      the name of this GamePiece. It queries the BasicName property from the outermost piece inward, allowing a "Basic Name" trait to possibly override ours when the Piece Name is being queried.

    • getRealLocalizedName

      public String getRealLocalizedName()
      Returns:
      the localized name of this BasicPiece. This is the translated version of the name typed by the module designer in the configuration box for the BasicPiece. It is used to fill the "BasicName" property if the search for it makes it all the way to this innermost piece.

    • getLocalizedName

      public String getLocalizedName()
      Description copied from interface: GamePiece
      And the translated name for this piece
      Specified by:
      getLocalizedName in interface GamePiece
      Returns:
      the localized name of this GamePiece. It queries the BasicName property from the outermost piece inward, allowing a "Basic Name" trait to possibly override ours when the Piece Name is being queried.

    • keyEvent

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

      In the case of BasicPiece, if a key command gets here, that means it has already been seen by any and all of its Traits (Decorators), as BasicPiece is the innermost member of the Decorator stack. The key events processed here by BasicPiece include the "move up"/"move down"/"move-to-top"/"move-to-bottom" stack-adjustment commands, along with legacy support for cloning and deleting.
      Specified by:
      keyEvent in interface GamePiece
      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:

    • getState

      public String getState()
      Specified by:
      getState in interface GamePiece
      Returns:
      The "state information" is 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.

      In the case of BasicPiece, the state information includes the current map, x/y position, the unique Game Piece ID, and the keys and values of any persistent properties (see setPersistentProperty(java.lang.Object, java.lang.Object))

    • setState

      public void setState(String s)
      Specified by:
      setState in interface GamePiece
      Parameters:
      s - New state information serialized in string form, ready to be passed to a SequenceEncoder#decode. The "state information" is 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.

      In the case of BasicPiece, the state information includes the current map, x/y position, the unique Game Piece ID, and the keys and values of any persistent properties (see setPersistentProperty(java.lang.Object, java.lang.Object))

    • mergeState

      public void mergeState(String newState, String oldState)
      For BasicPiece, the "merge" of a new state simply involves copying in the new one in its entirety -- if any difference is detected.
      Specified by:
      mergeState in interface StateMergeable
      Parameters:
      newState - new serialized game state string
      oldState - old serialized game state string

    • getId

      public String getId()
      Each GamePiece must have a unique String identifier. These are managed by VASSAL internally and should never be changed by custom code.
      Specified by:
      getId in interface GamePiece
      Returns:
      unique ID for this piece
      See Also:

    • setId

      public void setId(String id)
      Each GamePiece must have a unique String identifier. These are managed by VASSAL internally and should never be changed by custom code.
      Specified by:
      setId in interface GamePiece
      Parameters:
      id - sets unique ID for this piece
      See Also:

    • getHighlighter

      public static Highlighter getHighlighter()
      Returns:
      the Highlighter instance for drawing selected pieces. Note that since this is a static method, all pieces in a module will always use the same Highlighter

    • setHighlighter

      public static void setHighlighter(Highlighter h)
      Parameters:
      h - Set the Highlighter for all pieces

    • getDescription

      public String getDescription()
      Description copied from interface: EditablePiece
      A plain-English description of this type of trait/piece - includes data from fields where appropriate
      Specified by:
      getDescription in interface EditablePiece
      Returns:
      Description of what this kind of piece is. Appears in PieceDefiner list of traits.

    • getBaseDescription

      public String getBaseDescription()
      Description copied from interface: EditablePiece
      Support for a basic-name-only description introduced later, so this default retrofits it from the full description if an explicit one is not defined.
      Specified by:
      getBaseDescription in interface EditablePiece
      Returns:
      Description of what this kind of piece is. Appears in PieceDefiner list of traits.

    • getGpId

      public String getGpId()
      Returns:
      the unique gamepiece ID for this piece, as stored in the Property "scratchpad"

    • setGpId

      public void setGpId(String id)
      Parameters:
      id - stores the unique gamepiece ID for this piece into the Property "scratchpad"

    • getHelpFile

      public HelpFile getHelpFile()
      Specified by:
      getHelpFile in interface EditablePiece
      Returns:
      the help file page for this type of piece.

    • getEditor

      public PieceEditor getEditor()
      Specified by:
      getEditor in interface EditablePiece
      Returns:
      The configurer (PieceEditor for the BasicPiece, which generates the dialog for editing the BasicPiece's type information in the Editor window.

    • testEquals

      public boolean testEquals(Object o)
      Test if this BasicPiece's Type and State are equal to another This method is intended to be used by Unit Tests to verify that a trait is unchanged after going through a process such as serialization/deserialization.
      Parameters:
      o - Object to compare this Decorator to
      Returns:
      true if the Class, type and state all match

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      String enumeration of type and state information.

    • getI18nData

      public PieceI18nData getI18nData()
      Description copied from interface: TranslatablePiece
      Return a PieceI18nData object returning the I18n data about this GamePiece.
      Specified by:
      getI18nData in interface TranslatablePiece
      Returns:
      Object encapsulating the internationalization data for the BasicPiece

    • getPropertyNames

      public List<String> getPropertyNames()
      Specified by:
      getPropertyNames in interface PropertyNameSource
      Returns:
      Property names exposed by the Trait or Piece. In the case of BasicPiece, there are quite a few, mainly dealing with past and present location.

    • addLocalImageNames

      public void addLocalImageNames(Collection<String> s)
      See AbstractImageFinder Adds our image (if any) to the list of images
      Specified by:
      addLocalImageNames in interface ImageSearchTarget
      Overrides:
      addLocalImageNames in class AbstractImageFinder
      Parameters:
      s - Collection to add image names to