Package VASSAL.build.module

Class BasicCommandEncoder

java.lang.Object
VASSAL.build.module.BasicCommandEncoder
All Implemented Interfaces:
Buildable, CommandEncoder
Direct Known Subclasses:
BshCommandEncoder
public class BasicCommandEncoder extends Object implements CommandEncoder, Buildable
Although it is the CommandEncoder which handles the basic commands: AddPiece, RemovePiece, ChangePiece, MovePiece, this class is most commonly needed by module designers who want to make custom "Traits" for game pieces because it contains createDecorator(java.lang.String, VASSAL.counters.GamePiece), the BasicCommandEncoder.DecoratorFactory for Traits, which are usually internally referred to as Decorators because they are implemented using the Decorator Pattern. If a module is to add its own custom game pieces, it will need to override the createDecorator(java.lang.String, VASSAL.counters.GamePiece) method, and use this pattern to create any custom Traits: 
   package MyCustomClasses; // Your package name here
   public class MyCustomCommandEncoder extends BasicCommandEncoder {
     public Decorator createDecorator(String type, GamePiece inner) {
       if (type.startsWith(MyCustomClass.ID)) {
         return new MyCustomClass(type, inner);
       }
       //... more custom traits, possibly

       // Now allow BasicCommandEncoder to run so that "normal" Traits process
       return super.createDecorator(type, inner);
     }
   }
Then in the buildFile (XML) for the module, the VASSAL.build.module.BasicCommandEncoder entry is replaced with an entry for (in the example above): MyCustomClasses.MyCustomCommandEncoder The class files are placed in a MyCustomClasses (package name) folder in the Zip structure of the VMOD file, and At that point the new trait can be imported into a piece as MyCustomClasses.MyCustomClass (package name followed by class name). Less often, the createBasic(java.lang.String) or createPiece(java.lang.String) methods could be overridden to allow instantiation of custom GamePiece classes.

  • Field Details

  • Constructor Details

    • BasicCommandEncoder

      public BasicCommandEncoder()

  • Method Details

    • createDecorator

      public Decorator createDecorator​(String type, GamePiece inner)
      Creates a Decorator instance - a GamePiece "Trait". Modules which wish to provide their own custom classes should subclass BasicCommandEncoder and override this class. The override should check for and parse any definitions that match desired custom Traits(Decorators), and then use super to call this method for any unmatched definitions. Further documentation on creating custom traits appears in BasicCommandEncoder's own javadoc entry, or alternatively at the top of BasicCommandEncoder.java.
      Parameters:
      type - the type of the Decorator ("Trait") to be created. Once created, the Decorator should return this value from its Decorator.myGetType() method.
      inner - the inner trait/piece of the Decorator (the "innermost" member of a game piece will be a BasicPiece; each successive Trait in the trait list presented in a piece's PieceDefiner dialog represents a sep "outward").

    • createBasic

      protected GamePiece createBasic​(String type)
      Create a GamePiece instance that is not a Decorator ("Trait"). In other words a BasicPiece, a Stack, or a Deck.
      Parameters:
      type - the type of the GamePiece. The created piece should return this value from its GamePiece.getType() method.

    • createPiece

      public GamePiece createPiece​(String type)
      Creates a GamePiece instance from the given type information. Determines from the type whether the represented piece is a Decorator ("Trait") or not and forwards to createDecorator(java.lang.String, VASSAL.counters.GamePiece) or createBasic(java.lang.String). This method should generally not need to be overridden. Instead, override createDecorator(java.lang.String, VASSAL.counters.GamePiece) or createBasic(java.lang.String)
      Parameters:
      type - definition string of the piece or trait to be created.

    • build

      public void build​(Element e)
      Build a BasicCommandEncoder from the XML buildFile. See Builder
      Specified by:
      build in interface Buildable
      Parameters:
      e - the XML element containing the object data

    • addTo

      public void addTo​(Buildable parent)
      Adds this BasicCommandEncoder to its parent, which should be the GameModule.
      Specified by:
      addTo in interface Buildable
      Parameters:
      parent - the GameModule

    • add

      public void add​(Buildable b)
      Adds a buildable subcomponent. BasicCommandEncoder doesn't normally have subcomponents, so this is empty.
      Specified by:
      add in interface Buildable
      Parameters:
      b - the buildable subcomponent

    • getBuildElement

      public Element getBuildElement​(Document doc)
      Specified by:
      getBuildElement in interface Buildable
      Parameters:
      doc - An XML document
      Returns:
      an XML element from which this component can be built

    • decode

      public Command decode​(String command)
      Deserializes a string into a Basic Piece command (Add, Remove, Change, Move, and... Play Audio Clip!), readying it for execution.
      Specified by:
      decode in interface CommandEncoder
      Parameters:
      command - string form of the command
      Returns:
      Command object for command.
      See Also:
      CommandEncoder

    • encode

      public String encode​(Command c)
      Serializes a Basic Piece command (Add, Remove, Change, Move, and ... Play Audio Clip!) into a String, readying it for transmission to other clients.
      Specified by:
      encode in interface CommandEncoder
      Parameters:
      c - Command to be serialized
      Returns:
      String form of the command
      See Also:
      CommandEncoder