Node types

Every card on the flow canvas is a node. Add one from the toolbar, the right-click canvas menu, or by dropping a connection on empty space ("Create connected card"). Every card type also has a ? help button on its toolbar with a short in-app summary of the same information below.

Overview

Type	Role	Outputs
Flow	Nested sub-chart (chapter, location, scene)	Default (right)
Dialogue	Speech — scene container or single line	Default (right)
Condition	Branch on a variable, task, or clue	TRUE / FALSE
Instruction	Set/add/subtract a variable, task, or clue — no branching	Default (right)
Task	Quest/objective with editor state	Default (right); can be entered
Clue	Discoverable hint/evidence	Default (right)
Puzzle	Challenge gate	SOLVED / FAILED / LOCKED
Trigger	Fire a named event for the game engine	Default (right)
Inventory	Give or take an item entity	Default (right)
Timer / Delay	Wait, optional timed-choice branch	Default (right); + TIMEOUT
Audio	Play sfx / bgm / voice	Default (right)
Hub / Jump	Merge branches or a neutral waypoint	Default (right)
Note	Designer note, public or private (editor-only)	Annotation handles only
Group	Visual frame around multiple cards (editor-only)	—
Output pin	Named exit from a nested canvas	—
Choices	Not a card — a labeled, player-pickable edge	—

Runtime source of truth

All of this is generated straight from the exported story.json graph — see Game engine export for how the Godot/Unreal runtimes interpret each card kind.

Flow (nested sub-chart)

What it does: Groups a sub-story or chapter as its own inner flow chart. Double-click (or press Enter on) the card to open the nested canvas.

Fields: Label, optional card image. Connects like any other card.

Example: Create a Flow card named "Chapter 2 — The Lab" on the main canvas; open it and build the whole lab sequence inside, keeping the top-level story map readable as a chapter list.

Dialogue (scene or line)

Dialogue cards work in two modes:

1. Scene card (outer canvas): defines the cast (speaker entities) and an optional short scene note. Opening it enters an inner canvas for the actual lines.
2. Line card (inner canvas only): one spoken line — speaker, text (content), optional portrait image, per-line voice-over (voiceAssetId), and direction notes (tone/pace, useful for voice actors or TTS).

Fields: Speaker, text, voice-over asset, direction. Use Add reply on a selected line to chain the next line from the same or a different speaker.

Example: A scene card "Lab — DNA analysis" lists the two characters present; inside it, five line cards form the conversation, with a Condition card splitting into two branches depending on whether the player already has the keycard item.

One file per line

Attach one short audio file per line card, not a single file for the whole scene — this is what both the dialogue script export and the Godot/Unreal runtimes expect.

Condition (branch test)

What it does: Splits the story based on game state. Two outputs: TRUE (upper-right handle) and FALSE (lower-right handle).

Fields — pick one target to test:

• Variable — compare a boolean / integer / float / string / name variable with ==, !=, >, >=, <, <= (numeric operators only apply to integer/float).
• Task — check a quest's state (notStarted | active | completed | failed).
• Clue — check whether a clue card has been discovered.

Example: "Has Enough Fuel?" tests the integer variable fuel >= 10 → TRUE continues to the launch sequence, FALSE routes to a Dialogue line warning the player.

Derived variables are read-only here too

Variables generated from a Task, a Clue, or an inventory link (Tasks.*, Clues.*, item-count links) can be tested in a Condition, but they can't be written — write them via the Task/Clue card itself, or via Inventory.

Instruction (state change)

What it does: Applies a change without branching — always continues on the default (right) output.

Instruction is an advanced/tooling card. Prefer more direct authoring tools when they fit: choice effects for choice-specific changes, Task cards for task state, Clue cards for discovered hints, and Inventory cards for item changes. Use Instruction when you want an explicit, visible state-change step in the graph.

Fields — pick one target:

• Variable — Set, Add, or Subtract (Add/Subtract only available for integer/float variables).
• Task — set the task's state.
• Clue — mark it collected or not collected.

Derived variables (Tasks.*, Clues.*, inventory-linked variables) show as read-only here — change them through their source card instead.

Example: After the player answers a riddle correctly, an Instruction card sets the integer variable reputation with operation Add and value 1.

Task & Clue

Task (quest / objective)

What it does: Represents a trackable quest/objective. The card carries its own state (notStarted | active | completed | failed), editable directly on the card via a dropdown. Task cards are enterable — open one to add task-specific beats on an inner canvas, just like a Flow card.

Example: A Task card "Repair the reactor" starts notStarted; an Instruction card sets it to active when the player picks up the toolkit, and to completed once the puzzle inside is solved. A Condition card elsewhere checks active to unlock a hint dialogue line.

Clue (discoverable hint)

What it does: A discoverable piece of information (note, evidence, rumor) with a boolean discovered state.

Fields: Content (the player-facing text) and the discovered flag (toggled by an Instruction card during play, or manually while testing).

Example: A Clue card "Torn Diary Page" holds the text the player reads when they find it; a Puzzle card elsewhere lists this clue as a requirement, so the safe can't be opened until it's been discovered.

Puzzle (challenge gate)

What it does: Gates progress until the player solves, fails, or remains locked out. Three outputs: SOLVED (upper), FAILED (middle), LOCKED (lower).

Fields:

• Puzzle type — inventoryItem (needs items), codePassword (code/word), or logicMinigame (custom logic implemented by your game).
• Description — player-facing text.
• Solution — designer-only reference (not shown to the player).
• Requirements — a list of Clue cards and/or item entities the player needs before the puzzle is even attemptable; item requirements can also specify a required quantity. If any are missing, your runtime should route to LOCKED.

Example: A codePassword puzzle "Vault Keypad" requires the clue "Torn Diary Page" (which contains the code) as a requirement; SOLVED continues the story, FAILED loops back to a warning dialogue line, LOCKED routes to "You need to find a way to read the code first."

For logicMinigame, YarnDraft does not run the minigame itself. Treat the Puzzle card as a story marker, then use a Trigger/Game Event or your engine code to open the real minigame. When the player wins, set a YarnDraft variable, clue, or task state, and check that state with a Condition card before continuing.

Trigger (game event)

What it does: Signals the game engine to run custom code — spawn enemies, play a cutscene, shake the camera, save the game, etc. YarnDraft only exports the event name and parameters; your game listens for it.

Fields: eventName (e.g. spawn_enemy_wave), plus any number of free-form key/value parameter pairs.

Example: A Trigger card with eventName: shake_camera and a parameter intensity: 0.6 fires right before a Dialogue line about an explosion, so your Unreal/Godot code can react to OnTrigger and actually shake the camera.

Inventory (give / take items)

What it does: Modifies the player's inventory at this exact story beat.

Fields: Operation (give or take), item entity (picked from your item-template Entities), quantity (integer ≥ 1).

Example: Use an Inventory card with operation Take, item Fuse, quantity 3 right after the puzzle-solved branch — the player hands over 3 fuses the moment they solve the fuse-box puzzle. A matching Give card earlier in the flow is how they first received the fuses.

Timer / Delay (wait)

What it does: Pauses the flow for a duration before continuing.

Fields: Duration + unit (seconds | turns | days). Optional Timed choice: enabling it sets timedChoiceSeconds > 0 and adds a second TIMEOUT output (lower-right); the normal path (player answered in time) uses the default right handle.

Example (plain delay): A 3 days Timer card between two Dialogue lines simulates time passing before the next scene starts — leave the timed-choice checkbox off and only wire the right output.

Example (timed choice): A Timer card with a 10-second limit sits before a tense decision; the right output leads to the choice outcome, and TIMEOUT routes to "The moment passed — the door slams shut."

Audio (sound)

What it does: Plays a sound the moment the story reaches this card, then continues on the default output.

Fields: Asset (picked from Assets — audio files only), type (sfx | bgm | voice), volume (0–100%), optional fade-in/out seconds.

Example: Drop an Audio card with type bgm and a 2-second fade right after entering the "Chapter 2" Flow card, so the new chapter's music fades in cleanly instead of cutting abruptly.

Hub / Jump (merge & routing)

What it does: Merges multiple incoming paths, or acts as a neutral waypoint that doesn't change any state. No configurable fields besides the label — connections use standard four-way handles.

Example: Two different Dialogue branches ("apologize" and "explain") both eventually need to continue the same way — route both into a single Hub card labeled "After the argument" instead of duplicating the following cards twice.

Note (editor annotation)

What it does: Adds an editor-only design note to the canvas. Notes are for planning, reminders, review comments, or explaining nearby flow logic. They are never exported to the game runtime and are never traversed by simulation.

Visibility:

• Private notes stay local in the project's .yarndraft/private-notes.json.
• Public notes are saved with the flow JSON, so they can be shared through Git or project export.

Annotation links: Drag from a note's side handle to another card to create a visual annotation edge. These links explain relationships on the canvas, but they are not player choices and do not affect story flow.

Example: Add a public Note beside a puzzle cluster: "This branch teaches the breaker-code mechanic; keep the clue visible before the locked puzzle." Use a private Note for a personal TODO like "rewrite Mara's line later."

Group (editor organization)

What it does: A visual frame to organize cards on the canvas — select, move, and collapse a whole section together. Purely an editor convenience — it has no runtime behavior and isn't part of the exported story graph.

How: Select 2+ cards → Group (Ctrl+G). Drag the frame to move every member together; collapse to hide the children; Ungroup (Ctrl+Shift+G) to dissolve it.

Example: Group all the cards that make up a single side-quest into a labeled, collapsible frame so the main canvas stays readable while you focus on other chapters.

Output pin (nested flow exit)

What it does: Defines a named exit point from a nested canvas (inside a Flow, Dialogue scene, or Task). Only available inside a nested canvas — not on the root flow.

How it connects: Add via the right-click context menu inside the nested canvas. Route internal cards into the pin's left (input) handle. On the parent canvas, the enterable card (Flow/Dialogue/Task) automatically grows a matching output handle on its right edge — wire that into the rest of the story.

Multiple pins hide the default output

As soon as a nested canvas has at least one Output pin, the parent card's plain default right output disappears — every exit from that nested flow must go through a named pin.

Example: Inside a "Boss Fight" Task's inner canvas, add two Output pins — "Player Won" and "Player Died" — and route the fight logic into whichever applies. On the main canvas, the Task card now shows two right-side outputs that continue the story down the winning or losing path.

Choices (labeled edges)

A choice is not a separate card — it's the edge the player picks, with its label acting as the button text. Double-click or right-click an edge to open the choice editor, where you can optionally attach:

• Requirement: a condition (same picker as the Condition card) that gates this specific choice. Choose whether it's hidden entirely or shown greyed out when not met.
• Effect: an automatic variable/task/clue change (same picker as the Instruction card), applied the instant the player picks this choice — no separate Instruction card needed.
• Voice-over: an audio asset played when the player picks this choice.

Choice-specific requirements, effects, and voice-over are available only on edges that behave like player choices: outgoing Dialogue edges, and Timer edges when the Timer is configured as a timed choice. Other edges can still have labels, but they do not carry choice behavior.

Edges with any of these attached show a small 🔒 / ⚡ / 🔊 marker next to their label on the canvas.

Example: A choice labeled "Threaten the guard" carries a Requirement (variable strength >= 5, shown greyed out otherwise) and an Effect (Instruction: set guard_hostile to true) — the option is only usable by a strong-enough character, and picking it immediately flags the guard as hostile without any extra wiring.

Help buttons

Every card type also has a ? icon on its toolbar with a short in-editor explanation — handy while designing without leaving the canvas.