Category : A Collection of Games for DOS and Windows
Archive   : AGTNUM.ZIP
Filename : AGTNUM.DOC

 
Output of file : AGTNUM.DOC contained in archive : AGTNUM.ZIP
AGTNUM

The Adventure Game Toolkit Number Manager
Version 1.08; April 29, 1990

by Bill Martinson

The Adventure Game Toolkit Number Manager (AGTNUM), including all source
code, object code, and manuals on paper or on disk, is copyright 1988-1990
by William D. Martinson. AGTNUM is distributed by Softworks.

AGTNUM is provided to users of the Adventure Game Toolkit (AGT), and as
such is subject to the copyright, warranty, and license conditions of AGT.
Specifically, all such conditions that apply to COMPILE.EXE shall be
construed as applying to AGTNUM.EXE as well.


INTRODUCTION TO AGTNUM

AGTNUM is a sort of "pre-compiler" for the Adventure Game Toolkit compiler.
It is intended to simplify the creation and maintenance of the rooms,
nouns, creatures, commands, and messages (and the relationships between
them) that comprise an AGT adventure game. AGTNUM provides the following
benefits to the game designer:

 A single source file is used, which encompasses everything from
the .DAT, .CMD, .MSG, .TTL, and .INS files. Corresponding
commands and messages can be placed together in the file, and
they can immediately follow the room, noun, or creature they
affect. AGTNUM handles the task of creating the necessary AGT
source files and writing the appropriate information to each.

 Sequential items such as rooms, messages, and variables are
referred to with user-defined text labels instead of numbers.
When AGTNUM creates the AGT source files, it converts the labels
into the appropriate numbers.

 Games that outgrow AGT need not be "converted" to AGT BIG format.
Since AGTNUM handles all the numbering, a simple command-line
option allows normal or big-version output.

 Messages can be printed directly from within meta-commands
without explicitly creating a MESSAGE definition.

 Special "directives" provide capabilities for writing simple text
macros, setting program options, including other source files,
and commenting the source file.

 The use of these features makes the game file self-documenting to
a great extent.


OVERVIEW

AGTNUM is not an editor, but rather a sort of "pre-compiler." It modifies
the process of creating an adventure game by introducing an intermediate
step between editing and compiling:

A. Create or edit a game file using a suitable text editor (one that
creates standard ASCII files). This file will contain all the
definitions, commands, and messages for the entire game--in
short, everything that would ordinarily go into the .DAT, .CMD,
and .MSG files. Optionally, the text from the .TTL and .INS
files can also be included in the .AGT file.

B. Use AGTNUM to generate the normal AGT source files (.DAT, .CMD,
etc.) from the master game file.

C. Use COMPILE (or COMPILEB) to generate the final adventure game
from the normal AGT source files.

D. Test the game, and return to step A to make changes (don't edit
the intermediate files).

For example, the following series of DOS commands might be used to create
an AGT "Star Trek" game:

EDIT STARTREK.AGT ("EDIT" is a hypothetical text editor)
AGTNUM STARTREK (create STARTREK.DAT, STARTREK.CMD, etc.)
COMPILE STARTREK (generate the final adventure game)

If you press a key while AGTNUM is processing a file, the program will
display a "Cancel?" prompt. Press 'Y' or 'y' to return to DOS, or press
any other key and AGTNUM will continue processing your game file.


LABELS

The .AGT file looks very much like the standard AGT source files. The main
difference is that it uses text labels instead of numbers for rooms, nouns,
and the like. The labels are enclosed in delimiters, which are normally
the square brackets [ ]. (This can be changed, however.) Labels may
consist of any printable ASCII characters (even blanks and tabs), except
the closing delimiter. For example, the following labels are all legal
(and unique):

[bridge]
[the captain's quarters]
[transporter number 6]
[ transporter number 6 ]
[!@#$%{}^&*()]
[[[[[[]
[!]
[ ]
[ ]

The null label [] is not allowed. AGTNUM is normally insensitive to case,
so [bridge] and [BRIDGE] are considered identical. (This can be changed,
however.)

AGTNUM processes the .AGT file in two phases. During the first phase,
numbers are assigned to all proper labels encountered. During the second
phase, the output files are created with the numbers in place of the
labels. The .AGT file is not changed by AGTNUM.


LABEL DEFINITIONS

When AGTNUM encounters a label, it must determine what type of item the
label refers to (room, message, flag, etc.). For some labels, the normal
item definition gives this information. Consider this example:

ROOM [sickbay] (* [sickbay] is a ROOM label *)
Sickbay
EXIT [corridor]
END_ROOM

ROOM_DESCR [sickbay]
This is the sickbay, where the regulars are cured of all their ails
and the extras meet slow, painful deaths.
END_ROOM_DESCR

In this case, the word "ROOM" at the beginning of the first line of the
room definition tells AGTNUM that [sickbay] is a label for a room. This is
the label's definition. (All other occurrences of this label will be
references). Labels for nouns, creatures, messages, and questions are
determined in the same way.

Other AGT items, such as flags and variables, have no such definition.
Since a label for one of these items may appear practically anywhere in the
file, AGTNUM requires you to declare the type of item it refers to, to
ensure proper numbering. For this purpose, AGTNUM introduces some special
keywords:

FLAG [label]
COUNTER [label]
VARIABLE [label]

Each of these keywords must be on a line by itself, and may appear anywhere
in the file except in the middle of game text or in a definition such as
ROOM ... END_ROOM. They do not have any effect on the structure of the
game, but simply tell AGTNUM what type of item the label refers to. For
example:

FLAG [flashlight lit]
VARIABLE [energy left]
...
COMMAND ANY
Present [flashlight]
FlagON [flashlight lit]
VariableLT [energy left] 20
PrintMessage [batteries dying]
END_COMMAND

MESSAGE [batteries dying]
Your batteries will last only #VAR[energy left]# more turns.
END_MESSAGE

These keywords cause the labels to be defined with the next available
number for the particular item. For example, if there were already four
other variables defined, AGTNUM would assign the value 5 to the label
[energy left] upon encountering the VARIABLE definition.

More than one label can be defined on a single line, and all text that is
not part of a label is ignored. The following examples are all valid:

COUNTER [torch] (* # of turns torch can burn *)
FLAG [game started] [flashlight on]
VARIABLE [batt life] (energy left); [gold] (how much in player's
pockets)


THE SHORT-CUT MESSAGE FORMAT

AGTNUM provides a short-cut for printing messages from within meta-
commands: simply put the message in quotation marks following the
PrintMessage token; no label is necessary. Consider this example:

COMMAND FIRE PHASER
IsCarrying [phaser]
VariableEquals [phaser shots] 0
PrintMessage [phaser empty]
DoneWithTurn
END_COMMAND

MESSAGE [phaser empty]
The phaser is drained.
END_MESSAGE

The short-cut message format allows the game designer to abbreviate these
related COMMAND and MESSAGE structures to a single COMMAND:

COMMAND FIRE PHASER
IsCarrying [phaser]
VariableEquals [phaser shots] 0
PrintMessage "The phaser is drained."
DoneWithTurn
END_COMMAND

AGTNUM will translate the quoted text following the PrintMessage token into
a message number, and create a corresponding message definition in the .MSG
file. The quotation marks are searched for "from the outside in," so
messages that require quote marks as part of the text are possible:

PrintMessage "This message has "quotation marks" in it."
PrintMessage ""Aye, aye, sir.""

The first and last quotes are removed from the message; all others are left
intact. (If you find these "nested" quotes confusing or undesirable, you
can change the short-cut message delimiter characters, however.)

Multi-line short-cut messages can be written by putting the PrintMessage
token on a line by itself and terminating the message with
END_PrintMessage:

COMMAND ANY
Present [adderzag]
Chance 35
PrintMessage
The adderzag hesitates for a fraction of an eyeblink, then lunges at
you. You try to dodge the horrible mass of evil flying at your heart,
but you slip on the ice and lose your balance. The 'zag crashes into
your chest and you both go sliding across the frozen ground.
END_PrintMessage
...
END_COMMAND

Note that the text of the message is not indented along with the rest of
the meta-command instructions; if it were, the blank spaces at the left
margin would be included in the game. Note also that AGTNUM tells the
difference between single- and multi-line messages by the presence or
absence of text following the PrintMessage keyword.

Multi-line short-cut messages may contain as many lines of text as
necessary, and may freely use quotation marks.

Because a short-cut message can only be used by one meta-command, you will
still need to manually create MESSAGE definitions for messages used by
multiple meta-commands.


AGTNUM DIRECTIVES

Directives are special keywords that allow the game designer to manipulate
the source file in certain ways. They may be thought of as special
commands that are performed before the source file is processed. All
directives have two forms, a single-line form and a multi-line form. Using
the #COMMENT directive as an example, the general forms for AGTNUM
directives are:

#COMMENT This is a single-line comment.

#COMMENT
This is a multi-
line comment.
#END_COMMENT

Multi-line directives are limited to a total of 1023 characters within the
directive (counting each carriage return as one character). Note that
AGTNUM tells the difference between single- and multi-line directives by
the presence or absence of text following the directive keyword.


COMMENTS

The #COMMENT directive may be used to place notes or remarks anywhere in
the source file, even in the middle of game text, so long as the comment
begins and ends on its own line(s). AGTNUM will completely disregard these
comments, and they will not appear in any output files.


TEXT MACROS

A text macro is a special kind of label that can be defined as almost any
text string the game designer chooses. The format of a single-line macro
definition is:

#DEFINE [label] label definition

This causes the label to be defined as all text after the label to the end
of the line (not including the first character after the label, which is
normally a blank). Macros are useful for "constants" used throughout the
game file:

#COMMENT Macros for special "rooms"
#DEFINE [Nowhere] 0
#DEFINE [Carried] 1
#DEFINE [Worn] 1000

#COMMENT Macros for the directions used with ChangePassageway
#DEFINE [North] 1
...
#DEFINE [Exit] 12

It's sometimes handy to use a macro for something you may want to change,
so you don't have to track down every occurrence of the item each time you
change it. For example:

VARIABLE [health]
#DEFINE [max health] 100
#DEFINE [rest delay] 5
#DEFINE [rest benefit] 20
...
COMMAND REST
TimePasses
Delay [rest delay]
PrintMessage "Having rested for a while, you now feel much better."
AddToVariable [health] [rest benefit]
VariableGT [health] [max health]
SetVariableTo [health] [max health]
END_COMMAND

COMMAND REST
DoneWithTurn
END_COMMAND

This allows the game designer to quickly change, say, the maximum health
the player can have, no matter how many times that value is referred to in
the game. Here's another example, adapted from the Colossal Cave
Adventure:

#DEFINE [magic word] XYZZY
...
Dummy_Verb17 [magic word]
...
ROOM_DESCR [debris room]
You are in a debris room filled with stuff washed in from the surface.
A low wide passage with cobbles becomes plugged with mud and debris
here, but an awkward canyon leads upward and west. A note on the wall
says:
Magic Word "[magic word]"
END_ROOM_DESCR
...
COMMAND [magic word]
FlagOFF [cave closed]
AtLocation [debris room]
PrintMessage [transported]
GoToRoom [inside building]
DoneWithTurn
END_COMMAND
...
COMMAND [magic word]
FlagOFF [cave closed]
AtLocation [inside building]
PrintMessage [transported]
GoToRoom [debris room]
DoneWithTurn
END_COMMAND
...
COMMAND [magic word]
PrintMessage "A voice booms out, "That word doesn't work here!""
DoneWithTurn
END_COMMAND

Since macros are not expanded until the second phase of AGTNUM's operation,
they may not include any text which AGTNUM requires during its first phase.
Specifically, macros may not contain any of the following keywords:

ROOM, ROOM_DESCR
NOUN, NOUN_DESCR
CREATURE, CREATURE_DESCR
PUSH_DESCR, PULL_DESCR, TURN_DESCR, PLAY_DESCR
TEXT, MESSAGE, QUESTION
FLAG, COUNTER, VARIABLE
END_keyword
#DEFINE, #INCLUDE, #OPTIONS, #COMMENT, #END_directive

unless, of course, such text is intended as game description rather than
keywords. In other words, if for some strange reason you needed something
like "END_" or "#COMMENT" at the beginning of a line in a text description,
it would be allowable (and necessary) to define such text as a macro.

AGTNUM allows up to 500 macros per adventure game, independent of the
number of other labels in the file.


DYNAMIC MACROS AND RECURSION

Macros are normally "dynamic", meaning that they can include references to
other labels. When a macro is expanded, the resulting text is then scanned
for additional macros and labels. (This can be changed, however.) The
following example takes advantage of this feature:

NOUN [burning torch]
...
END_NOUN

NOUN [unlit torch]
...
END_NOUN

#DEFINE [extinguish] SwapLocations [burning torch] [unlit torch]
...
COMMAND ANY
Present [burning torch]
FlagON [wind blowing]
Chance 10
PrintMessage "The wind blows out your torch."
[extinguish]
END_COMMAND

If a macro refers to itself, either directly or indirectly, then the macro
is said to be recursive. A recursive macro's final value cannot be
determined, because AGTNUM would spend eternity trying to expand the macro,
forever ending up with another macro. For example:

#DEFINE [yoyo] xx[yoyo]xx

AGTNUM will define a macro called [yoyo] with the text "xx[yoyo]xx". When
the macro is expanded, a new macro (also called [yoyo]) is discovered which
must itself be expanded, ad infinitum. Here's another example, using
indirect recursion:

#DEFINE [tweedle dee] [tweedle dum]
#DEFINE [tweedle dum] [tweedle dee]

To detect recursive macros, AGTNUM will consider it an error if more than
30 macro expansions are performed on a single line of the file.


MULTI-LINE MACROS

#DEFINE is slightly different from other AGTNUM directives in that the
multi-line format requires a label on the line following the keyword. If
the #DEFINE keyword is followed by a label and other text, the single-line
format is assumed. If it is followed by a label only, the multi-line
format is assumed. (A #DEFINE keyword all by itself is an error.) Here is
an example of a properly-defined multi-line macro and its use:

#DEFINE [armed]
Present [sword]
OR
Present [axe]
OR
Present [mace]
#END_DEFINE
...
COMMAND BREAK LOCK
[armed]
InRoom [oak door]
...
END_COMMAND

In adventure games where there are multiple items with the same
description, a macro would allow you to keep just one copy of that
description, thus simplifying later editing. Here's an example of how Mark
J. Welch's "Underground Adventure" might use a macro for the six lookalike
bedrooms:

#DEFINE [bedroom description]
This is a small room, apparently a bedroom. Four bunks are mounted on
each of three walls -- it's hard to imagine how twelve people could
share one room!
#END_DEFINE

ROOM_DESCR [bedroom 1]
[bedroom description]
END_ROOM_DESCR
...
ROOM_DESCR [bedroom 6]
[bedroom description]
END_ROOM_DESCR

Since macros are limited to 1023 characters of text, you can get a little
over 121/2 full 80-character lines of text in a single macro. (If your
text description is longer than that, use more than one macro.)


MULTIPLE SOURCE FILES

It is not always possible or convenient to use a single source file for an
adventure game. For example, your game may grow until it is too large for
your text editor to handle. Or you may have a group of macros or meta-
commands that you'd like to use in more than one adventure game. For this
purpose, AGTNUM provides the #INCLUDE directive, which causes another
source file to be read in and processed as if it was part of the main file.
For example, if MYGAME.AGT contains these lines:

ROOM_DESCR [throne room]
#INCLUDE throne.agt
END_DESCR

and THRONE.AGT contains these lines:

You are in a shambled throne room. Rows of stone statues on either
side of the great hall seem to hold a mute vigil, awaiting the return
of their sovereign.

then AGTNUM will process MYGAME.AGT as if it looked like this:

ROOM_DESCR [throne room]
You are in a shambled throne room. Rows of stone statues on either
side of the great hall seem to hold a mute vigil, awaiting the return
of their sovereign.
END_DESCR

For your convenience there is a "standard definitions" file called
STDDEFS.AGT that contains some helpful macros. If your source file
contains the line

#INCLUDE stddefs.agt

then the following macros will be available for your use:

#COMMENT Macros for special "rooms"
#DEFINE [Nowhere] 0
#DEFINE [Carried] 1
#DEFINE [Worn] 1000
#COMMENT Macros for the directions used with ChangePassageway
#DEFINE [North] 1
#DEFINE [South] 2
#DEFINE [East] 3
#DEFINE [West] 4
#DEFINE [NorthEast] 5
#DEFINE [NorthWest] 6
#DEFINE [SouthEast] 7
#DEFINE [SouthWest] 8
#DEFINE [Up] 9
#DEFINE [Down] 10
#DEFINE [Enter] 11
#DEFINE [Exit] 12

Be careful with the names of your include files. It is wise to avoid
giving these files names with extensions of .DAT, .TTL, etc. For example,
don't try anything like this:

#COMMENT mygame.agt
TITLE
#INCLUDE mygame.ttl
END_TITLE

The presence of the TITLE keyword in the .AGT file would cause the .TTL
file to be destroyed, since AGTNUM would try to create the title file
itself.

Included files may include other files, up to a maximum of eight levels
deep.


OTHER AGTNUM KEYWORDS

To identify the text for the game title and instructions, AGTNUM provides
some additional keywords:

TITLE
The game title goes here, in the .TTL file format.
END_TITLE

INSTRUCTIONS
The game instructions go here, in the .INS file format.
END_INSTRUCTIONS

When one of these keywords is found, AGTNUM creates the appropriate file
and writes the description (without the keywords) to the file. If one or
both of these are omitted, AGTNUM will ignore the .TTL and/or .INS file, to
allow the game designer to maintain these files manually if desired.

Macros and other labels may be used in the title and instructions text.


CUSTOMIZING AGTNUM

The game designer can customize AGTNUM's operation through the use of
options. Options are special keywords preceded by one or more prefix
characters, which tell AGTNUM what should be done to the option. The
prefix characters are +, -, /, :, =, and ;. Most options are on-off
switches that enable or disable a certain feature. For these options, the
prefix characters have the following functions:

+ Enable the option, or turn it on.
- Disable the option, or turn it off.
/ Toggle the option. Turn it on if it's off, or off if it's on.
: Save the option. Its current state is recorded.
= Restore the option. Set it to the state it was in the last time
it was saved.
; Print the option. Its current state is displayed on the screen.

Some options are used to specify details about how a certain feature
operates, and these require some additional information (called parameters)
following the option keyword. For these options, the first three prefixes
(+, -, /) all cause the new parameter(s) to be used (though the slash is
preferred). An option can have more than one prefix; see STDDEFS.AGT for
an example of this.

These options are placed in the source file using the #OPTIONS directive.
Any number of options may be given in a single directive, but they must be
separated from the #OPTIONS keyword by one or more spaces. The options may
appear in any order. If conflicting options are given, the later one(s)
will override the earlier one(s). An option may have more than one prefix
character, and the characters are interpreted in order of appearance. For
example, three options

#OPTIONS :Test +Test ;Test

can be abbreviated as one option with three prefixes:

#OPTIONS :+;Test


CASE SENSITIVITY

AGTNUM is normally case insensitive, which means that uppercase and
lowercase letters are treated as identical. For example, the labels
[sickbay] and [SICKBAY] are considered to be the same label. To make
AGTNUM case sensitive, use the +CaseSensitive option.

When AGTNUM is case sensitive, keywords such as ROOM and VARIABLE must be
typed in all capital letters in the .AGT file, or they will not be
recognized.


DELIMITERS AND THE DIRECTIVE CHARACTER

The normal delimiters for labels are the brackets ([ and ]), the delimiters
for short-cut messages are the quote marks ("), and the initial character
for AGTNUM directives is the number sign (#).

To change the label delimiters, specify /LabelDelimiters OC (where O and C
are the new opening and closing delimiter characters). If you leave off
the second character, the first one will be used for both; for example:

#OPTIONS /LabelDelimiters ~

tells AGTNUM that the labels in the game are of the form ~label~. (It
doesn't matter whether there is any space between the keyword and the
characters).

Similarly, the short-cut message delimiters can be changed by specifying
/MessageDelimiters OC. For example:

#OPTIONS /MessageDelimiters `'

says to look for short-cut messages of the form PrintMessage `message'. As
with the /LabelDelimiters option, leaving off the second character causes
the first one to be used for both delimiters.

To change the directive character, specify /KeywordDelimiter C, where C is
the new initial character. For example:

#OPTIONS /KeywordDelimiter !

tells AGTNUM that subsequent directives in the file are spelled as !DEFINE,
!INCLUDE, !OPTIONS, and !COMMENT.


STATIC MACROS

To make macros static, or not dynamic, specify +StaticMacros. Static
macros are not re-scanned for new labels after they are expanded. Making
macros static allows error-free processing of macros such as

#DEFINE [left bracket] [
#DEFINE [legal null] []

but prevents the following definition from working properly:

#DEFINE [extinguish] SwapLocations [burning torch] [unlit torch]


RUNNING OTHER AGT PROGRAMS

After numbering a game, AGTNUM can automatically run the COMPILE and RUN
programs. Specify +Generate to run COMPILE and "generate" the game, or
+Run to run both COMPILE and RUN. COMPILE will not be run if there were
errors in the game file, or if you also specified the +Test option. RUN
will not be run unless COMPILE finished without reporting any errors.

If COMPILE is successful in generating the final game files, AGTNUM then
deletes the game's intermediate (.DAT, .CMD, and .MSG) files.


AGT VERSION SELECTION

There are now two different AGT versions, the regular version and a "big"
version. To cause AGTNUM to write its output files in the big version
format, specify +BigVersion. Specifying -BigVersion will cause AGTNUM to
revert to the regular output format. When +BigVersion is active, using
+Generate and +Run will cause AGTNUM to run COMPILEB and RUNB. (This
option differs from the others in that it cannot be used in an #OPTIONS
directive. It can only be used on the DOS command line or in the
environment variable [see below]).

MISCELLANEOUS OPTIONS

The normal assumed filename extension for game files is .AGT. This
extension is appended to any filename that lacks an extension. To change
the extension, specify /Xtension .EXT, where ".EXT" is the new extension
(be sure to include the period). For example:

#OPTIONS /Xtension .INC

to have the extension ".INC" appended to any include files that lack an
extension.

You can have AGT "test" the file for errors, but not create any files, with
+Test. This could be useful when you are making major revisions to your
game and expect some errors, since it speeds things up a bit.

You can have AGT "document" the output files with +Document. Labels will
be left in the output files as comments whenever they will not interfere
with the game. (This means that labels used in text descriptions will not
be "documented"). This feature can be very useful in debugging your
adventure game, when you need to see exactly what AGTNUM is putting into
the intermediate files.

Warning messages can be disabled with the -Warnings option. This can be
useful when you have, for example, a group of messages that are printed
randomly with the PrintRandomMessage token. Since only the first and last
messages would be referenced, the ones in between would generate "label not
referenced" warnings. Using #OPTIONS :-Warnings before the message group
and #OPTIONS =Warnings after it would suppress the unneeded warnings (see
STDDEFS.AGT).

AGTNUM always reports the number of labels defined for each item in the
game file. If you specify the +Inform option, these reports will include
the number of each item you have left to work with.

You can control how AGTNUM accesses the video display with the /Video
option, followed by a video access keyword (DOS, ANSI, BIOS, or Fast) or an
output-override keyword (Color or Mono). These keywords can be abbreviated
to their first letters, and they have the following meanings:

DOS: Output goes through the DOS "standard output device." DOS
automatically displays all output in the current color or video
attribute.

ANSI: Output goes through the standard output device, along with
"escape sequences" which will result in different colors (or
attributes, if you have a monochrome monitor) if ANSI.SYS is
loaded (or gibberish if it isn't).

BIOS: Output goes through the computer's Basic Input/Output System,
and the program uses BIOS functions to produce color. This is
AGTNUM's default mode of operation.

Fast: Output goes directly to display memory, bypassing DOS and the
BIOS. Multiple colors are used. Fast access should not be used
with Windows or DESQview, or in any situation that requires
programs to be well-behaved.

If you use ANSI, BIOS, or Fast access, AGTNUM tries to automatically
determine whether the monitor is color or monochrome; in most situtations
this autodetection will be sufficient. If you need to specify color or
monochrome output, however, use the Color or Mono keyword (Mono can be
useful if you have a black-and-white monitor being driven by a color video
card.). These keywords will not change the actual access method unless it
is DOS, in which case it will be changed to BIOS. In other words, you can
request ANSI codes and specify monochrome output as follows:

AGTNUM /Video ANSI /Video Mono

This option is different from the other options in two ways: (1) there
must be a space between the /Video option and the subsequent keyword; and
(2) it is valid only in the environment variable (see below).

Note that if you redirect the program's output to a file or "pipe" it into
another program and if the video method is BIOS or Fast, AGTNUM is smart
enought to automatically switch the video method to DOS in order to support
the redirection. (If the video method is ANSI, escape sequences will be
piped or redirected along with the program's output.)


OTHER USES OF AGTNUM OPTIONS

AGTNUM options can be used in several ways. In addition to being used in
an #OPTIONS directive, they can also be specified on the command-line when
AGTNUM is invoked. This allows you to change certain options each time you
run AGTNUM. For example:

AGTNUM MYGAME +Run

will number, compile, and run MYGAME. The options that are normally used
this way are Document, Generate, Run, Test, and Warnings.

Furthermore, options can be used in a DOS "environment variable" to change
the AGTNUM defaults, on a semi-permanent basis. Put a line of the form

SET AGTNUM=options

in your \AUTOEXEC.BAT file and reboot your computer, and AGTNUM will
automatically use the new options. The options that are normally used this
way are BigVersion, CaseSensitive, KeywordDelimiter, LabelDelimiters,
MessageDelimiters, StaticMacros, and Xtension.

Let's say you want to use braces {} for the label delimiters, and you want
to use them for every adventure game you ever write. It would be very
inconvenient to have to specify this each time you use AGTNUM, and almost
as inconvenient to put #OPTIONS /LabelDelimiters {} in every adventure
game. Just put

SET AGTNUM=/LabelDelimiters {}

in your \AUTOEXEC.BAT file and AGTNUM will expect labels to be enclosed in
braces from now on. Options given on the command line override those in
the environment variable, so if you type

AGTNUM MYGAME /LabelDelimiters []

AGTNUM will expect labels to be enclosed in brackets again in MYGAME.AGT.
(Options specified in a game file override environment variable options and
command-line options.) If you later decide to edit your \AUTOEXEC.BAT file
to change the options again, be sure to reboot your computer to put the new
options in place.

You can also use this variable to specify a default filename. If you tend
to work on a single game file at a time, you can include the filename in
the option string and have AGTNUM process that file if no other file is
specified on the command line. For example, if your \AUTOEXEC.BAT file has
the line

SET AGTNUM=MYGAME "/LabelDelimiters <>" +Run

then you can process MYGAME.AGT (looking for labels in angle brackets),
then compile and run the game, by simply entering the command

AGTNUM

Naturally, you can override this default filename by specifying one on the
command line. Note the double quote marks in the previous SET command. To
use the special DOS characters <, >, and | on the command line or in the
environment variable, you must enclose the prefix, keyword, and parameters
in double quotes. To use double quotes as literal characters, you must
precede them with a backslash (e.g., /MessageDelimiters \"). (Don't quote
the special DOS characters or use the backslash with the #OPTIONS method.)

All AGTNUM option keywords can be abbreviated to their first letter. While
this can be very convenient when you use options on the command line, for
the sake of clarity it is recommended that the full keywords be used in
game files and in the environment variable.

See your DOS manual for more details on environment variables, the SET
command, and the DOS meta-characters.


EXAMPLES

Here is a short excerpt from a sample .AGT file:

#COMMENT
AGT "Star Trek" game excerpt -- a simple example showing a few of
AGTNUM's features
#END_COMMENT

FLAG [game started]
VARIABLE [phaser shots] (* remaining phaser energy *)

COMMAND ANY
FlagOFF [game started]
TurnFlagON [game started]
SetVariableTo [phaser shots] 10
END_COMMAND

ROOM [bridge]
Bridge
SOUTH [turbolift]
END_ROOM
ROOM_DESCR [bridge]
You are on the bridge of the Enterprise.
END_ROOM_DESCR

ROOM [turbolift]
Turbolift
NORTH [bridge]
END_ROOM

ROOM_DESCR [turbolift]
You are in the turbolift.
END_ROOM_DESCR

NOUN [phaser]
Phaser
Hand
There is a hand phaser here.
LOCATION [bridge]
CAN_SHOOT
NUM_SHOTS 10 (* not used; we control this with meta-commands *)
SIZE 2
END_NOUN

NOUN_DESCR [phaser]
This is a standard box-shaped Phaser I. While not as powerful as the
pistol-shaped Phaser II, it is considerably more compact and thus
easily concealed.
END_NOUN_DESCR

COMMAND FIRE PHASER
IsCarrying [phaser]
VariableEquals [phaser shots] 0
PrintMessage "The phaser is out of energy."
DoneWithTurn
END_COMMAND

COMMAND FIRE PHASER
AtLocation [bridge]
IsCarrying [phaser]
SubtractFromVariable [phaser shots] 1
RandomMessage [fire phaser #1] [fire phaser #3]
EndGame
END_COMMAND

MESSAGE [fire phaser #1]
You level the phaser at the viewscreen and twist the dial to "KILL".
Fortunately, Spock's telepathic powers sense the sudden insanity
gnawing at your mind, and before you know what's happening you feel
his familiar grip on your shoulder and you crumble to the floor. You
will be relieved of command until McCoy can straighten you out.
END_MESSAGE

#COMMENT Turn off warnings -- this message is not directly referenced
#OPTIONS :-Warnings
MESSAGE [fire phaser #2]
You press the trigger, but nothing happens. For an instant you stare
at the phaser, baffled, puzzling over the acute pain in your thumb.
Then you remember that this is a prototype Scotty has been working on,
designed to foil an enemy who has stolen it. It's been modified to
inject a lethal drug into the hand of the firer if it is used on the
Enterprise.
END_MESSAGE
#COMMENT Return "Warnings" to its previous state
#OPTIONS =Warnings

MESSAGE [fire phaser #3]
You fire the phaser. The bridge wall is ruptured, and the area
rapidly depressurizes. You are killed, along with the rest of the
bridge crew.
END_MESSAGE

Here's the AGT flashlight example, modified to exploit some AGTNUM
features. Notice that it's still very readable, even though many of the
original comments have been deleted.

FLAG [game started], [flashlight lit]
VARIABLE [batt life] will count down the life of the battery

#DEFINE [initial battery charge] 100
#DEFINE [battery warning level] 20

COMMAND ANY
FlagOFF [game started] (* First turn -- initialize Battery life *)
SetVariableTo [batt life] [initial battery charge]
TurnFlagON [game started]
END_COMMAND

COMMAND ANY
FlagON [flashlight lit]
SubtractFromVariable [batt life] 1
END_COMMAND

COMMAND ANY
FlagON [flashlight lit]
Present [on flashlight]
VariableGT [batt life] 0
NOT VariableGT [batt life] [battery warning level]
PrintMessage "Flashlight will last only #VAR[batt life]# more turns!"
#COMMENT display the next message only once
VariableEquals [batt life] [battery warning level]
PrintMessage "You had better save your batteries!"
END_COMMAND

COMMAND ANY
FlagON [flashlight lit]
VariableEquals [batt life] 0
TurnFlagOFF [flashlight lit] (* Turn it off for the last time! *)
SwapLocations [on flashlight] [dead flashlight]
Present [dead flashlight] (* No message unless Flashlight here *)
PrintMessage "The flashlight's batteries are dead!!"
END_COMMAND

COMMAND LIGHT FLASHLIGHT
Present [off flashlight]
TurnFlagON [flashlight lit]
SwapLocations [off flashlight] [on flashlight]
PrintMessage "The flashlight is ON and shining brightly!"
DoneWithTurn
END_COMMAND

COMMAND LIGHT FLASHLIGHT
Present [on flashlight]
PrintMessage "The flashlight is already ON, dummy!"
DoneWithTurn
END_COMMAND

COMMAND LIGHT FLASHLIGHT
Present [dead flashlight]
PrintMessage "Sorry, but the batteries are dead!"
DoneWithTurn
END_COMMAND

COMMAND EXTINGUISH FLASHLIGHT
Present [on flashlight]
TurnFlagOFF [flashlight lit]
SwapLocations [off flashlight] [on flashlight]
PrintMessage "The flashlight is now off!"
DoneWithTurn
END_COMMAND

COMMAND EXTINGUISH FLASHLIGHT
Present [off flashlight]
OR
Present [dead flashlight]
PrintMessage "The flashlight is already OFF!"
DoneWithTurn
END_COMMAND


SUMMARY OF LABEL-DEFINING KEYWORDS

Since a label can be defined only once, it's important to remember which
keywords define labels. Labels are defined by the following AGT keywords

ROOM [label]
NOUN [label]
CREATURE [label]
MESSAGE [label]
QUESTION [label]

and by the following AGTNUM keywords

FLAG [label]
COUNTER [label]
VARIABLE [label]
#DEFINE [label] label definition


SUMMARY OF AGTNUM OPTIONS

+BigVersion Generate output for the big version of AGT.
-BigVersion Generate output for the regular version of
AGT. (Valid only in the environment variable
or on the command line.)

+CaseSensitive Make AGTNUM case sensitive.
-CaseSensitive Make AGTNUM case insensitive.

+Document Document output files--keep labels as
comments.
-Document Remove all labels from the output files.

+Generate Generate the final game files (invoke
COMPILE).
-Generate Do not invoke COMPILE or RUN.

+Inform Report on the number of each item remaining.
-Inform Do not report on remaining items.

/KeywordDelimiter C Make C the new initial character for
directive keywords.
/LabelDelimiters OC Make O and C the new opening and closing
label delimiters.
/MessageDelimiters OC Make O and C the new opening and closing
short-cut message delimiters.

+Run Run the game (invoke COMPILE and RUN).
-Run Do not invoke RUN.

+StaticMacros Make macros static.
-StaticMacros Make macros dynamic.

+Test Test mode: don't create any files.
-Test Create the normal output files.
(Valid only in the environment variable or
on the command line.)

/Video method Write output using method (DOS, ANSI, BIOS,
Color, or Mono).
(Valid only in the environment variable.)

+Warnings Enable warning messages.
-Warnings Disable warning messages.

/Xtension .EXT Make .EXT the new assumed filename extension.

/? Display a help screen.

Options can be abbreviated to their first letter. The +Generate and +Run
options cause the .DAT, .CMD, and .MSG files created by AGTNUM to be
deleted if COMPILE is successful.


AGTNUM ERROR MESSAGES

Errors reported by AGTNUM fall into three categories: warnings, errors,
and fatal errors.

Warnings are conditions which should be noted by the game designer. They
may be indicative of errors, but the file can be processed normally in
spite of them. It is entirely possible for a game file to have warnings
and still operate as the game designer intended.
Errors generally result from mistyped or incorrect labels, and probably
indicate problems that will cause the game to operate incorrectly. AGTNUM
continues to process the file in spite of the errors, for two reasons:

(1) There may be additional warnings and errors in the file, and it's
useful to display as many of them as possible to allow the game
designer to correct more than one problem at a time.

(2) The "error" may in fact be legitimate. For example, the game
designer may wish to have one or more brackets as part of some
game text. AGTNUM would report an undefined or null label, or a
missing closing delimiter, when no error actually existed.

Fatal errors are serious conditions that prevent AGTNUM from continuing,
because of an internal problem, because it's very unlikely the output files
will make it through the COMPILE program, or because AGTNUM cannot try to
guess what the game designer intended and thus doesn't know how to
interpret the rest of the game file.


WARNINGS

Label(s) defined but not referenced

One or more labels were defined but not used elsewhere in the file.
These are sometimes the result of typographical errors, and often will
"match up" with other error messages. For example, if a label is
referred to only once and either the definition or the reference is
mistyped, the definition will be reported under this warning and the
reference will generate an "Undefined label" error.

Option ignored

An option has been found which cannot be implemented during the
program's current phase. /BigVersion must appear in the environment
variable or on the command line, and /Video must appear only in the
environment variable.

Unrecognized video method

An invalid video keyword has been found. Only keywords beginning with
D, A, B, F, C, or M are valid.

No closing m-delim

A PrintMessage token was found followed by the opening message
delimiter, but no closing delimiter was found. This could be an older
style multi-line message that needs to have the opening delimiter
removed, or it could be a single-line message that needs a closing
delimiter. This warning may be promoted to an error in future
versions.


ERRORS

No closing delim

An opening label delimiter was found without a subsequent closing
delimiter. Probably a typo.

Null label

The null label [] was encountered. If you actually need these two
characters in a message, try something like this:

TEXT [sign]
#OPTIONS :/LabelDelimiters {}
The sign says "[][][][] Enter Here [][][][]"
#OPTIONS =LabelDelimiters
END_TEXT

Label not defined

A label is being referred to but has not been defined anywhere in the
file. If the label represents a flag, counter, or variable, you need
a FLAG, COUNTER, or VARIABLE line in the file. This is also often the
result of a typo.

Label redefined

A label definition has been found, and the label is already defined.
This could be a typo, or you could have (for example) both a ROOM and
a NOUN called [fountain]. Change one of the label names.

No #OPTIONS text

An #OPTIONS directive contains no command-line options.

Macro recursion

The limit of 30 macro expansions per line was exceeded, probably
because a macro refers to itself (either directly or indirectly).

No #DEFINE label

A macro contains no label following the a #DEFINE keyword.


FATAL ERRORS

#DEFINE too long, #INCLUDE too long, #OPTIONS too long

There are more than 1023 characters in a multi-line directive.
Shorten the directive or split it into two smaller directives.

Expansion too long

Expansion of a macro would cause the current line to be too long for
AGTNUM to handle. This error can also be caused by macro recursion,
if the maximum line length is exceeded before 30 expansions have been
performed.

Too many ROOMs (NOUNs, CREATUREs, etc.)

Your game file has more of the item in question than AGT allows. You
will probably need to restructure the game.

Too many #DEFINEs

Your game file has more macros than AGTNUM allows. You will need to
convert some of your macros into regular text.

No #INCLUDE file

An #INCLUDE directive contains no filenames.

Too many #INCLUDEs

Your game file has #INCLUDE keywords nested more than eight levels
deep. Make sure there are no recursive inclusions, either direct or
indirect.

#INCLUDE not found

The file specified in an #INCLUDE directive cannot be opened.

Out of memory

AGTNUM has run out of memory while allocating space for labels, or
while trying to define or expand a label. If you are running AGTNUM
in a multi-tasking environment, or with a lot of resident utilities,
you may need to remove some processes or utilities to free additional
memory.

Line too long

A line in the .AGT file is longer than 254 characters.

Disk Full

An error occurred while attempting to write to an output file. The
disk may be full.




  3 Responses to “Category : A Collection of Games for DOS and Windows
Archive   : AGTNUM.ZIP
Filename : AGTNUM.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/