The structure of an adventure can be thought of as a state machine (see this guide) or as a flowchart since state transitions are very constrained (time, single button press, or a binary choice). We'll use a limited form of the latter to diagram adventures.

Cards can be represented as a simple box. The box should contain at the very least the id of the card. This will serve to link cards in your diagram to those in the JSON file. You can add more information such as image, text, or sound, but the goal of the diagram is to work on the flow of the adventure, not detailed contents.

Transitions that are automatic or ones that occur when a single button is pressed can simple be a line connecting pages. Using an arrowhead to show the direction of the transition is generally a good idea and avoids any confusion. The line can be labelled with a time (e.g. "5s") or a button label (e.g. "Begin"), respectively.

When a card has two buttons, and each has a transition to another card. These should be labelled with the text of the corresponding button. While this will often be a yes/no choice, it can be any choice with two options.

An alternative is to use the diamond symbol from flowcharting. It makes the decision point clearer but does take more space. Both will be used in further examples. Note that the decision diamond is NOT a separate card, but is simply an aspect of the card above.

That's it: cards, simple transitions, and binary choices. These simple tools let us do plenty of interesting things.

Common Patterns

Building on the above atomic pieces, we can step back and look at structures of multiple cards that occur commonly.


Every adventure starts somewhere. Every story has a beginning. We denote that in our adventure diagram with a circle that is connected to the first card.


A common thing to do is present several cards to the user in sequence, either automatically or by using something like a "Next" button.


A big part of the idea of this framework is the ability to present the user with choices that let them have control over their path through the adventure. The framework supports binary choices. These can be Yes/No or any other two options. They provide points in the adventure where the path splits, taking the user down one of them based on their choice.


There is no limit on how many other cards can transition to a given card. You can make use of this when multiple paths in an adventure join back together.


Loops are when the path through an adventure returns to a card that was previously visited. It can be because of the user's choice or because the path they are on naturally returns them to a previous point; think in terms of a tunnel in a cavern that curves back and leads them to a previous part of the cavern.

Starting Over

This is a common application of a loop. At some point or points there is a transition back to a card near the start of the adventure. This is often when the adventure reaches a conclusion either good (you saved the prince/princess) or bad (you were eaten by a grue). 


Adding a maze is a fun way to frustrate users. It's simple a collection of rooms with the same description and exits to the left and right. You interconnect them in such a way as to allow the user to go in circles if they make incorrect choices. Eventually, a series of correct choices leads them out of the maze.

For example:

An Example

Here's the diagram for a simple, but complete example: the sample that is packaged with the library.

This guide was first published on Jun 22, 2019. It was last updated on Jun 22, 2019.

This page (Designing an Adventure) was last updated on Oct 15, 2020.

Text editor powered by tinymce.