Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pompom454/tea/llms.txt

Use this file to discover all available pages before exploring further.

Macros are Tea’s primary authoring tool—they let you set variables, branch on conditions, display dynamic content, respond to player input, and manipulate the page, all from within regular passage text. Every macro is written between double angle brackets: <<macroname>>.

​
Syntax

Macros come in two structural forms: void macros, which are self-closing, and container macros, which wrap content between an opening and a closing tag. 
→ Void macro — no closing tag
<<set $gold to 10>>

→ Container macro — opening and closing tag
<<if $gold gt 0>>
    You have gold.
<</if>>
The closing tag of a container macro always starts with a forward slash: <</macroname>>.

​
Argument types

Macros fall into two broad categories based on what kind of arguments they accept. Expression macros (e.g. <<set>>, <<print>>) evaluate their entire argument string as a single TwineScript or JavaScript expression: 
<<set $sum to $a + $b>>
<<print $weight.toFixed(2)>>
Discrete-argument macros (e.g. <<link>>, <<audio>>) treat whitespace-separated tokens as individual arguments. Variable substitution happens automatically, so $gold passes the value of $gold, not the name "$gold". When a macro needs the variable’s name instead (for example <<textbox>>), you must quote it: 
→ Passes the name "$pie" so the textbox can write back to it
<<textbox "$pie" "Blueberry">>
When you need to pass the result of an expression as a discrete argument, use a backquote expression — the backtick (`) causes its contents to be evaluated and yielded as a single argument: 
→ This WILL NOT work — the parser sees five separate arguments
<<link "Wake " + $friend + ".">> … <</link>>

→ This WORKS — the backquote evaluates to a single string
<<link `"Wake " + $friend + "."`>> … <</link>>

→ Alternatively, store the result in a temp variable first
<<set _text to "Wake " + $friend + ".">>\
<<link _text>> … <</link>>

​
Macro categories

Variables & Scripting

Set and unset story variables, capture loop values, run arbitrary expressions, and embed raw JavaScript or TwineScript blocks with <<set>>, <<unset>>, <<capture>>, <<run>>, and <<script>>.

Display & Control

Output expressions, include passages, suppress whitespace, type text character-by-character, branch with <<if>>, loop with <<for>>, match with <<switch>>, navigate with <<goto>>, and schedule delayed content with <<timed>> and <<repeat>>.

Interactive

Create player-driven links, buttons, inline text-reveal macros, and form controls: checkboxes, radio buttons, text boxes, cycling links, and listboxes.

Audio

Load, group, playlist, and control audio tracks with <<cacheaudio>>, <<audio>>, <<createaudiogroup>>, <<createplaylist>>, <<masteraudio>>, <<playlist>>, and friends.

DOM

Manipulate live page elements after render: add, remove, or toggle CSS classes, and append, prepend, replace, copy, or remove element content with CSS/jQuery selectors.

​
Quick-reference table

CategoryKey macros
Variables & Scripting<<set>> <<unset>> <<capture>> <<run>> <<script>>
Display & Control<<print>> <<= >> <<- >> <<include>> <<nobr>> <<silent>> <<type>> <<do>> <<redo>> <<if>> <<for>> <<switch>> <<goto>> <<repeat>> <<timed>> <<done>>
Interactive<<link>> <<button>> <<linkappend>> <<linkprepend>> <<linkreplace>> <<back>> <<return>> <<checkbox>> <<radiobutton>> <<textbox>> <<textarea>> <<numberbox>> <<cycle>> <<listbox>>
Audio<<cacheaudio>> <<audio>> <<createaudiogroup>> <<createplaylist>> <<masteraudio>> <<playlist>> <<removeaudiogroup>> <<removeplaylist>> <<waitforaudio>>
DOM<<addclass>> <<removeclass>> <<toggleclass>> <<append>> <<prepend>> <<replace>> <<copy>> <<remove>>
Story $variables are prefixed with a dollar sign and persist across passages. Temporary _variables are prefixed with an underscore and are reset on each new passage render. Both kinds can be used freely inside any macro expression.

Build docs developers (and LLMs) love

Get started for freeTalk to us