Sfrotz manual (sort of...)
Copyright © 2011 Aldo Cumani
Comments and bug reports to <sfrotz .at. writeme .dot. com> (apologies for the anti-spam-munging.)
This is just a preliminary draft of a manual. It refers to sfrotz v0.02
This document is relased under the terms of the GNU Free Documentation License.
1. Introduction
Sfrotz is a Linux (though potentially cross-platform) port of the well-known z-code interpreter Frotz 2.40. Sfrotz uses SDL for video rendering and either SDL-mixer or MikMod for audio. While in principle Sfrotz should run on any platform supporting SDL, in practice it has only been extensively tested on Linux (Debian 5 lenny x86 and Debian 6 squeeze x64).
1.1 Installation
Sfrotz is distributed in source form. Compiling the sources requires gcc (Mingw32 on Windows also works, more or less) and GNU make. The distribution does not currently include any configuration script, so the Makefile must be adapted by hand to the target system.
2. Features
2.1 Blorb resources
Sfrotz can render graphics (for V6 games) and sound effects packaged in a Blorb file (but see also the next section). As concerns pictures, Sfrotz supports both PNG and JPEG images. Regarding sound, AIFF sound effects, MOD songs and OGG music are currently supported, while SONG songs won't probably be ever supported.
Besides Blorb-packaged resources, Sfrotz can also render graphics and sound from individual files, provided the latter are either suitably named (e.g a common root with a numeric field specifying the resource number), or listed in a suitably formatted text file.
Note that this feature is not automatic, but must be enabled by the -L or -@ command line options. When the feature is enabled, resources found this way override those in the Blorb file, if present.
This feature can be useful to game designers, as it eases changing and adding resources without having to re-compile the Blorb file each time. The format of the list file used with the -@ option (see the Appendix) is identical to that of the BLC control file used by L. Ross Raszewski's iblorb package, so one can use the same list for compiling the final Blorb file for distribution.
2.3 Truetype fonts
Sfrotz can display text with Truetype or Type1 fonts,
using the FreeType2 rendering library.
The location of the
necessary font files must be specified in the setup file. Also,
antialiased rendering of Truetype fonts can be
specified.
Please note that this feature in Sfrotz is still experimental,
so don't expect
too much (e.g., kerning is not supported).
2.4 Default fonts
Sfrotz needs not Truetype fonts for working; in fact it has a default
monospaced font, based on an 8x16 VGA font, which 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. 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.
3. Command line options
3.1 Standard Frotz options
| -a |
For game debugging: watch attribute setting. |
| -A |
For game debugging: watch attribute testing. |
| -b colour |
Set the background colour. The colour argument
is the number of a z-machine colour, in the range 2..9: |
| -c lines |
Set the number of context lines. |
| -f colour |
Set the foreground colour. |
| -h size |
Set the z-machine screen height (see the NOTE). |
| -i |
Ignore non-fatal runtime errors. |
| -l margin |
Set the left margin. |
| -o |
For game debugging: watch object movement. |
| -O |
For game debugging: watch object locating. |
| -p |
Alter the piracy opcode. |
| -r margin |
Set the right margin. |
| -R |
Save/restore in the old Frotz format. |
| -s seed |
Set the random number seed value. |
| -S width |
Set the transcript width (in columns, default = 80). |
| -u number |
Set the number of slots for multiple undo (default: 500). |
| -w size |
Set the width of the z-machine screen to size (see the NOTE). |
| -x |
Expand abbreviations (g/x/z). |
| -Z level |
Set the z-code error reporting level. Level can be:
| 0 | don't report errors |
| 1 | report only the first error |
| 2 | report all errors |
| 3 | exit after any error |
|
3.2 Extended options
| -F |
Run in fullscreen mode (see NOTE). |
| -m msecs |
Set the timer interrupt cycle to msecs milliseconds,
instead of the default 100 (1/10 sec). |
| -N mode |
Set the mode for creating default file names for save/script etc. |
| -T |
Use traditional in-game requests for file names, intead of on-screen
dialogs. |
| -V |
Force the use of default monospaced VGA font. |
4. 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: @read opcode), whith the exception of Ctl-Alt-X which also works in single character input mode (@read_char opcode).
| Alt-D |
set debugging options |
| Alt-H |
help (print the list of hot keys) |
| Alt-S |
set random number seed |
| Alt-X |
exit game (after confirmation) |
| Ctl-Alt-X |
exit game immediately (no confirmation) |
5. The setup file
5.1 Section [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 -x option can set this switch.) |
| Tandy Bit = 0/1 |
Set/reset the Tandy bit. Default: 0 (the -t option can set this switch.) |
| Quetzal Format = 0/1 |
Save/restore in Quetzal format when set, in old Frotz format when reset.
Default: 1 (the -R option can only reset this switch.) |
| Wrap Script Lines = nc |
Set the width (number of columns) of the transcript to nc. Same
as -S option. |
5.2 Section [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 chunck 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.
| AcWidth = width |
Set the screen width (default: 640) |
| AcHeight = height |
Set the screen height (default: 400) |
5.3 Section [Display]
This section is for future developments.
5.4 Section [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. |
The following eight statements 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 the Appendix). This feature allows e.g. to use the same setup file on different systems.
| 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 |
Set the font file for TEXT_FONT, bold and italic
style |
| 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 |
5.5 Section [Resources]
| Dir = folder |
Specify the folder for individual graphics/sound resource files. |
The following two statements specify the templates for the names of individual picture/sound files.
Each template must contain exactly one C-style decimal format specifier (e.g. Pict%d) to be substituted by the resource number.
| Pict = template |
Template for picture resource files. |
| Snd = template |
Template for sound resource files. |
6. Credits
The original Frotz code was designed by Stefan Jokisch.
This port is heavily based on the Windows port by David Kinder.
The Blorb resource format and related software are by Andrew Plotkin.
The Simple DirectMedia Layer library is the work of Sam Lantinga.
TrueType font rendering relies on the freetype2 library.
Sound and music are rendered by the MikMod library.
PNG format images are decoded using libpng and zlib.
JPEG format images are decoded using the IJG software, whose authors kindly request us to state that
"This software is based in part on the work of the Independent JPEG Group."
Apologies to all those people and/or organisations who should have been mentioned, and were not :(
7. Appendix
# 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, ...
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