Ubuntu Manpage: frotz - interpreter for Infocom and other Z-Machine games

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.

       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.  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.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.

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. 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.

-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.

-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 Commodore 128
8 Commodore 64
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

Color names may be any of the following:

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.

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

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