Difference between revisions of "AGI/Specifications/Overview"

Jump to navigation Jump to search
m
no edit summary
(First pass at adding the overview page)
 
m
 
(7 intermediate revisions by 4 users not shown)
Line 8: Line 8:
=Versions of the AGI interpreter=
=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 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 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.
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).


<span id="GameFiles"></span>
<span id="GameFiles"></span>
Line 17: Line 26:
==Platform-specific files for the MS-DOS interpreter==
==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.
* '''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.
* '''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.
* '''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.
* '''*.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==
==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).
* '''*.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.
* '''sierrastandard''': The file containing the sampled instruments and sound effects used in the game.


==Platform-independent files==
==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).
* '''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).
* '''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.
* '''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.
* 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 <tt>Avis Durgan</tt>. Each object also has associated with it a number that gives the starting room for that object.




<span id="Logic"></span>
<span id="Logic"></span>
=LOGIC, PICTURE, SOUND, and VIEW data files=
=LOGIC, PICTURE, SOUND, and VIEW data files=
AGI uses four fundamental types of resources: Logic, Picture, View and Sound.


==Logic==
==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.
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 <tt>Avis Durgan</tt> string in the case of version 2 games.


==Picture==
==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.
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==
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).
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==
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.
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.


<span id="Ego"></span>
<span id="Ego"></span>
=What is Ego?=
=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.
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.


<span id="Commands"></span>
<span id="Commands"></span>
Line 62: Line 78:
Example LOGIC code (from the AGI version of KQ4):
Example LOGIC code (from the AGI version of KQ4):


<pre>
<syntaxhighlight lang="C++">
animate.obj (smoke);
animate.obj (smoke);
ignore.horizon (smoke);
ignore.horizon (smoke);
Line 73: Line 89:
cycle.time (smoke, work);
cycle.time (smoke, work);
draw (smoke);
draw (smoke);
</pre>
</syntaxhighlight>


<span id="Debug"></span>
<span id="Debug"></span>
=Debug modes=
=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.
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 <tt>ALT-D</tt> key combination. The other games used a magic phrase to enter the debug mode.


* Gold Rush: type "bird man".
{| border="1"  cellspacing="0" cellpadding="5"
* King's Quest 3: type "rats ass" (in some versions ALT-D works instead).
|-
* Police Quest: type "stink bug".
! Game
* Space Quest 2: type "backstage" or "dbg" (type "tester" to bring up Rogers screen coordinates).
! Command
|-
| Gold Rush
| '''BIRD MAN'''
|-
| King's Quest 3  
| '''RATS ASS''' (in some versions <tt>ALT-D</tt>)
|-
| Police Quest  
| '''STINK BUG'''
|-
| Space Quest 2  
| '''BACKSTAGE''' or '''DBG''' ('''TESTER''' brings up ego position)
|}


The following are standard debug mode commands:
The following are standard debug mode commands:


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


<span id="Priority"></span>
<span id="Priority"></span>
=Priority bands and control lines=
 
=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.
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==
==Priority Data==


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 colour on the priority screen. The higher the priority colour, the more priority it has to be drawn.
{| border=0 align=center
|[[Image:Agispec-visible_screen.png|320px|left|frame|AGI visible screen]]
|[[Image:Agispec-priority_screen.png|320px|left|frame|AGI priority screen]]
|}


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.
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.
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.
Line 153: Line 196:
</pre>
</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 colours 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.
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.
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.
Line 171: Line 219:
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.
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 colour of cyan.
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==


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


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.


<pre>
                                 _
                                 _
                                 |_| <- priority required for this pixel.
                                 |_| <- priority required for this pixel.
Line 186: Line 235:
                                 |_| /
                                 |_| /
                                 |_| <- use this pixels priority.
                                 |_| <- 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.
It may be possible to draw the control lines on a separate screen altogether which would conserve the priority information.
86

edits

Navigation menu