CD PowerPlay 6

home *** CD-ROM | disk | FTP | other *** search

/ CD PowerPlay 6 / TheCompleteAdventureCollection1995 / CDPP6.ISO / utility / agtm1 / agtlabel / agtlabel.doc next >

Wrap

Text File | 1992-01-03 | 23.1 KB | 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 __________________________________________