This is an old revision of the document!
Expressions are the ways in which you provide data to the macros of your stories. An expression is a lot like a mathematical formula. When a computer sees an expression, it simplifies it into a single value. This is a very simple expression using numbers:
<<print 2 + 2>>
When Twine processes this <<print>> macro tag, it results in the number 4. This process is called evaluation. This isn't algebra; everything you start with has to be a known quantity. You can do all the basic mathematical things you'd expect in an expression.
<<print (1 + 2) * 4 + (3 + 2) / 5>>
This evaluates to the number 13. The computer follows the normal order of operations in mathematics: first multiplying and dividing, then adding and subtracting. You can group subexpressions together and force them to be evaluated first with parentheses.
If you're not familiar with some of those symbols, here's a review:
| ||Subtraction. Can also be used to negate a number.||
| ||Modulo (remainder of a division).||
| ||Brackets/parentheses (causes an expression to be evaluated earlier).||
Modulo may seem somewhat obtuse an operator, but think of it like this: if you had a sequence of numbers:
0, 1, 2, 3, 4, 5, 6…, and you did
% 3 to each of them, they would become
0, 1, 2, 0, 1, 2, 0… - that is, a constantly looping sequence. This ability to simplify rising sequences allows you to perform some otherwise complicated calculations easily. See the visited() function for one such example.
You can also use strings in an expression. A string is a bunch of characters strung together, demarcated by matching pairs of either double or single quotes. You can use strings in expressions:
<<print "The" + ' former ' + "Prime Minister's">>
This expression pushes the strings together, and evaluates to “The former Prime Minister's”. Notice that spaces had to be added between the words in order to produce a properly spaced final string. Also, notice that you can only add strings together. You can't subtract them, much less multiply or divide them. Finally, notice that the apostrophe in “Prime Minister's” couldn't be included if that string had used single quotes, as they are the same character. (This is why both sets of quotes are permitted to build strings.)
As you can infer from the above, strings and numbers are separate types of data. What happens if you try to add a number to a string? Put simply, the decimal number is changed into characters and added to the string. So,
<<print 2 + "2">>
produces the string “22”, and
<<print 2 + 2 + "2" + 2>>
produces the string “422”. (The 2 and 2 are added, resulting in the number 4. Then the string “2” is added, resulting in the string “42”. Then the 2 is added to “42”, resulting in “422”.)
Strings can thus be considered a “contagious” data type - when they are added to other data types, the other data type becomes a string.
(One upshot of this is that you can convert a number to a string by simply adding the “empty string” to it - a string with zero characters, just two quotation marks with nothing between:
<<set $twentyfour to 24 + "">>
Usually, though, there isn't much call for this - numbers are generally as useful as strings.)
If they are all written into the story's code, expressions are not terribly interesting. After all, plain text already accomplishes what the «print» macros above can do. However, there are devices called functions which can be used to obtain interesting values that can't be written down.
For instance, there exists a built-in function named
either(), which randomly picks one of the values given to it. Using this, you can have a gun with a random number of bullets in it:
You have found a pistol! It's got <<print either(1,2,3,4,5,6)>> bullets.
For a list of the most useful functions, see the functions article.
Computers can perform more than just mathematical tasks - they are also virtuosos in classical logic. Much as how arithmetic involves manipulating numbers with addition, multiplication and such, logic involves manipulating the values “true” and “false” using its own operators. An expression that evaluates to “true” or “false” is called a condition
is is a logical operator that's short for 'equals.' Just as + adds the two numbers on each side of it,
is compares two values on each side and evaluates to true or false depending on whether they're identical. It works equally well with strings and numbers, but beware – the character “2” is not equal to the number 2.
There are several logical operators available. Some of these have aliases which were used in previous Twine versions. The aliases behave identically.
| ||Evaluates to true if both sides are equal.||
| ||Evaluates to true if both sides are not equal.||
| ||Evaluates to true if the left side is greater than the right side.||
| ||Evaluates to true if the left side is greater than or equal to the right side.||
| ||Evaluates to true if the left side is less than the right side.||
| ||Evaluates to true if the left side is less than or equal to the right side.||
| ||Evaluates to true if both sides evaluates to true.||
| ||Evaluates to true if either side is true.||
| ||Flips a true value to a false value, and vice versa.||
| || An older synonym of ||
Conditions can quickly become complicated. The best way to keep things straight is to use parentheses to group things:
<<if ($master is 'Selator') and ($berries > 2)>>
You must not use the = sign in place of
to used by the <<set>> macro, and causes unexpected behaviour to occur if you use it outside of that macro!
is, but is not recommended for use as it is too easily confused with the single-equals sign.)
You should take care when writing expressions to remember what the “and” and “or” keywords are capable of.
<<if $health > 2 and < 4 >>
This macro tag's expression is invalid because the > and < operators (and indeed, all expression operators except
not) require a distinct value to be on both sides of it. In a sense, the expression is interpreted as
($health > 2) and ( < 4), which is obviously nonsensical. So, you must rewrite this as
$health > 2 and $health < 4.
<<if $name is "Perone" or "Pavone" >>
This macro tag's expression is also invalid, for a different reason: it will be interpreted as
($name is “Perone”) or (“Pavone”) - which is to say, it is true if $name is “Perone”, or if the string “Pavone” is not false. This, of course, means that it's always true - an undesirable outcome. You must rewrite it as
$name is “Perone” or $name is “Pavone”.
Some macros, such as <<if>>, are designed to only accept conditions. But, if such macros receive an expression, then, depending on the value, it can be treated as if it was a condition in and of itself. The number 0, and a string with no characters in it “”, are both treated as false. The other numbers, and every other string, are treated as true. This means that you can simplify a number of expressions: «if $numberOfJavelins > 0» can simply become «if $numberOfJavelins».
To conclude, here is a summary of the types of values that you will most often encounter in macro expressions:
|Example of value||Description|
|“Some text”, “2”, “true”, 'More text', '4', 'true'||Strings: snippets of text characters that can be <<print>>ed, joined up, or compared. Note that “2” and “true” resemble other types but are nonetheless strings.|
|0, 2, 5, -11, 45.25, Infinity|| Numbers that can be used in arithmetic calculations.
|true, false||Logical values, created using the logical operators, and commonly used with to the <<if>> macro. True and false are the only values of this type.|