Table of Contents
<<set>>
Motivating example
Variables 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:
All you possess is an Axe and a Backpack containing 1 Meal. <<set $meals to 1>>
Later on in the story, you can change the value of a variable with another «set» statement.
You are feeling tired and hungry and you must stop to eat. <<set $meals -= 1>>
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:
bad expression: meals is not defined
Setter operators
The to and -= are special operators called setter operators - while expressions 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:
<<set $pants = "large">> <<set $shoes = "huge">> <<set $spats = "classy">>
…can be changed to just this:
<<set $pants = "large"; $shoes = "huge"; $spats = "classy">>
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:
/% The following code is ineffectual %/ <<set $lamp to "red">> [[The lamp is red]] <<set $lamp to "blue">> [[The lamp is blue]]
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 setter links:
[[The lamp is red][$lamp = "red"]] [[The lamp is blue][$lamp = "blue"]]
