VASSAL Reference Manual

Home > Concepts

Concepts

A brief overwiew of some of the main concepts you need to know to get started creating a VASSAL module.

Module

All the pieces that make up a Vassal implementation of a game are collected together into a single file called a Module, which typically have a .vmod suffix.

Physically, a Module is a ZIP archive containing the different files that go together to make up the Module.

You can inspect the files that make up a Module by opening it with any utility that can open ZIP Archives.

Note
 Some tools may require you to rename the module file from .vmod to .zip before you can open it. Just rename it back to .vmod when you have finished.

A Module contains various files and folders:

  • The buildfile.xml is an XML file that links all the parts of your module together and includes all the definitions of the different Components and Pieces that make up your module.
    The buildfile is normally maintained for you by the VASSAL Module Editor, but you can manually edit and update the buildfile if you know what you are doing. Make a backup first!!!

  • The moduledata file holds the summary information about your module that is displayed in the Module Manager.

  • The images folder holds all the image files used in your module.

  • HTML files shown in Chart Windows.

  • Pre-defined Setup files used to start games.

Extension

An Extension is a fragment of a Module that can be used to add additional functionality to an existing Module without modifying that Module directly.

A typical use for an Extension is to add additional scenarios to a module and some additional units that are needed to play those scenarios.

Components and Pieces

A VASSAL Module is made up of two fundamentally different types of elements that are defined and manipulated in two different ways.

Components Pieces

Mobility

Fixed elements making up the structure of the module.

Mobile element that can move about on Map components.

Duplication

Only one of each Component exists in a game.

There can be multiple instances of each Piece in a game.

Activation

Activated by Hotkeys, ignore Key Commands.

Activated by Key Commands, ignore Hotkeys.

Toolbar Buttons

Many Components can be activated by buttons that reside on the main Vassal toolbar.

Pieces are never associated with a Toolbar button.

Flexibility

Limited to in-built configuration and flexibility provided by core VASSAL.

Highly configurable and extensible by module designer.

Components

VASSAL Components consist of the structural pieces that are used to implement a game. Some key Components used in nearly every module are:

  • Maps that combine one or more boards into a playing surface that Pieces can be placed on.

  • Boards that implement an individual map or part of map

  • Zones identify individual subsections of a Board.

  • Charts allow the display of reference materials.

  • Game Piece Palettes where Pieces can be defined.

  • Dice Buttons to roll and report on Die rolls.

Pieces

Pieces are used to implement the individual units, counters and other display pieces that make up a game.

Pieces are constructed from more than 40 different 'trait’s, each of which adds or modififies the behaviour of a piece. The number, order and configuration of the different traits within a piece control how it looks and acts in a VASSAL game.

Some important traits used in many pieces are:

See the Game Piece for full details of all available traits.

Stacking and Game Piece Layers

By default, Pieces that are placed in the same Location in a Map will form a group called a Stack.

Stacks

A Stack is a set of Pieces in the same location and Game Piece Layer.

Pieces in a Stack are slightly offset from each other to give a visual cue that there are multiple pieces tacked together in that location.

Clicking on a Stack selects all Pieces in the Stack and the whole Stack can be moved as one unit. Double-clicking on a Stack expands it with a greated visual offset to show more of the counters in the Stack. Individual counters in the Stack can be selected and acted on.

The size of the visual offset for expanded and unexpanded Stacks is configurable in the Stacking Options Component of a Map.

At-Start Stacks

At-Start Stacks are a special kind of Stack that are defined as part of a Map. The Pieces on the Map are defined as part of the Map, not in a Game Piece Palette like ordinary Pieces.

Whenever a new game is started that uses that Map, a new Stack of those pieces is automatically created. Once the Pieces in an At-Start Stack have been moved away, the At-Start Stack no longer exists.

Decks

Decks are a special version of an At-Start Stack that have an independent existence, regardless of whether they contain any Pieces or not.

Decks act like a Deck of card, to hold and potentially hide the identity of Pieces (in the case of a face-down Deck.)

Hotkeys and Key Commands

KeyCommand

Hotkeys and Key Commands represent a Keystroke that Vassal components and Piece traits 'listen' out for and perform actions when they see one that they are interested in. They allow one VASSAL Component or Piece to activate a completely different Component or Piece.

Hotkeys and Key Commands can be defined as an actual Keystroke that can be pressed on a keyboard, or can be defined as a 'virtual' Named Keystroke. Named Keystrokes can only be generated by VASSAL Components and Piece traits. See the Keystroke Commands, Named Commands, Key Commands and Hotkeys page for more information.

Hotkeys and Key Commands look very similar when you define them, but they have two different uses.

Hotkeys

Hotkeys are recognized by VASSAL Components and are completely ignored by Pieces.

Whenever a Hotkey is generated, it is sent to ALL VASSAL Components in no particular order.

Hotkeys are generated in one of two ways:

  1. By the user pressing a key or key combination while a VASSAL Map or Chart component has the focus (Not if the Chat Windows is currenly in focus).

  2. By the Action Button Component, which can initiate a sequence of Hotkeys.

  3. By the Global Hotkey Piece trait.

Key Commands

Key Commands are completely ignored by VASSAL Components.

Whenever Key Commands are generated, they are always sent to a specific set of Pieces. The Key Commands are sent to every trait within the selected set of pieces, that can then react to them if they are configured to do so.

Key Commands are generated in the following ways:

  1. By right-clicking on a Piece and selecting a Menu Command. The Key Command associated with tha Menu Command will be sent to the piece that is being right-clicked.

  2. By activating a Trigger Action trait that can issue a sequence of Key Commands to the Piece that contains it.

  3. By activating any Global Key Command Component or Piece trait to send a Key Command to a specific group of Pieces selected by the conditions specified in the Global Key Command.

Global Key Commands

Global Key Commands (commonly referred to as GKC’s) are a group of very commonly used components that select a group of pieces and send a Key Command to all the selected pieces. From Vassal version 3.7, any GKC can also be used to set Dynamic Properties in the selected pieces.

There are 5 different kinds of GKCs:

  • Counter GKCs are a piece trait that can be included in any Piece definition. They are initiated by a Menu Command or Key Command on the piece and can affect any piece in the current game.

  • Module GKCs are defined in the top level Module component and are initiated by an associated Toolbar button and can affect any piece in the current game.

  • Map GKCs are defined in a Map and are initiated by an associated Toolbar button and can affect any piece on the Map they are defined on.

  • Deck GKCs are defined in a Deck and are initiated by a right-click menu item on the Deck, and can affect any piece in the Deck.

  • Startup GKCs are defined in the top level Module component and are initiated when a new game is started or loaded and can affect any piece in the current game.

Many of the features of GKC’s are shared between the different types and detailed usage of GKCs is detailed here.

Values in VASSAL

Al values used in VASSAL are stored as strings of characters. A number like 42 is actually stored as "42". True and False values are stored as "true" and "false".

When needed, Vassal will convert to and from numbers and true/false values, for example when adding numbers, or checking of a condition is true. You generally do not need to worry about this, but it is good to understand what is happening under the hood.

In general all Components and Piece Traits that use numbers, require whole numbers (Integers).

Decimal numbers (e.g. 1.5) can be used and stored if you are experienced enough to know the limitations.

Properties

Properties are named values provided by VASSAL, by Components and by Pieces that can be referenced and used in other Components and Pieces.

The values of Properties can change over time and represent the current state of the different Pieces and Components in the current game and of VASSAL itself.

See the Properties Page for a comprehensive list of the Properties available in VASSAL.

Many of the properties have values that are controlled by VASSAL, but the following two types are Properties defined by the Module Designer.

Global Properties

Global Properties are user-defined properties that can have their value changed by user actions during Play. Global Properties can be created at the Module level, the Map level or the Zone Level and follow the visibility rules outlined in the previous section.

Global Properties can have their value changed by

Piece Properties

Piece Properties are user defined properties that exist within a specific Piece and can have their value changed by user actions during play.

Dynamic Properties can have their value changed by

Property Visiblility

Properties exist at one of four levels:

  1. Module level properties

  2. Map level properties

  3. Zone level properties

  4. Piece properties

The Properties Page lists which level each Property is defined at.

When a Property value is needed, VASSAL starts searching at the level appropriate to the Component or Piece that needs the valie and searches upwards to find a value for the Property. If a Property of the same name exists on more than one level, then only the lowest level will be seen.

Module level components (such as Dice Buttons or Global Key Commands defined at the Module level) can only 'see' Module level properties.

Map level components (such as the Map Report Formats or the Line of Sight thread) can only 'see' the Map level properties defined on their own Map, plus Module level properties.

There are no Zone level components.

Pieces can only 'see' the Zone level properties in their current Zone, the Map level properties on their current Map and all Module level properties.

These visibility rules can be overridden using the GetProperty BeanShell functions.

Uniquely Identifying Pieces

In more advanced modules, there is a need to be able to identify particular pieces to perform automated operations on them.

Module designers can classify groups of pieces using Markers, applied via Prototypes. Pieces can also be identified by their BasicName property, but this will not be unique if multiple pieces have been created from the same definition.

Vassal provides the following properties available on Game Pieces to assist with identifying pieces in advanced modules:

Property Description

PieceId

The PieceId property uniquely defines the definition that created this piece. All pieces created from the same definition (Piece Definition in a Game Piece Palette, At-Start Stack or Deck, or a Piece Definition in a Place Marker or Replace trait) will have the same PieceId value.

PieceUID

The PieceUID property uniquely defines a piece. Each piece in a particular game is guaranteed to have a unique PieceUID and this is carried forward in Save games UNTIL the next time the game is manually refreshed by the Game Refresher, when a new PieceUID will be allocated. It will nearly always be better to use the UniqueID property rather than PieceUID.

UniqueID

The UniqueID property uniquely defines a piece. Each piece in a particular game is guaranteed to have a unique UniqueID and this is carried forward in Save games AND is maintained when a Game is refreshed via the Game Refresher. The UniqueID of a piece takes and keeps the value of the PieceUID that is first assigned to the piece.

ParentID

The ParentID property only exists in pieces that have been created with the Replace trait and contains the UniqueID of the Game Piece that created piece.

CloneID

The CloneID only exists in pieces that have been duplicated with the Clone trait and contains the UniqueID of the Game Piece that initial piece that performed the first Clone (which also has CloneID set).

If a new version of a Cloned piece is pulled from a Piece Paletter and Cloned, it and the new clones will have a different CloneID from any earlier clones.

Expressions

Old-Style Expressions

BeanShell Expressions

Property Match Expressions

Passing values to pieces

The Set Piece Property trait allows one piece to set a specific Dynamic Property in a selection of other pieces.

The Place Marker and Replace With Other traits and all varieties of Global Key Commands also have the ability to set the value of mulitple Dynamic Properties in the pieces they affect as well as perform their main purpose.

Values can also be shared between pieces by storing them in Global Properties that are accessible to all the pieces involved.

See the Passing values to pieces page for details on how to use these features.