VASSAL Reference Manual

Home > Module > Turn Counter

Turn Counter

A Turn Counter 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.

The Turn Counter is defined as a series of nested levels.  Advancing the turn moves the deepest level forward.  When a child level wraps around, the next child level under the same parent advances forward.  When the last child level has wrapped around, the parent level advances forward.

Example:  a level representing the Month may contain a level representing the Day, which contains a level representing Morning/Evening.  Advancing the turn moves from morning to evening, then to morning of the next day, etc.

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 Controls 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 controlled by the player's preferences.
Name:  A name for display in the Module Edit Window
Button text:  The text of the toolbar button to show/hide the controls when un-docked
Button Icon:  Icon for the toolbar button.
Button Tooltip:  The tooltip text of the button.
Show/hide Hotkey:  Keyboard shortcut to hide or show the Turn Counter window when un-docked.
Next Turn Hotkey:  Keyboard shortcut to advance the Turn Counter one step.
Previous Turn Hotkey:  Keyboard shortcut to return the Turn Counter to the previous step.
Turn Name Format:  Message Format to format the display of the current turn.  All module-level Properties will be substituted.  In particular, the properties exposed by any child 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.
Report Format:  Message Format to display a message in the Chat Window whenever the turn changes.
Turn Label Tooltip Text:  Tooltip text for the Turn Display.
Turn Label Display Length:  Set the number of pixels wide the turn display label should be, or use 0 to let it float to suit the current turn display.

Sub-Components


List

A List is a level that cycles through a specified list of text strings.
Description:  A name for display in the Module Edit Window
Property Name:  The name of the global Property that will hold the value of this level.
Turn Level Format:   A Message Format that gives the value of the level1, level2, etc property for use 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 player 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.

Counter

A Counter is a numerical level that advances by incrementing the number by a fixed value.  It can optionally loop when it reaches a maximum value.
Description:  A name for display in the Module Edit Window
Property Name:  The name of the global Property that will hold the value of this level.
Turn Level Format:   A Message Format that gives the value of the level1, level2, etc property for use 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 at which the level will loop.

Global Hotkey

A Global Hotkey fires a key sequence 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 name for display in the Module Edit Window
Global Hotkey:  The keyboard shortcut to fire.  The program will respond exactly as if one of the players had typed this key sequence.
Match Properties:   A Property Expression that specifies when to fire the hotkey.  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 Window when the hotkey fires.