SFROTZ(6)

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

💖 sfrotz 💖

okay bestie, sit down, we're doing this. This is sfrotz — it lives in the Games Manual, section 6, and it's the SDL-flavored version of everybody's favorite thing. You're gonna love her. 🎀

✨ NAME ✨

sfrotz — an interpreter for Infocom and other Z-Machine games (the SDL interface one, specifically 💅).

🌸 SYNOPSIS 🌸

sfrotz [options] file [blorb_file]

So, like, at least one file has to be on the command line, no cap. That file can be either a plain Z-code file or a Blorb file.

  • A Z-code file is a compiled executable for the Z-Machine, basically the game itself.
  • A Blorb file is the fancy little bundle: it's got audio, graphics, and other stuff wrapped up with the game into one single file. It can also optionally contain the Z-Machine executable inside it. Very main character of it.

If you hand it 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 it'll load it if it finds one. 🦋

If what you gave it on the command line is a Blorb file, then Frotz checks whether a Z-code file is contained inside. If there isn't one? It complains and exits. Sorry bestie. 😭

You can also hand over an alternatively-named Blorb file as the optional second parameter to the command line invocation. Options, we love to see it.

And if you wanna play any of those Infocom games that use sound or graphics, you're gonna need 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 that Infocom designed to run, like, all of their text adventures. It went through multiple revisions during the company's lifetime, and then two further revisions (V7 and V8) were created by Graham Nelson after the company's demise. The spec is now quite well documented; this version of Frotz supports version 1.1. See Z-MACHINE STANDARDS below. (there's a stray .P sitting in there in the original, we don't talk about it 💀)

This version of Frotz fully supports all these versions of the Z-Machine, including the graphical version 6. Graphics and sound are created through the use of the SDL libraries. AIFF sound effects and music in MOD and OGG formats are supported when packaged in Blorb container files, or optionally from individual files. Ate. 🔥

🎀 STANDARD OPTIONS 🎀

  • -a — Watch attribute setting. Setting and clearing of attributes on objects gets noted in debugging messages.
  • -A — Watch attribute testing. Every single time the Z-machine tests an attribute value, both the test and the result get reported.
  • -b <colorname> — Sets the default background color. <colorname> is one of the Z-machine colors, which are: black red green yellow blue magenta cyan white If color support is disabled or not available on your terminal, this option does literally nothing. 🙈
  • -c N — 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 how many lines of text Frotz will hold over and display at the top of the next screen.
  • -C <filename> — Load this configuration file instead of $HOME/.sfrotzrc.
  • -d — Disable color. bye color 💅
  • -f <colorname> — Sets the default foreground color. <colorname> is one of the Z-machine colors, which are: black red green yellow blue magenta cyan white If color support is disabled or is not available on your terminal, this option does nothing.
  • -h N — Manually sets the text height.
  • -i — Ignore fatal errors. When 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 doesn't have a clear idea of what's going on. But 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 meant to get around those bugs. > but be warned: Strange Things may happen if fatal errors are not caught. 👀
  • -I N — Set the interpreter number. Infocom designed the Z-machine so a game could tell what kind of machine the interpreter was running on. See INTERPRETER NUMBER below.
  • -l N — Sets the left margin, for those with specific formatting needs. we respect the vision ✨
  • -L <filename> — When the game starts, load this saved game file.
  • -o — Watch object movement. Turns on debugging messages from the interpreter describing 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 — 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.
  • -r N — Sets the right margin.
  • -s N — Set the random number seed value. The seed you give gets used as the initial seed value on every restart. By default the random number generator is initialized based on the system clock; this lets you make the RNG 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).
  • -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 lets you change that 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. iconic behavior honestly 🌈
  • -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. 😬
  • -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).

🦋 EXTENDED OPTIONS 🦋

  • -@ <listfile> — Use resource files listed in <listfile> (see NON BLORB RESOURCES).
  • -% — Use local resource files.
  • -F — Run in fullscreen mode (see NOTES).
  • -m <msecs> — Set the timer interrupt cycle to <msecs> milliseconds, instead of the default 100 (1/10 sec).
  • -N <mode> — Set the mode (date or name) for creating default file names for save/script etc. For date, a timestamp is prepended to the filename extension. For name, a four-digit number beginning with 0000 is prepended to the filename extension.
  • -T — Use traditional in-game requests for file names, instead of on-screen dialogs.
  • -v — Show version information and exit. This displays the version of Frotz, some info about what's enabled and what's not, the commit date of the source code, and a git(1) hash of that commit. nerd stuff, love it 💜
  • -V — Force the use of default monospaced VGA font.

💅 HOT KEYS 💅

Sfrotz supports the same hot keys as standard Frotz, plus the Ctl-Alt-X combination for immediate exit, which may be used in case of emergency. 🚨

Note that these hot keys are enabled only when the Z-machine is waiting for line input (for Z-machine experts: the @read opcode), with the exception of Ctl-Alt-X, which also works in single character input mode (the @read_char 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).
  • Ctl-Alt-X — Exit game immediately (no confirmation). the emergency eject button fr fr 💀

🫶 WINDOW 🫶

Sfrotz has a hardwired default screen size of 640x400. The screen size can be changed by the values in this section, by the values found in the Reso chunk of a Blorb file, and finally by the -w and -h command line options — in that order. 👑

Note however that Sfrotz shall refuse to set a screen width less than 640 and/or a height less than 400. no exceptions bestie.

NOTE: for normal (windowed) usage, the screen size should obviously be less than the physical screen resolution (taking into account also window decorations, taskbars etc.). For fullscreen usage, the size should preferably be one of those supported by the PC video driver; otherwise, SDL shall try to use the next higher available resolution, with black borders around the Z-machine screen. In fullscreen mode, however, it may happen that for some strange resolutions SDL accepts the request, but the screen goes blank... In such a case, you may shut down the program by pressing Ctrl-Alt-X. 😭 crisis averted

🌟 INTERPRETER NUMBER 🌟

The interpreter number is a setting in the Z-machine header which is used to tell the game what sort of machine the interpreter is running on. Sfrotz 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

okay that's part one bestie, there's more coming so don't go anywhere 🧚💖

🎀 NON BLORB RESOURCES 🎀

okay so bestie, Blorb-packaged resources are not the whole entire story 💅 — besides those, Sfrotz can also render graphics and sound straight from individual files, as long as those files are either:

  • suitably named (like, a common root plus a numeric field specifying the resource number), or
  • listed in a suitably formatted text file.
real talk: this feature is not automatic. you have to enable it with the -% or -@ command line options. and once it is enabled, resources found this way override those in the Blorb file, if present. 👑

This is lowkey a gift to game designers, because it makes changing and adding resources soooo much easier — you don't have to re-compile the Blorb file every single time you touch something. 🙈

And the format of the list file you use with the -@ option (peep EXAMPLE BLC FILE) is identical to the format of the BLC control file used by L. Ross Raszewski's iblorb package, so you can literally reuse the same list for compiling the final Blorb file for distribution. slay ✨

🦋 TRUETYPE FONTS 🦋

Sfrotz can display text with Truetype or Type1 fonts, using the FreeType2 rendering library. Where do the font files live? That has to be specified in the setup file. Also, antialiased rendering of Truetype fonts can be specified.

gentle heads up: this feature in sfrotz is still experimental, so don't expect too much (e.g., kerning is not supported). it's giving baby steps 🍼

🌸 DEFAULT FONTS 🌸

plot twist: Sfrotz does not need Truetype fonts to work at all. In fact it has a default monospaced font, based on an 8x16 VGA font, and that one can be used for both the TEXT_FONT and the FIXED_FONT of the z-machine, with suitable (though not very nice) modifications for the various styles. 🙈

And even if Truetype fonts are specified in the setup file, Sfrotz can be forced to use the VGA font by the -V command line switch. iconic 💅

🌈 UNICODE 🌈

Sfrotz supports Unicode glyphs by way of UTF-8, as long as the fonts loaded contain the glyphs you need. 🫶

The default font provided by SDL does not contain much beyond the Latin alphabet and some diacritical marks. Inverted punctuation marks as used in Spanish are missing. 😭

Two monospaced fonts known to work well with most commonly-encountered alphabetic languages are Leggie and FreeMono. They can be found at https://memleek.org/leggie/ (X11 BDF fonts) and https://www.gnu.org/software/freefont/ (Truetype fonts).

the sad part: Logographic glyphs (Kanji and Chinese are not currently supported.

👑 Z-MACHINE STANDARDS 👑

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

⭐ 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 graphics files, sounds directory, auxiliary, or blorb files — must be in the same directory as sfrotz finds the story file. no cap 📁

🎀 SETUP FILE 🎀

On startup, sfrotz will check $HOME/.sfrotzrc for setup information. The setup file has four sections: Interpreter, Display, Fonts, and Resources.

The Interpreter section deals with options having to do with how the Frotz core works.

The Window section deals with screen display. Sfrotz has a hardwired default screen size of 640x400. The screen size can be changed by the values in this section, by the values found in the Reso chunk of a Blorb file, and finally by the -w and -h command line options (in that order). Note however that sfrotz shall refuse to set a screen width less than 640 and/or a height less than 400.

NOTE: for normal (windowed) usage, the screen size should obviously be less than the PC screen resolution (taking into account also window decorations, taskbars etc.) For fullscreen usage, the size should preferably be one of those supported by the PC video driver; otherwise, SDL shall try to use the next higher available resolution, with black borders around the z-machine screen. In fullscreen mode, however, it may happen that for some strange resolutions SDL accepts the request, but the screen goes blank... In such a case, you may shut down the program by pressing Ctrl-Alt-X. 😭

The Display section is reserved for future developments.

The Fonts section is for defining the font directory, font files, and if antialiasing is enabled (which is currently not supported).

The following eight statements: textroman, textbold, textitalic, textbolditalic, fixedroman, fixedbold, fixeditalic, and fixedbolditalic; specify the eight font faces used by the z-machine (not counting the so-called graphics font used in Beyond Zork, which is hardwired in the program), that is the normal TEXT_FONT and the monospaced FIXED_FONT, each in four styles (roman, bold, italic and bold+italic). 💖

A single face is specified by the file name (with its suffix!), optionally followed by an @ sign and a number, indicating the font size in pixels (default is 14). Multiple face files can be specified, separated by pipe (|) characters; Sfrotz shall use the first one it finds (see the example in EXAMPLE SETUP FILE). This feature allows e.g. to use the same setup file on different systems. 🌈

The Resources section is for configuring graphics and sound resources. Each template must contain exactly one C-style decimal format specifier (e.g. Pict%d) to be substituted by the resource number.

✨ SETUP FILE GRAMMAR ✨

🧠 [Interpreter]

  • Number = number — Set the interpreter number (default is 4, i.e. Amiga Interpreter)
  • Error Reporting = level — Set the error reporting level (same as the -Z option)
  • Ignore Errors = 0/1 — Ignore (1) or not (0) non-fatal runtime errors.
  • Expand Abbreviations = 0/1 — Set/reset expansion of g/x/z abbreviations. Expansion is useful for old v1 games which do not understand such abbreviations. Default: 0 (the -xoption can set this switch.)
  • Tandy Bit = 0/1 — Set/reset the Tandy bit. Default: 0 (the -t option can set this switch.)
  • Wrap Script Lines = nc — Set the width (number of columns) of the transcript to nc. Same as -S option.
  • SaveNames = date/name — Set the mode (date or name) for creating default file names for save/script etc. For date, a timestamp is prepended to the filename extension. For name, a four-digit number beginning with 0000 is prepended to the filename extension.

🪟 [Window]

  • AcWidth = width — Set the screen width in pixels (default: 640)
  • AcHeight = height — Set the screen height in pixels (default: 400)

🖼️ [Display]

  • (This section reserved for future developments)

🎀 [Fonts]

  • antialias = 0/1 — Set antialiased rendering of Truetype fonts off (0) or on (nonzero). Note that this option cannot be overridden by a command line switch.
  • fontdir = folder — Specify the directory containing the Truetype fonts. If this does not begin with a slash, then the directory is assumed to be relative to the user's home directory.
  • textroman = fontspec — Set the font file for TEXT_FONT, roman style.
  • textbold = fontspec — Set the font file for TEXT_FONT, bold style.
  • textitalic = fontspec — Set the font file for TEXT_FONT, italic style.
  • textbolditalic = fontspec — the bold-and-italic TEXT_FONT one (the original page left this line blank, so consider it covered by the vibe of its siblings 💅).
  • fixedroman = fontspec — Set the font file for FIXED_FONT, roman style.
  • fixedbold = fontspec — Set the font file for FIXED_FONT, bold style.
  • fixeditalic = fontspec — Set the font file for FIXED_FONT, italic style.
  • fixedbolditalic = fontspec — Set the font file for FIXED_FONT, bold and italic style

🍓 [Resources]

  • Dir = folder — Specify the folder for individual graphics/sound resource files.
  • Pict = template — Template for picture resource files.
  • Snd = template — Template for sound resource files.

💖 EXAMPLE SETUP FILE 💖

# The # denotes the start of a comment
# Everything after the # is ignored, up to the end of the line

[Interpreter]
SaveNames=date

[Window]
# The following entries are commented out
# but they are the same as the hardwired defaults, anyway
#AcWidth = 640
#AcHeight = 400

[Display]

[Fonts]
antialias=1
fontdir=/usr/share/fonts/truetype/freefont
textroman=arial.ttf@16|FreeSans.ttf@16
textbold=arialbd.ttf@16|FreeSansBold.ttf@16
textitalic=ariali.ttf@16|FreeSansOblique.ttf@16
textbolditalic=arialbi.ttf@16|FreeSansBoldOblique.ttf@16
fixedroman=cour.ttf@16|FreeMono.ttf@16
fixedbold=courbd.ttf@16|FreeMonoBold.ttf@16
fixeditalic=couri.ttf@16|FreeMonoOblique.ttf@16
fixedbolditalic=courbi.ttf@16|FreeMonoBoldOblique.ttf@16

[Resources]
Dir=./        # the current dir
Pict=PIC%d    # i.e. PIC1, PIC2, ...
Snd=SND%d     # i.e. SND3, SND4, ...

🌟 EXAMPLE BLC FILE 🌟

Exec 0 ZCOD ani.z6

Snd 13 FORM busyalone.au.aiff
Snd 12 FORM s0020.au.aiff
Snd 11 FORM s0154.au.aiff
Snd 10 FORM s1484.au.aiff

Pict 10 PNG edleft.png0.png
Pict 11 PNG edleft.png1.png
Pict 12 PNG edleft.png2.png
Pict 13 PNG edleft.png3.png
Pict 14 PNG edleft.png4.png
Pict 15 PNG edleft.png5.png

Pict 16 PNG lauhoh.png0.png
Pict 17 PNG lauhoh.png1.png
Pict 18 PNG lauhoh.png2.png

Pict 19 PNG edfront.png0.png
Pict 20 PNG edfront.png1.png
Pict 21 PNG edfront.png2.png
Pict 22 PNG edfront.png3.png
Pict 23 PNG edfront.png4.png
Pict 24 PNG edfront.png5.png

Pict 25 PNG hoagie.png0.png
Pict 26 PNG hoagie.png1.png

Pict 30 PNG dott0.png

🦄 FURTHER INFORMATION 🦄

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

A git(1) repository of all versions of Unix Frotz from 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. 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 💀

okay bestie, sit down, we gotta talk about the ✨limitations✨ before you come for me in the group chat.

The Z Machine itself has trouble with the concept of resizing a terminal. Like, it genuinely cannot comprehend it. It assumes that once the screen height and width are set, they will never change — even across saves. And honestly? That made total sense back when 24x80 terminals were the norm and graphical user interfaces were mostly unknown. Different era, different vibes. 🕰️

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. 🚫🖥️ 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 energy only, periodt.

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

This manpage is not intended to tell users HOW to play interactive fiction, bestie, that's a whole other journey. 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. 🙈💅

okay but fr fr, if you find one, please report it to the Gitlab site referenced above in FURTHER INFORMATION. she wants to know. 🫶

👑 AUTHORS 👑

  • Frotz was written by Stefan Jokisch for MSDOS in 1995-7. iconic behavior, honestly.
  • The SDL port was done in 2009 by Aldo Cumani and is currently maintained by David Griffith <dave@661.org>.

not the two-decade-plus legacy 😭 the dedication is giving main character energy fr.

🌈 SEE ALSO 🌈

the whole friend group is here 🦋 go say hi to all of them.

and that's the whole page, bestie!! 💖✨ this one's from SDL Frotz v2.55, dated 2025-02-01 — go forth and play some interactive fiction, you absolute legend. 🎀👑🌸

📦 where this page comes from