VASSAL Reference Manual

121
VASSAL Reference Manual Home > Module > Game Piece Palette > Game Piece > Area of Effect Area of Effect Trait The 'Area of Effect' trait allows you to graphically highlight an area surrounding a game piece. The area is shaded with a specified color and transparency. Alternatively, you can point to a Map Shading component, contributing to the area that it draws. Use Map Shading: If selected, then the area of this trait will be added to the area drawn by the named Map Shading component (or subtracted from that area if it is of type Background). If not selected, then each piece with this trait will draw its own area, with overlapping areas shaded darker. Fill Color: The color of the area. Opacity: The opacity of the area. 100% is completely opaque. 0% is completely invisible. Radius: Distance, in local grid units, from the game piece that will be highlighted. If the piece is on a board with a Rectangular Grid or Hex Grid , this distince is in grid units and the shaded area will conform to the grid. Otherwise, it will be a circle with the given radius in pixels. Always Visible:If selected, the area is always highlighted when the piece is drawn on a Map. Area of Effect property window.

Transcript of VASSAL Reference Manual

Page 1: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Area of Effect

Area of Effect Trait 

The 'Area of Effect' trait allows you to graphically highlight an area surrounding a game piece.  The area is shaded with a specified color and transparency.  Alternatively, you can point to a  Map Shading component, contributing to the area that it draws.

Use Map Shading: If selected, then the area of this trait will be added to the area drawn by the named Map Shading component (or subtracted from that area if it is of type Background). If not selected, then each piece with this trait will draw its own area, with overlapping areas shaded darker.Fill Color: The color of the area.Opacity: The opacity of the area. 100% is completely opaque. 0% is completely invisible.Radius: Distance, in local grid units, from the game piece that will be highlighted. If the piece is on a board with a Rectangular Grid or Hex Grid, this distince is in grid units and the shaded area will conform to the grid. Otherwise, it will be a circle with the given radius in pixels.Always Visible:If selected, the area is always highlighted when the piece is drawn on a Map.Toggle Visible Command:If not always visible, this is the right-click menu command to show/hide the highlighted area.Toggle Visible keyboard shortcut:If not always visible, the keyboard shortcut to show/hide the highlighted area..

Area of Effect property window.

Page 2: VASSAL Reference Manual

Area of Effect applied to a Flat Top cloud counter. (Gray, 20%, 2)

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Basic Piece

Basic Piece

Page 3: VASSAL Reference Manual

The simplest game piece consists of an image and a name. Select the image by double-clicking on the box to the left, or select an image that has already been added from the drop-down menu.

The following Properties are defined in a Basic Piece:

BasicName returns the name of Basic Piece trait, as specified in the properties PieceName returns the full name of the piece, including all traits PlayerSide returns the side of the current player, as specified in the Definition of Player Sides LocationName returns the name of the current location, as determined by the local grid CurrentMap returns the name of the current Map Window CurrentBoard returns the name of the current Board CurrentZone returns the name of the current Zone Selected returns true when the piece has been selected with the mouse

(added 6 Feb 2007 by Brent Easton) An update to the BasicPiece Properties documentation page -

BasicPiece currently supports the following properties not yet reflected in the documentation:

DeckName - Name of the current deck the piece resides in, or "" if not in a Deck. CurrentX - current X co-ord of piece CurrentY - current Y co-ord of piece OldLocationName - Location name prior to last drag n drop move OldX - X co-ord prior to last drag n drop move OldY - Y co-ord prior to last drag n drop move OldMap - Map name prior to last drag n drop move OldBoard - Board name prior to last drag n drop move OldZone - Zone name prior to last drag n drop move

Page 4: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Map > Board

Board

A Board represents the physical board on which pieces are moved by the players. A Map Window can consist of multiple Boards laid out next to one another.

If a board image is specified (a GIF file that must be created beforehand with some external tool), then the size of the image determines the size of the board. If the board image is set to null (by hitting the "Select" button and then canceling the file dialog), then no image is used for the board, and the size and color may be specified directly.

Sub-Components

Hex Grid

Rectangular Grid

Irregular Grid

Page 5: VASSAL Reference Manual

Multi-zoned Grid

If a Board contains no grid, then pieces may be placed anywhere on the board. Pieces dropped on top of one another will stack. If it does contain a grid, then a piece will snap to the nearest legal location on the board as defined by the grid. The grid may be drawn over the board's GIF image or drawing may be suppressed (it the GIF already has a grid drawn on it).

VASSAL Reference ManualHome > Module > Charts

Charts

A window for holding game-play aids: charts, tables, etc. Adds a button to the toolbar of the main controls window. Pushing the button shows the window with the given name. The text of the button, an icon, and a keyboard shortcut may be specified.

Sub-Components

Chart

Each chart is a GIF/JPG/PNG image that you must create beforehand with an external program. You specify the image file and the name of the chart.

HTML Chart

Page 6: VASSAL Reference Manual

Charts can be specified using HTML as well, so long as the HTML is not too complex. Avoid using the <head> tag, for instance. HTML Charts can contain hyperlinks to one another, but not to external resources. You can reference any image that exists in the module file. For example, if inf.png is an image used in one of the Game Piece definitions, you can reference it using <img src="inf.png">. Note that because images stick around in a module file even after the components using them have been deleted, you can add images as a regular Chart, delete the Chart, and still use its image in an HtmlChart.

Tabbed Pane

A panel with tabs, each of which corresponds to a Chart, Panel, or other Tab panel subcomponent. The label of the tab will be the name of the subcomponent.

Panel

A panel that can contain Charts, Tab panels, or other panels. The "Fixed cell size" box allows you to specify a fixed number of columns that the panel will have. Otherwise, the subcomponents will appear in a single row, or a single column if the "Vertical layout box is checked.

VASSAL Reference ManualHome > Module > Map > Deck

Page 7: VASSAL Reference Manual

Deck

A Deck functions like a deck of playing cards. Each game begins with the contents of the Deck as specified in the Configuration window. During a game, players may remove cards from the deck by clicking on the deck and dragging the mouse. This removes the card from the Deck and assigns ownership to the dragging player. Dragging a card onto the deck adds it back to the Deck.

Page 8: VASSAL Reference Manual

In previous versions, a Deck was used for fixed pools of standard counters as well. The At-Start Stack component is now recommended for this use.

Name: The name of a Deck is not used during game play. It is just used for identification in the module editor.

Belongs to board: If a name is selected, the Deck will appear on that particular Board. If a game does not use that Board, then the Deck will not appear. If "<any>" is selected, then the Deck will always appear at the given position, regardless of the boards in use.

X,Y position: The position in the Map Window of the center of the deck. If this Deck belongs to a Board, the position is relative to the Board's position in the Map Window.

Width, Height: The size of the "tray" holding the cards. If the Deck is empty, this determines the area into which players may drag cards to add them back to the Deck. It should be set to the same size as the cards the Deck will hold

Allow Multiple Cards to be Drawn: Adds a right-click menu entry that prompts the user to specify the number of cards to be drawn from the deck with the next drag.

Allow Specific Cards to be Drawn: Adds a right-click menu entry that prompts the user to examine the deck and select exactly which cards will be drawn from the deck with the next drag.

Contents are Face-down: Determines whether cards in the deck are always face-down, always face-up, or can be switched from face-up to face-down with a right-click menu entry.

Face Down Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Face Down" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.

Draw new cards face up: If checked, then cards drawn from this deck will be placed face-up on the playing area. If un-checked, then cards in a face-down deck are drawn face down and owned by the drawing player.

Re-shuffle: If set to "Never" then cards remain in their original order; cards are drawn from and added to the top. If set to "Always" then cards are always drawn randomly from the deck. If set to "Via right-click menu" then a "Shuffle" entry is added to the Deck's right-click menu.

Re-shuffle Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Shuffle" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.

Page 9: VASSAL Reference Manual

Reversible: Adds an entry to the right-click menu that reverses the order of cards in the deck.

Reverse Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "Reverse" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.

Draw Outline When Empty: Whether to draw the "tray" for the cards. The "tray" is a rectancle of size width,height centered at x,y. Only drawn when there are no cards in the deck, to indicate where to drag cards to place them back in the Deck. May not be necessary if the Map Window contains a board onto which the tray is already drawn.

Color: The color of the rectangle representing the "tray" above.

Include command to send entire deck to another deck: If checked, the popup menu for this deck will include a command that sends every piece in this deck to a designated deck. For example, this can be used to reshuffle a discard pile into its original deck. The following three attributes all refer to this option.

Menu Text: The text that appears in the popup menu.

Report Format: A Message Format that is echoed to the chat text window whenever a player selects the "send to another deck" menu item (if enabled above): deckName is the name of this deck, commandName is the name of the menu item.

Name of deck to send to: The name of the deck that the contents will be sent to.

EXAMPLE: An ordinary deck of playing cards for, say, Crazy Eights would be set to: Allow Multiple = false, Allow Specific = false, Face Down = Always, Re-shuffle = Always, Reversible = false. The discard pile would be: Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false.

A Deck may contain any kind of Game Piece, so it can also be used for draw piles of chits or counters that are drawn randomly and whose total number are limited by the game. If the counters do not need to be selected randomly, use an At-Start Stack. EXAMPLE: A strategic game in which a nationality has a fixed force pool of variable-strength Infantry, Armor, etc. counters can be modeled by making a Map Window representing the force pool, with a Deck of Infantry counters, a Deck of Armor counters, etc. The decks would be set to Allow Multiple = false, Allow Specific = false, Face Down = Never, Re-shuffle = Never, Reversible = false. In order to guarantee that the number of each type of counter is fixed, the Clone and Delete functions of the Infantry and Armor counters should be disabled.

Page 10: VASSAL Reference Manual

Sub-Components

Card

A Card is identical to a GamePiece, but is initialized with a Mask trait appropriate for a playing card.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Dynamic Property

Dynamic Property

This trait attaches a Property to a Game Piece and allows you to define commands to change the value of the property during play.

Page 11: VASSAL Reference Manual

Name The name of the property.Value The value of the property at the start of a new game.Is Numeric If true, then changes to the value of the property will be restricted to integer values.Minimum Value Numeric values will be restricted to no less than this number.Maximum Value Numeric values will be restricted to no more than this number.Wrap Around If true, then when incrementing this numeric property, values will wrap around from the maximum to the minimum.Key Commands Adds any number of commands to the right-click drop-down menu for this Game Piece. Hit the New button to add a new command and the Remove button to remove one. For each command, specify the text of the drop-down menu entry and the keyboard shortcut. The type defines how the property value should change: Set value directly sets the property to a fixed value, after substituting values of other Properties defined for this Game Piece. Increment numeric value adds a fixed value to the property, after substituting values of Properties. Prompt user pops up a dialog for the user to type in a new value. Prompt user to select from list pops up a dialog with a drop-down menu for the user to select from.

VASSAL Reference ManualHome > Module Extension

Module Extension

A Module Extension defines optional additional components to a Module. Each extension is defined in its own file separate from the main Module file. When playing, an extension is automatically loaded when its file is placed in the proper folder. However, when editing, only the extension being edited is loaded. In order to create a new extension or load an existing one for further editing, fist click "Load Module" in the "Extensions" section of the VASSAL startscreen. Select and open your .mod file. For editing an existing extension file, click "Edit" in the "Extensions" section of the VASSAL startscreen and select and open your extension .mdx file. For creating an extension click "New" instead and save your work with a .mdx file ending.

Editing a Module Extension is done exactly like editing a Module, by adding and modifying components in the Configuration Window. The only difference is that you cannot delete or modify components of the main Module while editing an extension. Any components in an extension will always be added after those in the main Module. See the User's Guide "Installation" page on loading extension files for play.

VASSAL Reference Manual

Page 12: VASSAL Reference Manual

Home > Module

Module

The Module is the top component in the Configuration Window. Its properties are simply the name of the game and a version number.

Sub-Components

Help Menu

Every module has a Help menu in the main controls window. Only one Help menu is allowed, and it may not be removed.

Definition of Player Sides

In general, it is not necessary to define player sides for a module. If you define no sides, then all windows and all game pieces are visible and accessible to all players.

If you wish to create components that are available only to one side in a game (e.g. a Private Window), you must define the player sides here. Simply type a name for each side and refer to that name in the restricted component

Only one player may be assigned to a side. When joining a game, players will be prompted to take one of the remaining available sides. Any number of observers (players who belong to no side) are allowed. The "Retire" button, in the main controls toolbar, allows a player to relinquish his side (making it available to the next player joining the game). You can specify the text, icon, and mouse-

Page 13: VASSAL Reference Manual

over tooltip for the toolbar button.

Global Options

These are options that apply to the module as a whole. Each option may be be enabled "Always," "Never," or "Use Preferences Setting" in which case an entry will be added to the Preferences window to allow players to choose their own setting.

Allow non-owners to un-mask pieces: By default, only the player who originally masked a piece (see the Mask trait for Game Pieces) is allowed to unmask it. This option allows other player to unmask a masked piece

Center on opponent's moves: This option will center a map window in an opponent's move when reading a logfile or receiving a move on the server.

Auto-report moves: This option will automatically report a text description (e.g. "3rd Cav moves A10 ->B11") to the chat area of the control window whenever a player moves a piece in a Map Window.

Player Id format: A Message Format that is used to identify players when typing chat text. It is available for use as a short-cut other message formats such as move auto-reporting.

Icons and hotkeys: You can specify your own button icons and keyboard shortcuts for the logfile step/undo buttons and the button that shows/hides the server controls.

Map Window

By default, every module has one Map Window, although it may be removed and others added.

Page 14: VASSAL Reference Manual

Game Piece Palette

By default, every module has one Game Piece Palette, although it may be removed and others added.

Game Piece Prototypes Definitions

Allows you to define sets of commonly-used traits for Game Pieces.

Global Properties

Allows you to define default values for Properties

Toolbar Menu

Groups buttons in the toolbar into a single drop-down menu.

Game Piece Image Definitions

Allows you to define re-usable layouts for building custom images to use in Game Pieces.

Global Key Command

A button that applies a given command to many pieces at once. Applies to all Map Windows simultaneously.

Dice Button

Page 15: VASSAL Reference Manual

A button to generate random numbers in the text area of the main control window. You may add any number of buttons. Each button will roll a certain number of dice with a certain number of sides and report the result in the chat window. The name is the text accompanying the resulting roll in the chat window. You may specify text for the button and supply an image file to use as an icon. You may also define a hotkey that acts as a keyboard shortcut for pressing the button. Check the "Report Total" box to report the sum of all dice (e.g. 3-18 for 3x6-sided dice). If the box is unchecked, the dice will be reported individually (e.g. as "2,6,3"). If the Prompt for values box is checked, then players will be asked to select the number of sides/dice every time they press the dice button during a game.

The Report Format specifies the Message Format for reporting the results: name is the name of the button as specified above, result is the result of the roll.

Internet Dice Button

An Internet Dice Button functions just the same as a regular Dice Button, except that it uses a third-party automated dice roller from the internet to perform the rolls instead of Java's built-in random number generator. The results of each roll may optionally be sent to one or more email addresses, which may be specified in the preferences.

The put multiple rolls into single email option will prompt the player to combine multiple dice rolls into a single email. The player may supply detail text for each roll, which is inserted into the Report Format in place of the rollDetails variable.

Page 16: VASSAL Reference Manual

Random Text Button

A Random Text Button can be used to randomly select a text message from a list defined beforehand. For example, a button can be defined to select a random letter "A" "B" "C" or "D". Enter each test message into the box to the left of the "Add" button and hit the "Add" button. It can also be used to define dice with irregular numerical values, such as a six-sided die with values 2,3,3,4,4,5. If the values are numerical check the "Faces have numeric values" box, which enables the "report total" and "add to each die" options.

Symbolic Dice Button

Rolls dice whose faces are represented by graphical images.

Pre-defined setup

Replaces the "New Game" menu item in the File menu of the controls window with a new menu item that loads a saved game that you specify in advance.

Name: Text of the menu item.Contains sub-menus: Instead of specifying a saved game, you can check this box to add a sub-menu with the given name to the File menu. Then you can add more Pre-defined setups to this one to create entries in the sub-menu.Use pre-defined file: If left unchecked, this menu entry will start a new game from scratch, like the normal "New Game" action.

Page 17: VASSAL Reference Manual

Saved Game: Select a saved game from your local disk. This game will be loaded when the menu item is selected. If the file does not exist, then the menu item behaves like the normal "New Game" item.

Example: Add a Pre-defined setup named "Play Scenario" to the module and check contains sub-menus. Then add another set of Pre-defined setups named 1939, 1940, 1941, 1942 to the first and select a saved game file for each one. Players may now select File->Play Scenario->1939 to load the 1939 scenario, etc.

Charts

Adds a window that can contain gameplay-related charts and tables for player reference.

Private Window

A map window that can be seen only by the owning player.

Notes Window

A window for saving text notes along with a game. A "Notes" button will be added to the toolbar of the main controls window, enabled when a game is started. Pushing the button displays the window. The "Public"tab contains notes that are visible to all players, and to which all players may add. The "Private" tab contains notes that are visible only to the player who entered them. The "Delayed" tab is for writing messages to be revealed at a later time as a safeguard against cheating. To create a delayed message, hit the "New" button and enter a name and message text. Once created, the text of a message cannot be changed. At the appropriate time, the owning player may reveal the text of the message, at which point other players may read the contents of the message.

Page 19: VASSAL Reference Manual

A Game Piece is any counter, marker, or card used in a game. Game pieces in VASSAL are highly customizable and can have quite complex behavior. They are defined by adding 'traits' to a basic piece. A list of available traits appears to the left, and a list of traits in use by the piece you're defining appears at the right. Add a trait by selecting it in the list of available traits and pushing the 'Add' button. Remove a trait by selecting it and pushing the 'Remove' button.

As you define your piece, it will appear at the top of the window. You can select the piece and type commands for it or right-click to bring up its popup menu to test it as you go.

Once added to your piece, a trait's properties can be edited by selecting the trait and pushing the 'Properties' button, or by double-clicking on the trait.

When a piece is drawn, the traits are drawn in order, beginning with the basic piece and continuing downward. The order of traits can be important. For example the image in a Layer trait may obscure the Basic Piece or other Layers beneath it.

Page 20: VASSAL Reference Manual

For highly specialized pieces, you may supply your own Java classes. The Java class must implement the GamePiece interface and most commonly extends the Decorator class. First, add the Java .class file to the module file using a Zip utility (remember to preserve the package structure). Then hit the "Import" button and enter the fully-qualified name of the class. The trait corresponding to your class will appear in the list of available traits and you may add it normally. See the Coding Tutorial for more details.

Piece Traits

Basic Piece

A simple piece drawn from an image.

Delete

The ability to be deleted by players during a game. Specify the name of the corresponding menu item and the keyboard shortcut.

Clone

The ability to be duplicated by players during a game. Specify the name of the corresponding menu item and the keyboard shortcut.

Layer

Page 21: VASSAL Reference Manual

A sequence of images with key commands to loop through them

Prototype

Insert a pre-defined set of traits defined in a prototype elsewhere.

Label

A plain text label drawn somewhere on the piece.

Invisible

The ability to be hidden to non-owning players.

Mask

The ability to show only limited information to non-owning players.

Send to Location

Defines a command to automatically send a piece to a pre-defined location.

Global Key Command

Applies a command to to other pieces.

Move Fixed Distance

Defines a command to move a piece a fixed distance in a direction

Return to Deck

Defines a command to automatically send a piece to a Deck.

Page 22: VASSAL Reference Manual

Does Not Stack

Prevents the piece from combining with other pieces in a stack.

Property Sheet

Provides a popup window from which players may set and view auxillary information about a piece. Includes sophisticated controls for specifying single- and multi-line text notes and tick-mark boxes for depletable resources (hit points, shield levels, damage, etc.)

Spreadsheet

Attaches an editable informational table to a piece. Unlike a Property Sheet, it contains only plain-text fields, but can contain arbitrary numbers of rows and columns.

Place Marker

Defines a keyboard command that places another piece on top of this piece.

Replace with Other

Defines a keyboard command that replaces this piece with a different piece.

Can Rotate

Defines ability to rotate through a specified number of facings.

Can Pivot

Defines ability to pivot a piece, i.e. rotate around a point other than the center.

Non-Rectangular

Directs a piece to ignore image transparency for purposes of selecting a piece with the mouse.

Page 23: VASSAL Reference Manual

Mark When Moved

Allows the piece to be automatically marked when moved in a Map Window.

Movement Trail

Draws the recent movement path of the piece as a trail of points.

Area Of Effect

Highlights a specified radius around a piece.

Sub-Menu

Creates a sub-menu in the right-click drop-down menu.

Restricted Access

Limit control of a piece from non-owning players.

Report Action

Allows the piece to automatically report state changes to the chat text area.

Trigger Action

Allows you to trigger keyboard actions with other keyboard actions, combining multiple keystrokes into a single menu entry.

Marker

Assigns a fixed value to a named property on a piece.

Page 24: VASSAL Reference Manual

Dynamic Property

Assigns a user-changeable value to a named property on a piece.

VASSAL Reference ManualHome > Module > Game Piece Image Definitions > Game Piece Layout > Game Piece Image

Game Piece Image

This component is an actual image using the layout corresponding to the Game Piece Layout component which contains this component. Here, you specify the colors, text, and images to use in the layout, as well as the name under which this image will appear in the image-chooser drop-down.

Name: Specify a name for the image definition. This is the name under which this image will appear in the image-chooser drop-down menu in a Game Piece trait's properties.Background Color: Select a background color for the image from the drop down list of available colors.

The next section shows a visualization of what the finished image will look like with your choices.

The Items panel shows the configurable items that make up your image layout. Click on an item to display the configurable options for that item in the bottom display panel. There is a different display panel for each type of item.

Page 25: VASSAL Reference Manual

Symbol Item Configuration

Unit Size: Select the NATO Unit Size specifier from the drop-down menu.1st Symbol: Select the Primary NATO Symbol from the drop-down menu.2nd Symbol: Select the Secondary NATO Symbol from the drop-down menu.Symbol Color: Select the color used to draw the symbol lines.Background Color: Select the color to use for the background of the symbol body.Size Color: Select the color used to draw the Size Specifier drawn above the symbol body.

Label Item Configuration

Value: Enter the text to display on the image.Foreground Color: Select the color to use to draw the text.Background Color: Select the color to use to draw a box behind the text.

Text Box Item Configuration

Value: Enter the text to display on the image.Text Color: Select the color to use to draw the text.Background Color: Select the color to use to draw a box behind the text.

Image Item Configuration

Page 26: VASSAL Reference Manual

Import an image to draw at the position specified in the layout.

Shape Item Configuration

Foreground Color: Select the fill color for the shape.Background Color: Select the color for the shape's outline.

VASSAL Reference ManualHome > Module > Game Piece Image Definitions

Game Piece Image Definitions

Within the Game Piece Image Definitions you can build your own images by combining text, images, and standard NATO symbols. Images defined in this component will appear in the drop-down menu for selecting images for any trait of any Game Piece just like an imported GIF, JPG, or PNG.

You can use your own images instead of the computer drawn NATO ones so for many games, you will be able to define the whole counter set with just a handful of images. Furthermore, you can change the size and layout of all the counters in your game easily by adjusting the layouts.

Set up a Game Piece Image in two steps:

1. Add a Game Piece Layout component to the Game Piece Layouts compont. In the Game Piece Layout properties, you specify the position, size and style of all items to be drawn on counter. Colors and actual text and symbol selections are made in step 2.

2. Add a Game Piece Image component to the Game Piece Layout component. This defines an individual image using that layout. In each Image Definition, specify the actual colors, text and symbols to be used for that image, using the layout.

Page 27: VASSAL Reference Manual

Sub-Components

Named Colors

Each color you wish to use in Image Definitions is predefined and given a name. These colors will appear in a palette for selecting foreground/background colors in the image. 14 Standard colors are built-in: CLEAR, WHITE, BLACK, LIGHT GRAY, DARK GRAY, RED, GREEN, BLUE, ORANGE, PINK, CYAN, MAGENTA, YELLOW.

Color Name: The name of the color that will appear in drop-down menus in the Image Definitons.Color: Standard Color selector to select the color to be associated with the name

Font Styles

Font Styles used in Image Layouts are predefined here and selected by name from drop-down menus. A Font Style consists of a Font Family, size and style (plain, bold, italic, bold-italic). A default style is always defined.

Style Name: The name of the Font Style that will appear in drop-down menus in the Image Layout.Font Family: The Font Family to use. To ensure maximum compatibility and portablilty, only the pre-defined Java logical fonts are available as options.Size: The size of the font style in points.Bold: Click on to select a Bold font style.Italic: Click on to select an Italic font style.Sample: Display a sample of your selected font style.

Game Piece Layouts

A Game Piece Layout is like a template that defines positions, styles, and orientations of the components in an image, but not their actual values. This component is a container for all the layouts defined in the module.

Page 28: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Map > Game Piece Layers

Game Piece Layers

This component allows you to specify that certain Game Pieces will always be drawn on top of others. Property name is the name of the property that determines the order. Typically this will be specified with a Marker trait with the specified property name. Layer Order lists the expected values for that property, in the order that they will be drawn on the map. Pieces assigned to different layers will never combine into a stack. Pieces with no value specified for the given property are placed in the topmost layer.

Example: A Map has a Game Piece Layer specified with property name Layer and Layer Order Terrain, Land, Air. Then any piece with a Marker trait with property name "Layer" and value "Terrain" will be in the bottom-most layer. The middle layer will contain pieces with the value "Land" and the top layer will contain pieces with the value "Air". Pieces with no value for the "Layer" property will be in their own layer above all three.

Sub-Components

Game Piece Layer Control

Page 29: VASSAL Reference Manual

This adds a button to the Map Window toolbar that allows you to activate/deactivate the Game Piece Layers for that map, and to change their relative order. Game Piece belonging to Layers that have been deactivated are be hidden from view until the Layer is activated again. Each player can activate/deactivate Layers independently, and layer activation is not saved when the game is saved.

Specify the button's text, icon, and keyboard shortcut. Specify the names of the layers that this button will effect, and the action of the button. Rotate Layer Order Up/Down will change the relative order of the Layers on the map, moving each layer up/down by one in the order. I will activate or deactivate the specified Layers. Switch Layer between Active and Inactive will toggle the specified layers between active and inactive. Reset All Layers makes all Layers active and restores them to their default order.

VASSAL Reference ManualHome > Module > Game Piece Image Definitions > Game Piece Layouts

Game Piece Layouts

This component contains all the layouts used to define a Game Piece Image. Right-click and select "Add Game Piece Layout" to add a new layout.

A Game Piece Layout defines the general look and layout of the items used in drawing an image. Specific color and text information is defined for individual counter images in an Image Definition.

Page 30: VASSAL Reference Manual

An Image is built up by drawing in order:

1. A rectangle of the background color.2. A border.3. Each defined item in the order displayed in the Item panel.

Name: The name of the Image Layout.Counter Width: The width of all counters created using this layout.Counter Height: The height of all counters created using this layout.Border Style: The border style for all counters created using this layout. Border styles currently available are:

None - No Border Plain - Single pixel line of defined color. Fancy - Two pixel shaded line of defined color. Mild 3D effect. 3D - A 3D-style shaded border. Two pixels wide, colour automatically determined

from background color.

Reduce Images to 256 Colors: This option results in smaller module files and will not degrade image quality unless the counters use high-resolution photographic images

Visualizer

The next section conatains a visualizer, showing you in actual size what your finished counter will look like. No colors or text have been defined yet, so sample text values and images placeholders are displayed.

Item List

Page 31: VASSAL Reference Manual

The Items panel shows the list of defined items for this Layout. Layout items are drawn onto the counter image in the order specified. Click on an item in the panel to display and edit its attributes in the lower display panel.

Buttons

Use the buttons to add, remove or move Items in the list.

Symbol - Add a NATO Unit Symbol. Text - Add a Text label. Image - Add an image from the module images directory. Shape - Draw and color fill a rectangle, rounded rectangle or oval. Remove - Remove the selected Item. Up - Move the selected Item up the list (i.e. draw earlier). Down - Move the selected Item down the list (i.e. draw later).

Symbol Item

Page 32: VASSAL Reference Manual

A Symbol Item is a generic symbol to be drawn by the program.   The particular symbol is chosen in the Game Piece Image.

Name: The name of the Item. Items MUST be uniquely named within an Image Layout.Location: Select the location of the item on the counter.Symbol Set: Select the Symbol Set to use. Only Symbol set available currently is NATO Unit Symbols.Width: The width of the body of the symbol in pixels.Height: The height of the body of the symbol (not including the Size specifier) in pixels.Line Width: The width of the line (in pixels)used to draw the symbol. Fractional line widths can be used. The lines are drawn with antialiasing turned on to produce smooth looking lines of any width. When using a small symbol size, a line width of 1.0 will usually give the best results.

Label Items

A Text Item is a text label drawn in a particular font at a particular location.  The value of the text can be specifed in the individual images or in the layout, in which case all images using this layout share the same value.

Name: The name of the Item. Items MUST be uniquely named within an Image Layout.Location: Select the location of the item on the counter.  The location also determines the text justification, i.e. selecting Top Left ensures that the upper left corner of the text is in the upper left corner of the image.  Once the justification is set by the Location, you can still use the X/Y offset in the advanced options to place the text in a different location.Font Style: Select the name of the Font Style to be used for this Text Item.

Page 33: VASSAL Reference Manual

Text is: Select whether the text is specified in the layout or in the images.

Text Box Items

A Text Box Item is multi-line area of text drawn in a particular font at a particular location.  The value of the text can be specifed in the individual images or in the layout, in which case all images using this layout share the same value.

Name: The name of the Item. Items MUST be uniquely named within an Image Layout.Location: Select the location of the item on the counter.  The location also determines the text justification, i.e. selecting Top Left ensures that the upper left corner of the text is in the upper left corner of the image.  Once the justification is set by the Location, you can still use the X/Y offset in the advanced options to place the text in a different location.Use HTML If selected, then the contents will be interpreted as HTML.Font Style: Select the name of the Font Style to be used for this Text Item.Text is: Select whether the text is specified in the layout or in the images.

Image Item

An Image item is an imported image.

Name: The name of the Item. Items MUST be uniquely named within an Image Layout.

Page 34: VASSAL Reference Manual

Location: Select the location of the item on the counter.Image is: Specify whether the image is specified in this layout or in the images that use this layout.  Use the File Open Dialog box to locate a copy of the image you wish to use on your PC. When you save the module, VASSAL will attempt to copy this image into the images folder within the module zip file. You can also manually copy images into your images folder.

Shape Item

A Shape Item is a simple geometric shape.

Name: The name of the Item. Items MUST be uniquely named within an Image Layout.Location: Select the location of the item on the counter.Width: Select the width of the shape. Height: Select the height of the shape. Shape: Select the type of shape. Bevel: For Rounded Rectangle shapes, larger bevel values mean rounder corners.

Sub-Components

Game Piece Image

Page 35: VASSAL Reference Manual

An image using this layout.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Global Key Command

Global Key Command

This trait adds an action that applies a key command to to other pieces, similar to the Global Key Command component of a Map Window.

Command name: Name of the right-click menu itemKeyboard command: Keyboard shortcut of the menu item that initiates the commandGlobal Key Command: The key command that will be applied to other piecesMatching Properties: The key command will only be applied to pieces with the specified Properties.Restrict Range: If selected, the command will only apply to pieces located within a specified distance of this piece.Range: Only others pieces within this distance, inclusive, of this piece will have the command applied to them. If the pieces are on a board with a Hex Grid or Rectangular Grid, then the distance is in units of the grid. Otherwise, the distance is measured in screen pixels.Fixed Range: If selected, then the range is specified as a fixed number. If un-selected, then the range will be given by the value of the named property.Suppress individual reports: If selected, then any auto-reporting of the affected pieces will be disabled. Use the Report Action trait to provide a summary message in their place.

EXAMPLE: A leader counter and infantry counters both have Marker traits to specify their nationality and type. A Layer trait represents the rallied state of an infantry counter, uses CTRL A to activate the layer, and uses Rally as the name. A Global Key Command on the leader counter can select and rally all infantry counters within two hexes of the same nationality that are not rallied by specifying Range=2 and matching properties type=Infantry && nation=$nation$ && Rally_Active=false.

Page 36: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Global Properties

Global Property

Properties can be attached to a Map Window or Module. The Global Properties component is a container for all properties attached to the Map or Module. When looking for the value of a property of a GamePiece, global properties provide default values. If the property is not defined on the GamePiece itself, the Map to which it belongs will provide the value. If the property is not defined on the Map, the Module will provide the value.

Name The name of the property.Initial Value The value of the property at the start of a new game.Description Plain english description of the property.Is Numeric If true, then changes to the value of the property will be restricted to integer values.Minimum Value Numeric values will be restricted to no less than this number.Maximum Value Numeric values will be restricted to no more than this number.Wrap Around If true, then when incrementing this numeric property, values will wrap around from the maximum to the minimum.

Sub-Components

Change-Property Toolbar Button

Adds a button to the toolbar of the Map Window or Module that changes the value of the Global Property. You can combine multiple buttons into a single drop-down menu using a Toolbar Menu.

Page 37: VASSAL Reference Manual

Button text The text of the toolbar button.Button icon The icon of the toolbar button.Hotkey Keyboard shortcut for the toolbar button.Report Format Message Format of a text message to echo to the controls window when the button is pressed: oldValue is the value of the Global Property prior to the button press, newValue is the value after the button press, and description is the plain English description of the property as defined above.Type Defines how the property value should change: Set value directly sets the property to a fixed value, after substituting values of Properties. Increment numeric value adds a fixed value to the property, after substituting values of Properties. Prompt user pops up a dialog for the user to type in a new value. Prompt user to select from list pops up a dialog with a drop-down menu for the user to select from.

VASSAL Reference ManualHome > Module > Map > Board > Grid > Grid Numbering

Grid Numbering

Page 38: VASSAL Reference Manual

Specifies how labels are assigned to cells in a Hex or Rectangular Grid on a Board.

Order: Label cells by row/column vs. column/row

Separator: Text to place between the row and column, such as a comma

Numbering: Alphabetical (A,B,C, ... AA, BB, CC, etc.) vs numerical (1,2,3 ...)

Descending: If checked, numbering of rows/columns begins on the bottom/right edge of the board.

Leading Zeros: One leading zero means always use two digits for the row/column. Two leading zeros mean always use three digits, etc.

Starting Number: The number of the first cell ('A' == 0 if using alphatetic numbering).

Location format The Message Format for reporting locations within a map window (e.g. for move reporting): gridLocation is the name as drawn on the sample grid. This is useful for prepending a board name, for exaple.

Draw Numbering: If checked, the numbering of the grid will be drawn on top of the board image.

Font size: Size of the font to use when drawing the numbering.

Color: Color to use when drawing the numbering.

Rotate Text: Orientation of the numbering text.

Page 39: VASSAL Reference Manual

Text X offset: Distince in pixels to the right (relative to the text's orientation) of its default position that the text will be drawn. By default, text is center-justified at the top of the cell.

Text Y offset: Distince in pixels downward (relative to the text's orientation) of its default position that the text will be drawn. By default, text is center-justified at the top of the cell.

Odd-numbered rows numbered higher: For hex grids only. If checked, then the first number of staggered columns on the grid will be one greater than non-staggered columns.

Page 40: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Help Menu

Help Menu

The "Help" menu in the main control window contain general helpfiles for VASSAL. You may add more helpfiles specific to the module you are creating.

Sub-Components

Help File

Each Help File added adds an entry to the help menu. Helpfiles be either plain text or simple HTML. To add a plain text Help File simply create the file with any text editor on your machine and select it.

To add an HTML Help File, first create all the HTML files in a single directory (Simple HTML only: no Javascript, no frames). Any images that are used with the HTML should be together in a sub-directory named 'images'. Select the HTML and image files one at a time from the Help File properties dialog. The last HTML file you select will be the starting page.

The contents of the file will be displayed when the player selects that menu item from the help menu.

Page 41: VASSAL Reference Manual

Note: when editing a module, you will need to save before you are able to view the help contents.

About Screen

You may use any image you wish as an 'About' screen for your module. Feel free to include text in the image that credits you and any other contributors to the module.

The About Screen will always display the current version of the VASSAL and engine and module.

If you name your About Screen image 'Splash.gif' on your hard drive before importing it into the module, then that image will be used as a splash screen when loading the module directly from command line (as described in the VASSAL README file).

Tutorial

You may create a tutorial by writing a logfile and making it accessible from the help menu.

Menu Text is the menu item under the Help MenuLogfile is the logfile that players will step through when they select the corresponding menu item.Launch automatically If selected, then players will automatically be prompted to run the tutorial the

Page 42: VASSAL Reference Manual

first time they load the module.Confirm message provides the text in the yes/no dialog that is displayed to the player when they load the module for the first time. Answering "yes" will load the tutorial logfile.Welcome message is the message that displays in the main controls window chat area when the tutorial is loaded.

VASSAL Reference ManualHome > Module > Map > Board > Hex Grid

Hex Grid

A standard hexagonal grid for regulating movement on a Board.

Sideways: Check this box to make the hexrows of the grid run right-to-left instead of top-to-bottom. (Setting the grid to be sideways switches the meanings of horizontal/vertical and x/y below.)

X,Y offset: The horizontal and vertical position of the center of the first hex of the grid

Hex Height/Width: in pixels from hex center to hex center. If you specify only the height, the width will adjust, or you can create oblong hexes by also specifying a width

Legal Locations: Determines whether pieces can be placed on hex edges or corners, instead of only at hex centers.

Show Grid: If checked, then the grid will be drawn over the Board image using the specified

Page 43: VASSAL Reference Manual

color.

Sub-Components

Grid Numbering

Used to assign names to hexes on the grid. Used primarily for automatically reporting moves.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Invisible

Invisible

This trait gives a Game Piece the capability to be made invisible. Specify the key which the user will type to make the piece invisible and the name for the command that will appear in the popup menu. The same command turns invisible piece visible again. To the player who turned it invisible, the piece will appear transparent against a background of the specified color. To other players it will not appear at all. This trait actually only hides those traits that are before it in the list of traits, so it should generally be the last trait of a Game Piece.

The Can be hidden by option defines who may hide this piece (and see it once hidden). Any Player means that any player may hide this piece, including observers. Any Side means that any player who has been assigned a side in a game (not an observer) can hide this piece. If the player resigns and another player takes the side, then the new player for that side will be the owner. Any of the Specified Sides allows you to enter a list of sides. Only players assigned to one of the named sides can hide the piece, but the players of

Page 44: VASSAL Reference Manual

all the listed sides will be able to see and modify the piece. This is useful for referee players or games with multi-player teams.

This piece sets the Property InvisibleToOthers=true when invisible.

VASSAL Reference ManualHome

General

This manual describes the features of the VASSAL module editor. It is not necessary to be familiar with the contents if you are only using VASSAL to play games. The information here is also available from VASSAL's on-line help.

All modifications to a module are done through the Configuration Window, which is a familiar file/folder type browser in which each file/folder represents a module component. The Configuration Window can be used to edit either a Module or a Module Extension. It can also be used to create Module updaters and to update saved games

Editing Modules

Page 45: VASSAL Reference Manual

Right-click on an any component to get a popup menu with options for that component. Use the Cut, Copy, Paste, and Move commands to move components around within the module.

Properties

Brings up a dialog in which you specify the options for that components. Double-clicking on a component also brings up its Properties dialog.

Delete

Delete's the component from the module.

Clone

Makes an exact copy of the component and inserts it after the existing component.

Help

Brings up the corresponding page in this manual.

Add ...

Adds a sub-component to this component

Module Updaters

Since VASSAL modules can be large in size, VASSAL provides a tool to build compact downloads for automatically updating a module. The updater is a file named, for example, updateMyModule.jar for a module file named MyModule.mod. The user simply places the two files in the same folder and double-clicks on the .jar file to update the module.

To create a module updater, move a copy of the old module file and the new module file into your VASSAL folder. You will need to leave the old module file with its original name and give the new module file a different name. Then go to a command prompt and type

Page 46: VASSAL Reference Manual

java -cp lib/Vengine.jar VASSAL.tools.ZipUpdater oldModuleFile newModuleFile

VASSAL Reference ManualHome > Module > Map > Board > Irregular Grid

Irregular Grid

An irregular grid is used for area-based games. It allows you to define a set of named regions at arbitrary locations. When moving pieces on a board with an Irregular Grid, they will snap to the nearest region location.

Draw region names: If checked, the names of the regions will be drawn on the map.

Font size: The font size used to draw the names.

Define Regions: Hit this button to bring up a window for defining the regions. Right-click anywhere on the board to add a new region, or right-click on an existing region's name to change its name or remove it.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Text Label

Text Label

Page 47: VASSAL Reference Manual

This trait displays a text label along with a piece. The text of the label can be fixed or specifyable by a player at game time.

Text: The starting value for the label text. Properties of the piece are substituted as in a Message Format. By enclosing the text within tags, you can use simple html format to specify various colors, fonts and sizes. Example: <html><b>Bold text</b><p>with a line break<p>and <font color=red>different</font> <font color=blue>colors</font></html> will display as:

Bold textwith a line breakand different colors

Name Format: A Message Format that specifies how the name of this piece will be reported: pieceName is the name of the piece excluding the label, label is the value of the label text (including, unfortunately, html tags). If the label is empty, then the default name of the piece is always used.Menu Command: If not blank, gives the text of the corresponding menu item in the piece's right-click menuMenu key command: If blank, the text of the label is permanent. If set, then gives the keyboard command to set the text of the labelFont:Text is drawn using this font.Font size / Bold / Italic:The text is drawn at this size, optionally in bold or italics.Text Color: The text is drawn using this color.Background Color: The text is drawn within a solid rectangle of this color. Hit Select and then Cancel to use a transparent background.Vertical Position: Draw the label with the given offset from the top, bottom, or center of the piece.Horizontal Position: Draw the label with the given offset from the left, right, or center of the piece.Vertical justification: Whether the top edge, bottom edge, or center of the label will be drawn at the Horizontal Position specified above.Horizontal justification: Whether the right edge, left edge, or center of the label will be drawn at the Vertical Position specified above.Rotate Text:The text will be rotated clockwise by this angle. Rotation is performed after the

Page 48: VASSAL Reference Manual

horizontal/vertical justification and positioning specified above.Property Name:The value of this label will be exposed as a Property with the given name.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Layer

Layer

A Layer is the basic method for adding functionality to game pieces in VASSAL. A Layer consists of a number of 'levels,' each of which has an image and a name. The Layer can be activated with a keyboard command, and two other keyboard commands cycle through the levels. If the "Loop through levels" option is checked, then increasing the level past the last one will loop through to the first level and vice versa. A "reset" command resets the Layer to a particular level. A "randomize" command selects a random level. The image from the current level will be drawn whenever the Layer is activated. The Layer is drawn on top the traits that appear before it in the list of traits, but if the "Underneath when highlighted" box is checked, the Layer will be drawn on the bottom when the

Page 49: VASSAL Reference Manual

counter has been highlighted (by clicking on it).

A Layer can be given a name, which is used only for identification within the editor. Each level can be given an individual name, which is used for reporting changes to the piece during game play.

EXAMPLE: To implement a two-sided counter, add a layer, and select an image that represents the reverse side. Change "Activate" to "Flip" and set the key to "F". The resulting counter will show the reverse side when the user hits CTRL-F, and the counter's help window will list the "Flip" command with the proper key.

For Layers with more than a single level, two additional commands (increase/decrease) are used to select the level.

EXAMPLE: To implement an army counter that has four fatigue levels, select four images that represent the levels Change "Increase" to "Increase Fatigue" and "Decrease" to "Decrease Fatigue".

A "Reset" command can be specified to reset the Layer to a particular level. ('1' is the first level, etc.) This does not automatically activate the Layer.

EXAMPLE: A command named "Rest" using CTRL-R could be used to bring the Army counter back to full strength.

The text name of a GamePiece can also change when the Layer is active. Fill in the "Level name" box to use a different name when that level of the Layer is activated.

EXAMPLE: We can add level names for the four fatigue levels above. Suppose the name of the Basic Piece is "Army". By checking "is suffix" and naming the levels " (fatigue 1)" etc., the counter will be reported as "Army (fatigue 1)" etc. when being moved.

The images of a level are drawn with their center offset from the center of the base image by a number of pixels specified by the "offset" boxes, with positive numbers giving an offset down and to the right.

EXAMPLE: If a layer image is 40x40 pixels and you want it to be drawn so that the lower-left corner is at the center of the gamepiece, set the offset to 20,-20.

Advanced Tricks:

Taking advantage of transparency in your images can be very useful. Leaving the menu-command field blank means no entry appears in the right-click menu, but you can still use a keyboard shortcut. Keyboard shortcuts can be the same as those used by other traits. Typing the key will perform all corresponding actions. The Activate keyboard shortcut can specify a string of characters, such that the layer is activated only when all the corresponding keys have been

pressed. For example, a counter may have a Berserk Status and a Wound status, where the Wound status only applies to Berserk units. The counter

Page 50: VASSAL Reference Manual

could have a Berserk layer activated by 'B' and a Wound layer activated by 'BW'. The Increase/Decrease keyboard shortcuts can also specify a string of characters, such that the level is increased/decreased when _any_one_ of the

keys is pressed.

A Layer defines a number of Properties. In the name of the properties, <layer_name> is the name of the overall Layer as specified in the top field of the properties.

<layer_name>_Image returns the name of the currently-active level's image file <layer_name>_Name returns the name of the currently-active level <layer_name>_Level returns the number of the current level <layer_name>_Active returns true if the Layer is active, false otherwise

EXAMPLE: A Layer named Manpower that is active and showing level 4 defined with image Man04.gif and name (strength 4) would have the following properties:

Manpower_Image = Man04.gif Manpower_Name = (strength 4) Manpower_Level = 4 Manpower_Active = true

These properties could be used in a Global Key Command to automatically remove all counters whose manpower was zero.

VASSAL Reference ManualHome > Module > Map Window

Map Window

Page 51: VASSAL Reference Manual

The Map Window is the main interface for playing games with VASSAL. It displays the playing surface on which the players move game pieces by dragging and dropping with the mouse. It is possible to have two or more Map Windows; the players may drag and drop pieces between the different windows. A Map Window should be configured with at least one Map Board (in the "Map Boards" panel).

Map Name The name of this map windowMark pieces that move If checked, then any pieces with the "Can be marked moved" trait will be marked whenever being moved in this map window. The module designer can also allow players to set this option in their preferences.Vertical/Horizontal padding The amount of blank space surrounding the boards in the windowCan Contain Multiple Boards If checked, this map window can contain several boards arranged into rows and columnsBorder color for selected counters The color of the border to draw around pieces that have been selectedBorder thickness for selected counters The color of the border to draw around pieces that have been selectedInclude toolbar button to show/hide If checked, then this map window will not be automatically shown when a game begins. Instead, a button to show/hide this window will be added to the main controls toolbarToolbar button name The name of the show/hide toolbar button

Page 52: VASSAL Reference Manual

Toolbar button icon An icon for the show/hide toolbar buttonHotkey The hotkey for the show/hide toolbar buttonAuto-report format for movement within this map A Message Format that will be used to report movement of pieces completely within this map window: pieceName is the name of the piece being moved, location is the location to which the piece is being moved (in the format specified above), previousLocation is the location from which the piece is being moved.Auto-report format for movement to this map A Message Format that will be used to report movement of pieces to this map window from another map window: pieceName is the name of the piece being moved, location is the location to which the piece is being moved (in the format specified above), previousLocation is the location from which the piece is being moved, previousMap is the name of the map from which the piece is being moved.Auto-report format for units created in this map A Message Format that will be used to report pieces that are dragged to this map window directly from a Game Piece Palette: pieceName is the name of the piece being moved, location is the location to which the piece is being moved (in the format specified above).Auto-report format for units modified on this map A Message Format that will be used to report changes to pieces on this map: message is the text message reported by the Report Action trait of the game piece being modified.

Sub-Components

Map Boards

This component contains all the boards that may appear in this map window. It contain Board components and defines the dialog that is used to select boards when a new game is started.Dialog Title: The title of the dialog window for choosing boards on this map."Select Boards" prompt: The prompt message in the drop-down menu for selecting boardsCell scale factor: The relative size of the boards in the dialog compared to their final size during play.Cell width: The width of a cell when no board has been selected.Cell height: The height of a ceel when no board has been selected.Default Board Setup: Hit this button to choose a default set of boards. When a default has been set, the dialog will not be shown to players when a new game is begun. Instead, the game will always be started with the boards you select. If you hit this button and then clear the boards, then dialog will again be shown at the start of each game.

Page 53: VASSAL Reference Manual

Stacking Options

This component controls how stacking is handled in this Map Window. It may not be removed

Disable stacking: If checked, then pieces will never form stacks in this windowHorizontal Separation when expanded: The distance in pixels from the left edge (right edge if negative) of a piece in a stack to the edge of the piece above it when the stack is expanded.Vertical Separation when expanded: The distance in pixels from the bottom edge (top edge if negative) of a piece in a stack to the edge of the piece above it when the stack is expanded.Horizontal Separation when not expanded: The distance in pixels from the left edge (right edge if negative) of a piece in a stack to the edge of the piece above it when the stack is compact.Vertical Separation when not expanded: The distance in pixels from the bottom edge (top edge if negative) of a piece in a stack to the edge of the piece above it when the stack is compact.Color of pieces when not expanded: If set, then pieces below the top piece in a compact stack will be drawn as plain squares of this color and a black border. If not set (hit the "Select" button and cancel the color-selection dialog) then pieces will be drawn normally.

Overview Window

Adds a separate window that will be displayed whenever the main map window is displayed. The additional window will contain a view of the entire playing area at a smaller scale than displayed in the main map window. The area of the map currently visible in the map window is highlighted in the overview map with a colored rectangle. A player may click on the Overview window to center the Map Window at the point clicked on.

Page 54: VASSAL Reference Manual

The scale of the overview window relative to the map window can be specified in the "Scale Factor" property. You may also specify the color of the rectangle indicating the area visible in the main Map Window.

Line of Sight Thread

Adds a button to the toolbar of the Map Window. Pushing the button will allow the player to drag the mouse between any two points in the window, drawing a line between those two points.

Hotkey: Specifies a keyboard shortcut for the button.

Button text: The label on the button in the Map Window toolbar

Draw Range: If checked, draws the range between the two points, in hexes or squares, as appropriate for the board in use.

Pixels per range unit: If drawing the range on a board without a grid, this determines how many pixels on the screen equal a single unit of range.

Round fractions: For distances that are a fraction of a range unit, specify whether to round fractions up, down, or to the nearest whole number.

Hide Pieces while drawing: If checked, then all game pieces in the map will be hidden (or transparent) while the thread is being drawn.

Opacity of hidden pieces:Set the transparency of game pieces while the thread is being drawn. 0 is completely invisible, 100 is completely opaque.

Thread color: Specifies the color the thread on the screen. If set to null (by hitting the "Select" button and then the "Cancel" button in the color-choosing dialog), then a Preferences option will determine the color of the thread at game time.

Page 55: VASSAL Reference Manual

Toolbar Menu

Groups buttons in the toolbar into a single drop-down menu.

Hide Pieces Button

Adds a button to the toolbar of the Map Window. Pushing the button will temporarily hide all pieces on the map, until the button is pressed again.

Hotkey: Specifies a keyboard shortcut for the button

Zoom capability

Adds "Zoom in" and "Zoom out" buttons to the toolbar of the Map Window. Keyboard shortcuts can also be specified by filling in the "Hotkey" boxes. The "Zoom factor"specifies the magnification factor for each zoom level, and the "Number of zoom levels" specifies the maximum number of levels that may be zoomed out. The "Starting zoom level" is the default zoom level when a game is loaded.

Mouse-over Stack Viewer

Page 56: VASSAL Reference Manual

Adds a tool that displays the contents of a stack when the player leaves his mouse resting over it, after a specified delay.

Recommended Delay before display: When the mouse has been stationary for this many milliseconds, the viewer will appear. This can be overridden in the preferences.Keyboard shortcut to display: Players may display the viewer without waiting by typing this keyboard shortcut. This can be disabled in the preferences.Background color: Pieces/text are drawn against a background of this color.Border/text color: Color of any text drawn and the border around the overall viewer.Display when at least this many pieces will be included: If set to 0, then the viewer will display even if the location is empty. Otherwise, it will display only if 1 or 2 pieces have been included via the settings below.Always display when zoom level is less than: Regardless of the above "at least this many" setting, the viewer will also display when the map's magnification factor is less than this number.Draw pieces: If selected, then the included pieces will be draw in the viewer.Draw pieces using zoom factor: The magnification factor to use to draw the pieces in the viewer.Width of gap between pieces: Empty space in pixels to place between each drawn piece.Display text: If selected, then the viewer will draw some summary text and some individualized text for each piece.Font size: Size of the text to draw.Summary text above pieces: A Message Format specifying the text to display above the drawn pieces in the viewer. In addition to standard Properties, you can include a property with the name sum(propertyName) where propertyName is a property defined on a Game Piece. The numeric values of this property for all included pieces will be substituted.Text below each piece: A Message Format specifying the text to display below each included piece.Text for empty location: A Message Format specifying the text to display

Page 57: VASSAL Reference Manual

when no pieces have been selected.Include individual pieces: Specifies how pieces are to be selected for inclusion in the viewer. You may restrict the pieces according to the Game Piece Layer that they belong. Alternatively, you may specify the value of a Property.Include non-stacking pieces: If selected, then non-stacking pieces are eligible for inclusion in the viewer.Include top piece in Deck: If selected, then the top piece of a Deck is eligible for inclusion.

Last Move Highlighter

Draws a colored border around the last piece to have been moved, added, or deleted in a logfile or by an opponent during live play. Color is the color of the border and Thickness is the border thickness. The highlight is cleared by clicking on the map.

Game Piece Layers

Allows you to restrict Game Pieces to different layers on the map. Pieces in higher Layers are always drawn on top of lower Layers, and pieces never combine into stacks with pieces on other Layers.

Image Capture Tool

Page 58: VASSAL Reference Manual

Adds a "Camera" button to the toolbar of the Map Window. Pushing the button will dump the contents of the Map Window to a GIF file. This allows you to take a screen shot even if the map window is too large to fit entirely on the screen.

Text Capture Tool

Adds a "Save Text" button to the Map Window toolbar. Hitting the button will write a plain text summary of the contents of the map to a file, using the names assigned to the counters and the appropriate numbering of the board's grid.

Deck

A deck of cards.

At-Start Stack

A fixed draw pile of counters.

Recenter Pieces ButtonAdds a button to the map window toolbar. Then button will shift the position of all pieces on the map such that they are centered around the middle of the map as much as possible. This is useful for games where there are no absolute terrain features, such as some air and naval games.

Global Key Command

Page 59: VASSAL Reference Manual

Adds a button to the map window toolbar. Hitting the button will select certain pieces from the map window and apply the same keyboard command to all of them simultaneously.

Description: A description of the action used for the button's mouse-over tooltip.Key Command: The keyboard command that will be applied to the selected pieces.Matching properties: The command will apply to all pieces on the map that match the given Property expression..Button text: Text for the toolbar button.Button icon: Icon for the toolbar button.Hotkey: Keyboard shortcut for the toolbat button.Suppress individual reports: If selected, then any auto-reporting of the action by individual pieces via the Report Action trait will be suppressed.Report Format: A Message Format that will be echoed to the chat area when the button is pressed.

Example: Suppose you have configured some pieces to contain a Layer indicating that a piece has fired, activated by CTRL-F and with the name Fired. Give each piece the Marker trait with property name canFire and value true. Configure the Global Key Command to apply to pieces whose properties match canFire = true && Fired_Active = true. Specify CTRL-F as the key command. Now pushing the Global Key Command button will set all marked pieces on the map to not having fired.

Map Shading

Page 60: VASSAL Reference Manual

Applies a semi-transparent solid color or image tiling to the Map. In background mode, can be used to overlay a repeating image over solid-color boards. In foreground mode, the area is determined by the pieces on the map that name this Map Shading in an Area of Effect trait.

Name: A short name of this shading for reference by pieces with the Area of Effect trait.Shading Always On: If true then the shading is always drawn. If false, then visibility is controlled by a button in the Map Window toolbar.Shading Starts turned on: If true, then the shading will begin visible when a game is loaded.Button text: Text for the toolbar button.Button icon: Icon for the toolbar button.Hotkey: Keyboard shortcut for the toolbat button.All boards in map get Shaded: Allows you to select which Boards in the map to apply the shading to.Type: If set to Background then the shaded area includes the entire board, minus the areas attached to any Area of Effect traits. If set to Foreground, then the shaded area includes only the areas attached to Area of Effect traits.Draw Shade on top of Counters: If true, then the shading will be drawn over any counters on the map. Otherwise, it will be drawn underneath all counters.Shade Pattern: Choose between 100/75/50/25 % hatch patterns, or choose a custom image.Color: The color of the shading (if not using a custom image).Opacity: The opacity of the shading. 0 is invisible, 100 is completely opaque.Border: If selected, will draw a border around the shading area. You can specify the thickness, color, and opacity of the border.

Global Properties

Allows you to define default values for Properties

Page 61: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Marker

Place Marker

A Game Piece with this trait will have a menu command that places a different piece (the "marker") on top of this one. You can select any existing piece for the marker or define a new one from scratch.

Horizontal offset: The marker will be placed this many pixels to the right of the original piece.

Vertical offset: The marker will be placed this many pixels above the original piece.

Match Rotation: If selected, and both the original piece and the marker have the Can Rotate trait, then the rotation angle of the marker will be adjusted to match that of the original piece.

EXAMPLE: If a game uses a fortification counter to indicate fortified status of an army counter, this trait could be given to the army counter to place a fortification marker on the army with a keyboard command, as an alternative to dragging the fortification counter from the Game Piece Palette.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Mark When Moved

Mark When Moved

Page 62: VASSAL Reference Manual

Pieces that have the 'Mark When Moved' trait will automatically display a specifyable image every time they are moved. Specify the image and the position at which to draw the image. The board command.moved status of an individual piece can be toggled with a key.

NOTE: In order to enable this feature, you must also go to the Global Options of the module and enable the "Mark pieces that move" setting. Enabling this feature will automatically add a button to each Map Window that clears the moved status of all pieces on the map.

This trait sets the Property Moved=true when the piece has been moved.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Mask

Mask

Page 63: VASSAL Reference Manual

A masked piece looks different to players other than the one who hid it, but remains visible to all players (unlike an invisible piece). This trait is useful for playing cards. Players may drag a card face down from their hand to the playing area. The owning player will be able to see the identity of the card, but other players will only see the back until it is turned face up. Board games with a concept of concealment will also use this trait.

Like the "Can be Invisible" trait, this trait only hides traits that appear before it. Generally, it should be before any Invisible trait and after all other traits of the piece.

A piece with the Mask trait is "owned" by the player who masks it. If unmasked and masked again by a different player, the second player becomes the owner. Menu commands of traits hidden by a masked piece are not available to non-owning players. A setting in the Global Options determines whether or not non-owning players can unmask pieces.

Mask Command: The name of the right-click menu entry that mask/unmasks this piece

Keyboard Command: The keyboard command to mask/unmask this piece.

Can be masked by: Defines who may "own" this piece (i.e. mask it from other players). Any Player means that any player may mask this piece, including observers. Any Side means that any player who has been assigned a side in a game (not an observer) can mask this piece. If the player resigns and another player takes the side, then the new player for that side will be the owner. Any of the Specified Sides allows you to enter a list of sides. Only players assigned to one of the named sides can mask the piece, but the players of all the listed sides will be able to see and modify the piece. This is useful for referee players or games with multi-player teams.

Page 64: VASSAL Reference Manual

View when masked: To non-owning players, the piece will be drawn using this image.

Name when masked: To non-owning players, the piece will be given this name.

Display style: Determines how a masked piece is seen by the owning player. The following options are available:

Inset draws the regular piece with the mask image at reduced size in the upper left corner Background draws the mask image at full size and the regular piece at reduced size centered within it Plain draws only the mask image, so the piece looks the same to all players. A "Peek" command key may be specified. When the owning player selects

the "Peek" command, he will see the unmasked piece so long as it remains selected (i.e. until he clicks elsewhere on the map). If the "Peek" command key is left blank, then the owning player will see all selected pieces in their unmasked state.

Use Image draws the unmasked piece and then a specifyable image on top of the piece. The image should make use of transparency to let some of the information through.

EXAMPLE: An ordinary playing card can be implemented by setting the basic image to represent the front of the card. In the "Mask"controls, specify an image for the back of the playing card. When a player types CTRL-F, that card will be known only to him (as thoughheld in his hand). Typing CTRL-F again will reveal the card to the other players (as when playing it on the table).

This trait sets the Property ObscuredToOthers=true when the piece is masked.

VASSAL Reference ManualHome > Message Format

Message Format

A Message Format allows module designers to specify the format of text messages that are generated by VASSAL at various times during play. Any word surrounded by $ characters represents a variable whose value will be determined when the message is generated during play. Click on the Insert drop-down

Page 65: VASSAL Reference Manual

menu for a list of available variables. Selecting one of the variables from the menu will insert it at the current cursor position.

Available variables will vary depending on the component being configured. Some commonly-used variables are:

playerName is the player's name as specified in the PreferencesplayerSide is the side chosen by the player from the Definition of Available SidesplayerId is a combination of playerName and playerSide specified in the Global Options

When a Message Format is used in conjunction with a particular Game Piece, then the Properties of that GamePiece can be used in the Message Format.

VASSAL Reference ManualHome > Module Updater

Module Updaters

Since VASSAL modules can be large in size, VASSAL provides a tool to build compact downloads for automatically updating a module from an older version to a newer version. The player places the updater file in the same folder as the old module file. Double-clicking on the updater file will replace the old module file with the new version.

Updaters can be used in the same way to update module extensions.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Move Fixed Distance

Page 66: VASSAL Reference Manual

Move Fixed Distance

Defines a command to move the piece a fixed distance upwards and to the right. If the piece is part of a stack, and the stack is not expanded, and the Move entire Stack option is selected, then the command will move the entire stack.

NOTE: If this piece has a Can Rotate trait listed before this trait, then the resulting direction will be relative to the current facing of the piece. Example: If a piece has traits Can Rotate followed by Move Fixed Distance 60 upwards, then the move command will move the piece in whatever direction the top of the piece is facing. If a piece has traits Move Fixed Distance 60 upwards followed by Can Rotate then the move command will move the piece towards the top of the screen regardless of the facing of the piece.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Movement Trail

Movement Trail

Page 67: VASSAL Reference Manual

Pieces with this trait will leave behind a graphical trail showing the positions through which the piece has been moved. The trail consists of a circle for each past location, connected by straight lines. The piece should also contain a Can be Marked Moved trait. The movement trail is reset when the moved status of the Can be Marked Moved trait is cleared.

Key Command: The keyboard shortcut to show/hide the movement trail. If left blank, then the trail is always visible.Menu Command: The right-click menu command to show/hide the movement trail. If left blank, no menu entry appears, although the keyboard command may still be enabled.Trails start visible: At the beginning of each move, the trail will be visible if selected, invisible otherwise.Trails visible to all players: If selected, then toggling the visibility of the trail will affect all players' views and will be saved along with the game. Otherwise, each player controls the visibility of trails on that player's view.Circle Radius: The radius in pixels of the circle representing each location in the trail.Circle fill color: The color of the location circles.Line Color: The color of the connecting linesLine Thickness: The thickness in pixels of the connecting linesSelected transparency: The transparency of the trail when the piece is selected. 0 is invisible; 100 is opaque.Unselected transparency: The transparency of the trail when the piece is not selected. 0 is invisible; 100 is opaque.Display points offmap: If the map has buffer space surrounding the boards, the trail circles will be drawn within this distance from the board edges.Display trails offmap: If the map has buffer space surrounding the boards, the trail lines will be drawn within this distance from the board edges.

VASSAL Reference Manual

Page 68: VASSAL Reference Manual

Home > Module > Game Piece Palette > Game Piece > Non-Rectangular

Non-Rectangular

This trait allows you to specify an arbitrary shape for a GamePiece.

The shape of a piece is used to determine where the player must click to drag a piece or bring up its popup menu. It also is used to highlight the outline of the piece when it has been selected.

By using transparent colors in your GIF, you can make your piece be drawn with any shape. However, without the Non-Rectangular trait, the piece can be selected even by clicking on the transparent portions of the image, which can lead to confusion. The Non-Rectangular trait properties allows you to specify the shape of the piece to be identical to the non-transparent portion of an image. Simply select the appropriate image from the drop-down list.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Does not Stack

Does not Stack

The 'Does not stack' trait means that a piece will not form stacks with other pieces. If the "Ignore grid" box is selected, then this piece will not snap to the nearest grid location. The "select piece" option controls how the piece is selected: either normally, never (can never be selected) or when the shift key is down (shift-click to select the piece, then enter keyboard command. The "move piece" option controls how the piece is moved: either normally, never (cannot be moved once placed) or only if selected (select piece, then click and drag to move).

EXAMPLE: Use non-stacking pieces to represent playing cards in games that mix cards and counters,

Page 69: VASSAL Reference Manual

so that the cards can be placed on a map without interfering with stacks of counters.

EXAMPLE: Pieces that represent map features, such as destroyed bridges or control markers, can use the "Move piece never" option so that players do not inadvertently move them around.

VASSAL Reference ManualHome > Module > Game Piece Palette

Game Piece Palette

The Game Piece Palette is a panel that contains game pieces which the players may drag to the playing area during a game. An unlimited supply of each Game Piece is available through the palette If you need to limit the number of pieces available during play, use a Deck, an At-Start Stack, or Default Setups.

If the player has the Use combined application window preference checked, then the first Game Piece Palette in the module will dock into the main controls window to the left of the chat area. All others will appear in their own window.

Name: If the palette appears in its own window, this will be used for the title.Hidden: If checked, then this Game Piece Palette will not appear at all during play. This is useful if you need to define pieces for a Default Setup but don't want to allow players to create new pieces during play. You must restart VASSAL for this change to take effect.Button Text: The text on the toolbar button that shows and hides the Game Piece Palette.Button Icon: The icon image on the toolbar button.Hotkey: A keyboard shortcut for the toolbar button.

The Game Piece Palette is highly configurable, and can can contain any combination of tabs, lists, and pull-down menus containing individual Game Pieces. For example, the window may contain a tabbed pane with two entries, called "Info" and "Armies", each of which contain a list of pieces. Every component in the toolbar should end with

Page 70: VASSAL Reference Manual

a Single Piece. Since a typical game has many pieces that differ in only minor ways, you may find it convenient to clone Single Pieces. Also, the order of the pieces can be changed by dragging them within the configuration tree.

Sub-Components

Each sub-component (except a Single Piece) of a Game Piece Palette can contain any combination of the other sub-components.

Single Piece

A Game Piece that can be dragged onto a playing area.

Pull-down menu

A pull-down menu in which each menu item corresponds to a subcomponent. The name of the menu item will be the name of the subcomponent.

Scrollable List

Ascroll list in which each entry corresponds to a subcomponent. The name of the entry will be the name of the subcomponent.

Tabbed Pane

A panel with tabs, each of which corresponds to a Chart, Panel, or other Tabbed Pane subcomponent. The label of the tab will be the name of the subcomponent.

Panel

A panel that can contain Single Pieces, , Tabbed Panes, or other panels. The "Fixed cell size" box allows you to specify a fixed number of columns that the panel will have. Otherwise, the subcomponents will appear in a single row, or a single column if the "Vertical layout box is checked.

Page 71: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Can Pivot

Can Pivot

This trait allows a piece to pivot around a fixed point relative to its current position. This trait is only applicable if the piece also has a Can Rotate trait, which appears before the Can Pivot trait.

Command: The right-click menu command to pivot the piece.Keyboard command: The keyboard shortcut of the command.Pivot Point: The location, relative to the center of the piece and its current facing, around which the piece will rotate. Positive numbers are down and to the right. Example: For a piece of size 40x40, a pivot point of 20,-20 will rotate the piece around its upper right corner.Pivot through fixed angle: If selected, then invoking the command will pivot the piece through the angle specified in the Angle field, in degrees clockwise. If left unselected, then invoking the command will allow the player to pivot the piece interactively by any angle by dragging the mouse.

VASSAL Reference ManualHome > Module > Player Hand

Page 72: VASSAL Reference Manual

Private Window

A Player Hand is a specialized Private Window for containing a hand of cards. It is designated as belonging to a particular side or sides. The owning sides must correspond to one or more of the sides defined in the definition of player sides.

The main difference between a Player Hand and a normal Private Window is that in a Player Hand, the contents are automatically laid out in a row instead of stacking like counters.

Like a Private Window, a Player Hand can only be manipulated by the owning player, and can optionally be completely hidden from other players. Cards can be manipulated in the hand (turned face up, etc.) and can be rearranged in order. Cards can be dragged into and out of the window to add/remove them from the hand.

Other properties are the same as for ordinary Map Windows.

Sub-Components

See sub-components for Map Window.

VASSAL Reference ManualHome > Module > Private Window

Page 73: VASSAL Reference Manual

Private Window

A Private Window behaves like a normal Map Window, but is designated as belonging to a particular side or sides. The owning sides must correspond to one or more of the sides defined in the definition of player sides.

A Private Window may be hidden from all players not playing one of the owning sides. Even if visible to them, players not playing the owning side may not manipulate pieces on the map; both mouse and keyboard events are ignored.

A Private Window may designate another Map window to automatically use the same boards as that other window. If left blank, then the Private Window will use its own set of boards.

Other properties are the same as for ordinary Map Windows.

Sub-Components

See sub-components for Map Window. VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Properties

Properties

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components. Default values can be defined in a Global Property.

Properties can be matched using expressions like name = value for an exact match, name != value for a non-match, or name =~ value for a regular expression

Page 74: VASSAL Reference Manual

match. For properties that return a numeric value (e.g. the level in a Layer) you can use <, <=, >, and >=. You can combine expressions using && for logical AND and || for a logical OR.

Components that use properties

Any Message Format defined in a Game Piece will substitute values for the properties defined on that Game Piece The Global Key Command component uses properties to determine which pieces will respond to the command. The Game Piece Layers component uses properties to determine relative ordering when drawing pieces on the map. The Trigger Action trait uses properties to determine when to fire a keyboard command. The Text Label trait substitutes properties when setting the text of the label.

Common properties

The Basic Piece defines properties related to a piece's name, location, side, and whether it's selected The Layer trait defines properties related to the state of that Layer The Text Label trait returns the value of the label as a property The Marker trait allows you to define your own static properties The Dynamic Property trait allows you to define your own changeable properties. The Mark When Moved trait sets a property when a piece has moved The Mask trait sets a property when the piece is masked The Invisible trait sets a property when the piece is invisible The Property Sheet trait exposes a set of user-editable properties.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Marker

Marker

Page 75: VASSAL Reference Manual

A Marker is used to mark a game piece as having a particular Property. Setting a property does not in itself give a game piece any particular behavior. The property must be recognized by some other class in the module. Markers are used by Global Key Command and Game Piece Layers components and often by custom Java classes used in a module.

You can combine multiple name-value pairs by separating the names and values with a comma (','). To use a comma in a name or value, preceed it with a backslash ('\').

EXAMPLE: A Marker with property name "owner" and property value "sigmund" would return "sigmund" from getProperty("owner"). Use commas to set multiple properties with a single Marker. A Marker with name "owner,status" and value "sigmund,unknown" would also return "unknown" from getProperty("status").

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Property Sheet

Property Sheet

Page 76: VASSAL Reference Manual

This trait attaches an arbitrary set of editable properties to a Game Piece.

Menu Text and Keystroke specify the name of the menu item and keyboard command to show the properties window during play.

When a player edits the properties window during play, there are three methods for commiting changes:

1. Commit on Every Keystroke - Every keystroke and tick-mark click you make are immediately commited as you make them. Other players see your changes immediately.

2. Commit on Apply Button or Enter Key - Changes are not communicated to other players until you press the APPLY button at the bottom of the property sheet, or press the ENTER key on your keyboard, or close the Property Sheet window.

3. Commit on Window Close or Enter Key - Changes are not communicated to other players until you press the ENTER key or close the Property Sheet window.

You may customize the background color of each PropertySheet window, for example to use different colors for the pieces belonging to different sides.

You may select from 8 different formats in which to display properties:

Page 77: VASSAL Reference Manual

1. Text - A simple, single-line field that accepts text. 2. Multi-line text - A field that accepts multi-line text. This type of field stretches to fill extra space on the property sheet window. It is suitable for free

form notes. 3. Label Only - This is not really a property, it simply adds text to your property sheet. It is useful for documenting your property sheet. 4. Tick Marks - Displays one or more rows of checkboxes. Suitable for tracking ammo or damage. Players specify a current and maximum value range. 5. Tick Marks with Max Field - As above, but the maximum value is displayed in an editable field to the left of the checkboxes. Suitable for Role-Playing

games where damage-tracking is based on a character attribute that is also important. 6. Tick Marks with Value Field - As Tick marks, but the current value is displayed in an editable field. Suitable for large-value properties where clicking ticks

might be impractical and when the exact tick value is important. For example weapons that track 100+ rounds of ammo. 7. Tick Marks with Value & Max - As Tick marks, but both current value and maximum values are editable. 8. Spinner - A numeric property that includes increment and decrement buttons.

Here's an example of using PropertySheets to maintain character fighting stats, demonstrating the Tick Marks, Text, Spinner, and Multi-line text types.

Using Tick Marks

Page 78: VASSAL Reference Manual

Tick Mark property types have a value and a maximum.  Either, both, or neither may be displayed as a text box in addition to the tick marks.  Initially, the maximum and value are both 0, so no tick marks appear.  To set the value and/or maximum when the box is not shown, right-click in the area where the tick marks would appear.

VASSAL Reference ManualHome > Module > Prototypes

Prototypes

Most games have many counters that look different but behave very similarly. Prototypes are a method of using templates to vastly simplify the definition of most game pieces. The module author first defines a Prototype as a set of traits, then uses it in the definition of other game pieces. If the module author needed to change to a unit definition, such as using a different graphic for a layer trait, the author needs only to make the change in the prototype definition, instead of making the change in each individual game piece definition. Any number of Prototypes may be used within the same piece.

Once a piece based on a Prototype has been created during a game, it loses memory of being based on that prototype. Therefore, the definition of the prototype can change in a later version of the module without invalidating saved games from previous versions. All pieces in a Game Piece Palette, At Start Stack, or Deck will reset when a prototype definition changes while editing a module.

Page 79: VASSAL Reference Manual

If you want your pieces in the palette to start in a certain state, then you can edit the traits that appear in this prototype by right-clicking in the area below the name. You may need to resize the window to expose that area.

Sub-Components

Definition

The dialog for defining a prototype is just the same as for defining a Game Piece, but with a name and without the innermost Basic Piece. Prototypes may contain other prototypes.

VASSAL Reference ManualHome > Module > Map > Board > Rectangular Grid

Page 80: VASSAL Reference Manual

Rectangular Grid

A standard rectangular grid for regulating movement on a Board.

X,Y offset: The horizontal and vertical position of the center of the first cell of the grid

Hex Height/Width: in pixels of a single cell.

Legal Locations: Determines whether pieces can be placed on cell edges or corners, instead of only at cell centers.

Show Grid: If checked, then the grid will be drawn over the Board image using the specified color.

Sub-Components

Grid Numbering

Used to assign names to cells on the grid. Used primarily for automatically reporting moves.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Replace With Other

Page 81: VASSAL Reference Manual

Replace With Other

A Game Piece with this trait will have a menu command that replace this piece with a different piece. You can select any existing piece for the replacement or define a new one from scratch.

Horizontal offset: The replacement will be placed this many pixels to the right of the original piece.

Vertical offset: The replacement will be placed this many pixels above the original piece.

Match Current State: If selected, VASSAL will attempt to put the replacement piece in the same state as the original piece. Layers will be set to the same level, labels will be given the same value, rotation angles will match, etc. The state of a particular trait will carry over only if it has an exact match in the replacement, i.e. the properties settings of that trait are the same in both the original and replacement piece.

EXAMPLE: A unit that can be destroyed but still leaves a wreck behind can be given this trait to turn it into a wreck. This is more convenient than dragging a new piece from the Game Piece Palette and can't be accidentally undone, as a Layer triat could.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Report Action

Report Action

Page 82: VASSAL Reference Manual

A Game Piece that has this trait will report a configurable message to the main controls chat window when any of a given set of key commands are entered.

Report on these keystrokes: Specifies the keys that this trait will respond to. Hit the Add button to specify more than one key.Cycle through different messages: If left unchecked, the same message will be reported whenever any of the above keys are pressed. If checked, the message to be reported will cycle through the list specified below. Each time one of the keys if pressed, the next message in the list will be reported, returning to the beginning after the end is reached. Report Format: The Message Format for reporting non-cycling messages: menuCommand is the name of the piece's right-click menu command that corresponds to the control key pressed, oldPieceName is the name of the piece before the action is applied, newPieceName is the name of the piece after the action is applied, mapName is the name of the map where the piece is located, oldMapName is the name of the map before the action, location is the map location where the piece is located, oldLocation is the location before the action is applied. Note: if a piece is deleted or replaced as the result of an action, then the value of oldLocation and oldMapName will depend on the order of the traits, while mapName and location will be blank.

Message Formats: a list of Message Formats for cycling messages. Available variables are the same as above. Any Properties defined on the piece will be substituted. To access the value of a Property before the change, add old to the name. For example, if a piece has a property hitPoints, then $hitPoints$ gives the value after the key command and $oldhitPoints$ gives the value before.

Report previous on these keystrokes: When any of these keys are pressed, the message reported will be the one the preceeds the last reported message, instead of the following one.

EXAMPLE: A unit named 'Infantry' has a single layer that is activated with a CTRL-F "Flip" command. By adding a Report Action trait with report key 'F' and message $newPieceName$ flips in $location$ the chat text will echo "Infantry flips in A9" whenever a player flips the unit.

Page 83: VASSAL Reference Manual

EXAMPLE: If the unit above has the Can be Invisible trait activated by CTRL-I, then an additional Report Action trait with report key 'I' and two cycling messages $oldPieceName$ goes invisible in $location$ and $newPieceName$ revealed in $location$ will report when the unit becomes invisible/revealed.

EXAMPLE: If the counter above has the Can Rotate trait with 4 facings controlled by CTRL-] and CTRL-[, then an addition Report Action trait with report key ']' and report-previous key '[' and cycling messages $newPieceName$ rotates to face North, etc., will automatically report the appropriate facing.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Restricted Access

Restricted Access

Specify the side to which this piece belongs in the Properties of this trait. The sides must be one of those listed in the Definition of Player Sides. Only players playing one of the specified sides will be able to modify this GamePiece. Other players will not see menu items corresponding to traits appearing before this trait in the list of traits for the Game Piece, and the corresponding keyboard commands will do nothing.

Pieces in a Game Piece Palette can be manipulated by anybody so long as no game is in progress.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Return to Deck

Page 84: VASSAL Reference Manual

Return to Deck

The 'Return to Deck' trait adds a menu entry to a piece's right-click menu. Selecting that entry will place the piece in a Deck. If there is only one Deck in the module the piece will be added to it. If the module has more than one Deck, you may select the Deck that the piece will be placed in.

EXAMPLE: For a game in which cards are drawn from a deck, used, and placed into a discard pile, both the deck and the discard pile will be represented by a Deck component. By adding a Return to Deck trait to each card, with the text 'Discard' and the command 'D', then hitting CTRL-D on any card will automatically send it to the discard pile.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Can Rotate

Can Rotate

This trait allows a piece to be rotated through an arbitrary number of facings.

You can choose the number of valid facings. For example, a hex-based game may have 6 (or possibly 12) possible facings, while a game with a square grid game might have 4 or 8.

Alternatively, you can allow any arbitrary facing. In this case, selecting the 'Rotate' command will change the cursor and let the user drag the cursor to select the facing of the piece interactively.

Page 85: VASSAL Reference Manual

An optional additional command will rotate the piece to a random facing (in one of the valid facings, if applicable)

The "Can Rotate" trait will rotate only those traits that appear above it in the list of traits for a Game Piece. Traits below the "Can Rotate" trait will be drawn on top of the rotated image.

NOTE: Since the rotations are created on the fly from a bitmapped image, the image quality of a rotated counter may be lower than the unrotated version. You may get better image quality for your rotations by creating separate images for each rotation in an external paint program (If your images are based on vector objects, you can rotate them without degrading quality.) and putting them into different levels of a Layer.

VASSAL Reference ManualHome > Updating Saved GameS

Updating Saved Games

When a game is saved using one version of a VASSAL module, and then re-opened using a later version, the game pieces retain the original behavior, even if the piece has changed in the Game Piece Palette. This is necessary for modules to be backward-compatible with old saved games. This dialog allows you to update a game saved with an older version of a module to use the corresponding piece definitions in the current version. This is particularly useful to avoid having to recreate Predefined Setups from scratch.

To update a saved game, you must first import the GamePiece information from the earlier module version. Open the earlier version in the VASSAL editor, bring up this dialog and export the GamePiece information to a file. Then close VASSAL, load up the current module version in the

Page 86: VASSAL Reference Manual

VASSAL editor, and import the GamePiece information from the older version.

You can select any number of saved game files in the same folder to update at once. The files will be overwritten, so make backup copies first.

Under the covers, the updater works by matching each piece in a saved game to the component in the Game Piece Palette or Deck that it came from.  The piece is then replaced with the piece defined in the corresponding component in the current version. The Text Labels, Layer activation, rotation, etc., of the original piece is preserved as well as possible, but it is generally a good idea to load the updated games and give them a sanity check before releasing.  If the component that produced a piece no longer exists, the piece is untouched, so the updater won't work well if the Game Piece palette has been re-arranged significantly. .

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Send to Location

Send to Location

The 'Send to Location' trait adds a menu entry to a piece's right-click menu. Selecting that entry will transport the piece to a particular location on a Map. If no Map is selected, the piece is sent to that location on its current map. If a board is specified, the location is relative to that board. Otherwise, it is an absolute location in the map window. The piece will be combined into a Stack with any pieces at the location, if applicable.

EXAMPLE: A game may require that damaged units are returned to their home base for repairs. A game piece may be given a 'Send to Location trait with name 'Return to Home' and command CTRL-H and location corresponding to the base's position on the map.

Page 87: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Map > At-Start Stack

At-Start Stack

An At-Start Stack is an ordinary stack of playing pieces that is initialized at the beginning of every game. It is appropriate for any fixed pool of counters. Once the game begins, the pieces are in place just as if they had been dragged from the Game Piece Palette, except that no more can be created during the course of the game.

Name: The name is not used during game play. It is just used for identification in the module editor.

Belongs to board: If a name is selected, the stack will appear on that particular Board. If a game does not use that Board, then the stack will not appear. If "<any>" is selected, then the stack will always appear at the given position, regardless of the boards in use.

X,Y position: The position in the Map Window of the center of the deck. If this stack belongs to a Board, the position is relative to the Board's position in the Map Window. EXAMPLE: A strategic game in which a nationality has a fixed force pool of Infantry, Armor, etc. counters can be modeled by making a Map Window representing the force pool, with an At-Start Stack of Infantry counters, an At-Start Stack of Armor counters, etc. In order to guarantee that the number of each type of counter is fixed, the Clone and Delete functions of the Infantry and Armor counters should be disabled.

Page 88: VASSAL Reference Manual

Sub-Components

Single Piece

An At-Start Stack can contain any Game Piece.

VASSAL Reference ManualHome > Module > Symbolic Dice Button

Symbolic Dice Button

A Symbolic Dice Button is used to define dice that use arbitrary images. Each button can roll several dice (represented by Symbolic Die components), each of which may have any number of faces (represented by Symbolic Die Face components). When the button is pushed, a random face is selected for each Symbolic Die that this component contains. The results of the roll can be reported as text into the chat area, or graphically in a separate window or in the button itself.

Name: The name of the dice buttonButton Text: Text for the button in the main controls toolbar buttonHotkey: Keyboard shortcut for rolling the diceReport results as text: If true, report results to the chat areaReport format: AMessage Format specifying the format for reporting text results: name is the name of the button as specified above, result1, result2, etc is the result of the 1st, 2nd, etc. Symbolic Die as configured below (replace the '#' symbol with the desired number), numericalTotal is the sum of the numerical values of the Symbolic Die rolls.Show result in window: If true, show the results graphically in a standalone window.Window title format: AMessage Format specifying the format for reporting results to the titlebar of the standalone window.

Page 89: VASSAL Reference Manual

Show result in button: If true, show the results graphically in the toolbar button.Width: The width of the area for displaying results graphically.Height: The height of the area for displaying results graphically.Background color: The background color to be used when displaying results graphically.

Sub-Components

Symbolic Die

Name: The name of the dieResults format: A Message Format specifying how to report the result of this die roll. The resulting text will be substituted for result1, result2, etc in the Symbolic DiceButton's results format: name is the name of this die as specified above, result is the text value of the Symbolic Die Face that is rolled, numericalValue is the numerical value of the Symbolic Die rolled.

Symbolic Die Face

Each die face contains a text value, a numerical value, and an image.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Spreadsheet

Page 90: VASSAL Reference Manual

Spreadsheet

This trait attaches an editable table of data to a Game Piece Specify the number of rows and columns in the table, the keyboard command, and name of the item in the popup menu.

To initialize the values in the table, select the piece in the Game Piece palette (or the properties window for the piece), type the spreadsheet command and enter the starting values.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Sub-Menu

Sub-Menu

This trait allows you to cluster menu items associated with other traits into a sub-menu of the game piece's right-click menu. Provide the name of the menu and the name of the menu items that should be moved to the sub-menu. Sub-menus may contain other sub-menus to any nesting level.

Example: If a game piece has three separate layer traits with corresponding activate commands Entrench, Fortify, and Blockade, then those menu items can be gathered under a single sub-menu named Defense by creating a Sub-Menu trait with menu name "Defense" and sub-commands "Entrench", "Fortify" and "Blockade".

Pieces in a Game Piece Palette can be manipulated by anybody so long as no game is in progress.

VASSAL Reference Manual

Page 91: VASSAL Reference Manual

Home > Module > Toolbar Menu

Toolbar Menu

The Toolbar Menu component lets you group buttons from the toolbar of the main controls window or a Map window into a drop-down menu. Each button named in this component will be removed from the toolbar and instead appear as a menu item in the drop-down menu.

Button Text: The text of the button to be added to the toolbar. Pressing the button will reveal the drop-down menu.Button Icon: Icon for the toolbar button.Hotkey: Keyboard shortcut for revealing the drop-down menu.Menu Entries: Enter the text of the buttons that you wish to move to the drop-down menu. The menu item will have the same text. If the button uses an icon, the menu item will also use it.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Trigger Action

Trigger Action Trait 

Page 92: VASSAL Reference Manual

This trait alters the behavior of a piece, but not its look.  Using it, you can combine multiple keyboard commands into one, or automatically fire keyboard commands in response to other keyboard commands when certain conditions apply.

Trigger Name: Short name for identification purposes.Trigger when properties match: The corresponding key commands will be performed only if the piece matches this Property expression (after the triggering keyboard commands have finished)Menu Command: Adds an item to the piece's right-click menu that will fire the triggered commands (provided the property expression is matched).KeyStroke: The keyboard command corresponding to the menu item.Watch for these Keystrokes: After the user types any of these key commands, fire the triggered commands if the property expression is matched. Perform these Keystrokes: The key commands to invoke after one of the above key commands is observed and the property expression is matched.

Example: A piece has a Layer to track action points and a Move Fixed Distance trait to move it forward. The Move Fixed Distance trait can be assigned the key command CTRL-SHIFT-M with no command name (so that it does not appear in the right-click menu). Then a Trigger Action trait with the command Move and the keystroke CTRL-M can trigger both the Move command and decrease the action points layer by one.

Example: A piece has separate Layer traits for hit points and for a "critically wounded" status for when the hit points are less than 2. A Trigger Action triat can watch for the keystrokes that affect the hit-point layer and respond by activating the wounded layer by matching the property expression for when the hit points are < 2 and the wound level is not active.

VASSAL Reference ManualHome > Module > Game Piece Palette > Game Piece > Prototype

Page 93: VASSAL Reference Manual

Prototype

A Prototype is a set of common traits that can be shared. To use the prototype, simply type the name of a prototype that has been previously defined. A Game Piece may contain any number of Prototype traits in any order.

EXAMPLE: A Prototype named "Vehicle" can be defined with "Can Rotate" "Text Label" and "Can be Marked Moved" traits. Any counter can use these traits by using a Prototype trait and specifying "Vehicle" as the name. If the module author later decides that vehicles should also have another trait, it need only be added to the Prototype definition.

VASSAL Reference ManualHome > Module > Map > Board > Multi-zoned Grid

Multi-zoned Grid

A multi-zoned grid allows you to define any number of sub-regions of a board. Each sub-region, called a Zone, can have its own grid and naming format, which takes precedence over the default grid. For example a board with a hex grid may have zones along the edge for a turn track or force pools. Pieces will snap to positions in the appropriate zone and auto-reporting will use text supplied by the zone.

Page 94: VASSAL Reference Manual

Sub-Components

Zone

Each zone can have an arbitrary shape, which you specify in the Define Shape dialog. Each zone may define its own grid. When defining a zone's grid, the offsets and numbering are relative to the edge of the overall board, not the zone's edge.

Name: The name of the zone.

Location Format: A Message Format that will be used to define the location of a point for auto-reporting of moves: name is the name of this Zone, gridLocation is the location name according to this zone's grid.

Define Shape: Hit this button to bring up a dialog for defining the shape of this zone. To create the initial shape, drag the mouse to define a rectangle. Then right-click to add new points and use the mouse to drag points to their final locations. Delete a point by clicking on it and hitting the DEL key.

Use board's grid: If selected, then this Zone will use the grid from the containing board instead of defining its own grid.

If a given point does not fall within any of the defines Zones for a Multi-zone grid, the default grid is used. The default grid may be any of the usual types of grid:

Hex Grid

Rectangular Grid

Irregular Grid

Page 95: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Map > Board > Hex Grid

Hex Grid

A standard hexagonal grid for regulating movement on a Board.

Sideways: Check this box to make the hexrows of the grid run right-to-left instead of top-to-bottom. (Setting the grid to be sideways switches the meanings of horizontal/vertical and x/y below.)

X,Y offset: The horizontal and vertical position of the center of the first hex of the grid

Hex Height/Width: in pixels from hex center to hex center. If you specify only the height, the width will adjust, or you can create oblong hexes by also specifying a width

Legal Locations: Determines whether pieces can be placed on hex edges or corners, instead of only at hex centers.

Show Grid: If checked, then the grid will be drawn over the Board image using the specified color.

Sub-Components

Grid Numbering

Page 96: VASSAL Reference Manual

Used to assign names to hexes on the grid. Used primarily for automatically reporting moves.

VASSAL Reference ManualHome > Module > Map > Board > Rectangular Grid

Rectangular Grid

A standard rectangular grid for regulating movement on a Board.

X,Y offset: The horizontal and vertical position of the center of the first cell of the grid

Hex Height/Width: in pixels of a single cell.

Legal Locations: Determines whether pieces can be placed on cell edges or corners, instead of only at cell centers.

Show Grid: If checked, then the grid will be drawn over the Board image using the specified color.

Sub-Components

Grid Numbering

Used to assign names to cells on the grid. Used primarily for automatically reporting moves.

Page 97: VASSAL Reference Manual

VASSAL Reference ManualHome > Module > Map > Board > Irregular Grid

Irregular Grid

An irregular grid is used for area-based games. It allows you to define a set of named regions at arbitrary locations. When moving pieces on a board with an Irregular Grid, they will snap to the nearest region location.

Draw region names: If checked, the names of the regions will be drawn on the map.

Font size: The font size used to draw the names.

Define Regions: Hit this button to bring up a window for defining the regions. Right-click anywhere on the board to add a new region, or right-click on an existing region's name to change its name or remove it.