Yarn Basics

Yarn Spinner is a dialogue scripting language designed for games. This guide covers the syntax essentials for writing NONMP dialogue.

Node Structure

Every dialogue segment is a node. Nodes have three parts:

title: NodeName
---
Dialogue content goes here.
===

Part	Description
`title:`	Unique identifier for the node
`---`	Separates the header from the body
`===`	Marks the end of the node

A single .yarn file can contain multiple nodes.

Dialogue Lines

Basic dialogue uses the format Speaker: Text:

Lilith: Hello there!
Morpheus: Good morning.

Line IDs

Add #line:identifier to tag lines for localization:

Lilith: Welcome to my shop! #line:shop_greeting
Morpheus: I'm just browsing. #line:shop_browse

Write dialogue in English directly in your .yarn files. Line IDs connect to translation entries in CSV localization files (e.g., zh-cn.csv). See Project Development for the localization workflow.

Player Choices

Use -> to create options the player can select:

Lilith: What would you like?
-> Buy potions
    Lilith: Excellent choice!
-> Ask about rumors
    Lilith: I've heard some interesting things...
-> Leave
    Lilith: Come back anytime!

Indented content under an option runs when that option is selected.

Nested Choices

Options can contain more options:

-> Ask about rumors
    Lilith: What kind of rumors?
    -> About the forest
        Lilith: Strange lights have been seen...
    -> About the castle
        Lilith: They say it's haunted.

Variables

Store and retrieve values with variables:

<<set $gold = 100>>
<<set $has_key = true>>
<<set $player_name = "Hero">>

Access variables in dialogue:

Lilith: You have {$gold} gold coins.
Lilith: Ah, {$player_name}! Welcome back.

Conditionals

Use <<if>>, <<elseif>>, and <<else>> for branching:

<<if $gold >= 50>>
    Lilith: You can afford that potion.
<<elseif $gold >= 25>>
    Lilith: You're a bit short on gold.
<<else>>
    Lilith: Come back when you have more coin.
<<endif>>

Conditional Options

Show options only when conditions are met:

-> Buy the expensive sword <<if $gold >= 500>>
-> Buy the cheap dagger <<if $gold >= 50>>
-> I'll come back later

Commands

Commands trigger game actions. Wrap them in <<command>>:

<<char_creat Lilith 1 1 false 0,0 0.7 0 0.3>>
Lilith: Hello!
<<char_remove Lilith>>

Common command patterns:

// Visual commands
<<back_creat BG-1 false 0,0 1 0>>
<<char Lilith 1 54 true 0.3>>

// Audio commands
<<set_bgm bgm_1>>
<<play_sound_effect se_common_click>>

// Game state
<<change_gold 50>>
<<change_item 2007 1 true>>

Yarn Reference

See all available commands and functions.

Jumping Between Nodes

Use <<jump>> to move to another node:

title: ShopEntrance
---
Lilith: Welcome! What brings you here?
-> I want to buy something
    <<jump ShopBuy>>
-> Just looking
    <<jump ShopBrowse>>
===

title: ShopBuy
---
Lilith: Let me show you my wares.
===

Functions

Call functions to get values from the game:

<<if get_gold() >= 100>>
    Lilith: You look wealthy!
<<endif>>

<<if is_own_character(1003)>>
    Lilith: Sartre is with you? How wonderful!
<<endif>>

Many functions take integer IDs rather than string names. Character IDs, item IDs, and value IDs are defined in the game’s internal data tables. See the Functions Reference for parameter types.

Use functions in expressions:

Lilith: You have {get_gold()} gold.
Lilith: Your strength is {get_player_attribute("STR")}.

Functions Reference

Browse all available query functions.

Comments

Add comments with //:

// This is a comment
Lilith: This line will display. // Inline comment

Complete Example

title: TavernMeeting
---
<<back_creat BG-1 false 0,0 1 0>>
<<char_creat Lilith 1 1 false 0,0 0.7 0 0.3>>
<<set_bgm bgm_1>>

Lilith: Ah, a visitor! #line:tavern_greeting

<<if $met_lilith == true>>
    Lilith: Good to see you again. #line:tavern_return
<<else>>
    Lilith: I don't think we've met. I'm Lilith. #line:tavern_intro
    <<set $met_lilith = true>>
<<endif>>

-> Ask about work <<if $has_quest == false>>
    Lilith: Actually, I could use some help... #line:tavern_quest_offer
    <<set $has_quest = true>>
    <<jump TavernQuest>>
-> Buy a drink <<if get_gold() >= 10>>
    <<change_gold -10>>
    Lilith: Here you go! #line:tavern_drink
-> Leave
    Lilith: Safe travels! #line:tavern_farewell

<<char_remove Lilith>>
<<event_end>>
===

Next Steps

Quest Creation

Create map events and custom quests.

Visual Commands

Control backgrounds, characters, and effects.

Game Commands

Manage battles, items, and game state.

Functions

Query player and game information.

Getting Started

Essentials

Node Structure

Dialogue Lines

Line IDs

Player Choices

Nested Choices

Variables

Conditionals

Conditional Options

Commands

Yarn Reference

Jumping Between Nodes

Functions

Functions Reference

Comments

Complete Example

Next Steps

Quest Creation

Visual Commands

Game Commands

Functions

​Node Structure

​Dialogue Lines

​Line IDs

​Player Choices

​Nested Choices

​Variables

​Conditionals

​Conditional Options

​Commands

Yarn Reference

​Jumping Between Nodes

​Functions

Functions Reference

​Comments

​Complete Example

​Next Steps

Quest Creation

Visual Commands

Game Commands

Functions

Node Structure

Dialogue Lines

Line IDs

Player Choices

Nested Choices

Variables

Conditionals

Conditional Options

Commands

Jumping Between Nodes

Functions

Comments

Complete Example

Next Steps