YAML Syntax

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

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.

LanguageID

required

The language this file is authored in. See LanguageID.

TextDirection

required

Reading direction. LTR or RTL. See TextDirection.

Example

MetaData:
  Language: English
  TextDirection: LTR

Aliases

Reusable text snippets, organized as alias → key → value. Anywhere in dialogue text you write @alias.key, the value is substituted at load time. Useful for character names, titles, or any string you want to change in one place. Aliases resolve into Speaker, Text, and choice Text fields. Other fields (NextNode, flag names, etc.) are not alias-resolved. Example

Aliases:
  player:
    name: "Aria"
  captain:
    name: "Jack Fiddle"
    unknown: "???"

Used like:

Speaker: "@captain.name"
Text: "Pleased to meet you, @player.name."

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

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.

string

required

Who’s talking.

string

How they feel.

string

required

What they say.

string

Node to advance to. Omit to end the conversation.

list of strings

Flags to set when this node plays.

Plain dialogue

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.

node_4:
  Speaker: "Rupert"
  Text: "Fine, I'll help. But you owe me."
  SetFlags:
    - rupert_helped
  NextNode: node_5

A node’s name can be any string such as “node_3” or “help”.

Set Flags Node

A node that hanldes and sets all the flags you need, useful after a node that can’t set its own flags like the Branch Node.

list of strings

Flags to set when this node plays.

string

required

Node to advance to when this choice is picked.

Example

node_4:
  SetFlags:
    - first_flag
    - second_flag
  NextNode: serve_burger

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.

string

required

Who’s prompting the choice.

string

How they feel.

string

required

The prompt itself.

list of choices

required

Hide choice fields

string

required

The option label shown to the player.

list of strings

Flags to set when this node plays.

string

required

Node to advance to when this choice is picked.

Example

order:
  Speaker: "Jerremiah"
  Emotion: "Happy"
  Text: "What would you like to eat?"
  Choices:
    - Text: "Steak"
      NextNode: serve_steak
    - Text: "Burger"
      SetFlags:
        - wanted_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.

list of strings

required

Flags that must all be set for the True branch.

string

required

Node to advance to when all flags are set.

string

required

Node to advance to otherwise.

Example

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.

Welcome

Getting Started

How To

Reference

A complete file

Top-Level Blocks

MetaData

Aliases

Dialogue

Node Types

Dialogue Node

Set Flags Node

Choice Node

Branch Node

​A complete file

​Top-Level Blocks

​MetaData

​Aliases

​Dialogue

​Node Types

​Dialogue Node

​Set Flags Node

​Choice Node

​Branch Node

A complete file

Top-Level Blocks

MetaData

Aliases

Dialogue

Node Types

Dialogue Node

Set Flags Node

Choice Node

Branch Node