Skip to main content

A utility for parsing HTML Twine stories and saving them into json or graph formats

Project description

Twine Graph

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.


Twine Graph requires Python 3 and the beautifulsoup4 and graphviz packages. Tested primarily on Mac OS X within an Anaconda environment.


The easiest way to install Twine Graph is through pip:

pip install twine-graph

Example usage

The installed package can be called from the command line through its entry-point, as in the following sample call (using the example .html file included in the github project):

twine_graph twine_graph_example.html

The output .gv.pdf file can be opened for a visual representation of the passage and link structure of the story, while the output .json file provides a structured representation:

  "passages": [
      "pid": 1,
      "name": "Hello",
      "text": "[[Hello->World]]",
      "links": [
          "text": "Hello",
          "destination": {
            "name": "World",
            "pid": 2
      "pid": 2,
      "name": "World",
      "text": "Hello World",
      "links": []

Known Issues

  • Doesn't detect links produced by custom javascript
  • Doesn't detect links referenced through variables (i.e. variable tracking not supported)

Related Work

  • twine-parser: A Javascript utility for parsing twine stories into graph objects.
  • TwineJson: A utility for Twine that exports a story into JSON format.


Enrique Henestroza Anguiano


This project is licensed under the GNU GPL License - see LICENSE for details

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

twine-graph-0.0.1.tar.gz (5.2 kB view hashes)

Uploaded source

Built Distribution

twine_graph-0.0.1-py3-none-any.whl (5.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page