Using GoJS to Map and Maintain A Text Adventure Database

Exporting formatted records for PowerUp — GSoC at Systers

There was no way I was going to be able to edit and maintain the PowerUp database without some help.

PowerUp Scenario Builder

Starting out, I was just looking at what was already out there. I had hoped to find an app that essentially did what I wanted it to do. I came really close to trying to hack Twine to suit my needs, but then I came across GoJS.

GoJS is a feature-rich JavaScript library for implementing custom interactive diagrams and complex visualizations across modern web browsers and platforms.

I’d heard of it before, but I had never used it myself. I was really impressed with the large number of detailed examples they provided.

One of the examples looked really promising, and it ended up providing a great framework for creating the app I had in mind. It started out just as a mapping tool.

SQLite Mapper

It dynamically loaded PowerUp’s database right from the git repo, and laid out the records as connected nodes. This was cool and all, but I realized I would really need a better way to edit the database. I most certainly did not want to spend days scrolling through tables with hundreds of records just to find an incorrect value or fix a typo, so I started updating the mapping tool to be editable. There were some twists and turns, but I was able to get it together pretty quick thanks to GoJS.

The HTML for this is pretty solid. You just need a div to hold a canvas.

<div id="diagramDiv"></div>

The real magic happens in the node templates. See, GoJS graphs are based on these templates, but the best part is that pretty much anything can have a custom binding attached to it.

let fieldTemplate =
    $(go.Panel, "TableRow",
        $(go.TextBlock, {
            margin: new go.Margin(0, 5),
            column: 1,
            font: "italic 11px sans-serif",
            alignment: go.Spot.Left,
            fromLinkable: false,
            toLinkable: false
          },
          new go.Binding("text", "name")
        ),
        $(go.TextBlock, {
            margin: new go.Margin(0, 5),
            width: 100,
            column: 2,
            font: "11px sans-serif",
            alignment: go.Spot.Left,
            wrap: go.TextBlock.WrapFit,
            editable: true
          },
          new go.Binding("text", "info").makeTwoWay()
        )
    );

It didn’t take too long to set up a template that would cover all of the data needed for a PowerUp database record, and make the fields editable. I added logic to control linking to help ensure the database couldn’t get too messy, and automated as much of the process as I could think to.

I had this working tool now, where I could edit and see the data. But I was having to manually copy/paste the graph JSON if I wanted to save the work. So I started adding this toolbar at the bottom. It originally had buttons included in the example that saved and recalled data just in the window, as well as the Do Layout function. It wasn’t too far a leap to just have the save button download a separate JSON file, and have the load button open up a dialog to select that JSON file.

Then I just sort of kept adding features to make my life easier. You can export CSV files ready to be pasted into the main PowerUp database, and you can export PDF or SVG to make it easier to share progress and ideas. The little details started to become overwhelming, which some of the other Systers pointed out. They asked for some in-app documentation, so I added a simple menu with some instructions on how the app works.

Slide Out Instructions

I had originally intended this to just be for me, but then I saw that there was already a github issue to provide documentation and a schema for the database. I thought this could help tremendously with that, so I started sharing it with some people. It’s received a really positive reception since then. I’m certainly planning on using it to manage my work, but it makes it so much more worthwhile if it can be useful to the entire project. (And perhaps beyond…)

The project can be viewed on Github. And a live demo can be viewed here.