Adventure Book

version 1/110101 by Edward Griffiths

  • Home page
  • Beginning
  • Previous
  • Next

  • Section: Debugging

    As your story grows in size and complexity, it can get difficult to keep track of everything. The Adventure Book extension provides a number of debugging commands that are only available when you're testing your game in Inform 7. There are reports about the game state as well as cheats that allow you to skip to any page, modify any flag, and acquire any inventory item.

    On the most basic level, the game attempts to detect when a page has been left unwritten as you are playing it. How does the system decide if a page is unwritten? Well, whenever you refer to a new page -- when declaring a choice or a use or using "It is followed by..." to describe a page -- Inform 7 creates a blank page with that name. Unless a formal definition is provided for that page, the page will have no description, no choices, and no way to continue; if the game leads the player to that page, it will end abruptly and mysteriously. Since it's perfectly valid to create a page that doesn't have a text description (see the example "Conversation Trees" for a useful application), the system defines an unwritten page to be a page that has no way to continue -- no choices, no "It is followed by..." statement, no "It is a dead end." statement.

    As you're playing the game, any choice that would lead to an unwritten page is preceded by three asterisks (***). Here is an example of an unfinished story to show you how it works:

        "Unfinished" by Edward Griffiths
        Include Adventure Book by Edward Griffiths
        The sword is an inventory item. Xyzzy is a magic word.
        The First Page is a page.
        "An excellent start to your adventure! What are you going to do first?"
        A choice called tfpa is for The First Page. "Set off for adventure!" It triggers The Next Page.
        A choice called tfpb is for The First Page. "Set BOLDLY off for adventure!" It triggers The Third Page.
        A use called tfpc is for The First Page. It uses the sword. It triggers The Swordplay Page.
        A use called tfpd is for The First Page. It uses xyzzy. It triggers The Xyzzy Page.
        The Third Page is a page.
        "You take an appropriately BOLD stance as you set off for adventure!"
        It is followed by The Next Page.
        The Fourth Page is a page.
        "You find yourself high up in the mountains! What next?"

    Since we never defined The Next Page in this story, the choice "Set off for adventure!" is listed as:

        *** 1) Set off for adventure!

    This is a visual cue to the author, as he's testing, that that part of the game isn't working yet. It's a useful hint, but it has a limitation -- it doesn't check to the end of a chain of "It is followed by..." statements to make sure that it ultimately leads to a written page. And so the second choice isn't marked in any way, and if the player selects that choice, he is taken to The Third Page, which is followed by The Next Page, where the game comes to an abrupt halt. Moreover, there are no indications at all for the use commands, since they're never printed in the page descriptions.

    The "report" command is provided to help the author catch all of the missed connections in his story. At any time, you can type "report" instead of a normal game command to bring up a list of all unwritten pages and a summary of the paths that lead to that page as well as a list of pages that don't have any connection to them whatsoever. Print a report for the story above, and you'll see all sorts of problems with it:

        Searching for pages that don't have any option to continue...
        The Next Page has no options to continue.
        * The choice "Set off for adventure!" for The First Page triggers The Next Page.
        * The Third Page is followed by The Next Page.
        The Swordplay Page has no options to continue.
        * A use for the sword for The First Page triggers The Swordplay Page.
        The Xyzzy Page has no options to continue.
        * A use for Xyzzy for The First Page triggers The Xyzzy Page.
        Fourth Page has no options to continue.
        Searching for pages that can't be reached:
        Fourth Page

    It's a good idea to print a report for any game before you release it; short of exhaustively attempting every single choice of your game, it can be easy to miss one little connection along the way.

    Suppose, however, that you have intentionally written a page without any means to continue. For example, you're writing a page to replace The Last Page. In that case, it can be annoying or misleading to see choices that lead to those pages marked with asterisks or to see them show up in reports. If this is the case, you can indicate that a page is "a special page" when you declare it:

        The Really Last Page is a special page.
        "GAME OVER."

    Now The Really Last Page will never show up in any reports, and any choices that lead to this page will be unmarked. It's important that you only use this option if you really mean it. The whole point of the report command is to remind you of parts of the story that you still need to continue; declaring a page to be "special" to keep it from being included in reports as you work on other parts of the story defeats the purpose.

    As you're testing a large game, it can be a chore to have to exhaustively test every option, especially the parts of your game that depend on the states of flags and inventory items, and especially when you have to start from the beginning every time. To facilitate testing, a number of commands are provided to help you jump around to different parts of the story.

    First, there's the "skip to" command. Type "skip to [the name of a page]", and the game will behave exactly as if you'd selected a choice that led to that page; flags and inventory items will be given or removed, the chain of "It is followed by..." commands will be followed, and, if the final page is a dead end, it will return to the page you were just reading.

    To make navigation between pages a little easier, you can type "page names on" to display the name of each page as it's read. (And, of course, typing "page names off" turns them off again.) As a last resort, you can type "list pages" to get the complete list of all pages in the story, but this can get very, very long.

    Finally, there are commands for manipulating the flags. At any time, you can type "list flags" to get a list of all flags in the game, and whether they're on or off. (Similarly, you can get lists of all inventory items or magic words by typing "list items" or "list magic words", respectively.) You can set any flag or obtain any inventory item by typing "give [name of flag or item]", and you can turn any flag off or dispose of any inventory item by typing "remove [name of flag or item]". If you're in a hurry, "give all" will set all flags and give you all of the inventory items, and "remove all" will clear all flags and trash all items.