VASSAL Reference Manual

Home > Module > Map Window


Map Window


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 window
Mark 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 window
Can Contain Multiple Boards If checked, this map window can contain several boards arranged into rows and columns
Border color for selected counters The color of the border to draw around pieces that have been selected
Border thickness for selected counters The color of the border to draw around pieces that have been selected
Include 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 toolbar
Toolbar button name The name of the show/hide toolbar button
Toolbar button icon An icon for the show/hide toolbar button
Hotkey The hotkey for the show/hide toolbar button
Auto-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 mapmessage 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 boards
Cell 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.

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 window
Horizontal 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.

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.


 

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



Adds a tool that displays the contents of a stack when the player leaves his mouse resting over it. Alternatively, the user may choose to activate it by pressing CTRL-space. Delay before display sets the number of milliseconds the cursor must be stationary over a stack before the display pops up. Display Graphics and "Display Text" control visibility of the graphics and text parts of the display. The default viewer provides a panel of game piece images for the Graphics display and the name of the current map location for the Text display. By default, the viewer is not displayed for stacks consisting of only one game piece. This can be over-ridden using the two "... for single counter" options.

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.

Image Capture Tool

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 Button

Adds 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


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


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.