rss feed of the blog sol stuff discord follow sol email sol Sol::Code

DialogTree (d3)

Game dialog tree middleware engine

Concepts and Data

Instead of having separate "question" and "answer" nodes, each step of the dialog is considered to be a "card". Each card contains one question and zero to many answers, and each answer leads to another card (or, in a special case, the same card).

A bunch of cards create one dialog, and a set of cards is called a "deck". Each NPC the player talks to has their own deck (or, in some cases, several).

Each deck contains the following kind of information:

  • Deck ID, mostly for generating unique tags for answers (see below)
  • One or more cards
  • Optional user-defined data that the game engine can use.

Each card contains the following kind of information:

  • Card ID, so answers can refer to it as target.
  • Question text, if any, possibly localized to several languages.
  • List of tags to set, and list of tags to clear, whenever this card is shown.
  • Zero or more answers. Zero answers means this is an exit point.
  • Optional user-defined data that the game engine can use.

Each of the answers has the following kind of information:

  • Target ID, or the card to which selecting this answer will lead.
  • Answer text, again possibly localized to several languages.
  • List of tags that need to be there to show the question, and list of tags that may not be there to show the question.
  • Optional user-defined data that the game engine can use.

Dialog starts from the first card on the deck, unless the game engine forces it otherwise. You can also change the way dialogs start with some tag trickery; see below.

Questions With No Answers, Answers Without a Question

As a special case, if a question has no question text, the engine jumps to the next card without prompting the user to select an answer. Typically this would be the only answer available, but you can do more trickery by having several answers with no text, and using tags, only keep one active. If multiple answers are available with no text, the first one is used. This way you can, for instance, make an NPC say something unique the first time you talk to them, and "hello again" on later discussions.

Using a card with no question text but a list of answers and card(s) with question text but no answers lets the designer create more sensible dialogs where some "busy node" is visited many times without having to repeat the exact same question over and over again, like..

(multiple options node #1)
  Sure. What do you want to know?
(multiple options node #2)
  Not that I'd frequent such places, blahblah..
(multiple options node #2 - back to the same multiple-question node without "Sure.." question)
  Okay, it's not like I have anything better to do.
(multiple options node #1)


The system uses tags to control whether dialog options should be shown or not. In a simple, linear dialog you'd just show all options, but having the possibility of hiding parts of the dialog tree adds a lot of possibilities.


  • You can only ask about the murder after hearing about it first
  • After choosing your love interest, the romantic branches in other characters are closed

Tags are alphanumeric, case insensitive, and may use any combination of a-z, 0-9 and underscore, simlarly to variable names in most programming languages. Tags should also be relatively short in order to conserve resources.

While other characters might work in practise, they might break serialization (and/or other features) at some point, so stick to the defined set.

All dialogs in a single game share the same tag storage, so talking to one character and activating (or clearing) tags can change the way you can interact with other characters.

By default, all questions are defined as single use only by the tools that are used to create the script. Every single question has a tag that it sets whenever it's used, and has this tag on it's "don't show if this tag is active" list. To make a question persistent, simply remove the tag from the "don't show" list. The format for these autogenerated tags are deck id + '+' + card id + '+' + a + answer number. So the first answer for some question might be "gatekeeper+q3+a1". Note that normal tags may not use the character '+'. After some thought I think the tag just has to be unique and have a + in it.

Talking With D3 From Your Engine

You can interact with the d3 engine through several ways.

First, your engine can access the tag store, query, set or clear tags. So, after your character finds a murder weapon, the player can start asking about it. Or you could check what tags are active and show them on your "open quests" list.

Second, by tracking the exit nodes from the dialogs, you can make decisions on what to do next - should you move into battle or did the player manage to avoid confrontation?


Comments, etc, appreciated, as always.

Site design & Copyright © 2022 Jari Komppa
Possibly modified around: August 06 2011