General AGI overview

Written by Lance Ewing, with additions/modifications by Claudio Matsuoka (Last update: 22 May 1999).

AGI stands for Adventure Game Interpreter and it is the old version of Sierra On-Line's 3D adventure interpreter. It was used in Donald Duck's Playground, Kings Quest 1--3, King's Quest 4 (256K version), Space Quest 1 and 2, Police Quest, Leisure Suit Larry in the Land of the Lounge Lizards, Black Cauldron, Mixed Up Mother Goose, Gold Rush and Manhunter 1 and 2. There were also a number of demos that were written in AGI: the XMAS animated christmas card, King's Quest 4 demo, and Sierra demo packs 1--4.

Versions of the AGI interpreter

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 second version is the one we are most familiar with and was used for the majority of the above games. The third and final version of the AGI interpreter came out for only a short while before the SCI interpreter hit the scene. Sierra obviously 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 the same information).

AGI game files

An AGI game package contains the AGI game resource files, usually platform-idependent, and the platform-specific interpreter binaries. The MS-DOS version is the most popular and best known AGI interpreter; there are, however, versions for the Macintosh, Atari, Amiga, Apple IIgs and Tandy computers.

Platform-specific files for the MS-DOS interpreter

agi: This is the main interpreter file in the MS-DOS version. It contains all the routines for the various AGI commands.
agidata.ovl: In MS-DOS, this overlay file contains various bits of data for the AGI such as interpreter error messages and jump tables for the AGI commands inside the AGI file.
sierra.com: In MS-DOS, 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 the initials of the game.
*.ovl: Apart from agidata.ovl 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.

Platform-specific files for the Apple IIgs interpreter

*.sys16: The AGI interpreter in the Apple IIgs version. The name of the executable is the initial of the game (e.g. kq.sys16 for King's Quest).
sierrastandard: The file containing the sampled instruments and sound effects used in the game.

Platform-independent files

logdir, viewdir, picdir, snddir: These directory files give the location of each of LOGIC, PICTURE, VIEW, and SOUND data within the VOL 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 (e.g. 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 indexed by the directory files. In version 3 games, the VOL files are named *VOL where the * is the initials of the game (e.g. 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.

LOGIC, PICTURE, SOUND, and VIEW data files

AGI uses four fundamental types of resources: Logic, Picture, View and Sound.

Logic

LOGIC resources contain 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

PICTURE resources 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

VIEW resources 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).

Sound

SOUND resources 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. The IIgs version of the interpreter recognize PCM sampled sound effects and 16 channel wavetable-based MIDI music.

Other Resources

Besides the four main resource types, there are OBJECT resources, that hold information about inventory items and other objects, and WORD resources, containing the dictionary on known words.

What is Ego?

Ego is the name given to the player character (e.g. Rosella, Roger, Graham). The AGI games have commands which actually use the name ego in the command itself (e.g. follow.ego). The later SCI games retain this name.

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);

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 haven'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.

Game	Command
Gold Rush	BIRD MAN
King's Quest 3	RATS ASS (in some versions `ALT-D`)
Police Quest	STINK BUG
Space Quest 2	BACKSTAGE or DBG (TESTER brings up ego position)

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.

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. In this case most keys step forward one test command, and 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 or 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.

The priority screen

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 Data

AGI visible screen

AGI priority screen

To create a three dimensional sensation in the rooms, every object is constructed with a priority in relation to other objects. The higher the priority value, the more priority it has to be drawn.

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. This is used to give the affect of ego moving behind objects or scenario elements. AGI visible screen picture shows a scene of King's Quest 4, and AGI priority screen picture shows its priority data.

Although the priority bands are invisible in the finished product, the artist must use them like a horizontal grid as he draws the room. Considerable effort and time is spent placing houses, bushes, and trees so the player remains unaware of the rooms mathematical rigidity. It wouldn't so for things to look like they were lined up on a checker board.

In AGI games, the priority bands lie roughly in the following y ranges:

    Priority Band   Y range
    -------------- ----------
          4             -
          5          48 - 59
          6          60 - 71
          7          72 - 83
          8          84 - 95
          9          96 - 107
         10         108 - 119
         11         120 - 131
         12         132 - 143
         13         144 - 155
         14         156 - 167
         15            168
    -------------- ----------

The reason that there is no priority 0 to 3 shown above is because they don't exist. Priority four has the least priority. It is given to the background components. Nothing is ever given a priority of four except for the background parts of the picture itself. Values 0 to 3 (represented by colors black, blue, green, and cyan) are infact used for control lines drawn in the priority screen.

I've checked all the AGI games including those using version 3 and it looks as if nothing is ever drawn below 168. Some objects in the picture might have a priority of 15. These objects will start from a position with a Y component of 168. Ego can never walk below 167 and thus never has a priority of 15. SCI games are obviously a bit different because they extend the pictures down to the full 200 pixels.

Control lines

As the room nears completion, the artist adds control lines that determine where Ego can walk. Ego shouldn't walk through a wall or tree, for example, but sometimes Ego does. The Sierra staff spend a lot of time running Ego all over the rooms looking for places where Ego falls off or walks through something Ego shouldn't. Fixing an error may involve shifting things around or adding new features to a room to cover up a bug. I remember finding a bug in Space Quest 2 which allowed Roger to walk off into space in the starting room.

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. There are four types of control lines:

the black control line is a unconditional obstacle;
the blue is a conditional obstacle;
the green is an alarm line;
the cyan is typically used for water (or something that a VIEW can be confined to being on).

In most games, black and blue appear to be used for obstacle use which means that Ego can't walk past that line. This is the main use for control lines. Other uses include triggers which active an event. For example, control lines are used at the edge of water, or the edge of a cliff to tell the interpreter at what point it should execute its "drowning" or "falling" sequence of events. We can all remember the nasty trap that the hunter beast on Labion set for us in Space Quest II. This is activated when Ego walks past a green control line.

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 color of cyan.

Priority behind control lines

In the AGI interpreter, the priority bands and control lines are drawn on the same screen. This can lead to problems when the interpreter wants to know the priority of a pixel that has a control line drawn over it. The way that the interpreter deals with this is to search downwards until it finds a pixel that isn't a control line and it assumes that the pixel it is looking at is the same priority as the one it found by searching downwards (increasing Y). Usually this will be the pixel immediately below but for some pixels this can be as far away as twenty pixels or more! In some games this can cause a noticeable visual error if you are aware of it. For example, you could walk behind a strip of grass that thinks it is part of the tree below it (KQ1, room 20, blue control line beside left hand tree). There are also a number of other one pixel visual errors that are virtually unnoticeable if you don't know they are there.

An important point to note is that cyan pixels, which normally indicate a "water" condition, should not be skipped over during this process; only pixel values 0, 1 and 2 are skipped over. Room 6 of KQ3 (the kitchen) is a prime example: the majority of the floor is cyan on the priority screen, and should appear behind the ego.

                                _
                               |_| <- priority required for this pixel.
         Search downwards  |   |_| \
         for next pixel    |   |_|  \___ These pixels have all got a control
         with a priority  \|/  |_|  /    line covering their priority info.
                               |_| /
                               |_| <- use this pixels priority.

It may be possible to draw the control lines on a separate screen altogether which would conserve the priority information.

AGI/Specifications/Overview

Contents