2.1 General AGI Overview by Lance Ewing <be@ihug.co.nz> Last updated: 20 August 1997 What is AGI? AGI stands for Adventure Game Interpreter. It is the old version of Sierra on-lines 3D adventure interpreter. What games used the AGI interpreter? Kings Quest 1-3 Kings Quest 4 (256K version) Space Quest 1, 2 Police Quest Leisure Suit Larry Black Cauldron Mixed Up Mother Goose Gold Rush Manhunter 1, 2 There were also a number of demos that were written in AGI. XMAS animated christmas card KQ4 demo PQ1, THEXDER, HELICOPTER SIMULATOR, SQ2, LSL1, and MUMG one program demo I have been told that a game called Donald Duck's Playground used an early version of AGIv2 as well (v2.001 to be exact). How many versions of the AGI interpreter were there? There were three main version of the AGI interpreter. The first version was the one used with KQ1 and KQ2 when they were originally released. The graphics were in CGA but apart from that the games looked very much like the later EGA remakes. The second version is the one we are most familiar with and was used for the majority of the above games. It added support for the 16 colour EGA card but still kept the old 160x200 resolution that the original games had. The third and final version of the AGI interpreter came out for only a short while before the SCI interpreter hit the scene. There were five games that I know of which used this version. Sierra obvious noticed the increased size of the games and therefore added data compression to this version. There are a few differences in the way the data is stored other than the compression as well, but the data itself still contains exactly the same information. It is therefore possible to convert a version 3 game into the version 2 format and vice versa. What files make up an AGI game and what do these files contain? AGI: This is the main interpreter file. It contains all the routines for the various AGI commands. AGIDATA.OVL: This file contains various bits of data for the AGI interpreter such as interpreter error messages and jump tables for the AGI commands inside the AGI file. SIERRA.COM: This is the loader which loads the interpreter file. In some games this will be combined with the AGI file to give one executable often called SIERRA.EXE or maybe the initials of the game. LOGDIR, VIEWDIR, PICDIR, SNDDIR: These files are basically like an index into the VOL files. They give the location of each of LOGIC, PICTURE, VIEW, and SOUND data within the VOL files. They are therefore called directory files. In version 3 of the interpreter, these files are combined into one file with a header which gives the offset of each part. The name of this single directory file is *DIR where the * is the initials of the game (eg. KQ4DIR, MH2DIR, GRDIR, BCDIR, MH1DIR). VOL.*: These files contain the main game data. Whereas the AGI interpreter may not change between games, the VOL files will always be different. They look very much like a virtual device which contain many individual files whose positions are given by the directory files. In version 3 games, the VOL files are named *VOL where the * is the initials of the game. (eg. KQ4VOL.0, GRVOL.10, MH2VOL.5). WORDS.TOK: This file contains a list of all the words that the user may type in during the game. The words are partly compressed and encrypted as well, so you won't be able to see the words if you display the file as you normally would. OBJECT: This file contains a list of all the inventory items that the user can find in the game. This file is also encrypted but in a different way using the phrase "Avis Durgan". Each object also has associated with it a number that gives the starting room for that object. *.OVL: Apart from the AGIDATA overlay file which was mentioned above, most of these files are the device drivers for the various display adapters that are supported. They are overlay files which are only brought in depending on which display adapter has been selected. IBM_OBJS.OVL and HGC_OBJS.OVL seem to be more to do with the VIEWs (sprites) though. What are the LOGIC, PICTURE, SOUND, and VIEW data files? LOGIC: This data contains the logic scripts that contain the AGI commands which the interpreter runs. All rooms have a single LOGIC script that governs what happens within that room. At the end of a LOGIC file is a text section which contains all the messages that are specific to the functioning of that particular LOGIC script. These are encrypted with the "Avis Durgan" string in the case of version 2 games. PICTURE: These files contain the picture codes which are used to draw the full screen pictures that you see for each room. The codes are vector based and draw a screen in the manner that the artist originally did. There are two screens store in each PICTURE file: the visual screen and the priority screen. The priority screen contains priority bands and control lines. In version 3 games, this file is not compressed with adaptive LZW as the VIEW, LOGIC, and SOUND files are. The format is also slightly different for codes 0xF0 and 0xF2 in order to slighly compress the data. VIEW: These files contain all the still props (like objects), actors (like ogres and labion terror beasts), and animated props (like flags blowing in the breeze). All inventory item pictures are a specialized type of VIEW which has a text description tagged to the end of the file. Views are made up of many loops (animation cycles) that are in turn made up of many cels (a single frame of animation). SOUNDS: These files contain all the musical scores and sound effects which on most machines are one voice over the PC speaker but on some machines, like the PCjr, will be in three voices. What are the AGI commands? The AGI commands are what makes up the AGI programming language if you like. Everyones had a muck around with BASIC which is almost always an interpreted language. Well, the AGI commands are like the BASIC statements in BASIC, or like the procedures and functions in Pascal. In both of these languages there are two types of command, those that return a value and those that don't. AGI is much the same in that it has one group of commands that return boolean values and one group which returns nothing. It also has a small subset of keywords (if, else, not, else, or, and, goto, return) which aren't AGI commands as such. At the last count, there were about 181 procedure type commands and about 18 boolean returning function commands (test commands). We only know the names of 169 of the procedure type commands because this is all Sierra has included in their command list used in debug tracing. Example LOGIC code (from the AGI version of KQ4): animate.obj( smoke); ignore.horizon( smoke); set.view( smoke, v.fish.cabin); set.loop( smoke, 1); ignore.blocks( smoke); position( smoke, 95, 16); work = 3; step.time( smoke, work); cycle.time( smoke, work); draw( smoke); What are the debug modes? Testers often need some way to achieve certain things quickly so that they can test a certain part of the game. Most AGI games still have the debug code that these testers used when the games were being developed. Of the thirteen AGI games mentioned above, there are only three which I havn't discovered the debug mode in. Most of the games activate their debug modes by pushing the ALT-D key combination. The other games used a magic phrase to enter the debug mode. Gold Rush: type "bird man". Kings Quest 3: type "rats ass" (in some versions ALT-D works instead). Police Quest: type "stink bug". Space Quest 2: type "backstage" or "dbg". type "tester" to bring up Rogers screen coordinates. The following are standard debug mode commands: TP Teleport to another room. SHOW PRIORITY Show the current rooms priority bands and control lines. GET OBJECT Get any inventory item. GIMME GIMME Get all inventory items. SHOW FLAG Show one of the 256 flags. SET FLAG Set one of the 256 flags. RESET FLAG Clear one of the 256 flags. SHOW VAR Show one of the 256 variables. SET VAR Change the value of one of the 256 variables. POSITION Change egos position. SHOW POSITION Show egos current screen coordinates. OBJECT NUMBER Gives a list of all the objects and their object numbers. OBJECT ROOM Says which room an object is found in. ROOM Says what room number ego is currently in. SET PRIORITY Set the priority of ego. RELEASE PRIORITY Release the last priority that ego was set to. Of all the AGI games, it is unknown whether MH1, MH2 and Mixed Up Mother Goose have a debug mode or not. MUMG probably doesn't even though its words.tok file has all the debug words contained in it. Manhunter 2 has some kind of debug mode which allows you to teleport and change variable values because there are text messages in the first LOGIC file along these lines. Manhunter:New York probably has the same debug mode. Initially we didn't know whether the AGI version of KQ4 had a debug mode or not but we now know that it does have one and it is activated with the ALT-D key combination as is the common practice. You may be lucky to find a game which allows command tracing. Almost all games have this facility taken out. It is possible to get it to work on some games if you add certain things to the data. What this mode does is to respond to the Scroll-Lock key by displaying a window box which you can step through the test commands that are being executed. - Most keys step forward one test command. - The + key steps to the start of the next LOGIC file. Example: ============================= 0: greatern (17, 0) (0, 0) :F The line of = characters shows the start of an AGI cycle. The number at the start of a line gives the LOGIC number that is currently being executed. In the case above, the (0, 0) is the numeric value of the two parameters above it, i.e. the 17 in the above line refers to variable 17, and the 0 below it is the current value of variable 17. The 'F' and 'T' characters at the end of a line tell us whether the expression evaluated to be false or true. Notice that when you reach the start of LOGIC.0 again, all the controlled VIEW objects on the screen are updated. Using this tracing mode is a good way to get a feel for what happens which each cycle of interpretation. What are the priority bands and control lines? Okay, you've probably all seen those strange screens that you can activate by typing "SHOW PRIORITY" in the debug modes discussed above. Here's an explanation of what this screen is used for. PRIORITY BANDS: The screen has about eleven even sized invisible bands across the screen called priority bands. When ego walks up and down the screen, he or she will move from one priority band into the next priority band. The current priority band that ego is in, along with the priority screen that you see when you type "SHOW PRIORITY", is used to determine which parts of ego to draw and which parts not to draw. This is used to give the affect of ego moving behind trees and rocks etc. Everything on the screen has a priority associated with it which is given by its colour on the priority screen. The higher the priority colour, the more priority it has to be drawn. CONTROL LINES: These are the black, blue, green, and cyan lines that you see drawn on the priority screen. They control what happens to ego when he or she walks past these lines. They might trigger a falling script for the edge of a cliff or a drowning script for the edge of a lake. According to what I've been told, the black control line is a unconditional obstacle, the blue is a conditional obstacle, the green is an alarm line, and the cyan is typically used for water (or something that a VIEW can be confined to being on). The cyan control line will often be a whole filled area. A VIEW object such as a crocodile can be given the object.on.water command and then told to wander. The interpreter will only allow the crocodile to wander over the area that has a control colour of cyan. What is ego? Ego is the name given to the main character (eg. Rosella, Roger, Graham). This seems to be the case in all Sierra games. The AGI games have commands which actually use the name ego in the command itself (eg. follow.ego). The later SCI games retain this name.