gamebookformat

Hello. I created an account and introduced myself on this forum almost 2 years ago, but have not posted anything since. I did lurk a bit though (as I have, mostly, lurked on the usenet groups before that, on and off since 1995).

Gamebooks and tools to make them are sometimes discussed on this forum (I refuse to talk about them as CYOA after reading some actual CYOA books) so I thought someone might be interested in this open source tool I created last year to help me create such books:
github.com/lifelike/gamebookformat

It is a python script that reads a gamebook file with some simple markup. Output can be a gamebook as LaTeX, RTF, plain text, HTML for instance. Or you can generate playable HTML with JavaScript that lets you play/read in a browser, keeping track of stats and inventory, allowing you to disable choices not available (eg not being able to open a door without the right key or whatever). I have read many gamebooks, studied even more, trying to include enough features to implement most of them. The main thing lacking is a combat system (not that all gamebooks need one, right?).

Paragraphs are given symbolic names, and the paragraphs are shuffled and numbered automatically. The numbers used are saved to a separate file so the same paragraphs can be given the same numbers again when you re-run the script (trust me, that makes incremental development/playtesting a lot easier).

Why yet another format, you ask (or should ask)? Well, I started because I wanted to make paragraph-driven boardgames, so I needed nice printable output, plus some features that makes it easier for me to integrate with a printed board. I also wanted something that would play well printed on paper and played on a computer/tablet/smartphone. While the format supports adding some logic to the books, I have tried very hard to make the results always playable also in a printed version (or if you want to read the PDF on a screen; it has clickable links to take you between paragraphs, but of course no other logic). For instance I have avoided any feature, like optionally displaying text, that simply can not work in a printed book. That was the main problem I had with existing solutions I could find, that in the rare cases they supported static printable output it seemed more like an afterthought and relied on carefully using a subset of the tool. Or the tools only could create a static book, no playable digital version at all. There were probably some tools I did not see, but anyway NIH is always a strong reason as well I guess.

It is easy to add templates for more output formats, or add new tags to existing formats, for instance if a book needs some special ‘macros’ or formatting and/or scripting. I made a quick attempt at creating some Twine output, but there were some of my tags that were not trivial to translate to that format, so I put that project on hold for now (it felt a bit redundant too because I already export directly to HTML+JS, but since I have not spent much time making nice CSS for my HTML Twine would have been a nice shortcut to get much prettier results).

Here is an example file:
bgg.gamebook

And this is what the output looks like:
PDF
HTML
PNG (flowchart)
JSON (section-number map)

Not going to bother anyone much about this. It’s mainly for my own use, for games/gamebooks I want to make. But if it happens to be useful to someone I would be happy to discuss it and accept patches and/or discuss future updates.

I’m not able to access the site the examples are hosted on for some reason. Do you have any mirrors? (Or, alternatively, would you mind just sending me a zip with the different formats of the example in it?)

They are also all in the expected/ subdir in the github repo (together with some more examples).

Try a program called Advelh. Last release was in 2007 revision 36.1 for the pc windows system. It mainly tracks paragraphs so if you swap two locations around it changes all the pointers to acomidate the swap. That way you dont end up with “Goto X” and theres nothing at X. It can handle up to 800 “sections”. I find it verry usefull.

That sounds extremely limited though, as my system has no limit on the number of paragraphs, handles many more things than numbering paragraph links, do not force you to use a specific editor, and is not limited to just one operating system. Not to mention gamebookformat was last updated in 2013 and you can expect more in 2014

But I will have a look to see if there are other features worth borrowing from that tool. Do not remember if it was one of those I considered before writing my own.

It’ll be interesting for me to look at your option to shuffle paragraphs, I may be able to reuse it for using with my own tool, textallion, which has a similar purpose and aims at producing printed documents, ebooks or website (I’m also using graphviz and latex like you do), and it can exports to several other formats as well (among others, twine).
The manual: anamnese.online.fr/site2/textall … oa_en.html

You can find some examples there: anamnese.online.fr/site2/textall … lue_death/

Impressive list of output formats, and looks like a nice markup language!

Named paragraphs that are automatically numbered and have the correct number inserted for all links is very easy really. Surprised so few tools do that. Although mine just does a standard shuffle. Ideally it would use some algorithm to number sections more intelligently, eg never link from one section to the very next one.

gamebookformat now also includes the tool checkgamebook.py that for now can at least do some simple sanity-checking (finding unreachable sections and print out a list of all ending/death sections in a book). Requires a debug output-file built for a gamebook using the same flags as will be used for the real output-files (eg if ignoring some tags when making the HTML and PDF versions of a book, those same tags must be ignored when generating the debug file).

To support that script the old debug format has been changed to a much more formal one (in JSON) that makes it trivial to write scripts like checkgamebook.py. It would also make sense really to use that format for players. Maybe I will even throw out the old HTML+js gamebook-player and replace it with a new one that use the JSON data to render sections instead of the rather kludgy HTML data-tags in the current one. But if the debug format isn’t only used for debugging gamebooks it should probably have a better name.

Also some other misc bug fixes and small improvements, including a short section in the README with some hints on how to make EPUB (tl;dr: make the static HTML version of your book and convert it using Calibre) and also documenting a few other minor features in the README.

(Perhaps admin could move this thread to the choice-based if-tools forum now that it exists?)

Twine 2 looks very nice, and the generated HTML is (like old Twine) much nicer than what the HTML generated by gamebookformat is (TODO: borrow some nice stylesheets). For fun because I sort of had an hour to spare I added an option in gamebookformat to export to Twine 2. It is in the latest version on github now.

Here is an included example file and what it looks like when exported to Twine 2 (that file can be imported in the Twine 2 user interface to play or edit):

raw.githubusercontent.com/lifel … t.gamebook

raw.githubusercontent.com/lifel … est.twine2

… and this is what the story looks and plays like when exported from Twine to a stand-alone HTML file:

lysator.liu.se/~perni/Gamebo … ample.html

(Not much of a story though. Also that file is not updated with the latest changes from github so it differs slightly from what is in the files seen above.)

Obviously lots of things missing. To make it really useful I should add proper markup for collections and items. It looks like that will not be too difficult though. I think they did a great job on Twine not only with the user interface but also the data format (except I have some issues with whitespace being significant that is always annoying).

EDIT: Note how the generated “HTML” isn’t actually html at all. Maybe I should give it another extension in the future. It was just that the generated files when you exported from Twine were called html, so I followed that convention.

EDIT 2: Changed output type from html to twine2. Updated this post to reflect that to avoid confusion.

While at it I added a new command-line flag (-x, or --allow-unknown) and some supporting code and documented it a bit like this:

“Any of the built-in templates can be overridden easily. New tags can be added that can generate any output you need for different file formats. However to add a tag that is not included in the default distribution the command-line flat -x is required to tell gamebookformat that you know what you are doing. Otherwise when an unknown tag is encountered you get an ugly error message. The reason for making it moderately difficult to add a new tag is that all the builtin tags have been choosen to work reasonably well in anything from static printed gamebooks to dynamic digital app gamebooks. Anyone thinking of adding a new tag should think twice about how having that tag might mean that some output formats are not longer useful. Sticking to the default tags and not overriding them to do bad things ensures that your gamebooks are still readable and playable in all supported output formats. (The process of adding new templates and new output formats really should be better documented.)”

It is a difficult balance to make it easy to extend the format with any template the user want to have and also make sure that generated gamebooks work both on paper and on screen. To make books that only work on a screen there are many other tools, some most likely much better than gamebookformat. This tool is by design made to compromise and only include features that will also look good on paper, meaning that some stuff supported by eg Twine will never be included (anything dynamically generating text, essentially, so no inserting variables or optionally including a block of text).

Now instead of pretending that twine2 is a subtype of html (the -o twine2 option) twine2 is its own output format. Now on github! Hopefully I updated all the examples and documentation.

Thread moved by request. :slight_smile:

I wish you the best in your endevors Pelle.

A small update: There is now an option to generate books where each section begins at the top of a new page (ie adding a page-break before each new section). Some published books have that style (eg the Choose Your Own Adventure books for kids). Not useful at all for generating a book played/read on screen (when exporting to html or twine2) though.

So this project kind of died (as you might guess from the last post date being almost 4 years ago).

It does kind of what I wanted it to do, making static gamebooks in many different formats (and graphs of them) from a text file.

But I got a bit carried away with adding output formats and variations. Also all the tags supported by the markup language and all the tags I planned to support were a bit much. The markup got a bit complex, while still being oddly limited with many things forcing the text to be written in a specific orders for the story logic to work (e.g. the cost of following a link had to be specified before it in the text, left-to-right).

Thinking of rebooting the project, probably with a new name, and only support simpler paragraph structures. Text followed by a list of choices, like in most books. That just makes everything easier for everyone (i.e. me, authors, readers). No need to try to mix in story logic in the text itself.

Still of course doing the same basic things, probably using the same old code, shuffling paragraphs (and keeping the numbers between revisions), generating static output, Twine output, graphs etc. But relying more on external tools. Not doing my own JavaScript+HTML but relying only on Twine, and using an output format like Markdown to offload much of the output formatting to a tool like Pandoc. There is no good reason to maintain my own document layout system just to have many output formats. Relying on Twine and Pandoc for almost everything will result in probably better and more output formats, while keeping the gamebook tool focused on what it can do best.

Anyone looked at this and have any other suggestions? Have there appeared any similar tools that I might want to look at that can kind of do everything this anyway, so a new tool would just be redundant?

Had to think out loud a bit. Helped already to make up my mind about some things as I typed this. Kind of said many similar things in issues I opened myself in GitHub 1.5 years ago:

github.com/lifelike/gamebookformat/issues/1 (“Build on top of other tool for output formats”)
github.com/lifelike/gamebookformat/issues/2 (“Build on top of some other tool for playable electronic games”)

Also if/when I post an updated tool it will probably be with a new name in a new git repo. And a new thread here I guess. And write some books/games.

I should mention a special case of what the last post described: Using some existing format for digital choice-based if and use that as input format instead of a new format. Or more likely a subset of an existing format. It would then be something like “a tool to take your twine/ink/choicescript story and export it to a markdown file with shuffled numbered paragraphs so that you can make a static epub or pdf from your book”.

Not sure if that makes more or less sense than a unique file format. It might be worse in many ways, but have the benefit of maybe attracting some users that would have absolutely zero interest in a new format, but might like the idea of rendering their story in a new way. And more users for an open source project is an important consideration.

Not sure what format would make the most sense in that case.

It would probably require some special stuff to be present to make things like inventory management to work the same in the dynamic and static version of the story.

The opposite is also a possibility, but probably less interesting, to take a Markdown or similar static file as input.

I’m biased toward twine twee, for what that’s worth.
(Presumably twee is easier to parse.)

Often I’ve wanted to read the story without struggling through the puzzles.

I just googled the different formats to remind myself what options there would be (for input or/and input) these days. Forgot about twee! It also has JSON export already which might make even more sense than to write a parser for the twee format. And of course the entire tool is already python and open source, so it might even be reasonable to put gamebook-export code right into (a fork of) that script instead of having a separate tool.

EDIT: Or is it twee2 (written in ruby?) that is the twee to use these days? The old twee I find has not been updated in 2 years. dan-q.github.io/twee2/documentation.html

Full disclosure: I’m the developer of Tweego.

The Twee notation compiler landscape currently looks as follows:

  • Twee is the unofficial Twee notation compiler written in Python 2. It is neither under development nor actively maintained—it’s essentially abandonware at this point. The version within the Twine repository—rather than the older Twee repo—should be the most current version of the compiler.
  • Twee2 is an unofficial Twee notation compiler written in Ruby—it also leans heavily on various GEMS, so you’ll need the ecosystem as well. AFAIK, it’s no longer under development, though it’s still maintained.
  • Tweego is an unofficial Twee notation compiler written in Go. It’s actively developed and maintained—though it’s been a while since work has been committed due to health issues.

The above list only includes command line compilers in the style of the original. Twine 1 can also import/export Twee code and there are proofing formats for Twine 2 which can display Twee code.