Defining a TurnTracker

From VASSAL
(Redirected from Turn ref reference)
Jump to: navigation, search

Turn Tracker Definition

Adding a Turn Tracker to your module will how the following dialog to set the overall look of the turn tracker.

Turntracker.gif

Name: The name of this Turntracker.
Button Text: The Text to appear on the Launch Button.
Button Icon: The icon to use on the Launch Button.
Hotkey: Hotkey to toggle display of the Turntracker.
Background Color: Color to use in the background of the Turntracker display.
Turn Format: How to use the different levels within a multi-level turn tracker to build up a turn description. The top level is referenced using $level1$, Level 2 by $level2$ etc.
Report Format: Format of the report to generate each time the turn is changed.
Display Tooltip Text: Text to display when the mouse is held over the Turn Tracker display.
Display length of Turn label (0 for variable): Specify a fixed length for the Turn Tracker display window. Units are supposedly columns. Use 0 to let the length of the Turn Tracker adjust to the current display length.

Subcomponents

Counter

A counter is a turn element that just generates a number, counting up or down from a start value and optionally looping at a given value

Counter.gif

Name: The name of this level.
Turn Format: What text to generate for this turn level when generating a turn report. $turnName$ will be replaced by the name of this level. $turnText$ will be replaced by the current value of the counter.
Start Value: Default starting value for the counter.
Increment By: Value to increment or decrement the counter by each time this level activates.
Loop? Select on to have a looping counter, or off to have a counter that will keep incrementing.
Loop At: For a looping counter, the value at which this level will reset to the Start Value.

List

A list is a turn element that cycles through a predefined list of text items.

List.gif

Name: The name of this level.
Turn Format: What text to generate for this turn level when generating a turn report. $turnName$ will be replaced by the name of this level. $turnText$ will be replaced by the current value of the list.
List: Define the elements in the list.
Allow players to select list options? If this option is selected, it allows players to indivually select which List elements are to be used in this game by right-clicking on the turn window. For example, A basic scenario may use a subset of the full turn sequence.
Allow players to set first item in list? If this option is selected, it allows players to select which item in the List is considered to be 'first' when rolling over by right-clicking on the turn window. Useful when the starting side may change between different scenarios.
Prompt to select first item: If the first item is selectable, use this prompt in the configure dialog to select the first item.

Global Key Command

Global Key Commands can be attached to the Turn Tracker and set to fire off when particular turns are reached. See the standard VASSAL documentation for general details on Global Key Commands.

Global key command.gif

Run when Global Properties match: A Property Match string used to define when the Global Key Command is to execute. Can only contain references to Module level Global Properties. See below for a detailed description.
Description: A comment describing the Global Key Command.
Key Command: The Key Command to issue to counters.
Matching Properties: A Property String to select which counters to apply the Key Command to.
Suppress individual reports: Click on to stop each individual counter reporting the Key Command.
Report Format: Report to display when the Global Key Command executes.

Global Properties Match

The Global Key Command will only execute when the Property Match String defined in the 'Global Properties match' field is true. This field is just like a normal Properties match string EXCEPT that you can only reference Global Properties defined withing the module. The most useful Global Properties to reference are those generated by the Turn Tracker itself:

   <name>_name<n>  - The name of turn level <n> of Turn tracker <name>
   <name>_value<n> - The value of level <n> of Turn Tracker <name>
   <name>_command  - The last command that changed Turn Tracker <name>. Will be Next, Prev or Set


For example, for a Turn Tracker named xyzzy, typical values might be:

  xyzzy_name1   = Year
  xyzzy_value1  = 1914
  xyzzy_name2   = Season
  xyzzy_value2  = Summer
  xyzzy_command = Next