Fatal Distractions!/fataldistractions.bin/appndxa/masters/agtlabel.doc

Text File | 1992-01-03 | 24KB | 610 lines

                                    AGTLABEL                                    AGTLABEL

                   The Adventure Game Toolkit Label Generator                   The Adventure Game Toolkit Label Generator
                           Version 1.02; July 12, 1991

                                by Bill Martinson

   The Adventure Game Toolkit Label Generator (AGTLABEL), including all source
   code, object code, and manuals on paper or on disk, is Copyright 1991 by
   Bill Martinson Software.  AGTLABEL is distributed by Softworks.

   AGTLABEL is provided to registered 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 also to AGTLABEL.EXE.


   INTRODUCTION

   AGTLABEL is a companion program for AGTNUM.  It takes an adventure game in
   standard AGT format (with or without AGTIF commands) and converts it to
   AGTNUM format, by generating AGTNUM-style labels for as many numbers as
   possible.  In fact, you might say that AGTLABEL does just the opposite of
   what AGTNUM does.

   This document uses terminology defined in the documentation for AGTNUM, and
   assumes a certain level of familiarity with both AGT and AGTNUM.


   OVERVIEW

   The primary job of AGTLABEL is to convert existing AGT games to AGTNUM
   format.  It is not intended to become a regular part of your game
   development cycle, but rather to be a one-time tool that constructs labels
   for an existing AGT game.  Once you have run AGTLABEL on an adventure game,
   you can put it (and your old source files) on the shelf; the resultant .AGT
   file will be your new original source file.

   The usual sequence goes like this:

        A.   Make backup copies of your original AGT files (.DAT, .CMD, .MSG,
             .TTL, and .INS), just in case.

        B.   Use AGTLABEL to create a single .AGT source file from those
             files.

        C.   Examine the new file carefully to ensure that the conversion was
             successful.

        D.   Archive the old AGT files and use the new file in conjunction
             with AGTNUM for all subsequent game modifications.

   For example, the following series of DOS commands could be used to convert
   the  Colossal Cave  adventure:

        COPY CAVE.* C:\BACKUP               (back up CAVE.DAT, CAVE.CMD, etc.)
        AGTLABEL CAVE                                        (create CAVE.AGT)
        EDIT CAVE.AGT                                  (verify the conversion)
        AGTNUM CAVE      (recreate CAVE.DAT, CAVE.CMD, etc. this clobbers your
                 old original files so be sure you really made those backups!)
        COMPILE CAVE                       (generate the final adventure game)

   AGTLABEL also has two other potential uses:  First, it can be used as a
   final quality check on a completed game.  Carefully back up your .AGT file
   and run AGTLABEL on the intermediate files using the +Test option.  This
   can identify some (but not all) errors such as using a room label where a
   noun number is expected, not having enough numeric parameters for a meta-
   command token, or forgetting the final number sign (#) on a reference such
   as #VAR9#.

   Second, if something horrible should happen to your original .AGT file,
   AGTLABEL can help you reconstruct it from the intermediate files.  (Don't
   try this little exercise on purpose, though, because the conversion isn't
   perfect.  AGTLABEL cannot create macros, enumerations, or short-cut
   messages, and it can't always tell whether a number should be converted to
   a label or not.)


   LABELS

   AGTLABEL automatically generates labels for all room, noun, creature,
   message, question, flag, counter, and variable references.  The following
   describes the various methods used to generate labels.

   ROOM labels are created using the first five words of description line,
   e.g.,

    ROOM 17                            ROOM [Witt's End]
    Witt's End                         Witt's End
    END_ROOM                           END_ROOM

    ROOM 18                            ROOM [At a fork in the]
    At a fork in the brick road        At a fork in the brick road
    END_ROOM                           END_ROOM

   NOUN and CREATURE labels are created by combining the adjective with the
   noun's or creature's name , e.g.,

    NOUN 235                           NOUN [red wand]
    wand                               wand
    red                                red
    There's a red wand here.           There's a red wand here.

    CREATURE 316                       CREATURE [BIG BEAR]
    BEAR                               BEAR
    BIG                                BIG
    There's a big bear here.           There's a big bear here.

   MESSAGE labels are created using the first five (non-blank) words of the
   message, e.g.,

    MESSAGE 109                         MESSAGE [the wolf doesn't want your]
    The wolf doesn't want your dumb     The wolf doesn't want your dumb
    old sandwich.                       dumb old sandwich.
    END_MESSAGE                         END_MESSAGE

    MESSAGE 110                         MESSAGE [DO NOT ENTER!]

        DO NOT ENTER!                       DO NOT ENTER!

    END_MESSAGE                         END_MESSAGE

   QUESTION labels are created using the first five words of the question,
    e.g.,

    QUESTION 5 How is a pig made blue?  QUESTION [How is a pig made] How is...

    QUESTION 6 Who are you?             QUESTION [Who are you?] Who are you?

   FLAG, COUNTER and VARIABLE labels are all created using the item name plus
   the item number, e.g.,

    TurnFlagON 7                        TurnFlagON [Flag 7]

    It was on for #CTR5# turns.         It was on for #CTR[Counter 5]# turns.

    VariableLT 22 150                   VariableLT [Variable 22] 150

   In addition, AGTLABEL makes use of the predefined labels found in
   STDDEFS.AGT:

        [Nowhere]      [Carried]       [Worn]
        [Nothing]      [Any Light]
        [Debug]
        [North]        [South]         [East]        [West]
        [NorthEast]    [NorthWest]     [SouthEast]   [SouthWest]
        [Up]           [Down]          [Enter]       [Exit]

   Before a generated label is used, AGTLABEL may modify it in a couple of
   ways:

        (1)  If the label includes any opening or closing label delimiters as
             part of the text, those characters are changed to blanks.

        (2)  If the label is identical to a previously generated label, the
             code  (B)  is appended to the new label.  If there is also a B
             label already in existence, the new label is  bumped  up to C,
             and so on.  After Z, a label is bumped to AA, then AB, etc.

   The following presents some examples of these label modifications.


         Original File                   Output File

         ROOM 93                         ROOM [The End of the  Second tunnel]
         The End of the [Second] Tunnel  The End of the [Second] Tunnel
         END_ROOM                        END_ROOM

         ROOM 101                        ROOM [Twisty Little Passage]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM

         ROOM 102                        ROOM [Twisty Little Passage (B)]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM

         ROOM 103                        ROOM [Twisty Little Passage (C)]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM

         ...                           ...

         ROOM 126                        ROOM [Twisty Little Passage (Z)]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM

         ROOM 127                        ROOM [Twisty Little Passage (AA)]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM

         ROOM 128                        ROOM [Twisty Little Passage (AB)]
         Twisty Little Passage           Twisty Little Passage
         END_ROOM                        END_ROOM


   For each flag, counter, and variable label generated, AGTLABEL will write a
   definition line at the end of the .AGT file (see the next section).


   STRUCTURE OF THE .AGT FILE

   The .AGT file produced by AGTLABEL will have the following kind of
   structure:

         TITLE
         The Arachnoid Adventure
         By Ernie Eightlegs
         END_TITLE

         INSTRUCTIONS
         Here's whatcha do ta play...
         END_INSTRUCTIONS

         #INCLUDE stddefs.agt

         ROOM [The dark hallway]
          ...
         ROOM_DESCR [The dark hallway]
          ...
         HELP [The dark hallway]
          ...
         SPECIAL [The dark hallway]
          ...

         NOUN [dusty book]
          ...
         NOUN_DESCR [dusty book]
          ...
         TEXT [dusty book]
          ...
         TURN_DESCR [dusty book]
          ...

         CREATURE [ugly troll]
          ...
         CREATURE_DESCR [ugly troll]
          ...

         COMMAND EAT TROLL
         Present [ugly troll]
         FlagOn [Flag 7]
         PrintMessage [You fish out your fork]
         DoneWithTurn
         END_COMMAND

          ...

         MESSAGE [You fish out your fork]
         You fish out your fork from your knapsack and go to work on the
         troll's leathery hide.  You've never tasted a moldy sailor's shoe
         that's been soaking in the fish barrel, but you imagine that this is
         what it would probably taste like.
         END_MESSAGE

          ...

         FLAG [Flag 7]
         COUNTER [Counter 5]
         VARIABLE [Variable 22]


   DEFINING YOUR OWN LABELS USING THE .OVR FILE

   If you don't like the labels AGTLABEL creates, you can make an  override
   file  that overrides some or all of them.  Just supply a file with the same
   name as your game and an extension of .OVR, and fill it with lines like
   these:

        ROOM 2 grassy knoll
        NOUN 232 phony plover egg
        NOUN 250 magic dust
        FLAG 1 player hungry
        COUNTER 7 torch activity left
        VARIABLE 18 gold coins in pouch

   (Don't use any label delimiters in this file.)  Since AGTLABEL normally
   produces flag, counter, and variable labels that are totally
   nondescriptive, this is a good way to make better labels for those items.


   CUSTOMIZING AGTLABEL

   AGTLABEL uses many of the same options as AGTNUM.  They can be used in the
   environment variable or on the command line, but because AGTLABEL has no
   #OPTIONS directive they cannot be placed in the game files.  The following
   AGTNUM options are available in AGTLABEL:

        Audit                                   (this option is on by default)
        BigVersion
        CaseSensitive
        KeywordDelimiter  (used only to write the  #INCLUDE stddefs.agt  line)
        LabelDelimiters
        MessageDelimiters            (this option is not used in version 1.02)
        Test
        UserVersion
        Video
        Warnings
        Xtension

   In addition, there is an +Overwrite option that causes AGTLABEL to
   overwrite the .AGT file (if it already exists) without asking you for
   confirmation.


   THINGS TO WATCH FOR

   AGTLABEL is not perfect it can be fooled.  It performs relatively simple
   pattern-matching in order to correlate labels and numbers.  For example, if
   the number 5 appears in a game file, it might refer to a room, a message, a
   question, a flag, a counter, a variable, or a ChangePassageway direction or
   to none of these.  AGTLABEL decides what the 5 represents by examining the
   first word on the line.  If the word is  ROOM , then this must be room
   five.  If it's  VariableLT , then the 5 must be a variable reference, and
   so on.

   This strategy works well most of the time, but there are some situations in
   which it breaks down.  This is why it is very important to carefully
   inspect the resulting game file after running AGTLABEL.  A few examples of
   the kinds of things that need to be manually corrected are listed below.

   Variables Set To Item Numbers

   Consider this example:

        SetVariableTo 4 106             (* set variable 4 to the silly room *)
        GoToVariableRoom 4                          (* go to the silly room *)

   AGTLABEL can figure out that the 4 represents a variable that's no problem.
   However, there's no simple way for it to know that the 106 should be
   interpreted as a room.  Variables are general-purpose beasts, and the 106
   might just as easily be 106 pieces of gold going into a pouch or 106 turns
   of torch flammability remaining, or even message number 106:

        SetVariableTo 4 106
        PrintVariableMessage 4

   It is advisable to use your text editor to search for all occurrences of
   Variable in the output file, watching for numbers that should really be
   labels.

   References to Nonexistent Items

   It is perfectly legal for a meta-command token to reference a non-existent
   room, but since there is no ROOM definition, AGTLABEL does not define a
   label for that number.  To make your game as bullet-proof as possible, you
   should rewrite any meta-commands that reference phantom items.

   This usually happens with the meta-command tokens AtLocationGT and
   AtLocationLT.  For example, let's suppose your game has a swamp composed of
   five  rooms :

        ROOM 27 (* East End of Swamp *)
        ROOM 28 (* Eastern Swamp *)
        ROOM 29 (* Middle of Swamp *)
        ROOM 30 (* Western Swamp *)
        ROOM 31 (* West End of Swamp *)

   And you've been testing whether the player is in the swamp like this:

        AtLocationGT 26
        AtLocationLT 32

   This worked fine before you wanted to use AGTNUM, but now there's no way to
   guarantee that the east end of the swamp is going to end up as room 27.
   And even if rooms 26 and 32 happen to be real rooms with real labels you
   can use, what happens if you later insert a new room after room 26?

   Ideally, we would like the conditional tests to reference only rooms that
   are actually part of the swamp.  Instead of asking whether the player is
   between rooms 26 and 32, exclusive, it would be nice if we could ask
   whether he or she is between rooms 27 and 31, inclusive.  Unfortunately,                                                 _________
   AGT does not have an explicit  at this location or greater  token, but
   there is a way to produce the same result:

        NOT AtLocationLT 27
        NOT AtLocationGT 31

   Since this  backwards logic  can tend to make us have to think too hard
   about what the meta-command test is really asking, it's handy to use macros
   to create a couple of new conditional tokens:

        #COMMENT at location Greater than or Equal to, Less than or Equal to
        #DEFINE [AtLocationGE] NOT AtLocationLT
        #DEFINE [AtLocationLE] NOT AtLocationGT

   and then just do this:

        [AtLocationGE] [East End of Swamp]
        [AtLocationLE] [West End of Swamp]

   Resequencing Problems

   The rooms in an AGT-format game can appear in basically any order.  That
   is, you can describe room 183, then room 2, then room 77 if you like.  This
   presents a couple of problems.

   The first one is simple:  Unless your game includes a STARTING_ROOM
   designation, whatever room is listed first will ultimately become the new
   room 2 and therefore the starting room.  For example, assume these are the
   first two rooms described in the .DAT file:

        ROOM 51
        Hall of Mists
        END_ROOM

        ROOM 2
        Grassy Knoll
        END_ROOM

   AGTLABEL will convert those definitions to these:

        ROOM [Hall of Mists]
        Hall of Mists
        END_ROOM

        ROOM [Grassy Knoll]
        Grassy Knoll
        END_ROOM

   and AGTNUM will convert them to these:

        ROOM 2
        Hall of Mists
        END_ROOM

        ROOM 3
        Grassy Knoll
        END_ROOM

   and the Hall of Mists will become the new starting room.  This problem is a
   simple one because it is easily solved like this:

        STARTING_ROOM [Grassy Knoll]

   The second problem is more subtle, and more time-consuming to correct.
   Suppose you have a command like this:

        COMMAND ANY
        IsCarrying [mysterious powder]
        Chance 5
        PrintMessage [Suddenly you sneeze and everything]
        GoToRandomRoom [mop closet] [grimy bathtub]
        DoneWithTurn
        END_COMMAND

   If all of the rooms from [mop closet] to [grimy bathtub] appear in the
   proper sequence, everything is fine.  But if they are out of sequence, or
   if there are other rooms described between them, the outcome of this meta-
   command will be changed because other (unrelated) rooms will now be
   included in the range of rooms for the GoToRandomRoom token.  The same
   thing can happen with the PrintRandomMessage token.

   As a general rule of thumb, you should use your text editor to search for
   each occurrence of the word  random  (without case sensitivity) and verify
   that things are as they should be.  Print out the audit file (.AUD) and
   make sure that all of the items from the first one to the last do indeed
   belong to the sequence, and that they are all accounted for.

   Always remember that all of your game elements are going to be renumbered
   based on their order of appearance.  One way to avoid these problems is to
   make sure that your game elements are properly sequenced before running
   AGTLABEL.

    Special  Descriptions

   AGTLABEL knows that some tokens signal the beginning of a block of game
   text, while others do not.  This is important because game text is
   processed differently from other text.  For example, the word  room
   normally must be followed by a valid room number; if it isn't, AGTLABEL
   reports a  Number expected  error.  However, if a textual description just
   happens to have the word  room  at the beginning of a line, such an error
   message is inappropriate.  Therefore, when AGTLABEL encounters a token like
    ROOM_DESCR,   MESSAGE,  or  HELP,  it suspends the usual conversion of
   numbers to labels until a line beginning with  END_  is encountered, and
   instead tries to convert references like #CTR5# and #VAR12#.

   This works very well, except for specials.  The word  SPECIAL  is used both
   as a stand-alone token and as a text block initiator but AGTLABEL must
   pretend it isn't an initiator.  Consider this example:

        ROOM [Bathroom]
        Bathroom
        SPECIAL [A Violent Flood]
        KEY [leaky faucet]
        NORTH [Bedroom]
        END_ROOM

   If  SPECIAL  was treated as a text block initiator, the KEY and NORTH lines
   would be considered game text and would never be labeled.  Therefore,
   SPECIAL is treated as a self-contained, one-line token.  This means, of
   course, that any text in a SPECIAL description is fair game for regular
   conversion instead of Variable/Counter conversion.  So things like the word
    room  at the beginning of a line yield false error messages, and things
   like #VAR21# don't get converted to labels as they should.  Be sure to
   check out all of your specials very carefully (and use the audit file to             ___
   help you manually convert any variable/counter references).


   ERROR MESSAGES

   Warnings

   Option ignored

        An option was found which cannot be implemented during the program's
        current phase.

   Unrecognized option

        An option was found which does not begin with a recognized key letter.
        Probably a typo.

   Unrecognized video method

        An invalid video access keyword or output override keyword was found.
        Only keywords beginning with D, A, B, F, C, or M are valid.


   Errors

   Undefined number

        A number was found and AGTLABEL would really like to convert it, but
        no label was defined for it.  This is often a reference to a
        nonexistent room, noun, creature, etc.

   Number redefined

        A definable number was found, but a label was already defined for that
        number.  For example, you might have two NOUN 135s or two CREATURE
        301s.

   Number expected

        Non-numeric text was found following a keyword that is normally
        followed by one or more numbers.

   ROOM # expected (NOUN, CREATURE, etc.)

        An inappropriate number was found following a keyword (for example, a
        noun number where a creature number was expected).

   Item # expected

        A number that does not represent a room, noun, or creature was found
        following a keyword that requires such a number (for example, a number
        larger than the highest creature number).

   '#' expected

        An apparent textual reference to a counter or variable was not
        immediately followed by a closing number sign (for example,  it has
        been #CTR2 turns  or  you have #VAR11 # arrows ).


   Fatal Errors

   Line too long

        A line was found that was longer than 254 characters.  Split it into
        two or more lines.

   Disk full

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

   No user data file

        The +UserVersion option was selected, but the required AGTLABEL.USR
        file was not found in the current directory.

   Out of memory

        AGTLABEL ran out of memory while allocating space for labels, or while
        trying to generate a label.  If you are using a shell or multi-tasking
        environment, or any memory-resident utilities (TSRs), you will need to
        remove some processes or utilities to free up additional memory.  If
        that doesn't work, try the +UserVersion option with the following
        AGTLABEL.USR file:

           ;  agtlabel.usr -- last-ditch effort to conserve memory
           ;  omitted parameters (VARIABLE, QUESTION, etc.) will be unaffected
           ROOM        2  149              (* reduce ROOMs allowed by  50 *)
           NOUN      200  249              (* reduce NOUNs allowed by  50 *)
           CREATURE  300  349          (* reduce CREATUREs allowed by  50 *)
           MESSAGE     1  200           (* reduce MESSAGEs allowed by  50 *)
           FLAG        1   55              (* reduce FLAGs allowed by 200 *)

        This configuration will free up 400 labels' worth of memory.  You can
        adjust the numbers of ROOMs, NOUNs, etc. to suit the sizes of your
        game files.















   The Adventure Game Toolkit Label Generator                               13   __________________________________________