twine-graph 0.0.1

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

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.

Prerequisites

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

Installation

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.

Author

Enrique Henestroza Anguiano

• Website: Datalexic

License

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