VASSAL Reference Manual
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).
|
|
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.
- Allow Only Forward:
-
Setting this toggle prevents players form going backwards with the Turn Counter. This feature prevents the triggering of unintended automation. Players may still go back to correct errors, but they must use the "undo" button instead. The "undo" button will unwrap previously triggered automation instead of triggering it a second time as would occur when the Turn Counter goes backwards.
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.
|
|
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.
|
|
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.
|
|
