Introducing the Bocfel Z-machine interpreter

Bocfel is a Z-machine interpreter. It was initially released a couple of years ago, and although I’ve never formally announced it here, you’ve probably used it if you’ve played a Z-machine game on a recent release of Gargoyle. It targets Glk (with special support for Gargoyle), and if you’re interested in the source code, it is available at I just released version 0.6.2.

By default Bocfel is meant to be as unobtrusive as possible, ideally not even noticed by a player. Indeed, most people will not know, or need to know that Bocfel is the interpreter they’re using. However, there are features worth knowing about if you want to have a bit more control over your playing experience. Some features are simple to use, and will not take any extra work. Some take a bit more effort to make use of.

The primary documentation for Bocfel is its man page, available at There are boatloads of flags that can be passed to Bocfel to alter its behavior. Because most users will never invoke it directly, though, a configuration file can be used instead. The location of this file is platform-dependent: on Unix systems, it’s ~/.bocfelrc. On Windows it depends on a few factors; the path will be displayed if the -v flag is passed. This might be accomplished by running the following in a command shell (this is at least the case for Windows XP, the only Windows version I have access to):

“C:\Program Files\Gargoyle\bocfel” -v

Most options are rather useless for most users most of the time (disable_color is probably the must useful, if you find an author has used a garish color scheme).

Like many interpreters, undo support is provided, even for version 1-4 games. In addition, multiple undo is supported. Moreover, Bocfel provides undo support for the few version 5 games (e.g. Hitchhiker’s Guide) which do not natively support it. Bocfel has a special /undo command which can be used if the game doesn’t understand UNDO, or if the game’s UNDO command prevents multiple undo from working. Please note that the undo support for V5 games without undo is not available in the latest Gargoyle release, but will be in the next version.

/undo is one of many so-called “meta commands” supported by Bocfel. Following is a list of the commands. Please note that not all of these commands are supported in the latest Gargoyle; I have made a note of which are not (but will be available in the next Gargoyle release):

[]/undo - Undo a turn.[/]
[]/scripton - Start a transcript.[/]
[]/scriptoff - Stop a transcript.[/]
[]/recon - Start a command record.[/]
[]/recoff - Stop a command record.[/]
[]/replay - Replay a command record.[/]
[]/save - Save the game. This is meant to be used only when a game itself is preventing save from working. Otherwise, the game’s save command should be used, because /save does not create Quetzal-compatible save files.[/]
[]/restore - Restore a game saved by /save.[/]

The following are not available in the latest Gargoyle:

[]/ps - Create a save state and push it onto a save state stack. This is meant to be used right before you try something risky; it is a way to save your game without wasting time creating unnecessary saves on the disk. An optional description can be passed to /ps, and if given, will be displayed when saves are listed with /ls. If no description is given, the current time is used as the description. Up to 25 save states can be stored at a time; once this limit is reached, old states are discarded as new ones are created.[/]
[]/pop - Pop off and restore the last-saved state as created by /ps. An optional numeric argument can be given, corresponding to a save index as shown by /ls. This will unwind the save stack back to the given save state.[/]
[]/ls - List all save states in chronological order, most recent last. The most recent state is marked with an asterisk, and is the state that will be restored if /pop is called with no arguments.[/]
[]/disable - Disable meta commands for the rest of this session.[/]
[]/say [command] - Pretend like [command] was typed; this is meant to be used if a game itself can expect input to start with a / character.[/]
[]/help - List all meta commands.[/]

Bocfel also has rudimentary “cheating” support, which is achieved by forcing certain areas of memory to always contain the same value. This is meant mainly to suppress hunger and thirst puzzles. Cheating can only be enabled through the config file. See the man page for more details on the cheat syntax, and see for a list of some cheats I’ve put together.

That’s about it. If any of the options in the man page look intriguing but you’re not sure how to get them working, I’ll be happy to help.

I’ve been meaning to say that I am looking forward to playing around with the new features a lot. I hope the next Gargoyle release isn’t too far off.

I’ve compiled Bocfel on several system, it’s easy to setup and works very well! :wink: