Skip to main content

Chat Trees

Chat trees are the main way you author conversation content.

A chat tree is a ScriptableObject-based flowchart graph where each node represents a moment in a conversation and connections between nodes represent the possible paths a conversation can follow.

The data model​

A conversation is built from these parts:

  • ChatTreeData -- the top-level container, a ScriptableObject asset
  • nodes -- individual dialogue moments within the tree
  • connections -- edges between nodes, optionally gated by requirements

Node types​

There are four node types in a chat tree.

Chat nodes​

The standard dialogue node. Contains one or more beat groups that present content to the player or listener. Most nodes in a tree are chat nodes.

Start nodes​

The entry point of a tree. Every tree has exactly one. The start node is structural and does not display any content. It can have multiple outgoing connections with requirements, allowing the tree to branch from the very beginning based on conditions.

End nodes​

Mark the end of a conversation path. When the runtime reaches an end node, the conversation closes. End nodes can apply blackboard effects before closing, which is useful for recording that a conversation happened.

Reference nodes​

Point to another chat tree or back to the current one. They support three modes:

  • jump -- moves to the target tree permanently
  • call -- enters the target tree and returns when it ends (like a function call)
  • return -- pops back to the calling tree and continues from the next connection

This allows you to split large conversations across multiple tree assets and reuse common dialogue sequences.

Connections​

Connections link nodes together. Each connection can carry:

  • requirements that must be met for the connection to be available
  • blackboard effects that apply when the connection is traversed
  • a display label (for player-facing options)

When the player reaches the end of a node's content, the available connections determine what happens next. If only one connection is available, the conversation advances automatically. If multiple connections are available and marked as options, they appear as dialogue choices.

How agents select trees​

Each dialogue-capable agent references one or more chat trees. The simplest setup is one tree per agent.

For agents that need different conversations based on context, RequirementGatedDialogueTreeSelector evaluates a list of tree selection rules in order. The first rule whose requirements are met against the current participants wins.

This means you can have one tree for a first meeting with the blacksmith, another for return visits, and another for when the player is carrying a specific item -- all resolved automatically. It also allows for more complex decisions on headless chats.

Practical advice​

Start with a single tree containing a few chat nodes connected in a line. Add branching only after the basic flow works. Reference nodes and call/return logic are powerful but add complexity that is easier to debug once you are comfortable with simple trees.

Where to go next​

Last updated on