VASSAL Reference Manual

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