m. c. de marco: To invent new life and new civilizations...


DotGraph is a proofing format that uses a JavaScript implementation of Graphviz to automatically lay out a Twine story as a directed graph.


DotGraph works with Twine 1, Twine 2, Twee, or Twee2. It can color nodes according to their length or their tags, mark interesting nodes (missing nodes, end nodes, and checkpoints), omit node names, cluster by tags, skip special and/or specially tagged passages, skip display links, and rotate or shrink the graph. It also shows you some basic story statistics.


The current version of DotGraph is 2.0.2, which supports omitting passages with specified tags. Previous versions are archived here.

Each version of DotGraph comes in four forms, Twine 1 or Twine 2, and offline or online. (Twine 2 is not backwards compatible with Twine 1, so their story formats always differ.)

The offline versions package the entire Graphviz renderer in the head of the DotGraph output file, making it large but freestanding. The online versions fetch the Graphviz renderer from this website whenever you open them, meaning that an internet connection is required when using them, but the file may be also be cached, making your output file load faster if you run DotGraph frequently. In some cases you can only use the offline version; see the installation and sausage sections for more details.


Twine 2

To add DotGraph to the online version of Twine 2, use this URL (under Formats > Add a New Format): https://mcdemarco.net/tools/scree/dotgraph/format.js

To add DotGraph to the installable local versions of Twine 2, follow the installation instructions for online use, but use the following “offline” URL: https://mcdemarco.net/tools/scree/dotgraph/offline/format.js

Twine 1

To add DotGraph to Twine 1, create a new folder called dotgraph inside your targets folder, then download this file: https://mcdemarco.net/tools/scree/dotgraph/header.html and place it inside the dotgraph folder. For offline use, download and use https://mcdemarco.net/tools/scree/dotgraph/offline/header.html instead.

See the Twine wiki for more information about installing and using story formats in Twine 1.


Twine 2

After installation, you may want to click the star or radio button next to DotGraph in the Proofing Formats list (also under Formats) to make it your default proofing format.

Next, import your story (if it isn’t already in Twine 2), click on it to open it, and click View Proofing Copy in the popup menu in the lower left hand corner of the UI.

Twine 1

In Twine 1, open or create a story (under the File menu). Then, in the Story menu under Story Formats, select DotGraph as the story format. Choose Test Play or Build Story from the Build menu to see your story. (You may need to restart Twine 1 if you installed DotGraph while it was still running.)


You can also use DotGraph with an external Twine renderer like Twee or Twee2; just download the appropriate file (format.js or header.html, depending on the associated Twine version) to your filesystem and follow your renderer’s instructions for installing and using a new story format.


As a story format, DotGraph outputs an HTML file that contains the DotGraph controls, the graph of your story, and the dot source code of the graph. It will look like this:

The DotGraph UI

(The dot source is not pictured in the screenshot.)

As you change the settings (for tag color, graph direction, etc.), the graph and source code will be re-rendered live. You can save the image (SVG) and/or the source file. You can also edit the dot source manually and re-render the altered graph.


Sean Michael Ragan graphed a classic story, Chimney Rock, in the Graphviz dot style long before DotGraph.

DotGraph’s Twine 2 icon (which appears in the proofing format list after you install DotGraph) shows a simplified version of the graph of my Scree example story. Here it is, larger than life:

small example

Below is the graph of a longer, incomplete story with renumbered passages, end tags, and coloring by passage length.

large example


I described an issue with Chrome in the old Twine forum. This is why the offline mode is not only for running offline.

The source code is available at BitBucket.

DotGraph does not support Internet Explorer 8, but any newer browser should work.

I made DotGraph because my Scrivener template for Twine 2 stories, Scree, doesn’t give you a graphical layout of your story, and neither Scree/Scrivener nor Twine 2 support auto-layout of your story nodes into a graph, but Graphviz does. (Composing a story entirely in Twine gives you a manual layout of the story.)

I use coloring and/or clustering on the tags created from my Scrivener labels, which are one-per-passage anyway. You can get your Scrivener labels into your twee tags (using Scree) by adding [<$label>] to the beginning of the title suffix for each text document level under Compile > All Options > Formatting > Section Layout button. See the placeholder list under Help for other variables you might want to put there, but beware of anything with spaces in it, like the default “No Label” and “No Status” label and status, respectively. (You can edit those in Scrivener if necessary, even to the empty string.)