VASSAL Reference Manual

Home > Module > Global Properties and Scenario Options

Global Property

Properties are like variables in programming - they have a Value which can be used by referencing the Property’s Name. Properties can be attached to a Zone, Map Window, or Module. The Global Properties component is a container for all properties attached to a Map or the 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 value will come from the Zone occupied the by piece, the Map to which it belongs, or the Module overall, in that order.

A Game Piece can set the value of a Global Property with the Set Global Property trait.

To add a Global Property to your module, use the Editor’s configuration window to navigate to the [Global Properties] component, which is one of the top-level components of your module. Right-click on the [Global Properties] component and select Add Global Property. Your new Global Property will be added to the bottom of the list. You can follow a similar procedure to add a Global Property to one of your maps or zones — simply find the appropriate [Map] or [Zone] component and add to that.

Name:

The name of the property.

Initial value:

The value of the property at the start of a new game.

Description:

Short description of the property for your own reference.

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.

GlobalProperty

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.

To add a Change-Property Toolbar Button, locate the [Global Property] component which you wish to be able to change — in the Editor it will be inside the list of [Global Properties]. Right-click on the [Global Property] component and select Add Change-Property Toolbar Button.

Button text:

The text of the Toolbar button.

Tooltip text:

Text that appears when you hover the cursor over the Toolbar button.

Button icon:

The icon of the Toolbar button.

Hotkey:

Keystroke or Named Command 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.

ChangePropertyButton

Scenario Properties and Scenario Properties Option Tabs

Scenario Properties are a special kind of Global Property that have an associated preference setting and are grouped together in a tabbed dialog box accessible from the main Vassal File menu when a Vassal game is in progress.

ScenarioOptions1 ScenarioOptions2

Scenario Properties are defined by the Module Designer and create Global Properties that can be accessed by pieces in the module, but can be modified and optionally locked by players through a central user interface.

See the Scenario Properties page for more information.

Custom Code

Module custom code can read and modify a Global Property value. To get access to a Global Property named "PropertyName" you need to declare a variable as follows:

MutableProperty property = GameModule.getGameModule().getMutableProperty("PropertyName");

You can then get the value or set the value with:

property.getPropertyValue()
property.setPropertyValue()

You can also trigger events on the change of the global property with the following methods:

addMutablePropertyChangeListener()
removeMutablePropertyChangeListener()