About Expressions

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:

Operator

Function

Example

+

Addition.

5 + 5 (is 10)

-

Subtraction. Can also be used to negate a number.

5 - -5 (is 10)

*

Multiplication.

5 * 5 (is 25)

/

Division.

5 / 5 (is 1)

%

Modulo (remainder of a division).

5 % 26 (is 1)

( and )

Brackets/parentheses (causes an expression to be evaluated earlier).

(5 + 10) * 2 (is 30, not 25)

A note about modulo

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.

Strings of text

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.)

A note about strings and numbers

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.)

Printing Lists

If you have a list, you can print the contents separated by a comma like so:

<<set $myarray = ["this", "that"]>>
<<print $myarray.join(", ")>>

This will print the following:

this,that

If you have specific questions about using lists in Twine, the FAQ may help.

Functions

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.

Logical operators

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.

Operator(s)

Function

Example

is

Evaluates to true if both sides are equal.

$bullets is 5

neq

Evaluates to true if both sides are not equal.

$friends neq $enemies

>, gt

Evaluates to true if the left side is greater than the right side.

$money > 3.75

>=, gte

Evaluates to true if the left side is greater than or equal to the right side.

$apples >= $carrots + 5

<, lt

Evaluates to true if the left side is less than the right side.

$shoes < $people * 2

<=, lte

Evaluates to true if the left side is less than or equal to the right side.

65 <= $age

and

Evaluates to true if both sides evaluates to true.

$hasFriends and $hasFamily

or

Evaluates to true if either side is true.

$fruit or $vegetable

not

Flips a true value to a false value, and vice versa.

not visited(“Waterfall”)

eq

An older synonym of is that is no longer recommended for use.

$fingers eq 5

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)>>

Use "is" instead of "="

You must not use the = sign in place of is in conditions. The = sign is a Javascript operator which functions as a synonym of to used by the <<set>>macro, and causes unexpected behaviour to occur if you use it outside of that macro!

(It should be noted that the Javascript double-equals sign == can be used as a synonym of is, but is not recommended for use as it is too easily confused with the single-equals sign.)

Invalid "and" and "or" usage

You should take care when writing expressions to remember what the “and” and “or” keywords are capable of.

An example:

<<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.

Another example:

<<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”.

Treating numbers and strings as conditions

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».

Summary of types of data values

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. Infinity isn't really a number, but has the special property that it's always > and >= every actual number, so you can use it in that case. (The same applies to -Infinity and </⇐)