AGI Docs - Data Used by AGI

Tutorials and Guides Table of Contents

Data used by AGI
By Peter Kelly

 
Resources

Most data used by AGI is stored in resources. There are four types of resources, each storing a different type of data. Each AGI game can contain up to 256 resources of each type.

[../IDEs/AGIStudioOverview.html View resources] - animations and sprites
[data.html#picture Picture resources] - background pictures
[../IDEs/AGIStudioHistory.html Sound resources] - sound effects and music
[data.html#logic Logic resources] - scripts that determine what happens in the game

 

Other data

[data.html#object The OBJECT file] - list of inventory objects the player can get
[data.html#words The WORDS.TOK file] - list of words accepted by the game

[data.html#files Files used by AGI]

 

View resources

View resources contain some of the graphics for the game. Unlike the picture resources which are full-screen background images, view resources are smaller 'sprites' used in the game, such as animations. They are also stored as bitmaps, whereas pictures are stored in vector format.

Each view resource consists of one or more "loops". Each loop in the resource consists of one or more "cels" (frames). Thus several animations can be stored in one view, or a view can just be used for a single image. The maximum number of loops supported by the interpreter is 255 (0-254) and the maximum number of cels in each is loop 255 (0-254).

Views have a number of useful features:

Transparency: Each cel has a transparent color. When the view is shown on the screen, pixels of this color will show to the background.

Mirroring: You can set one loop to be a "mirror" of another, which means that all the cels in that loop will be mirror images of the corresponding cels in the other loop. This is handy if you have drawn an animation of a character walking right, and also want to have an animation of it walking left - you only have to do half the work (and the view takes up less memory).

Description: This is used when a view is a picture of an inventory item. When the view is displayed using the show.obj command (i.e. when the player "examines" an object), the first cel of the first loop is displayed on screen along with the description.

 

Picture resources

Picture resources are full-screen images, usually used for backgrounds. They are vector-based rather than bitmaps, which means they are drawn using drawing commands such as lines and brushes, rather than by plotting pixels.

Each picture has two images (screens) - the visual screen and the priority screen. The visual screen is what the player sees when playing the game. Views are placed on top of the pictures during the game and can be moved around the screen. The priority screen is what makes the game appear to be 3-dimensional. On the AGI screen, there are 12 priority bands in which objects can be placed. The priority given to different parts of the picture (i.e. the color of the pixels on the priority screen) determines where in 3-dimensional space objects appear. For example, a tree placed right at the front of the screen would be given a priority of 15 (the highest priority). A wall which is far away in the background would be given a priority of 4 (the lowest priority). If an object with a priority of 12 is displayed on the screen, it would be behind the tree but in front of the wall. The priority of a view is usually determined by its y-position.

Colors 0, 1, 2 and 3 on the priority screen are used for "control lines" which determine where the ego (the object controlled by the player) can walk.

 

Sound resources

Sound resources contain all the sound effects and music used in a game. They consist of three musical voices plus one sound effect voice. The format is based on the sound capabilities of the IBM PC Junior, for which the interpreter was originally written. On standard PCs only the first music voice is played, because the only sound device available to the PC at the time was the internal speaker. There is no sound card support in the original PC version of the interpreter, but hopefully any new interpreters that are written will support this.

Other systems such as Macintosh and Amiga supported the other voices as well.

 

Logic resources

Logic resources are the "guts" of an AGI game. They are scripts that contain all the commands necessary to control the view, picture and sound resources and to receive and act on input from the player, thus determining everything that happens in the game. Each room generally has its own logic which controls what happens in that room, and the game also has a few other logics to look after things like initialization and error handling.

Games are programmed in a special language specific to AGI and compiled into logic resources. The logic programming language is similar to standard programming languages like C, but a lot less powerful as it is designed for specific purpose. For more information on logic programming, see the AGI Specs documentation. Logic documentation will be included with the next version of the program.

 

The OBJECT file

The OBJECT file contains a list of inventory items (objects) that the player may possess during the game. Each item is numbered, and has a room number assigned to it. This room number is the room in which the object can be found.

It is not necessary to use these room numbers - it is up to the programmer to decide, but if they are used then the obj.in.room command can be used to find out if the object is in the current room when the player tries to get it.

Room 255 is the player's inventory, so any inventory items the player is to have at the start of the game should have their room number set to this.

Note: Do not confuse inventory objects with screen objects. These are two completely different things. Inventory objects (or "inventory items") are things that the player carries round with them during the game. Screen objects are views that are displayed on screen and represent things like characters and props. All the commands in the logic programming language that are called (something).obj refer to screen objects, except for show.obj and show.obj.v. Usually when the word "object" is used in the logic programming documentation it means screen object.

 

The WORDS.TOK file

The WORDS.TOK file contains a list of all the words that the game accepts. These words are sorted into groups of synonyms, and each group has a number. It is generally best to have several synonyms in each group, as this can reduce the "type 'till you bleed" frustration that is typical in many parser-based games by making the input more flexible.

There are three groups that have special meaning:

Group 0: Words in this group are ignored. Examples of these sorts of words are "a", "the", "with", "my" etc. When the player types in "poke the bush with the stick", it is the same as typing in "poke bush stick".

Group 1: This group should contain only one word, "anyword". It can be used to respond to general statements such as "kill anyword", e.g. if the player types "kill alligator", "kill girl" or "kill plant" then the statement said("kill","anyword") will be TRUE.

Group 9999: This group should contain only one word, "rol". rol means rest of line, e.g. if the player types "fight", "fight beast" or "fight beast with sword" then the statement said("fight","rol") will be TRUE.

 

Files used by AGI

Game files

These are the files that contain the actual data for the game.

Vol files (VOL.*): These files contain the resources. They are stored one after the other in the file, with a small header at the start of each resource identifying its size.

Directory files (LOGDIR, PICDIR, VIEWDIR, SNDDIR): These store the locations of each resource in the VOL files.

OBJECT and WORDS.TOK: See above.

In version 3, the VOL files have the game ID in front of them (e.g. KQ4VOL.0) and all the directory files are combined into one file (e.g. KQ4DIR)

If you want to know the format of these files, check out AGI Specifications.

 

Interpreter files

These are the files used by Sierra's original DOS interpreter. Other interpreters (there are two in progress at the time of writing) will use different files.

AGI: The interpreter itself
AGIDATA.OVL: Data used by the interpreter
All .OVL files: Graphics drivers
IERRA.COM: The loader file. Sometimes named after the game (e.g. SQ.COM). This loads the AGI file into memory, decrypts it, and then runs it.

 

Tutorials and Guides Table of Contents

< Previous: AGI Docs IndexNext: Defines >