Provided by: frotz_2.54+dfsg-3_amd64 
NAME
frotz - interpreter for Infocom and other Z-Machine games
SYNOPSIS
frotz [options] file [blorb_file]
At least one file must be specified on the command line. This can be either a plain Z-
code file or a Blorb file. A Z-code file is a compiled executable for the Z-Machine. A
Blorb file contains audio, graphics, and other things in addition to the game wrapped up
into a single file. It can also optionally contain the Z-Machine executable. If a plain
Z-code file is supplied, then Frotz will check for a Blorb file with the same base name
but an extension of .blb, .blorb, or .zblorb and load it if found.
If the file supplied on the command line is a Blorb file, then Frotz will check to see if
a Z-code file is contained within. If not found, then Frotz will complain and exit.
An alternatively-named Blorb file can be supplied as the optional second parameter to the
command line invocation.
DESCRIPTION
Frotz is a Z-Machine interpreter. The Z-machine is a virtual machine designed by Infocom
to run all of their text adventures. It 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.0.
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.
OPTIONS
-a Watch attribute setting. Setting and clearing of attributes on objects will be
noted in debugging messages.
-A Watch attribute testing. Every time the Z-machine tests an attribute value, the
test and the result will be reported.
-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.
-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.
-d Disable color.
-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.
-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 to Frotz to
display colors, use this.
-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. 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.
-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.
-L <filename>
When the game starts, load this saved game file.
-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.
-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.
-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.
-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.
-s N Set the random number seed value. The given seed value is used as the initial seed
value on every restart. This is helpful for testing games like Curses which make
random decisions before the first input (such that the hot key Alt-S does not
really help).
-S N Set the transcript width. By default your transcript files are formatted to a
width of 80 columns per line, regardless of the current text width. This switch
allows you to change this setting. In particular, use -S 0 to deactivate automatic
line splitting in transcript files.
-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.
-u N Sets the number of slots available for Frotz's multiple undo hotkey (see below).
This defaults to twenty, which should be sufficient for most purposes. Setting too
high a number here may be dangerous on machines with limited memory.
-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.
-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).
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.
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 Commodore128
8 Commodore64
9 Apple IIc
10 Apple IIgs
11 Tandy Color
CONFIGURATION FILES
On startup, frotz will first check the system's frotz.conf then $HOME/.frotzrc for
configuration information. The configuration file uses a simple syntax of
<variable> <whitespace> <value>
Color names may be any of the following:
black | red | green | blue | magenta | cyan | white
ascii on | off
Use plain ASCII only. Default is "off".
background <colorname>
Set background color. Default is terminal's default background color.
color yes | no
Use color text. Default is "yes" if supported.
errormode never | once | always | fatal
Set error reporting mode.
never Don't report any errors except for fatal ones.
once Report only the first instance of an error.
always Report every instance of an error.
fatal Abort on any error, even non-fatal ones.
Default is "once".
expand_abb on | off
Expand abbreviations. Default is off. 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 the "g", "x", or "z" for different purposes.
foreground <colorname>
Set foreground color. Default is terminal's default foreground color.
ignore_fatal on | off
Ignore fatal errors. 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.
Default is "off"
piracy on | off
Alter the piracy opcode. Default is off. The piracy opcode was never used by Infocom.
This option is only useful for those who like to toy around with Z-code.
randseed <integer>
Set random number seed. Default comes from the Unix epoch.
sound on | off
Turn sound effects on or off. Default is "on".
tandy on | off
Set the machine's Tandy bit. This may 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>
Set number of undo slots. Default is 500.
zcode_path /path/to/zcode/files:/another/path
Set path to search for zcode game files. This is just like the $PATH environmental
variable except that 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 want to force a certain look (like play in 40-column mode).
context_lines <integer>
Set 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. Default is "0".
left_margin <integer>
Set the left margin. This is for those who might have special formatting needs.
right_margin <integer>
Set the right margin. This is for those who might have special formatting needs.
text_height <integer>
Manually set text height. Most curses libraries are intelligent enough to determine the
current width of the terminal. You may need to use this option to override the default.
text_width <integer>
Manually set text width. Again, this should not be necessary except in special
circumstances.
script_width <integer>
Set the transcript width. Default is 80 columns per line, regardless of the current text
width. This switch allows you to change this setting. You may set this to "0" to
deactivate automatic line-splitting in transcript files.
The following options are mainly useful for debugging or cheating.
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 time the Z-machine tests an attribute value, the test and
the result will be 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 option enables debugging messages from the interpreter which
describe the movement of objects in the object tree. Default is "off".
COLOR
Whether or not Frotz will display color depends upon the curses library and the terminal.
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". This 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.
UNICODE
Frotz supports Unicode glyphs by way of UTF-8 if the terminal used supports UTF-8. If you
prefer using xterm, start it as uxterm. This is a wrapper script that sets up xterm with
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.
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.
SEE ALSO
ash(1) bash(1) csh(1) ksh(1) sh(1) zsh(1)
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.
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 is available for public
perusal here:
https://gitlab.com/DavidGriffith/frotz/.
The bleeding edge of Frotz development may be followed there.
The Interactive Fiction Archive is a good place to find games to play with Frotz. Various
ports and builds for Frotz may also be found here. Here is its URL:
http://www.ifarchive.org/
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.
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
The Z Machine itself has trouble with the concept of resizing a terminal. It assumes that
once the text height and width are set, they will never change; even across saves. This
made sense when 24x80 terminals were the norm and graphical user interfaces were mostly
unknown. I'm fairly sure there's a way around this problem, but for now, don't resize an
xterm in which frotz is running. 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.
Audio latency might be unreasonably long depending on the settings of your operating
system. Linux generally has things right. 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. While processing frotz.conf and $HOME/.frotzrc, a shell is not used.
Therefore you cannot use environmental variables in the "zcodepath" option within the
config files.
This manpage is not intended to tell users HOW to play interactive fiction. Refer to the
file HOW_TO_PLAY included in the Unix Frotz documentation or visit one of the following
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,
please report it to the Gitlab site referenced above in FURTHER INFORMATION.
AUTHORS
Frotz was written by Stefan Jokisch for MSDOS in 1995-7.
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
SEE ALSO
sfrotz(6) dfrotz(6) nitfol(6) rezrov(6) jzip(6) xzip(6) inform(1)