Creating Modules

=Creating VASSAL Modules=

Re-organization of this FAQ section
Starting to get a bit long here, I plan to re-organise this page into sub-pages. Suggest categories:
 * Questions about Maps and Grids.
 * Questions about Counters and traits.
 * Questions about decks (or does this overlap counters?)
 * Graphics and image questions (overlaps with maps & grids?)
 * General Questions

I want to make a module for such and such a game. Am I allowed to?
Legally, to post a module onto the VASSAL site you need the permission of the copyright holders of the original game. Many module creators now try and identify and contact the copyright holders and ask for permission. This can be difficult at times.

Theoretically, if you create the module for your own use and for distribution to only people who you know also own the game, then you possibly do not need permission. This point of view is open to argument.

If no repsonse is recieved from the copyright holders, or they cannot be identified, an often followed course of action is to inform the copyright holders (as best you can), that you accept their silence as tacit approval and post the module for general distribution, with the understanding that the module will be removed should the copyright holders wake up and request it to be removed. Rodney has a policy of removing modules from the VASSAL site when requested by the copyright holder.

How do I align the Vassal hex grid with my scanned mapsheet?
These descriptions assume the grid is sideways. Slightly different procedure for a normal grid.
 * Work on one axis a time.
 * Draw the grid and center dots in red so they stand out.
 * Change Hex height up/down bit by bit until the grid hexes are approximately the same width as the map hexes.
 * then adjust the y offset to get them lining up closely.
 * then fine tune the hex height. Look at a couple of hexes, are the red hexes slightly bigger or slightly smaller? Look at the pattern over a few hexes to tell for sure.
 * Fine tune the y offset.
 * Up till now, completely ignore the x offset and hex width.
 * Now with the Hex height and the y offset set, use the same procedure on the Hex width and the x offset. Leave the Hex height and y offset unchanged while you work on the Hex width and x offset.
 * Adjust the Hex width until you get a repeating pattern showing the hexes are about the same size.
 * Adjust the x offset to get the pattern in the right place.
 * fine tune.

The key is to always adjust the Hex height and y offset first and get that right before doing anything with the width and x offset.

I have an Area Movement map, how can I implement that in vassal?
To implement an Area Movement map, use an 'Irregular' grid on you Map boards. An Irregular grid allows you to place named points (termed 'Regions') anywhere on the map board. These named points will act like the cell centre points on hex or rectangular grids. Units can be made to snap to the nearest named point. Unit location will be reported as the nearest named point.

For maps with very irregular shaped areas, you may need to specify more than one point in each area, each with the same name. These additional points will be invisible if you turn the 'Snap to grid points' and 'Draw region names' off.

It is also possible to implement an Area Movement map using Zones drawn to cover the map areas. This method is not recommended for large numbers of Zones.

How can I have areas on my map with a different Grid setting?
Multiple Grids are added using Zones. Grids are added at the Board level, not the Map level, so need to be set on each Board that makes up your map. Follow this procedure for each Board:
 * 1) First create a 'Multi-zoned Grid'.
 * 2) Next, create your standard Hex, Rectangular or Irregular grid that covers most of the board. This is the 'default' or 'background' grid that will be used for all areas of the Map not covered by a Zone.
 * 3) For each area of the Board that is to have a different Grid, create a Zone. Don't click the 'Use Board's grid' button as this will force the Zone to use the grid you specified in step 2.
 * 4) Right-click on the newly created Zone and you can now add a Hex, Rectangular or Irregular grid that will apply only within that Zone.
 * 5) If Zones overlap at a given point, the Zone defined first in the module will take precedence at that point.

Why doesn't trait X work correctly?
See next entry.

How come the mask trait doesn't hide Y?
The most common reason that a trait doesn't affect things the way you expect it to is because it isn't in the correct order in the traits list. Many messages reporting bugs and module problems that all stem from the same basic misunderstanding about the way that counter traits work.

The Three most important things to remember when setting up traits in a counter are

LOCATION, LOCATION and LOCATION!

The order of traits is VITALLY important. This needs to be engraved on the forehead of every budding VASSAL module designer.

Each trait is only affected by other traits that are BELOW it in the expanded list of traits after taking prototypes into account.

If you want Text Labels to Rotate, then the Text Label trait must be ABOVE the Rotation trait. If you don't want your Text Labels to rotate, then they must be BELOW the Rotation trait. You need to think about each trait, how it affects the counter and whether it should affect, or be affected by other traits that affect the counter.

This is a FEATURE, not a BUG. You can't just blast in the traits you want in any order and expect them to work. You can't move a trait from one prototype to another and expect it work in exactly the same way (though it may). You need to take into account the order of all traits in all prototypes after they have all been expanded.

Thanks to Brent Easton

My Rotate trait is not rotating all of my layers, what's wrong?
You probably have a problem in the order of the traits defined in your counter.

The order of the Traits in a counter is vitally important in vassal. This is a very important aspect of the way the Vassal works. Any given Trait will affect all other traits above it on the list, but does not affect any traits below it on the list. See previous entry.

Why do I get large selection boxes when using Masks and Movement Trails?
Because the Mask is being applied to the Movement Trails, which generate a bounding box to cover the entire trail. Moving the Mask trait above the Movement Trail trait on the trait list should cure this problem.

How to restrict access to a trait while allowing drag'n'drop operations on the gamepiece?
Basically a restrict access trait effects all traits above it. However the gamepieces drag'n'drop mechanisms do work differently: They honor the bottom most restrict access trait. Here's a solution that works for the Downtown module:
 * Basic Piece
 * Trait to be protected
 * Restricted Access - Side(s) that may use trait
 * Restricted Access - All Sides that may move the gamepiece

What 'system' properties are returned by counters?
The new Properties Filter in the GlobalKeyCommand allows you to select units based on Marker properties. Are there any 'system' properties that counters return that can be used in the same way?

All counters will return the following properties:-

 Invisible: "true" if this piece is Invisible to the current player. InvisibleToOthers: "true" if this piece is Invisible to other players. Obscured: "true" if this piece is masked to the current player. ObscuredToOthers: "true" if this piece is masked to other players. Immobile: "true" if this piece is an immobile Terrain piece. IgnoreGrid: "true" if this piece ignores the map grid. NoStack: "true" if this piece does not stack with other pieces. Selected: "true" if the piece is currently Selected. Restricted: "true" if there are restriction as to who can access this piece. Moved: "true" if the piece has moved. LocationName: Current Location Name of piece as displayed in Chat Window. CurrentMap: Current Map name or "" if not on a map. CurrentBoard: Current Board name or "" if not on a map. CurrentZone: If the current map has a multi-zoned grid, then return the name of the Zone the piece is in, or "" if the piece is not in any zone, or not on a map. DeckName: Current Deck name, or "" if not in a Deck. CurrentX: Current X Map co-ordinate of the piece. CurrentY: Current Y Map co-ordinate of the piece. OldLocationName: Location name of the piece prior to last movement. OldMap: Map name prior to last movement. OldBoard: Board name prior to last movement. OldZone: Zone name prior to last movement. OldX: Map X co-ordinate prior to last movement. OldY: Map Y co-ordinate prior to last movement. PieceName: Full name of the piece as reported in the Chat Window. BasicName: Name of the piece recorded in the BasicPiece trait. PlayerSide: Side of the current player (not side of the piece).

Different counter trait's will also return properties:

PropertySheet:  : The value of each property on the Property Sheet can be accessed via the property name.

Layer:   _Image: The Image Name of the currently active layer for Layer.  _Name: The Lavel Name of the currently active layer for Layer.  _Level: The level number of the currently active layer for Layer.  _Active: "true" if the Layer is currently active.

Can Rotate:   _Facing: The Current Facing number (1, 2 etc.) for the Can Rotate trait.  _Degrees: The Current Degrees of rotation for the Can Rotate trait.

Decks also have map-level properties that you can reference:   _numPieces: The number of pieces in the deck.  _: The number of pieces for which the named expression evaluates to true in the deck.

When Do I Need "$" in Property Comparisons?
Have a look at the example in the reference manual:

Hitpoints_Level < 2 && Wound_Active != true

No $ signs. The left side of the comparison is always treated as the name of the property. So it doesn't need $ signs.

You use the $ signs in two situations:

1. To compare a property to another property, use the $ signs in the second (right side) part. The $ signs are needed to show that you want the value of a property rather than testing against a literal string. For example: Rand5_result = $Another_property$

2. To use indirection, where one property contains the name of a property to compare. If the property "prop1" has a property name as a value, then to compare the value of the property contained in "prop1" to a value, use $ on the left side:

$prop1$ = 2

when Property prop1 contains the name of the property we want to compare to 2. So, for example, if "prop1" had as its value "strength", then the expression above would be true if the value of the "strength" property was equal to 2.

This will work in Vassal version 3.1 and higher.

Why do my cards disappear in a deck?
Whenever I try to add one or more cards to the deck, both the card AND the deck outline disappear, and there is no way to make them appear again.

This is a very common problem that reoccurs again and again with masked pieces, of which cards are one. The module designer forgets to provide a backside image for the piece or card. For masked pieces, you must edit the piece and examine the masked trait. You must provide an image for the reverse side of the card/piece. For cards, you would need an image of the back side of the card (ideally, the same dimension as the card face image), which you specify in the mask trait. You can also specify how a facedown card appears to the player who owns the card.

If you omit the back image in mask, then when the card is flipped over (as it happens when it goes to a deck), it disappears.

How do I send a card to the bottom of the deck?
The "Down Arrow" command sends a selected counter to the bottom of the Stack, but if sent to card in a Deck, it will send it to the bottom of the Deck. So, to send a card to the bottom of the deck use a trigger that
 * 1) issues the "Return To Deck" command
 * 2) issues the "Down Arrow" command (Just press the down-arrow key in the 'Perform these keys' section.)

What's so good about prototypes anyway?
If you design your module carefully from the start to use Prototypes, I guarantee you will save yourself much heartache and MANY, MANY hours during on-going development and maintenance.

Do not even consider starting a new module without using prototypes. I just can't stress this strongly enough!

A prototype is just a set of gamepiece traits that can be shared between the counters you define in your gamepiece palletes. As a general rule, if I have any trait that is common between more than 1 unit, I put it in a prototype and add the prototype to the units instead.

Say every counter in your module uses the 'Delete' trait. Just create a 'Game Piece Prototype Definition' called, say 'BasicUnit'. Add the Delete trait to to 'BasicUnit'. Now when you create each unit, add the Prototype trait 'BasicUnit' to each unit. Now, when each unit is created, it will get the Delete trait defined in the prototype.

If you suddenly decide that every unit needs the Control key for Delete changed from 'Ctrl D' to 'Ctrl X', you just change it in the 'BasicUnit' prototype.

If then decide that every unit also needs the ability to have the players add a label, then just add a 'Text Label' trait to 'BasicUnit' and voila, every unit will have text labels.

Prototypes can contain prototypes and Units can contain multiple prototypes, so it allows you to create a hierachy of levels that contain the behaviours of your counters. eg. you might have prototypes for 'Allied', 'Axis', 'BasicUnit', 'Infantry', 'Artillery', 'Vehicle' and perhaps 2nd level prototypes

e.g. 'AlliedInfantry' = 'Allied' + 'Infantry + 'BasicUnit'

IMPORTANT - Once a unit has been created and is on a Map, the prototypes that created it no longer have any effect. You cannot change the properties of units on a Map by changing prototype definitions. These only effect units yet to be created!

How do I set the state of counters in the GamePiece Palette that use prototypes?
If you want your pieces in the palette to start in a certain state, then in general, you can use key commands to put them in that state while you're editing the module and save. However, if the pieces use prototypes, then the palette always loads with the default state of the prototype. To solve this, you can change the state of a trait within the prototype itself, rather than within each piece that uses it. In the properties of the Prototype, just right-click in the area immediately below the name of the prototype (where the view of the generated counter is displayed) to modify that traits in thePrototype.

Here's the annoying part. If the prototype doesn't use any images, the space where you need to right-click has zero height. Try resizing the window to make it taller and it should appear as a white background.

How do I have Movement Trails turned on permanently?
Marking a unit 'Not moved' does not actually turn Movement trail display off, it actually sets the visibility of the trail to the start setting for the unit. This is controlled in the Movement Trail trait, by selecting 'Trails start visible'. These units will now start with the movement trail visible and marking them as Not Moved will actually turn trail display on! If you want to turn trail display permanently on, then just select 'Trails start visible' for each unit and removed the Control key. Marking a unit as moved still clears the current trail, but display is left on.

Is there a setting to make a piece always be at the top of any stack?
There are two ways to approach this. You can use the 'Does Not Stack' trait with the 'Never' option to force a particular piece to be always on the bottom of any stack and not selectable. Good for terrain type pieces. Add a 'Game Piece Layers' component to your Map to separate counters into non-stacking layers.
 * Does Not Stack trait.
 * Game Piece Layers.

How do I implement Un-moveable terrain pieces that I can interact with?
//I'd like to create a game piece layer with a number of terrain-related counters. I'd like to be able to right-click these counters to access options to change their individual layers/appearance. However, I would like to make it impossible for players to accidentally move these counters and for the drag-select feature to ignore them.//

There are a couple of options.
 * 1) If you want the players to be able to manipulate the pieces, but not easily or by accident, give the terrain pieces the 'Does Not Stack' trait.
 * 2) If you want to make it so that players cannot manipulate the pieces at all during play, then you can do the following:
 * 3) Create your terrain overlays (or whatever they are) as actual basic piece counters. Then add the restricted access trait to the counter - assign the side to a fake player no one will use (i.e moderator). Place the piece on the board with an "at start stack trait"
 * 4) All other traits such as sub menus, layers can be placed in the counter below the restricted access trait in the stack and still function normally for any player, except now they cannot move the piece (unless of course they join the game as the fake player:)

Why does it take an extra step to rotate through game piece layers?
When you create additional Game Piece Layers, you are just creating additional Layers under the default 'top' layer. So if you create 2 layers A & B, you now have 3 layers in total :- A, B and default.

Rotating the Layers rotates through all 3 layers, even if there are no pieces on a given layer.

There is already an RFE in to add an option to the game piece layer controls to 'Skip empty layers'. This has not been done yet.

Thanks to Brent Easton

How do I delete a counter that does not have the Delete trait?

 * Save and close your game
 * Create a new Map called 'Trash' in your module and give it a blank board.
 * Load your game back up, open up the 'Trash' board and move the units you want to get rid of into it.
 * Go back to your Edit Module window and delete the 'Trash' Map
 * Save your game.

Here's another method:
 * Create a new version of the module and give the pieces you want to delete a Delete trait.
 * Use the Saved Game Updater feature to update the saved game containing the pieces you want to delete. This will give those pieces a Delete trait.
 * Load the updated saved game and delete the pieces.
 * Reverse the process if there are now pieces that should not have a delete trait.

I have an old module with Clone and Delete Traits built-in, how do I get rid of them?
Current method to add Delete and Clone functionality is to add a Delete or Clone trait to the counter, best via a prototype.

Old method was to put the Delete and Clone function keys directly into the Basic Piece trait. If you create a new counter now, there is no option to put Delete/Clone into Basicpiece anymore. But compatibility means that of the module was created with an old version of VASSAL and Delete/Clone where included in BasicPiece, then these will still appear and be active.

To remove the Delete/Clone option from the Basic Piece trait, just open up the Basic Piece trait and backspace over the the Control characters in the 'To Clone' and 'To Delete' fields so the fields are left blank, then save the trait. When you open the trait again, you will find the whole Delete or Clone option is now gone. Then you can add Delete and/or Clone trait's to only those counters that need them (i.e. usually just info markers).

How do I have Text labels with a Transparent background?
By clearing the current setting of the Background Color.

In the Text label trait, click on the Background Color 'Select Button'. Then click on the 'Cancel' button immediately. This will close the color selector and set the Background Color swatch to white. Transparent background color is now selected.

How can I have multiple colors, fonts, styles and line breaks in Text Labels?
Was looking at the VASSAL RFE list and came across one for asking for Bold, Italic, Underline etc. in text labels.

Started having a look at this and discovered that as text labels are implemented using JLabel's, they support HTML so you can actually do this already! Try changing the label on a unit to:

Not exactly user friendly, but it works and would be useful for setting up labels that do no need to be changed often. Unfortunately, Bold  does not work for the default Dialog font at size 10, but you can just bump the size up or do stuff like:

Which image format is best for my maps and counters, JPG, GIF or PNG?
PNG format is recommended. See why.

I load images from different directories, but they are overwriting each other in the module?
In VASSAL, all images will end up in a single folder in the zip file called 'images', regardless of where you load them from. If you have used the same names for different images, then the images loaded later would have overwritten the earlier images inside the module. You must ensure that different images have different names in VASSAL.

How do I get really small writing on my counters that looks good?
You can get text as small as depicted on the Sherman by hand drawing it, or by using a font which is legible at very small point sizes (5pt or 6pt).

The example uses a font named "Small Fonts" which was distributed with Windows 98. The free, open-source artwiz fonts are an excellent source of fonts legible at tiny sizes. When using fonts at very small sizes, be sure to turn off antialiasing in your drawing program, as this will only make them blurry.

Are there any free Graphics programs available?
VASSAL users have found the following free programs useful:


 * The GIMP
 * A full featured image manipulation program similar to Photoshop.


 * Inkscape
 * An vector image manipulation program, supporting the SVG format.


 * ImageMagick
 * A suite of extremely powerful command-line programs that can do just about anything to an image that Photoshop et al. can, plus many things that they can't. Great for applying transformations to many images in batches.


 * SplitImage
 * A useful utility for splitting counter sheets up into individual images. Windows only. CAVEAT: SplitImage has a bug that creates corrupted PNG images that cannot be directly loaded into VASSAL. You must load and save any image with another graphics program (e.g., GIMP or ImageMagick) to fix the image before loading into VASSAL.


 * OptiPNG
 * A small utility to make PNG files smaller. Also converts other bitmap formats to PNG.

How do I extract an image from a Powerpoint Presentation?
To save a whole slide: Open the powerpoint presentation and go the slide you want. Select 'File' -> 'Save As' and the change the 'Save as type' from 'Presentation (*.ppt)' to '(*.gif)' or (*.png) and save.

To save an individual slide element: Select the image or background to save and right click, select 'Save as Picture' and save it as a GIF or a PNG.

How do I get the Player Names to display in my movement reports?
In Global Options, make sure you have the 'Player Id Format' set up with at least '$playerName$'. If you are using Sides, then something like '<$playerName$[$playerSide$]>' is good too.

Then, in the 'Auto Report Format' boxed in your Map Window definition, include $playerId$ in the reports.

e.g. '$playerId$ $pieceName$ moves $previousLocation$ -> $location$ *'

You can also use $playerName$ and $playerSide$ directly, but the global Options let's you set up $playerId$ as a shortcut for a more complex id tag that can be used anywhere.

You probably also want to include $playerId$ in any 'Report Action' traits also.

How are Player Hands and Private Windows different?
Player hands are private windows with the addition that pieces are spread out like a hand of cards instead of a stack of counters.

How do I create a player who can observe all the private windows?
''How do I create a player who can observe all the private windows (each player will have the cards in his window) and protect that "master" player with a password? And to protect each window with a password?''

You can create the "master" player in the Definition of Player Sides, then list the master player as one of the owners of the private windows. When starting a new game, the first player to select the "master" side will be the master for the rest of the game, tied to his password in the preferences. If you never want anybody other than yourself to take the master side, create a Pre-Defined Setup from a saved game in which you have taken the master side. Then put the Pre-Defined Setup into the File menu in place of the normal New Game entry. The master side will be tied to the password you had when editing the file.

Can you have Pre-Defined setups and still have "New game" in the File menu?
Yes. It's an option in the Pre-Defined Setup properties. If you don't specify a saved game, it starts a new one like the normal 'New Game' command. Check the Reference Manual.

How do I show the number of items in a stack?
In the Mouse Over Stack viewer dialog box there is an check option for Display Text. Enable that and in the summary text select the sum(propertyname) option. From the manual: 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. So give each piece a marker trait property with a value of 1 and a name such as ArmyCount, then in the MOS viewer dialog, turn on the display text with the field saying

Thanks to Timothy McCarron

I have a Report Action that refuses to work!
In the Map configuration, check the field 'Auto-report format for units modified on this map'. This should be something like '<$playerId$> $message$'. This field controls the overall format of 'Report Action' reports for this map.The $messsage$ is replaced by the text generated by 'Report Action' trait. If this field is blank, 'Report Action' traits will never report anything on this map.

If you're giving the command while the piece is still in the palette, some of the text (having to do with location) may not appear because the piece isn't on a map. Otherwise, of course, you must drag a new copy of the piece to the map after making the change to the Report Action trait.

I have a great idea for an enhancement, but am not a programmer, what do I do?
Discuss the idea on the Forums and get other peoples ideas. Generate some energy. Work out as much detail as possible:- What buttons, windows, controls are needed? How do they interact with each other?

When you have a good feel for the structure of your enhancement, go to the Vassal page at the Sourceforge site and create a new Request For Enhancement (RFE) with your idea. Include as much detail as you can. Try and have a good idea of what the enhancement will look like, what commands/buttons/windows etc. it will need. This does not mean that your idea will get done, but it creates a central reference point for information and comments on your idea.

Two of the biggest time burners for developers are Analysis (Working out the details of what it needs to look like and it how it works from a high-level point of view) and Testing. Neither Analysis or Testing required programming experience and if you can make yourself available for these, you have a far better chance of getting a developer interested in your project.

How do I make my Module smaller?
Everything you ever wanted to know about trimming the fat from your modules' bulging waistline.

What can I do about OutOfMemory errors?
Color depth is the main culprit eating up memory in VASSAL. It doesn't matter what the image compression level is. You don't get savings unless you use a reduced color palette. Using the same palette for all your images will help as well. You can also get a benefit from reducing the number of colors used in your Display settings. For some reason a large image takes up more space than several smaller images, so you can break up large map images into smaller pieces. You can reassemble them as Boards using the default Board layout, so players need never know that the map's been broken up.

Why is the New Game Wizard Window so Big?
The size of the new game wizard window is determined by the size of the options in the drop-down menus and by the size of the splash screen. Use of an excessively large splash screen image can lead to a window that will not fit on all user's displays.

Developers: Please use a fairly small splash screen for your module. Also make sure that the names of sides and boards are not too long.

Users: If you find a module with a startup wizard screen that is too large, you can fix this by modifying the module. Unfortunately, you can't do this from the editor directly. You will have to open the module using a tool that can unzip the file and then delete the "Splash.gif", "Splash.png" or "Splash.jpeg" file from the Images subfolder. Then zip the file up again.

When I try to Import a Custom Class, nothing happens!
If the custom class generates an exception while being loaded, it will fail quietly and generate an error message in the Errorlog file. Check the following first: If the component still fails to load, then send a copy of your Errorlog file to the component developer.
 * You are using the correct spelling for the custom class (watch upper/lower case).
 * You are using '.' to separate components in the name, not '/' (i.e. 'Test.myComponent' not 'Test/myComponent').
 * Make sure you have loaded the class files into your module zip file.

How do I get the default Quick Start/User Guide/Splash screen back?
If you accidentally edit or delete the entries for the default Quick Start guide, VASSAL User Guide and the standard Splash Screen, you can lose the original settings and it is not possible to restore them through the module editor. To fix these, you will need to Edit your buildfile, find the appropriate lines and replace them with the default values:







What is the buildfile and how do I edit it?
The buildfile is a text file that describes the components of your module and how they fit together. A module file is just a zip archive, regardless of what it is called. You can open the module file using any standard tools for manipulating Zip atchives. If you are having trouble, try changing the name of the module file to .zip. You will find the buildfile inside the module archive at the top level. Extract it out and edit it with any standard text editor. After making changes, make sure you save it back as a text file. Then, copy the buildfile back into your module Zip archive and rename it back to its original name.

Here's an example of how to change all occurences of 'Activate Ctrl A' to 'Mode Change Ctrl Z':

//You can edit the buildfile if you are very, very VERY careful and take a backup before you start.

Inside your module, you will find a file called buildfile. It is a text file that describes the contents of your module.

Take a copy of this file and have a look at it, you will see the entire setup for your module.

Now, edit your module, choose two similiar counters and make the changes you want to make to one of them. Save the module. Copy the buildfile, edit it and find where these counters are defined. Look carefully at what has been changed from the unhanged unit to the changed unit.

It will be something like changing 'Activate;2;A' to 'Mode Change;2;Z' for the activate fix. Make sure you don't remove any of the ';' characters.

Use Edit/Replace in your editor to CAREFULLY make the same changes to all units.

Take a copy of your module.

Finally copy the modified buildfile back into your module and test.//