\documentstyle[12pt,jeep]{article}
\renewcommand{\baselinestretch}{.95}
\headheight 14pt
\cfoot{\thepage}
\underhead
\tighttoc
\thispagestyle{plain}
\numberbysection
\lhead{\large\tt ZMachine 1.0.3 Manual} \rhead{\sc Amiga Version 6/10/92}
\begin{document}
\begin{center}
\large\sc {\tt ZMachine 1.0.3}\smallskip\\
A ZIL Interpreter for the Commodore Amiga
\smallskip\\
Kent Dalton \\
Ported from the original UNIX version written by leo@marco.UUCP\\
\bigskip
{\em Amiga Port \copyright 1992 by Kent Dalton\\Read ``Copying'' section
of this manual for redistribution information.}
\end{center}

\tableofcontents
\pagebreak

\section{Introduction}

ZMachine is a program which can interpret ``Zork Implementation
Language'' (ZIL) data files. ZIL is the language used by the interactive
fiction series of games from Infocom, Inc. (a subsidiary of
Activision/MediaGenic).  This
program does not incorporate any code from Infocom software and is not
associated with or a product of Infocom, Inc. All game names mentioned
in this document are trademarks of Infocom.

ZMachine can interpret normal interactive fiction data files. It is not
compatible with interactive fiction plus (games with graphics, i.e.
Beyond Zork, Zork Zero, etc). This program has a number of excellent 
features not available in the software from Infocom and has some
customizations for the Amiga environment also. (For more information
see the ``Features'' section of this document)

This version of ZMachine was ported from a UNIX version. It was ported
using a PD termcap library and GCC 2.1. It also requires GCC's
ixemul.library V39 or greater (V39.26 of which is included in the archive). 
({\em Many} thanks to Markus Wild
for porting GCC to the Amiga and writing the ixemul.library! Great Job
Markus!). 

This program comes with no warranty express or implied. Use at your own
risk.

\section{Copying} 

The Amiga version of this program is Copyright \copyright 1992 by Kent Dalton.
Non-commercial redistribution of the program is allowed provided all files are
included in the distribution in unmodified form. Public Domain and Freely
Distributable libraries may change handling, shipping, and copying fee charges
to distribute the program provided the above condition is met. I will consider
honoring E--Mail requests (see ``Bug Reports'' section for E--Mail address)
for source code for this Amiga version. Requestors who add new functionality
or do bug fixes to ZMachine are required to return those changes to me.  I
think it will be best for the user base, in general, to have a single most
robust and featureful version available via one source. Contributors to
ZMachine development will be fully credited.

I will only distribute source to the the Amiga version, however.  The original
UNIX version is available via anonymous FTP (If you don't know how to find
things available for ftp, learn about the archie archive search server.  I'm
getting far too much ZMachine related mail as is, I do have a day job ya know!
:-))

\section{Features}

This program provides a number of features not available in the Infocom
ZIL interpreter:

\begin{itemize}
\item Support for workbench screens larger than the default NTSC (or PAL) 
hires (640x200) via the termcap enviroment variable.
\item Command history via the arrow keys.
\item Function Key support.
\item Emacs-like command line editing.
\item Support of the Amiga clip board for cutting and pasting text.
\item Support for automatic location of game files for hard disk users
\item Ability to use Interactive Fiction files from other computers. For
example, I transferred the Atari ST version of Leather Goddesses of
Phobos to my machine with MSH and use it on the Amiga. This way, you
can track down IBM or ST (maybe mac too) versions of some of the
classics that aren't available in the Lost Treasures collection.
\item Special support for running Infocom games on a BBS.
\end{itemize}

\section{System Requirements}

ZMachine was ported using an Amiga 3000 with 6Mb RAM and AmigaOS 2.04.  I do
not know if it works with AmigaOS 1.3. If it does not, no effort will be made
to port it to 1.3 (see ``Copying'' section for info on how to obtain source
code.). The ixemul.library definitely requires the 2.04
mathieeesingbas.library, ZMachine does not use floats though, so you might be
able to get away with copying over another library in its place (or you could
get the library from someone who has 2.04, although I'm not sure if this is
legal or not.)

NTSC and PAL displays and all Motorola 680x0 CPU's are supported.

The amount of memory used is determined by the game being played. The
average seems to be on the order of 256K.

\section{Installation}

\begin{enumerate}
\item Copy termcap file to S: directory.
\item Set TERM environment variable for proper screen type i.e. {\tt
setenv~TERM~amigalace}. You'll probably want to add this to your
user-startup (or startup-sequence) file. 
\item Copy ixemul.library from the libs directory to LIBS: if you currently 
do not have a copy of ixemul.library version 39 (or greater) there already.
\item If you are using a 68000 or 68010 CPU you'll probably want to copy
zmachine.68k over zmachine since `zmachine' is the 68020+ version.
\item If your termcap entry is smaller than 640x400 (amigalace) you'll
also want to edit the dimensions of the WINDOW= tool type for the
zmachine.info file (this controls the size of the window popped by
zmachine (and the `iconified' window size also.))
\end{enumerate}

{\bf Hard Disk Users Note:}\\
If you are using a hard disk you may want to {\tt assign~LTOI:} to
the directory where your infocom games are located.

ZMachine assumes a directory structure of:
\begin{verbatim}

         LTOI: ->GameName1->Story.Data
               ->GameName2->Story.Data
               .
               .
               .
               ->GameNameN->Story.Data

\end{verbatim}

when using this directory structure, ZMachine will be able to
automatically locate the main data file for the game you wish to play
and automatically place and retrieve game save files from the directory
of that specific game as well.
\\
 
You'll probably want to rename the Zork 1-3 data files to Story.Data
as well. They work properly with ZMachine, Infocom just named them
differently.
\\

I recommend copying zmachine and zmachine.info to LTOI: as well.

\section{Running ZMachine}
\subsection{From Workbench}
An icon will be opened and zmachine will prompt you for a game name.
If you have not assigned LTOI: to a directory, you must type in the full
name of the file you wish to run. If you are you using zmachine with the
LTOI: assign and directory structure mentioned in the Hard Disk
Installation notes above, you can just type the name of the games
directory that you wish to play. For example: if you type `moonmist',
ZMachine will attempt to open: LTOI:moonmist/Story.Data as the game
file. From then on, the default SAVE/RESTORE path will be LTOI:moonmist,
this way, you don't get a whole bunch of files from different games 
getting mixed up in your LTOI: directory.

\subsection{From CLI}

CLI startup works similar to the UNIX version. Switches are
preceeded by a '--' character and switches which take arguments are
seperated from the argument by whitespace. Here is the usage
information with all the switches ZMachine understands:

\begin{verbatim}

Usage:  zmachine  [-p  protocolfile]  [-w  protocol  linewith]
        [-s  storyfile]  [-r  restorefile] [-cli]
        [-bbs savepath] [-nowrap] [ -li lines] [-co columns]
        [<storyfile>] [<restorefile>]


-p protocolfile     : send output after script command to protocolfile
-w protocol linewith: set protocol linewith to linewith
-s storyfile        : use storyfile
-r restorefile      : restore savefile restorefile before starting game
<storyfile>         : use storyfile
<restorefile>       : restore restorefile
-cli                : ZMachine will not prompt user to hit return on exit.
-nowrap             : Do not handle long lines the "amiga" way. May be
                      necessary for running on some non-amiga terminals
                      over serial connection.
-bbs                : BBS mode. Allows exit on CTRL-C, restricted save
                      path, and automatically invokes -cli mode.
-co                 : Override the termcap column entry.
-li                 : Override the termcap lines entry.


If you call zmachine without arguments, it trys to open the file
Story.Data on the current working directory. 
\end{verbatim}

Notice the default file extensions. Zmachine checks and {\em enforces}
these (case-sensitively) when started from CLI. If lots of people are
bothered by this, I can change it.

\section{Command Editing}

\subsection{Editing Keys}

\begin{verbatim}
Cursor left             :       ^B (also Left-Arrow on Amiga)
Cursor right            :       ^F (also Right-Arrow on Amiga)
Up in history           :       ^P (also Up-Arrow on Amiga)
Down in history         :       ^N (also Down-Arrow on Amiga)
Delete left             :       BackSpace (and Del on Amiga)
Delete right            :       ^D 
Start of line           :       ^A
End of line             :       ^E
Kill to end of line     :       ^K
Kill to start of line   :       ^X
Program function key    :       ^I (TAB)
Undo                    :       ^Y
Function key 0-9        :       F1-F10
\end{verbatim}

\subsection{Using the Clipboard}

\begin{enumerate}
\item Select text with mouse
\item Hit Amiga-C to Cut text
\item Hit Amiga-V to paste text at cursor position
\end{enumerate}

\section{BBS Mode}
BBS Mode causes three features to be active:
\begin{enumerate} 
\item CLI mode becomes active so the user is not prompted for a return
keystroke on exit.
\item ZMachine will recognize a Control--C character as an exit signal.
This provides a way for the sysop to signal the program to exit on time-out 
or disconnect.
\item It restricts the save path, so users can only write to or read from
specific files in a sysop specified directory. This keeps a user from
unintentionally (or maliciously) writing to important system files, etc.  
When the user tries to save or restore the game, they are prompted for
a save position [0-9], which is used to formulate the save/restore file
name. The file name is formulated by first appending the save position to 
the save file path specified with the -bbs option, an extension of 
``.sav'' is then appended to that. Examples:

\begin{verbatim}
    zmachine -bbs LTOI:saves/
\end{verbatim}

Yields save file names of:

\begin{verbatim}
    LTOI:saves/0.sav
    LTOI:saves/1.sav
    .
    .
    LTOI:saves/9.sav
\end{verbatim}

If the user name and game name are put in the savepath, the sysop can make
multiple games available to the users:

\begin{verbatim}
   zmachine -bbs BBS:userfiles/kentd/moonmist
\end{verbatim}

Yields:

\begin{verbatim}
   BBS:userfiles/kentd/moonmist0.sav
   BBS:userfiles/kentd/moonmist1.sav
   .
   .
   BBS:userfiles/kentd/moonmist9.sav
\end{verbatim}
\end{enumerate}

The ``-co'' and ``-li'' switches which allow overriding the termcap
column and line values on the command line, are also useful for BBS
mode (but can be used independently of it, as well). Using this
feature, your BBS can invoke ZMachine with the user's terminal
settings rather than forcing them to use the same terminal settings
as the BBS's termcap entry.

This scheme should provide enough flexibility for most BBS operators
who wish to make ZMachine interpreted games available to their 
users, provided their BBS software is reasonably configurable.

\section{Caveats and Known Bugs} 

Lurking Horror will hang when it tries to do the
Amiga sound stuff. Do not use this program with the Amiga version of Lurking
Horror (you can use it with versions of Lurking Horror from other
computers' versions which do not do sound, I've used it with the Atari
ST version for example.)
\\
ZMachine save game files are incompatible with game save files created
by the Infocom ZIL interpreter and vice versa. ZMachine will give a fatal
error (i.e. it stops the game. Zmachine must be restarted) if one is
attempted to be read.
\\

\section{Reporting Bugs, Comments, and Questions}

I have tested this program with most of the non-plus interactive fiction
games from Lost Treasures and several others from other computers and
they have all worked great so far. Let me know if you find any that do
not.

Feel free to send Bug reports, comments, or questions to me via E--Mail:
\begin{verbatim} 
Kent.Dalton@FtCollinsCO.NCR.com
\end{verbatim}

I will try to respond as time allows. 

I hope you enjoy this program! I use it for all of my interactive
fiction now!

\section{Revision History}
\subsection{Version 1.0.0}
\begin{itemize}
\item Original release.
\end{itemize}

\subsection{Version 1.0.1}
\begin{itemize}
\item ZMachine now resets terminal characteristics on exit.
\item Fixed "character wrap" bug on Amiga terminals.
\item Added cli switch for no prompt on exit.
\item Added nowrap switch that handles line wrap old way. (May be necessary
     for some non-Amiga terminals or running over serial line, experiment
     both ways to see which works best.)
\item Tested Function Key support (works).
\end{itemize}

\subsection{Version 1.0.2}
\begin{itemize}
\item BBS mode added: CTRL-C handling, Quick exit, and restricted save paths.
\item Internal argument parsing routines completely rewritten. The old
ones were seriously brain-dead, IMHO.
\end{itemize} 
\subsection{Version 1.0.3}
\begin{itemize}
\item Command line override of termcap column and line entries added (user
request).
\item No longer forces extensions for filenames. (misfeature) 
\end{itemize}
\end{document}