> ## Documentation Index
> Fetch the complete documentation index at: https://nonkit.rlaneth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Yarn Basics

> Yarn Spinner syntax for writing dialogue

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:

```yarn theme={null}
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`:

```yarn theme={null}
Lilith: Hello there!
Morpheus: Good morning.
```

### Line IDs

Add `#line:identifier` to tag lines for localization:

```yarn theme={null}
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](/development) for the localization workflow.

## Player Choices

Use `->` to create options the player can select:

```yarn theme={null}
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:

```yarn theme={null}
-> 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:

```yarn theme={null}
<<set $gold = 100>>
<<set $has_key = true>>
<<set $player_name = "Hero">>
```

Access variables in dialogue:

```yarn theme={null}
Lilith: You have {$gold} gold coins.
Lilith: Ah, {$player_name}! Welcome back.
```

## Conditionals

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

```yarn theme={null}
<<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:

```yarn theme={null}
-> 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>>`:

```yarn theme={null}
<<char_creat Lilith 1 1 false 0,0 0.7 0 0.3>>
Lilith: Hello!
<<char_remove Lilith>>
```

Common command patterns:

```yarn theme={null}
// 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>>
```

<Card title="Yarn Reference" icon="book" href="/yarn-reference/introduction">
  See all available commands and functions.
</Card>

## Jumping Between Nodes

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

```yarn theme={null}
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:

```yarn theme={null}
<<if get_gold() >= 100>>
    Lilith: You look wealthy!
<<endif>>

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

<Note>
  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](/yarn-reference/functions) for parameter types.
</Note>

Use functions in expressions:

```yarn theme={null}
Lilith: You have {get_gold()} gold.
Lilith: Your strength is {get_player_attribute("STR")}.
```

<Card title="Functions Reference" icon="function" href="/yarn-reference/functions">
  Browse all available query functions.
</Card>

## Comments

Add comments with `//`:

```yarn theme={null}
// This is a comment
Lilith: This line will display. // Inline comment
```

## Complete Example

```yarn theme={null}
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

<CardGroup cols={2}>
  <Card title="Quest Creation" icon="map" href="/essentials/quest-creation">
    Create map events and custom quests.
  </Card>

  <Card title="Visual Commands" icon="image" href="/yarn-reference/visual-commands">
    Control backgrounds, characters, and effects.
  </Card>

  <Card title="Game Commands" icon="gamepad" href="/yarn-reference/game-commands">
    Manage battles, items, and game state.
  </Card>

  <Card title="Functions" icon="function" href="/yarn-reference/functions">
    Query player and game information.
  </Card>
</CardGroup>