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.

Tea stories are made up of passages — named blocks of text and markup that the engine displays one at a time. You move between passages through links. Variables let you track what the player has done and branch the narrative accordingly. This guide walks you through all three concepts with working code you can copy directly into Twine 2 or a .twee file.
Make sure you have Tea installed before continuing. See Installing Tea for setup instructions.

​
What you’ll build

A minimal two-passage story where the player picks up a key, and the next passage reacts to whether they have it. Along the way you’ll use <<set>> to store a value, <<if>> to branch on it, and [[link markup]] to navigate between passages.
1

Create your starting passage

Every Tea story needs a passage named Start. In Twine 2, double-click on the canvas to create a new passage and name it Start. In Twee, write:
:: Start
You stand in a dimly lit hallway. A brass key glints on the floor.

[[Pick up the key|Corridor]]
[[Leave it and move on|Corridor]]
The [[Text|PassageName]] syntax creates a clickable link. The text before the pipe (|) is what the player sees; the name after it is the passage to navigate to.
You can also write [[PassageName]] when the link text and passage name are the same — Tea uses the passage name as the link label.
2

Set a variable when the player clicks a link

Tea’s story variables start with $ and persist for the entire playthrough. Use <<set>> to assign a value. Update your Start passage to set $hasKey when the player picks up the key:
:: Start
You stand in a dimly lit hallway. A brass key glints on the floor.

<<link "Pick up the key" "Corridor">><<set $hasKey to true>><</link>>
[[Leave it and move on|Corridor]]
The <<link>> macro runs the code inside its body silently when clicked, then forwards the player to the named passage. Here it sets $hasKey to true before navigating.
The to keyword is Tea’s TwineScript syntax for assignment. You can also use the standard JavaScript = operator: <<set $hasKey = true>>.
3

Branch on a variable with `<<if>>`

In the destination passage, use <<if>> to show different text depending on whether the player grabbed the key:
:: Corridor
You enter a long corridor. At the far end is a locked door.

<<if $hasKey>>
	You try the brass key. The lock turns with a satisfying click.
	[[Open the door|Beyond]]
<<else>>
	The door is locked. You have nothing to open it with.
	[[Turn back|Start]]
<</if>>
<<if>> evaluates its condition and renders the matching branch. The <<else>> branch renders when the condition is false or undefined. Close the block with <</if>>.Variables in passage text are interpolated automatically — you can write $hasKey anywhere in your prose and Tea substitutes its current value. For example:
Your inventory: $hasKey
outputs Your inventory: true if $hasKey is true.
4

Add a final passage

Add the destination passage so the story has somewhere to go:
:: Beyond
Beyond the door lies a sunlit courtyard. You made it.

[[Play again|Start]]
[[Play again|Start]] sends the player back to the beginning. Tea preserves history so they can also use the back button in the UI bar.
5

Run the story

In Twine 2: Click Play in the toolbar. Tea compiles your passages and opens the story in a new browser tab.In Tweego: Compile the .twee file to HTML:
tweego --format=tea -o story.html story.twee
Open story.html in any browser.

​
Complete example

Here is the full story as a single Twee file you can save and compile: 
:: StoryTitle
My First Tea Story

:: Start
You stand in a dimly lit hallway. A brass key glints on the floor.

<<link "Pick up the key" "Corridor">><<set $hasKey to true>><</link>>
[[Leave it and move on|Corridor]]

:: Corridor
You enter a long corridor. At the far end is a locked door.

<<if $hasKey>>
	You try the brass key. The lock turns with a satisfying click.
	[[Open the door|Beyond]]
<<else>>
	The door is locked. You have nothing to open it with.
	[[Turn back|Start]]
<</if>>

:: Beyond
Beyond the door lies a sunlit courtyard. You made it.

[[Play again|Start]]

​
Next steps

Macro reference

Explore all built-in macros for control flow, audio, DOM manipulation, and more

TwineScript variables

Learn how story variables, temporary variables, and expressions work

Link markup

Setter links, arrow separators, and image links

State and saving

Understand history, sessions, and save slots

Build docs developers (and LLMs) love

Get started for freeTalk to us