View source for AGI Specifications: Chapter 2 - Overview

== 2. 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]]--[[Kings Quest 3|3]], [[King's Quest 4]] (256K version), [[Space Quest 1]] and [[Space Quest 2|2]], [[Police Quest 1]], [[Leisure Suit Larry in the Land of the Lounge Lizards]], [[Black Cauldron]], Mixed Up Mother Goose, [[Gold Rush]] and [[Manhunter 1]] and [[Manhunter 2|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 Pack 1|Sierra Demo Packs 1]]--[[Sierra Demo Pack 4|4]].

=== 2.1 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 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 color 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 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 exactly the same information. It is therefore possible to convert a version 3 game into the version 2 format and vice versa.

=== 2.2 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:

* <code>AGI</code>: This is the main interpreter file in the MS-DOS version. It contains all the routines for the various AGI commands.
* <code>AGIDATA.OVL</code>: 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.
* <code>SIERRA.COM</code> OR <code>AGI.COM</code>: 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.
* <code>*.OVL</code>: Apart from <code>AGIDATA.OVL</code> 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:

* <code>*.sys16</code>: 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).
* <code>sierrastandard</code>: The file containing the sampled instruments and sound effects used in the game.

Platform-independent files:

* <code>LOGDIR, VIEWDIR, PICDIR, SNDDIR</code>: 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 <code>*DIR</code> where the * is the initials of the game (e.g. <code>KQ4DIR, MH2DIR, GRDIR, BCDIR, MH1DIR</code>).
* <code>VOL.*</code>: 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).
* <code>WORDS.TOK</code>: 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.
* <code>OBJECT</code>: 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 &quot;Avis Durgan&quot;. Each OBJECT also has associated with it a number that gives the starting room for that OBJECT.

=== 2.3 LOGIC, PICTURE, SOUND, and VIEW Data Files ===

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 &quot;Avis Durgan&quot; string in the case of version 2 games.

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

=== 2.4 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. <code>follow.ego</code>). The later SCI games retain this name.

=== 2.5 AGI commands ===

The AGI commands are what makes up the AGI programming language if you like. Everyone who's 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):

----

<code>animate.obj (smoke);<br />
ignore.horizon (smoke);<br />
set.view (smoke, v.fish.cabin);<br />
set.loop (smoke, 1);<br />
ignore.blocks (smoke);<br />
position (smoke, 95, 16);<br />
work = 3;<br />
step.time (smoke, work);<br />
cycle.time (smoke, work);<br />
draw (smoke);</code>

----

=== 2.6 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 <code>ALT-D</code> key combination. The other games used a magic phrase to enter the debug mode.

* Gold Rush: type &quot;bird man&quot;.
* King's Quest 3: type &quot;rats ass&quot; (in some versions <code>ALT-D</code> works instead).
* Police Quest: type &quot;stink bug&quot;.
* Space Quest 2: type &quot;backstage&quot; or &quot;dbg&quot; (type &quot;tester&quot; to bring up Rogers screen coordinates).

The following are standard debug mode commands:

* <code>TP:</code> Teleport to another room.
* <code>SHOW PRIORITY:</code> Show the current rooms priority bands and control lines.
* <code>GET OBJECT:</code> Get any inventory item.
* <code>GIMME GIMME:</code> Get all inventory items.
* <code>SHOW FLAG:</code> Show one of the 256 flags.
* <code>SET FLAG:</code> Set one of the 256 flags.
* <code>RESET FLAG:</code> Clear one of the 256 flags.
* <code>SHOW VAR:</code> Show one of the 256 variables.
* <code>SET VAR:</code> Change the value of one of the 256 variables.
* <code>POSITION:</code> Change egos position.
* <code>SHOW POSITION:</code> Show egos current screen coordinates.
* <code>OBJECT NUMBER:</code> Gives a list of all the OBJECTs and their OBJECT numbers.
* <code>OBJECT ROOM:</code> Says which room an OBJECT is found in.
* <code>ROOM:</code> Says what room number ego is currently in.
* <code>SET PRIORITY:</code> Set the priority of ego.
* <code>RELEASE PRIORITY:</code> 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:

<pre>     =============================
     0: greatern (17, 0)
                 (0, 0)         :F</pre>

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.

=== 2.7 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

To maintain and enhance the three dimensional quality of the rooms, every OBJECT is constructed with a priority in relation to other OBJECTs. The priority is shown by its color on the priority screen. The higher the priority color, 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. 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.

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:

<pre>    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
    -------------- ----------</pre>

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. The colors black, blue, green, and cyan are infact used for control lines because the control lines and the priority bands are drawn on the same screen for AGI games, and this means that there would be a clash if we had priority 0 to 3.

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 &quot;drowning&quot; or &quot;falling&quot; 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.
Control lines and priority information

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.

<pre>                                 _
                                |_| <- 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.</pre>

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