Gamebook Creation Tool using Twine/Sadako/TiddlyWiki/Markdown as Input

I made a thingy:

It’s a tool for the purpose of creating gamebooks. It takes TiddlyWiki exported JSON, Twine published/archived HTML, Twine twee source files, Sadako script files, and standard markdown files as input. It outputs standard markdown (converted from other formats), graphviz flowcharts, and epub files.


  • Configuration settings are done inside <!-- --> HTML comments so they don’t interfere with viewing of HTML or markdown, and will also be supported by most syntax highlighters.

  • Graphviz flowcharts have some mild markup to allow you to color start, bad ending, and good ending sections, along with listing story flags that are enabled/disabled in a passage.

  • Conversion to an epub book is as simple as setting two metadata settings (a title and a unique identifier for ISBN) and table of contents. Then just zip the folder and rename to .epub and you have a working book that you can dump into your ebook reader. I made sure all generated epub files don’t throw a single error or warning when being checked against epubcheck.

  • Some convenient epub settings:

    • Marked blocks of sections to be can be collected into a single page, which is really convenient for a gamebook (not so much for a normal book).

    • Marked blocks of sections can be automatically renamed in a numeric ascending order starting with a defined starting point. In other words, you can use normal names for your sections (“get key” or something) and the converter will rename it to 1, 2, 3, etc. Links in the sections’ text directing to these sections will also be changed to reflect the name change. So if you link to it with Turn to [[get key]]. in the source, it’ll display as Turn to [[1]]. in the epub.

    • Marked blocks of sections can be shuffled. Not only will they be rearranged in the print order, but if you have numeric renaming of sections enabled, they will be be renamed in correct order. In other words, if “get key” was the 10th section in the story and it gets changed to being the 2nd section from where the title renaming begins, it’ll be renamed to “2” and all links directing to it will also be renamed to “2”.

I think that’s about it. Just like Sadako, this is a toy that I made for myself and decided to share with others. Hopefully someone find it helpful.

Here’s an example of the generated graphviz flowchart, for those curious.


I uploaded a new version of my converter.

The biggest change is that you can have fixed sections within a shuffled block of sections. So, for example, say you have sections 1 - 10 and they’re set to be shuffled, but you have one section that you want to always be 5. Now you can do that.

Additionally, you can also reference a fixed section with another fixed section, which makes the referenced section an anchor. So if you have a section named “apple” and fixed it at 5, you can then have another section fixed at “apple + 5” and so it’ll be set to section 10.

If you are unfamiliar with gamebook conventions, you may be wondering why in the world this would be something I would feel the need to add. Well, this is how gamebooks do puzzles.

For example:

What animal meows? If you think you know the answer, add the letters together (where A=1, B=2, C=3, etc) and turn to that section.

In this case, you’d want section 24 (3+1+20) to be fixed in place so that the player could turn to that section after they solved the puzzle. There’s no direct link to this section. The whole puzzle is that unless the player gets the answer, they won’t know what section they’re supposed to read next. They have to turn there manually to check their answer, and then continue reading from there if they guessed right.

Another kind of puzzle:

You have found a key. If you come across a door that you think can be unlocked with the key, add 50 to the section number and turn to that section.

In this case, you would want the section with the correct solution to be anchored to the section with puzzle. So if there is a locked door on section 30, the player can use their previous knowledge of how to use the key and turn to section 80 to unlock it.

Anyway, that’s it. You can get the new version from here:

And you can read more info on the fixed sections here.


I released a small update to the converter. It’s mostly a bug fix to account for the fact that I forgot markdown doesn’t allow spaces in its links. :sweat_smile:

Absolutely no changes to your code will have to be done. The accounting for lack of spaces will be handled internally by the converter.

These are the changes:

  • You can now use varying input types that are combined into a single story. For example, you can write your cover, table of contents, etc in markdown (.md) but write your story in twine (.html) and the converter will combine them in the order listed on the command line.

  • Converting of links have been adjusted to account for limitation in standard markdown format. CommonMark doesn’t allow spaces or underscores; they’re converted to dashes. To account for this, a link such as [[Some Link]] in twine now converts to [Some Link](#some-link). You can still use section names like Some Link and some_link – it’s only the link used to reference them that’s been changed (to align with CommonMark standards) and the converter will make the automatic adjustment for you.

You can nab the new version here:

1 Like

This is interesting, I’ve never played any of the old game books but I’ve been interested in the format since browsing some reviews of the classics.

I’ve been designing some puzzles for a tabletop game with my nieces, and now I’m thinking of making a nice printable version in a format like this.

1 Like

I love gamebooks. :smiley: There’s something about trying to do more with less that is really appealing, I think. I have a feeling most IF fans have an idea of what I mean.

There have been some really great digital adaptions of gamebooks, like the mobile versions of the Lone Wolf series, or the Sorcery series adapted by the Inkle guys (another good example of Ink). However there’s still something really fun about flipping through an actual book or ebook, tracking stats and items by hand, and rolling your own dice.

If you’re curious and would like to check out the format, Joe Dever released all of his Lone Wolf books under public use. You can find all of them under various formats (epub, pdf, mobi, html) on Project Aon.

There are also a few sites that host some fan made gamebooks online. For example Fighting Fantasy Project which has a bunch of stories using the – you guessed it – Fighting Fantasy ruleset. Although those are scripted web pages, so you don’t need to take notes or roll dice. They’re still presented like a gamebook though.

There’s also Chronicles of Arborell which is a huge indie gamebook series that’s an original work. It’s really impressive.


I can definitely understand the appeal of “more with less”, that’s a big part of the draw of text games for me to begin with.

Thanks for the recommendations, I’ll check them out and experiment more with your program here as time allows. The old Gamebook Adventures which were the predecessors to Fighting Fantasy were already on my list thanks to some (now very exclusive and difficult to find) reviews I read of most of the series on the IFDB.

I’m going to go and get the Project Aon app downloaded right now.