Build a dialogue

A dialogue is a conversation drawn as a graph: each node is something that happens — a line of speech, a set of replies, an ending — and the lines between them are what happens next. This walkthrough builds a short branching conversation between two characters the project already has, from an empty graph to one that runs end to end.

Follow along: download the project this walkthrough starts from. The zip holds two projects — create_dialogue, where the walkthrough begins, and create_dialogue_final, where it ends up if you want to compare.

The conversation: Mira Thorne, an innkeeper, greets Charlie, the character the player is playing. Charlie picks one of three replies, Mira answers each one differently, and every branch ends the conversation.

Open the Quests & Dialogues view

Quests and dialogues are both graphs, and they live together in the Quests & Dialogues view. Click its icon in the left sidebar, or press ⌥2.

The left panel lists the project's graphs. The middle is the canvas you build on, and the right panel shows the properties of whatever is selected.

Add a dialogue and name it

Click Add in the toolbar and choose Dialogue.

The new graph appears in the tree with its name ready to edit. Type a name and press Enter.

This name is how your game's code refers to the conversation, so it has to be a valid identifier — letters, digits and underscores, no spaces. This walkthrough uses MiraGreeting.

Give it a title and a description

With nothing on the canvas selected, the properties panel edits the graph itself. Fill in the Title and Description.

The distinction matters:

• Name is the identifier. It's not meant to be shown to players.
• Title is player-facing — the text a quest log or dialogue header would show. It can be anything, including spaces and punctuation.
• Description is the short summary of what this conversation is.

Notice the pale blue node on the canvas. That is the dialogue entry — where the conversation starts, created with the graph and not removable. It displays the graph's title, so it updates as soon as you set one.

Give yourself room

A conversation gets wide quickly. The button in the top-right corner of the canvas hides the tree and properties panels and gives the whole window over to the graph; the same button brings them back.

Two things worth knowing before you start placing nodes. The Shortcuts panel in the bottom-right lists a single-key shortcut for every node type — with the pointer over the canvas, pressing one of those keys drops that node where the pointer is, and right-clicking the canvas offers the same list as a menu. And the small toolbar in the bottom-left corner zooms, frames the whole graph, and arranges it; you'll use the last two at the end.

Mira's first line

Drag from the round handle on the right edge of the entry node and let go over empty canvas. Releasing a connection with nowhere to land opens the insert menu, and whatever you pick arrives already wired up to the handle you dragged from. Choose Dialogue Node.

Click the new node to edit it in place, then fill in three things:

• Speaker is which character says this. It lists the entities in your project; pick Mira Thorne and her portrait appears beside the line.
• Short Text is a label for you — a few words naming what this node is, so you can scan the graph without reading every line. It is not shown to players.
• The larger field below is the line itself, the text your game displays.

Charlie's replies

Now the important part, and the one that is easy to get backwards.

A node's choices are spoken by that node's speaker. So Charlie's replies do not belong on Mira's node — putting them there would have Mira reciting Charlie's lines to herself. They belong on a node of Charlie's own.

Drag from Mira's output, add another Dialogue Node, and set its speaker to Charlie. Leave its text empty: a node carrying choices does not have to say anything itself. Then click + Add choice.

Add a row per reply and write each one, in Charlie's voice. If the node is cramped, you can grab the handle in the bottom right to resize it.

Each row grows its own output handle on the right edge — that is what makes the branches separate. The two small icons at the start of a row set conditions for hiding or disabling that reply; leave them alone for now.

If you want a lead-in before the options — a line Charlie says before the player chooses — put it in this node's text rather than adding another node.

There is also a Choice Node in the insert menu. It presents choices outside the flow of a conversation, so it is not what you want here.

An answer for each reply

Drag from the first row's handle, drop on empty canvas, and add another Dialogue Node with Mira as the speaker — the same gesture as before, but starting from a specific reply, so the branch is bound to that reply.

Do the same for the other two.

End the conversation

Every branch has to finish somewhere. Drag from the middle branch's output, drop it on empty canvas and choose End Conversation. Then drag from each of the other two branches' outputs onto that node's input handle on its left edge — several branches can share one ending.

The warning banner across the top of the canvas disappears once the graph has an End Conversation node. Without one the conversation never signals that it is over, and a game showing it would leave the dialogue window open forever.

Tidy the layout

Placing nodes by hand as you go gets a conversation built, but it rarely leaves it evenly spaced. The last button on the bottom-left toolbar arranges the whole graph — it is also on the canvas right-click menu as Auto Arrange, and on ⇧⌘A.

Conversations read left to right and the branches of a choice stack top to bottom, which is the shape arranging produces. The button above it frames the whole graph in the window, which is the quickest way to see what you have.

It now reads as it plays: Mira speaks, Charlie picks a reply, Mira answers, the conversation ends.

Save

Leave the expanded canvas with the same button that opened it, and the tree and properties come back.

Press ⌘S to write your work to disk. A * next to the project name in the title bar means there is unsaved work.

Next

The conversation you just built runs the same way every time. To make it react to the rest of your game, give a choice a condition so it only appears when the player qualifies — see Variables and conditions for the state those conditions read.

Your dialogue is now a text file on disk. Documents and the file format covers what that file looks like and how it behaves in version control, and Exporting takes it into your engine.