AGiliTy: The (Mostly) Universal AGT Interpreter
            ====================================

                     Info from the Net

AGiliTy is an interpreter for game files created with Malmberg and
Welch's _Adventure Game Toolkit_. It is universal in the sense
that it understands and interprets most of the many versions of
the AGT game file format (unlike the original interpreters, which
were only intended to run the game file format associated with
them), and also in that it is written in ANSI C, so it should be
straightforward to port AGiliTy to other systems.

It is *not* a port of the original interpreters but rather a
completely new interpreter built around the game file format;
while it follows the original interpreters on most things, there
are some differences which are described below.

This software is copyright 1996, 1997 by Robert Masenten but may
be freely distributed and used for non-commercial purposes so long
as this file (and hence this copyright notice) is included
unaltered. Since this is a beta version, I ask that this not be
placed on FTP sites or BBSs other than the Interactive Fiction
archive at ftp.gmd.de and its mirrors.

Since this is free software, it has NO WARRANTY of any kind.

For information on compiling and porting this program, see the
file 'agility.doc'. A list of known bugs is in the file 'buglist'
and a list of changes from earlier versions is in 'changes.txt'.
(If this is with a binary and not the source version, some of
these files may not be present).

Send comments and bug reports to Robert Masenten at:
masenten@math.upenn.edu

AGiliTy versions for DOS, Windows 95/NT, Macintosh, Linux,
UnixWare/SCO 2.02, Amiga, and the Acorn Archimedes RISC OS are
presently available from the IF Archive at GMD, as is the
program's ANSI C core source code.

AGT and AGX Game Files
====================

Games in the AGT format can be found at the Interactive Fiction
archive: ftp://ftp.gmd.de/if-archive/games/agt

AGT games are recognizable by having several different files with
names like MYGAME.D$$, MYGAME.DA1, MYGAME.DA2 . . . MYGAME.DA6,
MYGAME.TTL, and so on.  They also usually come with a DOS runtime
interpreter (usually called RUN.EXE or MRUN.EXE), which can be
deleted without affecting AGiliTy. (DOS users might want to keep
it around *just in case,* depending on available hard drive space.

As of version 0.5, AGiliTy also has its own file format (with the
extension ".AGX"); existing AGT games can be converted into this
format using the utility AGT2AGX which comes with AGiliTy.

The new format takes all of the various AGT files (MYGAME.DA1,
MYGAME.DA2, MYGAME.DA3, MYGAME.DA4, MYGAME.DA5, MYGAME.DA6,
MYGAME.TTL, MYGAME.INS, MYGAME.VOC, MYGAME.D$$, MYGAME.OPT, and
parts of MYGAME.CFG) and puts all of the data in one file
(MYGAME.AGX).

Aside from the reduction in directory clutter, it has the
following advantages:

1) It's smaller; for large games the new format can save over 100K
(The most extreme case I've run across so far is _Shades of Gray_:
790K vs. 568K uncompressed or 273K vs.  148K ZIPed).

2) It loads faster since it's closer in structure to AGiliTy's
internal format. (In particular, the interpreter doesn't need to
build the dictionary or convert metacommand opcodes into a common
format).

3) It's more portable. For example, there are platforms out there
that can't handle the 'D$$' extension.


AGT Versions Supported
===================

AGiliTy understands the following versions of AGT (which includes
every AGT game at ftp.gmd.de that I know of):
--1.0
--1.18
--the early "Classic AGT": e.g. 1.19, 1.2, 1.21
--"Classic AGT", both big and small: e.g. 1.3, 1.32, 1.35, 1.5,
1.7
--the "Even Bigger 1.32" used by _Cosmoserve_
--the "Chemically Altered 1.32" used by _Shades of Gray_,
--Menichelli's 1.82[untested] and 1.83
--Both known proto-Master's Edition 1.5 variants
--The "Master's Edition", versions 1.0, 1.5, 1.55, and 1.56/1.6.

_The Pyramids of Mars_ and _Cliff Diver_ require configuration
options to be set; they use variant interpreters that are
supported but can't be detected by the interpreter. In particular,

_Pyramids_ needs the ALT_ANY option and _Cliff Diver_ requires the
IRUN option.

_Klaustrophobia_ is now supported. Use AGiliTy to play each of the
chapters as usual. To switch between chapters, just SAVE at the
end of one chapter and RESTORE at the beginning of the next (the
game will tell you when to switch chapters; however, use SAVE
instead of DONE1 or DONE2).  This is still experimental and so I'd
appreciate any feedback on how well it works (or doesn't work, as
the case may be).

Unlike the DOS programs that _Klaustrophobia_ originally used for
this, AGiliTy doesn't check that you've actually reached the end
of the previous chapter; be warned that if you switch chapters
before the game tells you to, things may break.

There is also no way for AGiliTy to support the intermission or
endgame text from the original game: these are all printed out by
DOS programs rather than by the AGT interpreter.

Differences between AGiliTy and the Original Interpreters
===========================================

--Disambiguation is done on the normal command entry line rather
than having a special prompt.
--LISTEXIT ON, LISTEXIT OFF will turn automatic listing of exits
on or off (in AGT there is a LIST EXITS command, so some AGT games
fail to list exits to a room).
--OOPS, UNDO, and RESTART are supported (at least on systems with
enough memory).
--Adjective-only matches are accepted by the parser.
--The parser is capable of intelligent disambiguation.
--It is also able to expand ALL and ALL EXCEPT.
--Some more multiple word verbs are automatically recognized (for
example, GET IN is automatically translated into ENTER).
--Some built-in verbs have additional synonyms. (In particular,
standard one-letter abbreviations are supported: X for EXAMINE, Z
for WAIT)


--The standard error messages are different than the original
(except in Master's Edition games where most of the standard error
messages are included in the game file)
--SCRIPT output is sent to a file rather than to the printer.
--AGiliTy has an extended AGILDEBUG debugging verb and supports
more detailed metacommand tracing output.
--There are some minor differences in the way that weight and size
are handled, and in the behavior of thrown liquids.
--AGiliTy uses a different save file format.
--COLORS is not supported, although on some systems equivalent
functionality may be supported in the configuration file.
--The special title screen effects of the Shades of Gray and
Cosmoserve97 interpreters aren't duplicated.
--Graphics, sound, and fonts are not supported by any of the
existing ports, although hooks exists to implement them, but all
of the remaining Master's Edition language extensions *are*
supported.



List of Special Verbs
===============

These are all of the special verbs recognized by the interpreter:
SCORE:    Print out your score.
NOTIFY:    Turn score notification on and off
INSTRUCTIONS or INS:  Display the instructions for the game.
INTRODUCTION or INTRO:  Repeat the introduction of the game.
BRIEF:    Don't print room descriptions for rooms you've seen.
VERBOSE:  Print room descriptions even for rooms you've already
seen.
LIST EXITS:    List the exits from a room.
LISTEXIT ON, OFF:    Turn on/off automatic listing of exits.
SCRIPT:    Start sending a transcript to a file.
UNSCRIPT:    Stop creating a transcript.
SOUND ON, OFF:    Turn sound on/off.
LOG:    Start sending all of your commands to a file.
REPLAY (number):  Replay your commands from a file, one every
(number) seconds.

REPLAY STEP:  Replay your commands from a file, one for every
keypress.
AGILDEBUG:    Access debugging commands.
MENU:    Toggle menu mode on or off.
OOPS:  Correct a word you just mistyped; must be the first command
on a line.
UNDO:  Undo your last move; must be the first command on a line.
SAVE:    Save the game.
RESTORE:    Restore the game.
RESTART:    Restart the game.
QUIT:    Quit the game.

Configuration Files
==============

The interpreter gets configuration information from as many as
three places: the global configuration file, the game-specific
configuration file (usually with an extension '.cfg'), and, in the
case of AGX-format games, the game file itself.

Options in the game-specific file override options specified from
the other two sources; options in the AGX file override those in
the global file.

The following configuration options are supported on all
platforms. Other options may be supported on your particular
system; see appropriate platform-specific documentation for
information.

Each option should be on a separate line in the configuration
file. Lines starting with '#' will be treated as comments and
ignored. Options can be negated by prefixing them with 'NO_' so
that, for example, DEBUG would become NO_DEBUG.

General options:
VERBOSE:    Start the game in VERBOSE mode
DEBUG:  Allow the use of AGILDEBUG for pre-Master's games (for
Master's Edition games, this decision is based on the DEBUG flag
in the game file itself).

PATH:  Gives a space-separated search path for AGT games (not
implemented yet).
TONE:  Enables the *tone* action token, which allows games to make
annoying beeps on some platforms. The only game I might recommend
enabling this for is _CosmoServe_, which has some interesting
sound effects. Not all platforms support this command.
INPUT_BOLD:  Makes the input line bold. (This doesn't work on all
platforms)
IBM_CHAR:  Try to use the IBM character set; don't translate them.
If your platform doesn't support the IBM character set, this will
probably just produce garbage.

Game-specific options:
ROOMTITLE:  Print the room title in bold before the room
description in pre-Master's games (Master's Edition games do this
automatically).
IRUN:  Print error messages in first person. This should be set
for _Cliff Diver_.
NO_BLOCK_HOSTILE:  Allow the player to leave a room containing a
hostile creature if they go back the way they came.
NO_GET_HOSTILE:  Prevents the player from picking up objects in a
room containing a hostile creature. (Intended to be used with
NO_BLOCK_HOSTILE.)
CONST_TIME:  Increment time at a constant rate instead of
randomly.
SLASH_BOLD:  If set the slash character toggles bold on and off.
(This should be set automatically for 1.8x games, but you may
still need to set it explicitly for version 1.82 )
PRONOUN_SUBS:  Do $you$-style substitutions even in game-author
defined messages.
ALT_ANY:  This scans the ANY metacommands *with* the metacommands
rather than before them. Should be set for _Pyramids of Mars_ and
not for any other games I know of.
SMART_DISAMBIG:  This turns on smart disambiguation.  This works
better with some games than others.
EXPAND_ALL:  This turns on ALL and ALL EXCEPT expansion in the
parser (by default, expanding them is the responsibility of the
individual verb execution routines); see remarks on


SMART_DISAMBIG: both of these options use the same engine and so
they are likely to work or fail together. If you're using this,
you'll probably also want to set FIX_MULTINOUN.

Technical options: These are fine tuning.
FIX_METAVERB:  Don't run ANY metacommands when executing a
metaverb.
FIX_MULTINOUN:  Only advance one turn when manipulating multiple
nouns, rather than a turn for each noun.
PURE_ANSWER:  Require AND-connected answers to be in the right
order. (The Master's Edition documentation claims order doesn't
matter, but in the actual interpreters it does.)

Parse Options: These are all pretty technical.
PURE_DUMMY:  Allow dummy verbs to be run by typing "dummy_verb3"
PURE_SUBNAME:  Allow subroutines to be run by typing "subroutine3"
PURE_SYNONYM:    Treat synonyms exactly as nouns.
ADJ_NOUN:  Don't pick noun matches over adjective-only matches.


Debugging Options
===============

With AGILDEBUG you can access various debugging commands. You can
move objects around; change the values of flags, variables and
counters; list objects in the game; examine and edit objects; and
turn metacommand tracing on or off.

When metacommand tracing is on, every metacommand that is run will
be displayed. You can turn off tracing of ANY metacommands and
tracing of metacommands during disambiguation (the latter is off
by default).

--adapted from the file README.AGILITY.





                              - o -