gamebook.js - an IF-style gamebook engine

What is it

It's an experimental crossbreed between interactive fiction (IF) and gamebooks: instead of navigating an explicit set of choices, you are free to type any command after each section. The engine then tries to match what you typed with the best available choice, using a parser. The parser is quite simple (as it wouldn't really make sense for it to be otherwise) but nevertheless uses some techniques like stemming and synonym matching, to improve flexibility (and fun!) a bit. To read more about the idea:

http://cjauvin.blogspot.ca/2013/03/suspension-of-parser-disbelief.html

It currently implements the full version of Fire on the Water, the second book in the Lone Wolf series, whose content is freely available (for doing such mashups) through Project Aon.

#Try playing it first!

How it works

Gamebook Content

The gamebook data is entirely contained in a JSON file with a simple structure (and is the only part that can't be versioned since it is copyrighted material, which has to be hosted on Project Aon's web server). This means that the engine operates client-side only, with no need for any server interaction. The main object contains a sections object with a key corresponding to each section:

{
    "sections": {
        "1": {
            "text": "Captain D’Val and his guards...",
            "options": [{
                "section": "273",
                "text": "If you wish to draw your weapon and attack your unknown assailant,\nturn to 273.",
                "words": ["weapon", "attack", "assailant", "combat"]
            }, {
                "section": "160",
                "text": "If you wish to try to pull free of his grasp, turn to 160.",
                "words": ["pull", "free", "grasp", "struggle", "assailant"]
            }]
        },
    ...
    }
}

The extraction of content from the original Project Aon XML file is semi-automated using a Python script, which weaves it with another customized, handcrafted "override" file, to yield a single final JSON file.

Parser

The engine will tokenize the player's input and try to match it against each option's list of words, with a certain tolerance (using word stemming and synonym matching). The option with the greatest number of matches is considered the chosen one (a confirmation is asked though).

Of course this mechanism is so simple that it could hardly be defined as a command parser, but in the context of a gamebook, where there are only a few options per section anyway, it makes sense. To increase the illusion that it's a "real" (or deeper) parser, it has a few more features:

• the engine uses a dictionary of synonyms (defined in the data file) to expand the game vocabulary

• an ambiguous command (resulting in two options having the same number of matches, for instance) will often gently push the player into making more complex entries; e.g. "assailant" alone would be ambiguous in the example above, whereas "attack assailant" wouldn't be

• there is a syntax for compound commands, for which each word must be matched, for example:

"words": [["don't", "want"], "attack"]

would match "don't want" (or even "don't really want"), but not "want" alone.

Pluggable Book-Specific Interface

The engine is contained in a single module that should (more or less) implement the general logic of any Lone Wolf gamebook (expanding it to be more general and implement any gamebook would require much more work). The book-specific logic (not to be confused with its content) is kept separate in a module with a straightforward pluggable interface:

var fotw_special_sections = {
    '144': function(engine, sect) {
        engine.action_chart.gold = 0;
        engine.echo('You have lost all your Gold.', 'blue');
        engine.doSection();
    }, [...]
}

which in this example implements a special behavior for section 144 of FotW, which is triggered by simply setting the is_special flag set to true for that section in the JSON content file (there are also similar mechanisms for special choices and combats).

Installation and dependencies

The engine is pretty straigthforward to install and serve (via your preferred web server), but you have to pay special attention to these aspects:

jQuery Terminal

The console is implemented using jQuery Terminal, which I modified to add word autocompletion and some other minor things, so make sure you are using the word-completion branch of my forked repo.

Gamebook Content Access

Since the JSON gamebook content contains copyrighted material, it must be hosted on Project Aon's web server (I obtained permission to host the entire codebase for the FotW demo). As the gamebook.js codebase is not limited by that restriction, it can access the content remotely, via JSONP. In the case of FotW, for instance, it would mean using that value for the gamebook_url engine variable:

gamebook_url: '//projectaon.org/staff/christian/gamebook.js/fotw.php?callback=?'

Porter Stemmer

A JS version of the Porter stemmer is also used (without modification).