nfrotz
========================================================================
NFrotz is a Z-Machine interpreter (virtual machine) for text mode
interactive games.  It is an ncurses-based synthesis of the Windows
version of frotz (WinFrotz) with the Unix one, adding support for the
Quetzal savefile format, Blorb and iFiction support, and Unicode output
on terminals that support it. It supports zcode specification 1.1,
including all versions v1 thru v8 (except for some v6 [graphical] games).

This release includes a bundled version of the great grand-daddy of them
all, "Colossal Cave Adventure" (aka Adventure). The original, written
in Fortran in 1975 by Will Crowther, was expanded by Don Woods in 1977
to a 350 point version, which was the most widely-distributed variant.
This was then ported DOS MS Fortran, which was itself re-implemented
using the TADS virtual machine interpreter. Finally, the TADS version
was ported to zcode -- and now you have it!

The more-or-less public domain version of the original MIT Zork (aka
"Dungeon") is installed as zdungeon. This was the original mainframe
version, which was later modified and divided into the Zork Trilogy. It
was ported to zcode from the 1981-era PDP-10 MDL source by Ethan Dicks:
  http://www.penguincentral.com/retrocomputing/zdungeon/
Note that there ARE gameplay differences between Dungeon and similar
situations/locations in the Zork Trilogy.

There is also a script `/usr/bin/zork-config' which can be used to
download and install the Zork I, Zork II, Zork III, and Zork: The
Undiscovered Undergound games.  These four games were released gratis,
but not libre, by Infocom/Activision as part of the promotional campaign
for Zork: Nemesis and Zork Grand Inquisitor.  However, the license for
these games prohibits redistribution, so they are not directly bundled
here. Instead, use the script to download directly from the (unofficial,
now that Infocom is dead) Infocom homepage.

Also, see http://www.csd.uwo.ca/Infocom/ for walkthrus and "invisiclues"
(that is, cheats) if you're desparate. And many more games -- most
libre as well as gratis -- can be downloaded from
  http://www.ifarchive.org/indexes/if-archiveXgamesXzcode.html
  http://www.ifarchive.org/if-archive/games/zcode/


Runtime requirements:
  cygwin-1.7.1-1
  libgcc1-4.3.4-2
  libncursesw10-5.7-18
  diffutils             (for preremove script)
  wget                  (for zork-config script)

Build requirements:
  cygwin-1.7.1-1
  cygport-0.9.9-1
  libncursesw-devel
  gcc4-core-4.3.4-2
  binutils-2.19.51-1
  make, sed, awk, ...

Canonical homepage:
  http://www.ifarchive.org/indexes/if-archiveXinfocomXinterpretersXfrotz.html

Canonical download:
  http://www.ifarchive.org/if-archive/infocom/interpreters/frotz/

License:
  GPLv2

Language:
  C

========================================================================

Build instructions:
  unpack nfrotz-0.3.3-X-src.tar.bz2
    if you use setup to install this src package, it will be
         unpacked under /usr/src automatically
  cd /usr/src
  cygport nfrotz-0.3.3-X all

This will create:
  /usr/src/nfrotz-0.3.3-X-src.tar.bz2
  /usr/src/nfrotz-0.3.3-X.tar.bz2

========================================================================

Files included in the binary distro

  etc/defaults/etc/frotz.conf
  etc/postinstall/nfrotz.sh
  etc/preremove/nfrotz.sh
  usr/bin/advent
  usr/bin/nfrotz.exe
  usr/bin/zdungeon
  usr/bin/zork-config
  usr/share/doc/Cygwin/nfrotz.README
  usr/share/doc/nfrotz/*
  usr/share/games/zcode/advent.z5
  usr/share/games/zcode/zdungeon.z5
  usr/share/games/zcode/unicode.z5
  usr/share/games/zcode/graphics/
  usr/share/games/zcode/sound/
  usr/share/games/zcode/infocom/graphics
  usr/share/games/zcode/infocom/sound
  usr/share/man/man6/nfrotz.6.gz

========================================================================

Port Notes:

Required Advertisement
======================
Incorporates modified versions of gi_blorb.h and gi_blorb.c from
WindowsGlkSrc-137.zip. These files were written by Andrew Plotkin, and
released under a BSD-ish license.


Installation Notes
==================
It's recommended that you add something like:
  export ZCODE_PATH="$HOME/.zcode"
to your .bashrc. (The default /etc/frotz.conf already takes care
of /usr/share/games/zcode:/usr/share/games/zcode/infocom).

For games that include graphics (not supported) and sound (supported),
you must install the sound files in the 'sound' directory, underneath
the zcode file and the graphics files in the 'graphics' subdirectory.
That is:
   /usr/share/games/zcode/infocom/sherlock.z5
   /usr/share/games/zcode/infocom/zorkzero.z6
   /usr/share/games/zcode/infocom/sound/sherlo03.snd
   /usr/share/games/zcode/infocom/sound/sherlo04.snd
   /usr/share/games/zcode/infocom/sound/...
   /usr/share/games/zcode/infocom/graphics/zorkzero.mg1
   /usr/share/games/zcode/infocom/graphics/...


General Discussion
==================
Some Z-code interpreters support a new, combined [z]blorb format, which
is a container that bundles the various components into a single file.
This format also supports "iFiction" records, which allow to specify
metadata about the game.  You will typically see these in three different
forms:

  1) all-in-one: for instance
        /usr/share/games/zcode/infocom/journey.zblorb
     would contain about 130 PNG files, plus the various 'iFiction'
     metadata entries, AND the journey.z6 z-code.  This is usually
     indicated by the .zblorb (or .zblb) extention, instead of
     the .blorb (or .blb) extension.

  2) z-code and meta-data separately. For instance:
       /usr/share/games/zcode/infocom/journey.z6
       /usr/share/games/zcode/infocom/journey.blb
     where the first contains the z-code, and the second contains
     all of the various images, and possible iFiction metadata.

  3) z-code + metadata, but no bundled (gameplay) media. That is:
       /usr/share/games/zcode/violet.zblorb
     which really just contains violet.z6 and the iFiction metadata.
     (Newer games, like violet, now routinely include a single graphic
     called the "frontispiece", which some Z-code interpreters display
     upon loading the game; the "frontispiece" is like the title page
     or box art -- it does not appear during actual gameplay, and is
     simply ignored by non-graphical interpreters.)

One interesting note about blorb and media files: the bundled media are
always in a different format than the original standalone media.

               |     infocom        |       blorb
     ----------+--------------------+--------------------
     graphics  | .mg1 .eg1 .cg1 [1] |   .png .jpeg [2]
     sound     |     .SND [3]       | .aiff .ogg .mod [4]

There are tools available to convert between all of these formats;
check the interactive fiction archive.

[1] There will typically be one file in each of these three formats
    per game (if the game incorporates graphics). These are multiframe
    containers themselves, at three different resolutions and color-
    depths: mg1 ("MCGA/VGA") is nominally 320x240 with 14 colors (plus
    one transparent and one foreground/text color), although individual
    images may be smaller.  The .eg1 ("EGA") and .cg1 ("CGA") versions
    are downscaled versions of the .mg1 files.

    nfrotz ignores graphics files.

[2] The .blorb file may contain any number of separate .png or .jpeg
    images, each in its own "chunk". PNG files are most common, and are
    typically palette-indexed, with 2, 4, or 8 bits per pixel; newer
    interpreters support alpha-blending.

    nfrotz ignores graphic images in .blorbs.

[3] There are actually three different incompatible .SND formats used
    with z-code games: the modern version, infocom's Macintosh format,
    and infocom's Amiga format.  These are uncompressed sample formats,
    as opposed to MIDI or compressed data.  Each consists of a header,
    followed by a stream of 8-bit sample sample values. 16-bit values
    (sometimes used in the header) are always big-endian (MSB first).
    The content and layout of the header varies between the three
    formats, and the Amiga uses 8-bit signed samples, while the other
    two uses 8-bit unsigned ones.  Most Z-code interpreters support
    the "modern" version; the interactive fiction archive has tools
    to convert if necessary.

    nfrotz supports "modern" .SND files, located in the sound/ directory
    below the z-code file. The volume is very loud, and on cygwin can't
    be lowered: the cygwin OSS emulation doesn't support /dev/mixer,
    and nfrotz doesn't know how to talk with the modern Gnome- and KDE-
    derived sound daemons.

[4] AIFF is a standard uncompressed sampled-data sound format. OGG
    is a container format that tyically contains sampled-data which has
    been compressed using the (lossy) Vorbis encoder (or rarely, the
    lossless Flac encoder, or the lossy Speex encoder).  Support within
    Z-code interpreters for these codecs varies.  MOD is an Amiga-derived
    MIDI-like format for music synthesized from note samples.  MOD files
    in blorb are limited to the ProTracker 2.0 format: 31 note samples,
    and up to 128 note patterns.

    nfrotz does not support any of these formats. It can detect the
    presence of sound chunks in the .blorb, but cannot play them.
    Realistically, playback would require linking in some audio library,
    and that's not something I wanted to consider, simply to support
    two games -- when there's a workaound already: extract from the blorb,
    convert to SND, give them the appropriate names, and install them
    under sound/.

nfrotz and blorb support
========================
nfrotz fully supports only the third kind of blorb listed above -- those
which contain just the z-code, and possibly some iFiction metadata. If
the metadata includes a frontispiece, nfrotz ignores that item.  nfrotz
can use the all-in-one kind of blorb; it will simply ignore any graphics
and complain about audio in the blorb (see below).

Unlike many other interpreters, nfrotz does NOT support variant number
two (separate z-code file and multimedia blorb).  Why should it? It
will ignore the graphics, and would only complain about the audio. So,
it ignores -- actually, doesn't even look for -- any $GAME.blorb file
next to the z-code.

Since nfrotz is console-only, it ignores any and all graphic elements:
whether frontispiece, graphics/*.mg1, or bundled into the blorb. Also,
the only Z-Machine version to support graphics is .z6 -- that Z-Machine
version includes some op-codes that are not supported by nfrotz, even
though its ancestor WindowsFrotz does. Thus, .z6 games MAY be playable
using nfrotz, if the graphics are not necessary for gameplay -- or they
might not be playable, if the Zcode uses any of the unsupported op-codes.

nfrotz supports sound, but only in the unbundled SND format and file
arrangement (where the SND files are located in the sound/ directory
below the z-code file. If you use a blorb file that contains audio
media, nfrotz will detect and report that those samples are present,
but that it cannot play them. You can disable these messages using the
  > $SOUND
command -- or use tools from the interactive fiction archive to unpack
them from the blorb and convert back to the original SND format. I don't
really expect this to be much of an issue; infocom released only two
text adventures that used sound: The Lurking Horror and Sherlock: The
Riddle of the Crown Jewels. If you have a copy of sherlock, you can
quickly test sound support by starting the game, and doing this:
  > knock on door
  > u
  > n
  > take violin
  > play violin


nfrotz and unicode
==================
Seems to work fairly well now that cygwin supports libncursesw. Currently,
nfrotz detects whether the $LC_* or $LANG variables are set and specify
use of the UTF-8 character set, OR if the user has specific -U on the
command line.  In that case, all strings are output as unicode to the
terminal, leaving it up to the terminal to display.  This works...in some
terminals, with properly installed fonts that support the necessary range
of glyphs.

  rxvt: displays incorrect characters for high code points

  rxvt-unicode: Works quite well, for version 9.07 and above. See the
                rxvt-unicode.README file in /usr/share/doc/Cygwin for
                information on how to install/configure a suitable font
                selection.

  mintty: Works pretty well. You need to install and use a font with
          a large range of glyphs.  Courier New, Consolas, Lucida Console
          are the best pre-installed ones. The DejaVu Mono font is pretty
          good too, as is DejaVu LGC Mono (but supports only Latin,
          Greek, and Cyrillic glyphs):
            http://dejavu-fonts.org/wiki/index.php?title=Download
          Finally, the GNU FreeFont collection has the largest range of
          glyphs of all:
            http://ftp.gnu.org/gnu/freefont/
          In all cases, mintty has issues with Arabic glyphs, even when
          the font provides them.
          Consolas is available by default on Vista, but can be downloaded
          for other Windows versions here:
            http://www.microsoft.com/downloads/details.aspx?familyid=22e69ae4-7e40-4807-8a86-b3d36fab68d3&displaylang=en

   cmd: Also works pretty well. The typical cmd window only allows
        "raster" fonts, and Lucida Console (+Courier New, pre-Vista).
        To add additional fonts to this list, you need to use regedit (on
        Vista, launch as Administrator) and go to the following key:
          HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Console\TrueTypeFont
        Once there, create a new string value with name "00" and value
        that specifies the name of the desired font.  E.g.
          00     Courier New
        Additional entries can be added as follows:
          000    Consolas
          0000   DejaVu Sans Mono
        Unfortately, FreeMono doesn't work. I can only suspect that it
        violates one of the restrictions mentioned here:
        http://support.microsoft.com/default.aspx?scid=kb;EN-US;Q247815
        Anyway, then you have to reboot. Once you do, the cmd properties
        Font tab will have the additional selections.

To test unicode support, run the unicode.z5 test program:
  nfrotz -U unicode.z5
which is installed into the /usr/share/games/zcode/ directory.

----- nfrotz-0.3.3-4 -- 2016-Mar-25 -----
* Update packaging
* Update URLs in zork-config script
* Initial build for x86_64

----- nfrotz-0.3.3-3 -- 2010-Jan-06 -----
* Compile against libncursesw10, for unicode support
* Update documentation
* Install unicode.z5 test file

----- nfrotz-0.3.3-2 -- 2009-Oct-22 -----
* Initial public release.
* Corrected setup.hint errors.
* Fix a few issues with auto-detecting output type (flat-ascii,
  latin-1 ascii, unicode).

----- nfrotz-0.3.3-1 -- 2009-Oct-19 -----
* Preview release.
* Includes a port to zcode of 'Colossal Cave Adventure'.
* Also includes a zcode port of the more-or-less public domain Dungeon
  (aka MIT Zork), the mainframe version that was the predecessor of
  the famous Zork Trilogy.
* Incorporate os_audio_oss.c from frotz-2.43 to enable (SND) sound
  support, and gi_blorb.h and gi_blorb.c from the windows port of
  the Glk library (WindowsGlkSrc-137.zip) to enable detection -- but
  not playback -- of sound samples embedded in a blorb.

Cygwin port maintained by: Jon Turney <jon.turney@dronecode.org.uk>
