Software

The example games in this manual do not declare IFIDs, which is mandatory when the zblorb output format is used. To compile the examples, you must ask the compiler to emit raw z8 (or z5) code by adding -t z8 (or -t z5) to the command line:

dialogc -t z8 example.dg stdlib.dg

This will produce a file called example.z8.

The examples in Part I do not make use of the standard library at all, so they are compiled like this:

dialogc -t z8 example.dg

When you use the z5 output format, the resulting file is limited to 256 KiB, compared to 512 KiB for z8. However, the z5 format is more compact, and switching to this format can reduce the size of the story file by about 5%.

The Å-machine (pronounced “awe machine”) is a compact, binary story format designed to improve the performance of Dialog stories on vintage hardware beyond what is possible using the Z-machine. It also allows Dialog stories to be published on the web with support for hyperlinks and CSS styles.

To compile for the Å-machine, add -t aa to the command line:

This will produce a file called example.aastory. The .aastory file may in turn be bundled with a javascript interpreter, or with an interpreter for the Commodore 64, using the tool aambundle from the Å-machine release archive.

The following command:

creates a directory called my_game, and populates it with all the necessary html, css, and js files. Simply point a web browser to the play.html file in this directory to run the game.

To create a Commodore 64 disk image, use the following command instead:

The -v flag makes the compiler more verbose. Give it once, and the compiler will print the wordcount for your story, as well as some technical stats. Give it twice -vv and the compiler will dump additional information that can be useful for debugging.

To see the full list of options supported by dialogc, type:

At startup, the debugger analyzes your program, reporting any compilation errors. If everything looks fine, it launches the program. You can then play your game normally.

When the game is asking for input, you may instead choose to type an arbitrary query, multi-query, or now-statement. This can be used to inspect or control the running program.

The debugger remains operational after your program terminates. To start over, type (restart). To quit the debugger, either press Control-D (Linux), close the window (Windows), or type the special command @quit.

The interactive debugger watches your source code files for changes. New code is merged into the running program automatically, so you can test new functionality without restarting the game.

If there are compilation errors in the new version of the source code, the debugger will report them and put the execution on hold until you’ve fixed them.

Any dynamic predicates that have changed during gameplay retain their value, so that e.g. the player character remains in the current room, with any picked-up objects still in their inventory. But unchanged dynamic predicates will reflect the initial value declarations as they’re given in the new version of the source code.

The debugger also tries to match select statements in the old and new versions of the code, in order to make the transition as seamless as possible. But you may occasionally find that a select statement has been reset.

Be aware that by modifying the source code, you can introduce new objects and dictionary words, but you can’t remove them. This affects the operation of the built-in (object $) predicate, as well as (get input $), with particular consequences for games that use the removable word endings feature. To remove extraneous objects and dictionary words, use (restart) (or @replay; see below).

In addition to arbitrary queries and now-statements, the debugger allows you to type debugging commands at the game prompt. These are recognized by a leading @ character.

The debugger maintains a list of all accumulated input that you’ve typed into the running program. Only proper input counts, not queries or debugging commands. The list is cleared on restart, and trimmed on undo, so in that sense it represents a straight path from the beginning of the game to the current game state. The following debugging commands make use of it:

You can get a full list of debugging commands by typing @help at the prompt. These commands can be abbreviated as long as the abbreviation is unique; @h works for @help, for instance.

The terminal version of the debugger (i.e. not the Windows Glk version) allows you to suspend a running computation by pressing Control-C at any time. This will immediately take you to a prompt where you can type queries and debugging commands.

To resume execution, type a blank line at this prompt.

Suspending is useful when you’ve enabled tracing and found that you got a bit more than you bargained for. At the [More] prompt, simply hit Control-C, type (trace off), and press return a second time.

It can also be used to escape from an accidental infinite loop, using (stop). This is rarely needed, however, because the debugger does not perform tail-call optimization, and there’s a limit on the number of recursive calls.

Use queries to inspect the state of the running program, e.g. type *($ has parent #box) into the game to get a list of every object that’s currently a direct child of the #box object.

Insert (log) …​ statements to print variables and other information while debugging.

The standard library provides (actions on) and (actions off), for controlling action tracing. When enabled, this feature makes the library print the names of actions as it tries them.

The library also provides (scope), for listing every object that’s currently in scope.

The following predicates are highly useful for manipulating the state of the running game:

Query tracing can be enabled interactively with (trace on), and disabled with (trace off). Tracing a complete player command will produce a lot of output as the command is parsed. Sometimes it makes more sense to temporarily add (trace on) and (trace off) to the source code, surrounding the particular bit that you’re interested in. Remember, the debugger lets you do this while the program is running.

Use the built-in predicate (breakpoint) to suspend the program from within the source code, in order to inspect the game state at arbitrary points during execution.

The command AGAIN (or G) lets the player repeat the last line of input. During development, you will often want to change something in the most recent response, and then retry the action to see what the new version looks like. AGAIN usually works for this, but there’s a snag: If you’ve added new dictionary words, e.g. by changing a (dict $) rule, then a regular AGAIN will fail to pick up the new words. Use the up-arrow to fetch the command from the input history instead. Another option is to use the debugging command @again (or @g), which will handle this corner-case transparently. That command also performs an implicit undo, which is particularly useful for debugging games with timed puzzles.

Finally, a word of warning: The interactive debugger does not try to emulate the Z-machine backend, nor the Å-machine backend. The Z-machine truncates dictionary words, but the debugger doesn’t. The debugger allocates larger heap areas, but doesn’t optimize tail calls. Always test the compiled version of your game thoroughly, preferably both in a Z-code interpreter and an Å-code interpreter, before releasing it.