Tutorial: Your First Story (No Code Required)

This tutorial is for game designers and writers. You don’t need to know how to program — you just need a text editor and the plotknot compiler. By the end, you’ll have written and compiled a short branching story.

What you’ll build

A short tavern scene where the player talks to a barkeep, makes choices, and sees different text on repeat visits.

Step 1: Create your file

Open any text editor and create a file called tavern.plotknot. The .plotknot extension tells the compiler this is a story file.

Step 2: Write your first section

A section is a named block of narrative. It starts with a heading (#):

# The Tavern

The tavern is warm and loud. A fire crackles in the hearth.

"What'll it be, friend?" asks the barkeep.

The first stage in your file is where the story starts. The heading (# The Tavern) becomes the stage’s name — the compiler turns it into an ID like the_tavern automatically.

Every plain line below the heading becomes text shown to the player. Each paragraph is delivered as a separate line.

Step 3: Add choices

Players need to make decisions. Add a choice: block:

# The Tavern

The tavern is warm and loud. A fire crackles in the hearth.

"What'll it be, friend?" asks the barkeep.

choice:
- Ale, please. -> order_ale
- Just information. -> order_info

Each choice has two parts:

• The display text (what the player sees)
• The target (where the story goes next), written as -> section_name

The targets (order_ale, order_info) must match stage headings you define. Let’s add them:

## Order Ale

"One ale, coming up. That'll be two coppers."

You pay the barkeep and settle in.

## Order Info

"Information costs more than ale, friend. What do you want to know?"

## works the same as # — the heading level doesn’t affect behavior, only organization. Use ## for subsections to keep your file visually organized.

Step 4: Navigate between sections

Sometimes you want to jump to another stage without showing a choice. Use ->:

## Order Ale

"One ale, coming up. That'll be two coppers."

You pay the barkeep and settle in.

-> tavern_hub

The -> arrow navigates immediately. The player never sees a choice — the story just moves on.

Step 5: Make choices disappear

Some choices should only appear once. Prefix a choice with -- instead of -:

## Tavern Hub

The fire pops and hisses. The tavern continues its evening rhythm.

choice:
-- Ask about the stranger in the corner -> ask_stranger
- Talk to the barkeep -> talk_barkeep
- Leave the tavern -> ending

The -- choice (“Ask about the stranger”) disappears after the player picks it. Regular - choices always remain available. This is perfect for “ask about X” options that shouldn’t repeat.

Step 6: Vary text on repeat visits

If the player returns to a stage, you can show different text each time using a variation block:

## Tavern Hub

cycle
  You enter the tavern for the first time. The noise hits you like a wall.
--
  The tavern again. The barkeep nods. You're becoming a regular.
--
  You barely notice the noise anymore. This place feels like home.

The fire pops and hisses.

choice:
- Talk to the barkeep -> talk_barkeep
- Leave the tavern -> ending

The cycle keyword means: show the first item on the first visit, the second on the second visit, the third on the third visit, then loop back to the first. Items are separated by -- on its own line.

Five modes are available:

For most “flavor text that changes” situations, cycle or sequence is what you want.

Step 7: Add comments

Document your story without affecting the output. Lines starting with // are ignored:

// Design note: keep this stage short — pacing is critical here
// TODO: add a third variation for late-game visits

## Tavern Hub

cycle
  You enter the tavern for the first time.
--
  The tavern again. The barkeep nods.

Comments are invisible to the player. Use them for author notes, pacing reminders, or TODO markers.

Step 8: Compile your story

Save your file and compile it:

plotknot compile tavern.plotknot --output output/

The compiler produces output/tavern.lua — a data file your game engine can load. You don’t need to read or edit this file; it’s for the engine.

If you made a mistake (like a choice pointing to a stage that doesn’t exist), the compiler tells you:

plotknot validate tavern.plotknot

Validation catches broken references, duplicate stage names, and other structural errors without generating output.

Your complete story

Here’s the full tavern story you just built:

// A simple tavern scene demonstrating core plotknot features

# The Tavern

The tavern is warm and loud. A fire crackles in the hearth.

"What'll it be, friend?" asks the barkeep.

choice:
- Ale, please. -> order_ale
- Just information. -> order_info

## Order Ale

"One ale, coming up. That'll be two coppers."

You pay the barkeep and settle in.

-> tavern_hub

## Order Info

"Information costs more than ale, friend. What do you want to know?"

choice:
- Who's the stranger in the corner? -> ask_stranger
- Any work available? -> ask_work

## Ask Stranger

"That's Vex. Been here three days, asking questions."
"Something about the old church. Best stay clear."

-> tavern_hub

## Ask Work

"Work? The mill needs hands. Boring but honest."
"Or... there's the crypt business. Dangerous pay, but dangerous coin."

-> tavern_hub

## Tavern Hub

cycle
  You enter the tavern for the first time. The noise hits you like a wall.
--
  The tavern again. The barkeep nods. You're becoming a regular.
--
  You barely notice the noise anymore. This place feels like home.

The fire pops and hisses.

choice:
-- Ask about the stranger in the corner -> ask_stranger
- Talk to the barkeep -> order_ale
- Leave the tavern -> ending

## Ending

You step into the cool night air. The road stretches in both directions.

Some stories aren't yours to tell.

What’s next

• Programmer Tutorial — add variables, conditions, and game integration
• Language Guide — every feature explained with examples
• Examples — complete annotated stories