FROTZ(6)

📦
version 2.55 · 3 versions
, in alpine 3.24, arch rolling, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 okay so, welcome to FROTZ(6) 🦋

Games Manual energy, bestie. This is frotz, section 6, and she is literally the moment. Sit down, grab a strawberry, we're doing this. 🍓

✨ NAME ✨

frotz — interpreter for Infocom and other Z-Machine games

💅 SYNOPSIS 💅

frotz [options] file [blorb_file]

okay so first thing's first: you gotta give her at least one file on the command line. No file, no game, no vibes. 🫶

That file can be either a plain Z-code file or a Blorb file. So what even are those? A Z-code file is a compiled executable for the Z-Machine — that's the actual game, bestie. A Blorb file is like a little gift bag 🎀 that has audio, graphics, and other things in addition to the game, all wrapped up into a single file. And it can optionally contain the Z-Machine executable too.

Here's the cute part: if you hand her a plain Z-code file, Frotz will go looking for a Blorb file with the same base name but an extension of .blb, .blorb, or .zblorb, and load it if she finds one. She's proactive like that. 👑

But flip it around — if the file you supplied on the command line is a Blorb file, then Frotz will check to see if a Z-code file is contained within. And if it's not found? She will complain and exit. Not mad, just disappointed. 💀

You can also supply an alternatively-named Blorb file as the optional second parameter to the command line invocation. Fancy. ✨

And listen — if you want to play any of the games from Infocom that use sound or graphics, you will need to get a corresponding Blorb file from the Interactive Fiction Archive. See FURTHER INFORMATION below.

🌸 DESCRIPTION 🌸

Frotz is a Z-Machine interpreter. The Z-machine is a virtual machine designed by Infocom to run all of their text adventures. She went through multiple revisions during the lifetime of the company, and two further revisions (V7 and V8) were created by Graham Nelson after the company's demise. The specification is now quite well documented; this version of Frotz supports version 1.1. See Z-MACHINE STANDARDS below.

This version of Frotz fully supports all these versions of the Z-Machine except for version 6. Version 6 is semi-supported by displaying the outlines of V6 graphics with the picture number in the bottom-right corner. So like… she shows up, she's in the group chat, but she's not fully participating. 🙈

💖 OPTIONS 💖

  • -a — Watch attribute setting. Setting and clearing of attributes on objects will be noted in debugging messages. Little spy behaviour, but make it helpful. 👀
  • -A — Watch attribute testing. Every time the Z-machine tests an attribute value, the test and the result will be reported. She's telling you everything.
  • -b <colorname> — Sets the default background color. <colorname> corresponds to one of the Z-machine colors, which are as follows:
black red green yellow blue magenta cyan white

If color support is disabled or not available on your terminal, this option does nothing. Zero. Nada. 💀

  • -c N — Sets the number of context lines used. By default, after a ''[MORE]'' prompt, and assuming there is enough output pending, Frotz will allow all the currently visible lines to scroll off the screen before prompting again. This switch specifies how many lines of text Frotz will hold over and display at the top of the next screen. Considerate queen. 👑
  • -d — Disable color. Boom. Gone. Monochrome era. 🖤
  • -e — Enable sound. If you've disabled sound in a config file and want to hear sound effects, use this.
  • -E <mode> — Emphasis mode. <mode> corresponds to one of three possible ways to render emphasized text. Possible choices are as follows:
italic underline none

Infocom created an EMPHASIS_STYLE for the Z-machine, which was supposed to make the text be underlined or be italicized. Exactly what to do is left up to the interpreter. Some platforms/terminals could support either, both of these, or neither. Underlining was more common than italic. This option allows you to choose how EMPHASIS_STYLE is displayed. Pick your fighter. ✨

  • -f <colorname> — Sets the default foreground color. <colorname> corresponds to one of the Z-machine colors, which are as follows:
black red green yellow blue magenta cyan white

If color support is disabled or is not available on your terminal, this option does nothing.

  • -F — Force color mode. If you've disabled color in a config file and want Frotz to display colors, use this. She's gonna be colorful whether you like it or not. 🌈
  • -h N — Manually sets the text height. Though most curses libraries are intelligent enough to determine the current width from the terminal, it may sometimes be necessary to use this option to override the default.
  • -i — Ignore fatal errors. Okay so real talk, bestie: if a Z-Machine interpreter encounters a zcode error such as division-by-zero or addressing an illegal object, the proper response is to abort execution. This is done because the zcode program doesn't have a clear idea of what is going on. There are some games out there that cause fatal errors because the authors were careless and used an interpreter that didn't properly check for errors. This option is intended to get around such bugs, but be warned that Strange Things may happen if fatal errors are not caught. 😭
fr fr, this is the "ignore the smoke alarm" option. Use it knowing the house might be on fire.
  • -I N — Set the interpreter number. Infocom designed the Z-machine such that a game could tell on what kind of machine the interpreter was running. See INTERPRETER NUMBER below.
  • -l N — Sets the left margin, for those who might have specific formatting needs. Aesthetic. 🎀
  • -L <filename> — When the game starts, load this saved game file. Right back where you left off, no cap.
  • -m — Enable mouse support. Naturally, this is quite limited, but it's available for anyone who wants to experiment with it. When active, the mouse cannot be used to copy text from the terminal. So it's giving… a trade-off. 🙈
  • -o — Watch object movement. This option enables debugging messages from the interpreter which describe the moving of objects in the object tree.
  • -O — Watch object location. These debugging messages detail the locations of objects in the object tree.
  • -p — Plain ASCII output only. This inhibits the output of accented letters and other characters from the Latin-1 character set, replacing them with reasonable alternatives. This may be necessary on devices lacking these characters. The OE/oe dipthongs are missing from the Latin-1 set. These are handled as well.
  • -P — Alter the @piracy opcode. The @piracy opcode was never used by Infocom. This switch is really only useful for those who like to toy around with Z-code. Chaos agents, this one's for you. 💅
  • -q — Quiet. Turns off sound effects. Useful when running Frotz on a remote machine and you don't want to bother whoever's near the console with weird noises. Respectful. 🫶
  • -r N — Sets the right margin.
  • -R <path> — Restricted read/write. Reading and writing files will be restricted only to the provided path. Ordinarily Frotz will write or read its saves, transcripts, and move recordings in whatever path or directory the user provides when the SAVE, SCRIPT, or RECORDING commands are given. This can be undesirable if Frotz is run in a restricted environment, by a front end, or by a chatbot. This option will cause Frotz to write or read only to the provided path and nowhere else. Then the controlling process can then watch that directory for changes and need not worry about someone scribbling or snooping who-knows-where. Contained. Boundaries. We love to see it. 👑
  • -s N — Set the random number seed value. The given seed value is used as the initial seed value on every restart. By default, the random number generator is initialized based on the system clock; this allows you to make the random number generator predictable, for use in recorded scripts or debugging. For instance, Curses makes random decisions before the first input (such that the hot key Alt-S does not really help).
  • -t — Sets the Z-machine's Tandy bit, which may affect the behavior of certain Infocom games. For example, Zork I pretends not to have sequels, and Witness has its language toned down. She's on her best behaviour. 😇
  • -u N — Sets the number of slots available for Frotz's multiple undo hotkey (see below). This defaults to 25, which should be sufficient for most purposes. Setting too high a number here may be dangerous on machines with limited memory. Don't be greedy, bestie. ⚠️
  • -w N — Manually sets the text width.
  • -x — Expand the abbreviations "g", "x", and "z" to "again", "examine", and "wait". This switch is for use with old Infocom games that lack these common abbreviations which were introduced in later games. Use it with caution: A few games might use "g", "x" or "z" for different purposes. 👀
  • -v — Show version information and exit. This will display the version of Frotz, some information about what's enabled and what's not, the commit date of the source code, and a git(1) hash of that commit. Receipts! 🧾
  • -Z N — Error checking mode.
0 = don't report errors.
1 = report first instance of an error.
2 = report all errors.
3 = exit after any error.

Default is 1 (report first instance of an error).

⌨️ HOT KEYS ⌨️

These hot keys are enabled only when the Z-machine is waiting for line input (for Z-machine experts: the @read opcode). So like, they only work when she's listening. 🎧

  • Alt-D — Set debugging options.
  • Alt-H — Help (print the list of hot keys).
  • Alt-N — New game (restart).
  • Alt-P — Playback on.
  • Alt-R — Recording on/off.
  • Alt-S — Set random number seed.
  • Alt-U — Undo one turn.
  • Alt-X — Exit game (after confirmation).

👑 INTERPRETER NUMBER 👑

The interpreter number is a setting in the Z-machine header which is used to tell the game on what sort of machine the interpreter is running. Frotz will automatically choose the most appropriate number for a given Infocom-produced game. Should you want to override the number, the -I option is available.

An interpreter should choose the interpreter number most suitable for the machine it will run on. In Versions up to 5, the main consideration is that the behaviour of 'Beyond Zork' depends on the interpreter number (in terms of its usage of the character graphics font). In Version 6, the decision is more serious, as existing Infocom story files depend on interpreter number in many ways: moreover, some story files expect to be run only on the interpreters for a particular machine. There are, for instance, specifically Amiga versions. The DECSystem-20 was Infocom's own in-house mainframe. Iconic.

For Infocom's four V6 games, the interpreter number will be automatically chosen based on the title and release number. Of course, this can be overridden at the command line.

Infocom used the following interpreter numbers:

 1  DECSystem 20
 2  Apple IIe
 3  Macintosh
 4  Amiga
 5  Atari ST
 6  IBM PC
 7  Commodore 128
 8  Commodore 64
 9  Apple IIc
10  Apple IIgs
11  Tandy Color

💖 CONFIGURATION FILES 💖

okay so bestie, when Frotz boots up it's nosy in the best way — it peeks at the system's frotz.conf first, and then it goes looking at $HOME/.frotzrc for all its config tea. ✨

The config file is giving super simple syntax, like:

<variable> <whitespace> <value>

Color names can be any of these, periodt:

black | red | green | blue | magenta | cyan | white
  • ascii on | off — plain ASCII only, no fancy glyphs. Default is "off".
  • background <colorname> — sets the background color. Default is whatever your terminal's default background is (living its own life, honestly).
  • color yes | no — use color text. Default is "yes" if it's supported.
  • errormode never | once | always | fatal — sets how errors get reported. Here's the breakdown, bestie:
    • never — don't report any errors except the fatal ones. 💀
    • once — report only the first instance of an error.
    • always — report every single instance, no skipping.
    • fatal — abort on any error, even the non-fatal ones. dramatic much?
    • Default is "once".
  • expand_abb on | off — expands abbreviations. Default is off. It takes the abbreviations "g", "x", and "z" and blows them up into "again", "examine", and "wait". This switch is for playing old Infocom games that don't have these common abbreviations (they got introduced in later games). Use it with caution. A few games might use "g", "x", or "z" for totally different purposes, and then it's chaos.
  • foreground <colorname> — sets the foreground color. Default is your terminal's default foreground color.
  • ignore_fatal on | off — ignore fatal errors. 😭 So here's the thing: if a Z-Machine interpreter hits a zcode error like division-by-zero or addressing an illegal object, the proper response is to abort execution, because the zcode program genuinely does not have a clear idea of what's going on. But some games out there cause fatal errors just because the authors were careless and used an interpreter that didn't properly check for errors. This option is meant to get around those bugs, but be warned that Strange Things may happen if fatal errors are not caught. Default is "off".
  • piracy on | off — alters the piracy opcode. Default is off. The piracy opcode was never used by Infocom, so this option is only useful for those who like to toy around with Z-code. 🏴☠️
  • randseed <integer> — sets the random number seed. Default comes from the Unix epoch.
  • sound on | off — turns sound effects on or off. Default is "on". 🔊
  • tandy on | off — sets the machine's Tandy bit. This can affect the behavior of certain Infocom games. For example, Zork I pretends not to have sequels, and Witness has its language toned down. Default is "off".
  • undo_slots <integer> — sets the number of undo slots. Default is 500.
  • zcode_path /path/to/zcode/files:/another/path — sets the path to search for zcode game files. It's just like the $PATH environmental variable, except you can't put environmental variables in the path or use other shortcuts. For example, "$HOME/games/zcode" is illegal because the shell can't interpret that $HOME variable. 🚫

The following options are really only useful for weird terminals, weird curses libraries, or if you just want to force a certain look (like playing in 40-column mode, iconic behavior honestly).

  • context_lines <integer> — sets the number of context lines used. By default, after a [MORE] prompt, and assuming there's enough output pending, Frotz will let all the currently visible lines scroll off the screen before prompting again. This switch says exactly how many lines of text Frotz will hold over and display at the top of the next screen. Default is "0".
  • left_margin <integer> — sets the left margin. This one's for those who might have special formatting needs. 💅
  • right_margin <integer> — sets the right margin. Again, for the special formatting needs girlies.
  • text_height <integer> — manually sets text height. Most curses libraries are smart enough to figure out the current width of the terminal on their own, but you may need this option to override the default.
  • text_width <integer> — manually sets text width. Again, this shouldn't be necessary except in special circumstances.
  • script_width <integer> — sets the transcript width. Default is 80 columns per line, no matter what the current text width is. This switch lets you change that setting. You can set it to "0" to deactivate automatic line-splitting in transcript files.

The following options are mainly useful for debugging or cheating. 👀 (no judgement, bestie)

  • attrib_set on | off — watch attribute setting. Setting and clearing of attributes on objects will be noted in debugging messages. Default is "off".
  • attrib_test on | off — watch attribute testing. Every single time the Z-machine tests an attribute value, the test and the result get reported. Default is "off".
  • obj_loc on | off — watch object location. These debugging messages detail the locations of objects in the object tree. Default is "off".
  • obj_move on | off — watch object movement. This enables debugging messages from the interpreter which describe the movement of objects in the object tree. Default is "off".

🌈 COLOR 🌈

Whether Frotz shows color or not depends on the curses library and the terminal, so it's giving ✨collaboration✨. In general, an xterm or other X11-based terminal emulator will support color. Sometimes the value of $TERM will need to be set to something like "xterm-color" or "rxvt-256color". For a Linux console, $TERM is almost always set to "linux", and that will support color. For a NetBSD or OpenBSD console on an x86 or amd64, the default value of $TERM is "vt100" — to get color supported there, you need to set $TERM to "pc3". A FreeBSD console's $TERM is "xterm" and will support color. Color on text consoles on machines other than x86 or amd64 is untested. 🫣

On some operating systems, Xterm will not change the cursor color to match that of the text. To fix this, add the following line to your .Xresources file and type xrdb -merge $HOME/.Xresources:

xterm*cursorColor:      *XtDefaultForeground

This can also be added to a systemwide file such as /etc/X11/Xresources/x11-common or /etc/X11/app-defaults/XTerm. The names and locations of the system-wide files can vary from OS to OS, so don't come for me if yours is different.

🦋 UNICODE 🦋

Frotz supports Unicode glyphs by way of UTF-8 if the terminal you're using supports UTF-8. If you prefer xterm, start it as uxterm — that's a wrapper script that sets up xterm with a UTF-8 locale. You can also manually tell an xterm to switch into UTF-8 mode by holding CTRL and the right mouse button to bring up the VT FONTS menu. Depending on how xterm was installed, you may see an option for "UTF-8 Fonts" which will allow Unicode to be properly displayed. 🎀

Getting normal xterm to behave like this all the time can vary from system to system. Other terminal emulators have their own ways of being set to use UTF-8 character encoding, so iykyk, check your own fave.

🌸 NON ASCII CHARACTERS 🌸

Non-ASCII glyphs can be displayed without the use of UTF-8 by way of the ISO-8859-1 or ISO-8859-15 (Latin-1 or Latin-9) character sets. ISO-8859-15 is more or less identical to ISO-8859-1 except that the OE/oe dipthongs are supported, replacing the seldom-used 1/2 and 1/4 glyphs. See also luit(1), charsets(7), iso_8859-1(7), and iso_8859-15(7) for more information.

🧚 LOCALE 🧚

An important means of ensuring the system knows to use UTF-8 is to make sure the locale is set appropriately. This is valid only when Dumb Frotz runs under Unix-ish systems.

Using the command locale will tell you what is currently in use. Using locale -a will show you what's available. Then set your LANG evironmental variable to something appropriate by using one of these commands:

export LANG=C.UTF-8 export LANG=en_US.utf8

This can be put in your shell configuration file, be it .profile, .bash_profile, .login, .bashrc, or whatever. It can also be set system-wide in the equivalent files in /etc.

👑 Z-MACHINE STANDARDS 👑

Frotz complies with the Z-Machine Standard 1.1 of May 2006, revised February 2014. The authoritative version is found here: http://inform-fiction.org/zmachine/standards/z1point1/index.html

As of 1.1, an additional optional prompt parameter is allowed on Version 5 extended save/restore. This parameter allows a game to read or write an auxiliary (aux) file without prompting the player. See section 15 of the Standard for details. Frotz restricts such files to having an ".aux" filename extension. When the -R (restricted read/write) option is active, reads and writes through this mechanism are restricted to the provided path the same as all other file accesses.

⭐ ENVIRONMENT ⭐

If the ZCODE_PATH environmental variable is defined, Frotz will search that path for game files. If that doesn't exist, INFOCOM_PATH will be searched. Any additional files required, such as auxilary, or blorb files, must be in the same directory as Frotz finds the story file.

For the Alt key to be read correctly in an Xterm, the following lines should be in your .Xresources file:

XTerm*metaSendsEscape: true
XTerm*eightBitInput: false

💜 FURTHER INFORMATION 💜

The Frotz homepage is at https://661.org/proj/if/frotz/.

A git(1) repository of all versions of Unix Frotz back to 2.32 to the bleeding edge is available for public perusal at https://gitlab.com/DavidGriffith/frotz/. 🔥

The Interactive Fiction Archive, at https://www.ifarchive.org/, is a good place to find games to play with Frotz. To play Infocom's games that use graphics or sound, you'll need to get corresponding Blorb files from there. Various ports and builds for Frotz may also be found at the IF Archive.

Most distributions of Linux and BSD include Frotz in their package repositories.

It is distributed under the GNU General Public License version 2 or (at your option) any later version. It may be viewed at https://www.gnu.org/licenses/gpl-2.0.en.html

This software is offered as-is with no warranty or liability. If you find a bug or would like Frotz to do something it doesn't currently do, please visit the above Gitlab website and report your concerns. 🫶

💀 CAVEATS 💀 (read this, bestie, fr fr)

Okay so the Z Machine? Iconic. Legendary. But it has absolutely zero chill about resizing your terminal. It assumes that once the text height and width are set, they will never change — not even across saves. Which, like, made total sense back when 24x80 terminals were the norm and graphical user interfaces were mostly unheard of. Different era, different vibe. 🕰️

The author is fairly sure there's a way around this problem, but for now: don't resize an xterm in which Frotz is running. That's the rule. Also, you should try to make sure the terminal on which you restore a saved game has the same dimensions as the one on which you saved the game. Matching set, bestie. ✨

Audio latency might be unreasonably long depending on the settings of your operating system. Linux generally has things right (as always 💅). The BSDs may need some sysctl(8) settings adjusted. See the sound(4) or audio(4) manpages for more information. 🎧

You can use a path like /usr/local/games/zcode:$HOME/zcode with $ZCODE_PATH or $INFOCOM_PATH because the shell will digest that $HOME variable for you before setting $ZCODE_PATH. Shell doing the heavy lifting, love that for us. 🫶

But — and this is important — while processing frotz.conf and $HOME/.frotzrc, a shell is not used. So you cannot use environmental variables in the zcodepath option within the config files. No shell, no expansion, no exceptions. 😭

This manpage is not intended to tell users HOW to play interactive fiction. That's a whole other journey. Refer to the file HOW_TO_PLAY included in the Unix Frotz documentation, or visit one of these sites:

http://www.microheaven.com/ifguide/
http://www.brasslantern.org/beginners/
http://www.musicwords.net/if/how_to_play.htm
http://ifarchive.org/

🐛 BUGS 🐛

This program has no bugs. no bugs. no bugs. no WHAP thank you. 😤

If you find one (you won't) (but if you do), please report it to the Gitlab site referenced above in FURTHER INFORMATION. Snitches get... well, actually, snitches get bug fixes, so snitch away. 💖

👑 AUTHORS 👑

  • Frotz was written by Stefan Jokisch for MSDOS in 1995-7. OG status. 🌟
  • The Unix port was done by Galen Hazelwood.
  • The Unix port is currently maintained by David Griffith <dave@661.org>.

🌈 CONTRIBUTORS 🌈

In 2019, a Kickstarter campaign was run to raise funds to pay Mark McCurry to overhaul the audio subsystem for the curses port of Frotz. The following people contributed $100 towards that effort:

  • Simon Martin
  • Dan Sanderson
  • Justin de Vesine
  • Daniel Sharpe

Legends, all of them. Absolute patrons of the arts. 🎀

👀 SEE ALSO 👀

sfrotz(6), dfrotz(6), nitfol(6), rezrov(6), jzip(6), xzip(6), inform(1)

and that's the whole page, bestie!! 🦋✨

This was Frotz v2.55, dated 2025-02-01, and yeah — it's FROTZ(6). Go forth, play some interactive fiction, don't resize your terminal, and remember: no bugs. no bugs. no WHAP. 💜🎀🌸

📦 where this page comes from