===== <<set>> =====

====Motivating example===
[[Variable]]s are a good way to keep track of what a reader has chosen in a story, or to manage some other part of the story state. For example, many gamebooks start off with something like this:

> All you possess is an Axe (note under Weapons on your Action Chart) and a Backpack containing 1 Meal (note under Meals on your Action Chart).

(Joe Dever, //Flight from the Dark//)

You can keep track of the number of meals that the protagonist carries with the [[<<set>>]] macro, like so:

<code>
All you possess is an Axe and a Backpack containing 1 Meal.
<<set $meals to 1>>
</code>

Later on in the story, you can change the value of a variable with another ''<<set>>'' statement.

<code>
You are feeling tired and hungry and you must stop to eat. <<set $meals -= 1>>
</code>

If you make a mistake with ''<<set>>'', a pink highlighted message will appear where you invoked it. Here's a sample error message, in this case forgetting the sigil before the variable ''$meals'':

<code>
bad expression: meals is not defined
</code>

====Setter operators ====
The ''to'' and ''-='' are special operators called **setter operators** - while [[expression]]s may contain comparison operators like ''+'' or ''not'', setter operators are commands to modify the values of variables. The ''-='' operator lowers the variable on the left by the value on the right. There is also a ''+='' operator that does the opposite.

The most useful setter operators are as follows:

^ Operator(s)    ^ Function                                           ^ Example ^
| to, =          | Sets the variable on the left to the value on the right          | ''$bullets to 5'' |
| +=          | Increases the variable on the left by the number on the right, OR adds the string on the right to the end of the variable. ''$var += 1'' is shorthand for ''$var to $var + 1''         | ''$dogs += 2'' |
| -=          | Decreases the variable on the left by the number on the right. ''$var -= 1'' is shorthand for ''$var to $var - 1''         | ''$health -= 2'' |
| *=          | Multiplies the variable on the left by the number on the right. ''$var *= 2'' is shorthand for ''$var to $var * 2''         | ''$shields *= 2'' |
| /=          | Divides the variable on the left by the number on the right. ''$var /= 2'' is shorthand for ''$var to $var / 2''         | ''$coins /= 2'' |

====Multiple operations in one <<set>> ====

When you have multiple <<set>> macro tags next to one another, you can replace them with a shorthand that uses only one <<set>>. Simply take the operations in each instance, and join them together using either commas or semicolons.
For instance, these three macro tags:
<code><<set $pants = "large">>
<<set $shoes = "huge">>
<<set $spats = "classy">></code>
...can be changed to just this:
<code><<set $pants = "large"; $shoes = "huge"; $spats = "classy">></code>
====A note about <<set>> and links====

It is easy to assume that the placement of links in a passage has some bearing on what the game's variable state will be once you click it:
<code>
/% The following code is ineffectual %/
<<set $lamp to "red">>
[[The lamp is red]]
<<set $lamp to "blue">>
[[The lamp is blue]]
</code>
But this is erroneous! All of these [[<<set>>]] macros are run as soon as the passage is displayed, in order. Clicking the "The lamp is red" link won't cause the <<set $lamp to "blue">> tag to not have happened.

To achieve the desired effect in the above passage, you should use [[link|setter links]]:
<code>
[[The lamp is red][$lamp = "red"]]
[[The lamp is blue][$lamp = "blue"]]
</code>