Macros & Functions

What is a Macro?

If you want to add some extra functionality or effects to your Twine story, you need to use macros.

A macro is a piece of pre-defined code that can remember information, create elements, and add variables to your story. Here is a quick list of some of the things you can do with the help of macros:

  • Keep track of the items a player has in their inventory.

  • Randomize the outcome of a player's choice.
  • Remember what rooms a player has gone to or the people a player has met.
  • Save and display a player's information, such as their name.
With the Harlowe or SugarCube story format, you can use macros to add numerous layers of interactivity to your Twine story.

Note: The Snowman story format does not support macros.

Commonly Used Macros

set

This macro allows you to create a variable and assign a value to it. The value can then be referenced on multiple pages. In the example below, a variable called name is created with the value Alice.

Harlowe:
(set: $name to "Alice")

"My name is $name, your Majesty," she said politely.

SugarCube:
<<set $name to Alice>>

My name is $name, your Majesty," she said politely.


if/else

This macro is used to check if a variable or value is true or false, and defines what will happen if after the check.

Harlowe:
Alice picks up the teacup {
(if: $teacup is 'blue')[
    and notices a Dormouse, fast asleep inside of it.
] (else:)[
    and takes a long sip.
]}.

SugarCube:
Alice picks up the teacup
<<if $teacup is "blue">>
    and notices a Dormouse, fast asleep inside of it.
<<else>>
    and takes a long sip.
<</if>>


display

The display macro is perfect for when a section of text needs to be repeated multiple times throughout your story.

For example, if Alice is lost in the forest, you might want to repeat descriptions to indicate that Alice has already tried walking down a specific path.

First, you would create a separate passage in Twine with the name "Path". Write your description in the passage. Then, back in your "Forest" passage, you would write something like this:

Harlowe:
Alice walks down the path on the right.

(display: "Path")
The macro will be replaced with the text from the "Path" passage.


include

Similar to Harlowe's display macro, this macro displays the contents of the passage with the given name.

SugarCube:
Alice walks down the path on the right.

<<include "Path">>