Twine Graph is a Python package and command line tool for parsing passage and link structure from published .html Twine stories and outputting the resulting graphs in visual (.pdf) or structured (.json) formats. The goal of Twine Graph is to allow for research and analysis of story structure in freely-available Twine games.
The initial release is now available through PyPI under the name twine-graph
, and the source code is available on GitHub.
Story Visualization
To demo Twine Graph’s capabilities, let’s look at two recent, highly rated Twine stories from the annual Interactive Fiction Competition (IFComp). Cactus Blue Motel (2016) is a game that involves a large amount of movement between the rooms of the titular motel, while Will Not Let Me Go (2017) is a more linear story that moves from scene to scene with only a few clusters of densely interlinked passages.
The twine-graph
command line utility takes a published .html Twine file as input and programmatically derives a directed graph structure of passages and links. It outputs a structured .json file and corresponding graph image file, with the nodes laid out according to heuristics encoded in the graphviz
library. The automatic layout appears to work well for many Twine stories, creating a top-to-bottom flow with nodes clustered into visually coherent sections.
In Cactus Blue Motel, the start and end sections are apparent, along with an interesting mid-game containing large clusters of highly-connected nodes indicating distinct explorable areas. [Visualization]
In the case of Will Not Let Me Go, the flow of the story is more linear, with only a few occasional clusters of nodes for scenes that focus on interlinked passages and choices. [Visualization]
Corpus of Twine Stories
In order to unveil insights into Twine story structure on a larger scale, I’m working on putting together a corpus of story files in .json and .pdf formats for all of the freely available Twine games that have been submitted to both IFComp and the Spring Thing festival since the inception of Twine games in those competitions, which goes as far back as 2012. I’m excited about the possibilities that this data will open up for the IF community to research and analyze choice-based game structure.