• gamebookformat
  • Usage
  • Supported Output Formats
  • Included Optional Templates
  • Styles and Scripts
  • EPUB
  • Check Gamebook
  • Number Map Files
  • Gamebook Format
  • Dependencies
    • Required
    • Optional
    • Development
  • License

gamebookformat

A tool to format gamebooks into various formats useful for playing the gamebook on paper or a screen (or for debugging it).

Usage

formatgamebook.py [-h] [-M] [-t D] inputfile [inputfile ...] outputfile

positional arguments:
  inputfile             input gamebook file (eg test.gamebook)
  outputfile            output file (eg test.tex or test.rtf)

optional arguments:
  -h, --help            show this help message and exit
  -i T, --include T     only include sections with tag
  -e T, --exclude T     exclude sections with tag
  -M, --no-default-map  ignore default map file
  -t D, --template D    add custom template dir
  -o D, --option D      add template override options dir
  -S, --no-shuffle      do not shuffle sections
  -m F, --map-file F    number map file

Supported Output Formats

Name	Extension	Description
LaTeX	.tex	Useful to generate PDFs using pdflatex or whatever LaTeX tools you prefer.
Rich Text Format	.rtf	Supported because the Windhammer Prize requires it.
Graphviz DOT	.dot	Use with the Graphviz dot tool to generate a flowchart graph of all sections in the gamebook.
HTML	.html	Play gamebook in browser.
Plain Text	.txt	Raw plain text without formatting.
JSON	.json	JSON-format for debugging

More to be added. Custom output formats or modifications to the default formats can easily be added. Use the -t command-line option to add subdirectories containing new templates or overrides for default templates.

Included Optional Templates

The -o command-line option is like -t but searches the options subdirectory (next to the default templates subdirectory) that contains useful overrides for some behavior of the default output formats. For example adding -o letter to the command-line will produce LaTeX files in Letter size rather than the default A5 size. You can use -o list to generate a text file listing all sections and their numbers, or -o list -i todo to only list sections tagged as todo (or substitute whatever other tag(s) you are interested in).

Name	Formats	Description
a4	tex	A4 paper size documents (PDF).
a5	tex	A5 paper size documents (PDF).
htmlbook	html	Generate HTMLBook compatible HTML.
letter	tex	Letter paper size documents (PDF).
list	txt	Only generate list of sections.
static	html	Remove script link from HTML output.

Styles and Scripts

Generated html files use the included gamebookformat.css for styling and gamebookformat.js for scripting (except with the htmlbook or static options). You need those files in the same directory (folder) as your generated html file for it to look right. Of course for a more professional look you probably want to tweak that CSS and possibly the script to look better. A problem with using your own modified versions is that you have to manually merge them with future versions of the files provided with gamebookformat. To avoid that it is better to add styles and scripts using custom templates. There are some hooks in the standard templates to make it easy to add overrides without replacing anything (for instance by making a template with a html/head-overrides.html file). (TODO: Add example showing how to do that, because the last few sentences here probably did not make sense to anyone.)

EPUB

There is no built-in support for generating EPUB books, however there are numerous tools out there to import one of the file formats generated by gamebookformat that can convert them to EPUB (and other ebook formats). The most suitable format is probably html with the -o htmlbook or -o htmlbook options. Calibre seems to do a good job converting these to EPUB, so that should be a start. You probably want to do some experimentation to find a way that creates results you like.

Check Gamebook

The included checkgamebook.py script can be used to run tests on a book and warn about things that do not look right. To use it first generate a json output file version of the book, using the same flags (eg include-tags) as when formatting the real book. Then run checkgamebook.py bookname.json. Currently only tests that all sections can be reached, in theory, from the start section. It only looks for existing references, and has no idea for instance if a locked door can never be unlocked because it is impossible to find enough money to pay for a key. Future versions will hopefully catch more problems, but never all of them in complex books.

Run checkgamebook.py -v for verbose mode. Currently that just means that all ending (death?) sections of the book are printed, allowing you to manually check that there are no unexpected dead-ends.

Number Map Files

Whenever formatgamebook.py runs it looks for a file with the same name as the output file, but with a .map suffix (eg output.map if the output file is output.html). That file is expected to contain a JSON object mapping section names to numbers, and all sections included in that file are given those numbers rather than being randomly shuffled like other paragraphs. You can also add more map files using the –map-file (or -m) option on the command-line. The -M flag disables the default map file. Unless it has been disabled a default map file is also written, containing all the sections output. This way if you generate the same output file (or files with the same name but different types) they always get the same section numbers assigned. The generated map file can also be used from other scripts to easily read what numbers were assigned to sections, if you need to use the number of some section for something outside of the gamebook itself.

tl;dr: If you make different output files in different formats the generated .map file will ensure that all files use the same random numbers for the same section.

Gamebook Format

The input file expected by the formatgamebook.py script must be in a format containing information about all sections in the book plus some optional metadata. The format should (when TBD) be documented here.

By design the format is similar enough to Emacs Org-Mode that some edit shortcuts works in that mode without additional configuration (eg C-c C-q to edit section tags). References to sections can be followed using C-c C-o while editing the book in org-mode.

Dependencies

Required

Python 2.7

To run formatgamebook.py.

Optional

To make something useful from some of the outputted files.

pdflatex

Or other tool to make PDF documents from tex files.

Graphviz

Includes the dot command that can make images from dot files.

Development

The following are only needed for working on improving the scripts (and even then you can proabbly do without all or most).

GNU make

Runs tests and various other useful development tasks. (This in turn depends on some tools like diff, but if you have make installed you probably have them as well.)

node.js

To run some tests of HTML (JavaScript) templates.

nodeunit

Unit test framework for node.js.

License

Copyright (c) 2013 Pelle Nilsson All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.