This is an old revision of the document!
Expressions by themselves aren't much use to your stories. Unless you're writing a mathematical thriller, you probably don't need to evaluate 2 + 2 too often. Where they do come in handy, however, is when variables enter the picture.
A variable is a place to store a value so that you can remember it later. You can store both strings and numbers in variables. The variable
$name might contain the main character's name, “Agatha Christie”, or the variable
$money might contain the amount of money Agatha has in her pocket – the number 15.75.
Variables have a few restrictions on their names. They must start with a $ sign. That's called a sigil — it tells the computer that what's coming next is a variable, not a number or string.
After the initial $ sign, a variable name can begin with a letter, either uppercase or lowercase, or an underscore _. After the first letter, you can have any combination of letters, numbers, or underscores. Punctuation and spaces aren't allowed anywhere.
Here are some legitimate variable names:
$housesDestroyed $_my_favorite_color $AN_EXTREMELY_IMPORTANT_NUMBER $street8 $i $_
Some bad variable names:
$what was it called $Idon'tRemember $3.95 I_Forgot_Something_Important $8thSurprise $$$make_money_fast$$$
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>>
The left side of the equals sign has a single variable, and the expression to set it to is on the right. It's on the same line as the real text of the story so that extra whitespace doesn't appear in the story text.
Later on in the story, you can change the value of a variable with another
You are feeling tired and hungry and you must stop to eat. <<set $meals -= 1>>
-= operator lowers the variable on the left by the value on the right. There is also a
+= operator that does the opposite.
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
bad expression: meals is not defined
Variables are reset every time the reader restarts a story. If you'd like to remember the value of a variable permanently, use the
«remember» macro. It works exactly the same way as
«set», only it stores the variable in a browser cookie that remains between sessions.
At long last, you have escaped the dungeons. <<remember $escapes = $escapes + 1>> So far, you have escaped the dungeons <<print $escapes>> times.
If you are only interested in remembering the current state of a variable, you don't need to include an assignment:
If you want to reset the remembered value, you can use the «forget» macro: