User Tools

Site Tools


This is an old revision of the document!

Remembering Things with Variables

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 dollar 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 dollar 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:


Some bad variable names:

$what was it called

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 = 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 «set» statement.

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

Notice how the same variable was used in the expression to decrease the number of meals by 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

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:

<<remember $meals>>

Since readers can't reset the value of a «remember»ed variable themselves, the macro should be used carefully.

remembering_things_with_variables.1384320116.txt.gz · Last modified: 2017/10/09 20:37 (external edit)