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

# YAML Syntax

> Reference for the Parley YAML schema, all the top-level blocks and the node types that make up a conversation.

A Parley conversation is a single YAML file with three top-level blocks: `MetaData` (language and reading direction), `Aliases` (reusable text snippets), and `Dialogue` (the actual nodes). Files live under `Resources/{languageEnglishName}/{folderName}/{langCode}.{fileName}.yaml`.

## A complete file

```yaml theme={null}
MetaData:
  Language: English
  TextDirection: LTR

Aliases:
  captain:
    name: "Jack Fiddle"

Dialogue:
  greet:
    Speaker: "@captain.name"
    Text: "Welcome aboard."
    NextNode: offer_room

  offer_room:
    Speaker: "@captain.name"
    Text: "Will you be staying the night?"
```

The rest of this page documents each block and node type in detail.

## Top-Level Blocks

### MetaData

Language and reading direction for the file. Used by Parley at load time and and used for UI layout decisions.

<ParamField path="Language" type="LanguageID" required>
  The language this file is authored in. See [LanguageID](/parlite/reference/scripting/localization/language-id).
</ParamField>

<ParamField path="TextDirection" type="TextDirection" required>
  Reading direction. `LTR` or `RTL`. See [TextDirection](/parlite/reference/scripting/localization/text-direction).
</ParamField>

**Example**

```yaml theme={null}
MetaData:
  Language: English
  TextDirection: LTR
```

### Dialogue

The conversation itself — a map of node IDs to nodes. Node IDs are arbitrary strings you reference via `NextNode`, `TrueNode`, and `FalseNode`. The first node in the map is where the conversation starts.

**Example**

```yaml theme={null}
Dialogue:
  greet:
    Speaker: "Innkeeper"
    Text: "Welcome to the Crooked Crown."
    NextNode: offer_room

  offer_room:
    Speaker: "Innkeeper"
    Text: "Will you be staying the night?"
```

## Node Types

Every node uses the same underlying schema — the fields you populate determine what kind of node it acts as at runtime.

### Dialogue Node

Spoken dialogue. The most common node type.

<ParamField path="Speaker" type="string" required>
  Who's talking.
</ParamField>

<ParamField path="Emotion" type="string">
  How they feel.
</ParamField>

<ParamField path="Text" type="string" required>
  What they say.
</ParamField>

<ParamField path="NextNode" type="string">
  Node to advance to. Omit to end the conversation.
</ParamField>

<ParamField path="SetFlags" type="list of strings">
  Flags to set when this node plays.
</ParamField>

**Plain dialogue**

```yaml theme={null}
node_1:
  Speaker: "Rupert"
  Emotion: "Bored"
  Text: "Another day, another shift."
  NextNode: node_2
```

**With flags**

Flags persist across the conversation and can be checked later by a [Branch Node](#branch-node).

```yaml theme={null}
node_4:
  Speaker: "Rupert"
  Text: "Fine, I'll help. But you owe me."
  SetFlags:
    - rupert_helped
  NextNode: node_5
```

<Info>
  A node's name can be any string such as "node\_3" or "help".
</Info>

### Choice Node

A dialogue node that presents the player with options. Same as a Dialogue Node but with a `Choices` list. When `Choices` is populated, `NextNode` on the parent is ignored and is prefered to not be set as it is semantically incorrent. The player's selection determines the next node.

<ParamField path="Speaker" type="string" required>
  Who's prompting the choice.
</ParamField>

<ParamField path="Emotion" type="string">
  How they feel.
</ParamField>

<ParamField path="Text" type="string" required>
  The prompt itself.
</ParamField>

<ParamField path="Choices" type="list of choices" required>
  <Expandable title="choice fields" defaultOpen>
    <ParamField path="Text" type="string" required>
      The option label shown to the player.
    </ParamField>

    <ParamField path="NextNode" type="string" required>
      Node to advance to when this choice is picked.
    </ParamField>
  </Expandable>
</ParamField>

**Example**

```yaml theme={null}
order:
  Speaker: "Jerremiah"
  Emotion: "Happy"
  Text: "What would you like to eat?"
  Choices:
    - Text: "Steak"
      NextNode: serve_steak
    - Text: "Burger"
      NextNode: serve_burger
    - Text: "Pizza"
      NextNode: serve_pizza
```

### Branch Node

A utility node that routes to one of two targets based on flag state. Branch nodes have no speaker or text. They're invisible at runtime, used for control flow.

When `CheckFlags` is populated, the node evaluates: if every listed flag is set, it routes to `TrueNode`; otherwise `FalseNode`.

<ParamField path="CheckFlags" type="list of strings" required>
  Flags that must all be set for the True branch.
</ParamField>

<ParamField path="TrueNode" type="string" required>
  Node to advance to when all flags are set.
</ParamField>

<ParamField path="FalseNode" type="string" required>
  Node to advance to otherwise.
</ParamField>

**Example**

```yaml theme={null}
returning_check:
  CheckFlags:
    - met_blacksmith_before
  TrueNode: greet_warmly
  FalseNode: greet_coldly
```

Branch nodes are also how you build loops — point `FalseNode` back to an earlier node in the conversation to create a loop.