VASSAL Reference Manual

Home > Module > Turn Counter


Turn Counter

A Turn Counter places a button and/or widget on the Toolbar of the Module window which keeps track of the current turn/phase/sub-phase, etc. of a game. Players can advance the turn forward or backward, or optionally jump directly to a turn.

To add a Turn Counter to your module, right-click on the [Module] component at the very top of the Editor’s configuration window list, and select Add Turn Counter. Then, after configuring its fields appropriately, you will find your new component’s [Turn Counter] component entry at the bottom of the Module’s list of components. You can right-click on the [Turn Counter] component entry to add sub-components to represent levels within your Turn structure (see details and examples below).

TurnTrackerTurnWindow

TurnTrackerExample

The Turn Counter is defined as a series of nested levels, each represented by a sub-component of the Turn Counter. "Advancing the turn" moves the deepest level forward. When a level wraps around, the next level above it (but under the same parent) advances forward. When the last, outermost, child level has wrapped around, the parent level itself advances forward.

Example (see screenshots above and below): A level representing the Month may contain a level representing the Day, which in turn contains a level representing Morning/Evening. Advancing the turn moves from morning to evening, then to morning of the next day, etc. Configuration for this example can be seen in the various screenshots throughout this article._

Each level of the Turn Counter exposes its value as a module Property. A hotkey can be configured to fire when a certain combination of levels is reached.

The Turn Counter controls can be docked into the main Module Toolbar, or can be opened in a separate window that is shown/hidden via a button on the Toolbar. Whether the controls are docked is remembered in the player’s preferences.

Name:

A name for display in the Editor window

Description:

Optional description of the turn tracker. Never displayed to the player, this is more of a comment/documentation field for the module designer.

Button text:

The text of the Toolbar button to show/hide the controls when un-docked

Button icon:

Icon for the Toolbar button.

Show/hide hotkey:

Keystroke or Named Command to hide or show the Turn Counter window when un-docked.

Next turn hotkey:

Keystroke or Named Command to advance the Turn Counter one step. The turn can also be advanced by clicking the "+" button displayed to the right of the turn when the turn counter is visible.

Previous turn hotkey:

Keystroke or Named Command to return the Turn Counter to the previous step. The turn can also be moved back by clicking the "-" button displayed to the left of the turn when the turn counter is visible.

Turn name format:

Message Format to format the display of the current turn in the counter. All module-level Properties will be substituted. In particular, the properties exposed by any sub-components (Counters or Lists) can be used. In addition, the special properties level1, level2, etc. can be used to represent the values of the active Counter or List within the Turn Counter. Example: If the Turn Counter contains a Month level that contains a Day level, then level1 gives the value of the Month and level2 gives the Day. NOTE: As of VASSAL 3.6 updates to module properties caused by any global hotkeys issued by this turn tracker when changing turns will be properly registered in this display.

Report format:

Message Format to display a message in the Chat Log whenever the turn changes.

Turn label tooltip text:

Tooltip text for the Turn Display.

Turn label length:

Select from the drop-down the method that determines the length of the turn label:

  • Variable: The turn label will change size to suit the current length of the turn text.

  • Fixed: Enter a specific length in pixels.

  • Maximum: Use a fixed width that will hold the largest value possible.

Turn label display length:

Set the number of pixels wide the turn display label should be for the Fixed turn label length type.

Width of + and - buttons:

Width in pixels of the + and - buttons provided on the turn display.

Height of Turn Tracker widget:

Height in pixels of the turn tracker display. This can be used to help match your turn tracker to the heights of icons you are using on your toolbar.

TurnTracker

Module level defaults and preferences

The font size and style of the turn tracker, and whether the turn tracker docks to the module toolbar, are remembered in the user preferences. The initial default font size is normally 14 (non-bold), and the turn tracker does not dock into the toolbar by default. As a module designer you can override these default preferences for new users loading your module for the first time, by defining the following Global Properties: TurnTracker.defaultFontSize, TurnTracker.defaultFontBold, and/or TurnTracker.defaultDocked. For example, setting them to 18, true, true would mean new players loading your module for the very first time would see an 18 font size, bolded, and a docked turn tracker. Once these module defaults are initially loaded, they will thereafter follow the user’s preference settings.


Sub-Components

To add a new level to your Turn Counter, open the Editor and navigate to your [Turn Counter] component. Right-click on the [Turn Counter] component and select Add List or Add Counter , depending on whether you want the level to be a list (e.g. "Spring", "Summer", etc) or a numeric value (e.g. 1914, 1915, etc). You can then optionally right-click on the new [List] or [Counter] you’ve just added, to add another level beneath it, and so forth.

You can also add a Global Hotkey to your Turn Counter (see below).

List

A List is a turn level that cycles through a specified list of text strings.

Description:

A brief description of this turn level, which will appear in the Editor’s configuration window.

Property name:

The name of the global Property that will hold the value of this level. The Global Property will be updated whenever this level’s value changes.

Turn level format:

A Message Format that specifies how the value of the level1, level2, etc. property will appear in the Turn Counter’s Turn Name Format property.

List of items:

A list of text strings that the level will cycle through.

Allow players to hide items in this list:

If selected, then players will be allowed to disable items in this list at game time.

Allow players to change which item goes first:

If selected, then players will be allowed to change which should be the beginning item in the list, i.e. the item at which the parent level will be advanced.

Example: If a List represents sides in a game, but the order in which sides move is not always fixed.

TurnTrackerList

Counter

A Counter is a numeric turn level that advances by incrementing the value by a fixed amount. It can optionally loop around when it reaches its maximum value.

Description:

A brief description of this turn level, which will appear in the Editor’s configuration window.

Property name:

The name of the global Property that will hold the value of this level. The Global Property will be updated whenever this level’s value changes.

Turn level format:

A Message Format that configures how the value of the level1, level2, etc. property will appear in the Turn Counter’s Turn Name Format property.

Start value:

The initial/minimum numeric value.

Increment by:

The amount by which the numeric value increases when the level advances.

Loop:

If selected, the level will return to its starting value after reaching the maximum value.

Maximum value:

The maximum value, after which the level will loop.

TurnTrackerCounter

Global Hotkey

A Global Hotkey sub-component of a Turn Counter fires a Keystroke or Named Command whenever a certain state of the Turn Counter is reached.

Example: When the Refit phase is reached, a hotkey can fire that corresponds to the keyboard shortcut of a Global Key Command that removes all Damage counters from pieces on the map.

Description:

A brief description of this subcomponent, for display in the Editor’s configuration window.

Global hotkey:

The Keystroke or Named Command to fire. The module will respond exactly as if one of the players had pressed this key or selected a menu item corresponding to a Named Command.

Match properties:

A Property Expression that specifies when to fire the Keystroke or Named Command. If the expression is true after any level of the Turn Counter advances, the hotkey will fire.

Report format:

A Message Format that will be echoed to the chat log when the hotkey fires.

TurnTrackerGlobalHotkey