View source for Flags and Masks for ToT

[[Category:Tips]]
[[Category:Cam Hills]]
[[Category:William Keenan]]
<big>'''Learn how to create 'masks' for Test of Time events. Understand the different numerical codes that may be used for these masks.'''</big>

'''by [[Cam Hills]] and [[William Keenan]] (April 2000)'''


__TOC__

{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Prologue ==
|}
This design tip is intended to follow on from [[An Introduction to Flags|Introduction to Test of Time Flags]] and assumes an understanding of the concepts laid out in that paper.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== The Goal ==
|}
The goal of this design tip is to educate designers in the application of multiple flags in Test of Time's event macro facility that may take into account several happenings in order to trigger a consequent event.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== What is a Mask? ==
|}
Much as it suggests, a mask is designed to cover or hide certain details. In this instance, it is used to cover up certain flags in any or all of a tribes' ranges of flags, while the program can check the status of other unmasked flags.

To illustrate, you may only want to check what's happening with Flag #0, #3, and #5. How many are 'on'? A mask will temporarily cover up every other flag except #0, #3 and #5, and will then direct the next part of the event to consider the state of just these three.

A mask is used in the 'trigger' part of an event structure.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Why use Masks? ==
|}
The use of flags may better direct the scenario to follow a path that makes sense given what has previously happened, however masks can strengthen this further by considering the state of several flags and fine-tune the scenario to accommodate for more intricate circumstances.

In other words, it allows the scenario designer to create and then check multiple trigger conditions before executing the event.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== A Mask's Structure ==
|}
There are four key variables to bear in mind when developing a mask for an event:

# '''[Mask]''' — Which flags do we want to consider, and which do we want to disregard for this part of the event?
# '''Tribe]''' — Which tribe's set of flags are being examined? (Note that 'Somebody' or 'Everybody' may be used instead of a tribe name).
# '''[Count]''' — When applying the mask, do we want it to trigger an event when the exact number of flags are 'on' or 'off'?
#:—  ''or''  —
#:'''[Threshold]''' — When applying the mask, do we want it to trigger an event when a minimum number of flags are 'on' or 'off'?
#'''[State]''' — The program is looking to see if the flags are in an 'off' state or an 'on' state.

To muddy this set up marginally, there is also an optional [Technology] parameter has no effect unless you specify a single civilization in [Tribe]. This causes the entire trigger to be ignored unless the specified civilization has that technology. The technology index number is the position of the particular advance in the advances list in the rules.txt file.

So, to illustrate these four key variables with a simple example;

# We want to consider the state of Flags #0, #3, and #5…
# ... for the English tribe
# ... and we want to trigger an event when exactly two are
# ... in the 'On' state.

This will take the following trigger structure;

<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt1.png]]</div>


You will notice that a mask takes on a similar structure to a flag. In the trigger above, it will look at the #0, #3, and #5 flag positions (remember Reverse Programmer Notation, or right to left), as indicated by the '1' of the English tribe. If it counts exactly two of these three flag positions for the English as being in the 'on' state, it will proceed to the 'action' stage of the event (i.e. what follows "@THEN").


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== A Practical Example ==
|}
In the design tip [[An Introduction to Flags|Introduction to Test of Time Flags]] an example themed on the American Revolution was used to illustrate the use of flags. We will pursue this theme further to demonstrate the application of a mask.

Let us say that we would like the French to 'intervene' with the activities of the American Revolution if certain conditions are met;

# Benjamin Franklin has been dispatched to Paris and has been there for over a year;
# The British have not captured more then ten strategic cities;
# General Washington remains alive; and
# The game year is 1779 or later.

Each of these conditions could be achieved by allocating a flag to be in the 'on' or 'off' state for the Americans. Let us say Flags #0 to #3 respectively.

An event trigger may be structured as such;


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt2.png]]</div>


In order to complete this event, the following simple action may be added;


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt3.png]]</div>


Three turns after the necessary conditions being met, the text would pop up and six French veteran dragoons would appear at tile 111,41 to assist the Americans in their plight.

You may have been wondering exactly how we could represent the British Control of cities using only four flags. In the above example, American flag #1 (second flag from the right) is On (1) if the British control fewer then ten cities and is turned Off (0) if the British control ten or more cities. We accomplish this through the use of a CheckFlag statement with a mask and a threshold.

Each time the British capture an American held objective city the corresponding British Flag is turned 'On'.


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt4.png]]</div>


After the flags have been set we then check to see if the British have captured ten or more cities. If so then American flag #1 is turned 'On'.


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt5.png]]</div>


The application of masks is therefore far ranging, and will keep a well-planned scenario lively and well synchronized with the incidents' unfolding.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Binary vs. Hexadecimal — Different ways of counting ==
|}
Test of Time supports 'hexadecimal' numbering in addition to 'binary' numbering. These are simply different systems of counting, an alternative representation to our day-to-day 'decimal' numeric system.

Binary, as we know, uses two integers — 'zeros' and 'ones' in groups to form its value. The mask above has been represented as 0b00000000000000000000000000001111, the initial 0b is a code to identify the following number as binary. The extra 'zeros' used to indicate flags #4 to #31 are actually superfluous, and the number can be more simply represented as 0b1111. This is the same concept that we would use to express the number fifteen as '15' and not '000000000015'.

The numbers can get a little unwieldy and could be a little prone to error as the number of flags grow in a scenario, such as; 0b11010010011000011010001110001011

There is another numeric system that mathematicians and computer programmers use; hexadecimal, which is a numbering system that uses sixteen digits. '0' to '9' plus 'A' to 'F' (to represent the extra six). A hexadecimal number uses the '0x' code to identify the numbering system.

'Test of Time' uses both the binary and the hexadecimal systems in its events macro language.

While it is not terribly important that an understanding of how these systems do count to create numbers, we will look at a practical example of representing number 157.


=== Decimal ===
The number 157 in our day to day lives uses the decimal ('deci' is the prefix for ten), so we understand;

{|width="100%" style="text-align: center"
|-
| Units||1||5||7||
|-
| Conversion||100||10||1||
|-
| ||1 x 100||5 x 10||7 x 1||
|-
| || ||100 plus 50 plus 7|| ||= 157
|}


=== Binary ===
The same number is interpreted the following way in binary ('bi' for two) using the following conversion table;

{|width="100%" style="text-align: center"
|-
| Units||1||0||0||1||1||1||0||1
|-
| Conversion||128||64||32||16||8||4||2||1
|-
| ||1x128|| || ||1x16||1x8||1x4|| || ||= 157
|}

Therefore, 0b10011101 = 157


=== Hexadecimal ===
The same number is interpreted the following way in hexadecimal, remembering A=10, B=11, C=12, D=13, E=14, F=15.

{|width="100%" style="text-align: center"
|-
| Units||0||9||D||
|-
| Conversion||256||16||1||
|-
| || ||9 x 16||1 x 13||
|-
| || ||144 plus 13|| ||= 157
|}

Therefore, 0x9D = 157

'Hexadecimal' was a term implemented by computer giant IBM in the 1960's to replace the more correct term 'Sexidecimal' that was considered to be a term too risqué for the conservative company!

As such the same number is;

{|width="70%"
|-
| Binary||10011101
|-
| Decimal||157
|-
| Hexadecimal||9D
|}

Again, if less digits are used for a flag or a mask than the maximum, the leading digits are considered to be zeros.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Binary vs. Hexadecimal - An Example ==
|}
So, back to masks, interpreting the binary expression 0b10101011110 in a more manageable form would be 0x55E in hexadecimal.

The same trigger therefore would be;

<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt6.png]]</div>


as the trigger;


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Evt7.png]]</div>


Manually typing in very long binary numbers may be somewhat prone to error. Thankfully 'Notepad' supports the copy and paste feature, so the same mask may be reproduced exactly several times when authoring the events file. However if editing of the masks is undertaken for whatever reason, the matter can start to become a little messy. It is generally easier to identify irregularities with the hexadecimal code (which has only a few characters) than the binary code (which has many characters).

Essentially long strings of binary code are often difficult to quickly tell apart, and making the conversion across to hexadecimal can prove to be a most useful check that the relevant masks have been entered correctly.

The decision to stick with binary or use hexadecimal is a personal preference issue for scenario designers. John Possidente who wrote the events for the Lalande 21185 science fiction game utilised binary flags, while Mick Uhl opted for hexadecimal in the fantasy game.


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Converting Binary and Hexadecimal ==
|}
Should you choose to adopt Hexadecimal numbering for masks over Binary, there are a few easy to use conversion facilities at your fingertips!

=== The Calculator ===

The Calculator that comes with the Windows software can be toggled between 'Standard' and 'Scientific' formats via the 'View' menu.


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Calc1.png]]</div>


In the 'Scientific' view, you may enter a number using Hexadecimal (Hex), Decimal (Dec), or Binary (Bin) format. The number pad also has the 'A' to 'F' for Hexadecimal numbers. Simply selecting Binary (Bin), typing in a number in the number, then clicking Hexadecimal (Hex) will make the conversion.


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Calc2.png]]</div>


=== @Debug and Report.txt ===

The conversion can also be made by using the Event Parsing Debugger (EPD) that functions to seek out any errors in the events file. If you insert the line @Debug after @Beginevents, when the scenario is loaded the EPD opens a file called report.txt and keeps track of each line of the event file as it is processed.

As part of the debugging process, the report identifies the hexadecimal alternative expressions for binary flags and masks, which therefore may be used to then edit out the binary expression if desired.


<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">[[File:sl_tot_masks_Rept.png]]</div>


{|width="100%"
|style="padding: .1em .5em .1em; background-color: #ccffcc;"|
== Concluding Comments ==
|}
This guideline has focused on the technical aspects of implementing masks more so than the thematic ways masks may enhance your scenario. The example of French intervention in the American Revolution is a fairly straightforward illustration of how masks can enhance the complexity of your scenarios. Designers are encouraged to examine the official scenarios' event structures to better understand how flags and masks can be used to great effect by triggering events in a timely and well reasoned manner.