AGI/Specifications/Introduction

Introduction

AGI (Adventure Game Interpreter) was the first major interpreter used by Sierra. With the release of King's Quest 1 in the early 80's, it introduced the gaming world to the concept of a 3D graphical adventure game, where the player could move a character around the screen, behind, in front of and over objects. Other commands could be typed in, just like a text adventure. This concept, in various forms, has been used many many times since, by Sierra and other companies such as Lucas Arts. It has proved very successful and continues to be used today in games such as Larry 7.

About this document

The latest version of this document can be found at http://wiki.scummvm.org/index.php/AGI/Specifications.

If you have any questions about the individual sections in this document, use the "Discussion" page of that section.

If you have documented an aspect of the interpreter, or have updated your documentation which is already included this document, please send it to the ScummVM team (contact information) so that it can be added in future versions.

Audience

AGI specs is intended for people writing AGI programs such as editors, viewers and interpreters. It is not supposed to be a beginners' introduction to AGI, or a LOGIC programming guide for those who just want to create games (although it can serve as a reference for more advanced LOGIC programmers). If you want to learn the LOGIC programming language, we suggest you read the logic section of the AGI Studio help file, and the various other bits of documentation and tutorials available on-line. The programming info contained in this document is mostly from the AGDS package and uses different syntax and terminology for the language and can be confusing if you are using AGI Studio for your programming.

Conventions used in this document

• Keyboard key names are given in fixed width font (e.g. ENTER).
• Metasyntatic variables are given in italics (e.g. n).
• File names are case sensitive and given in fixed width font (e.g. sierra.com).
• AGI resource names are given in all caps (e.g. LOGIC, VIEW).
• AGI command names are given in fixed width font (e.g. print.at).
• AGI variable n is noted as vn or Var(n) (e.g. v15, Var(18)).
• AGI flag n is noted as fn or Flag(n) (e.g. f2, Flag(11)).

What's still missing

Although this document has many details about the AGI specs, a few pieces of information are still missing:

• Savegame file format
• Some chunks of the memory organization
• Unknown view table entries
• Unknown fields in the IIgs sound header
• The release date of many AGI games
• The purpose of commands 171, 172 and 174
• The meaning of bit 0 in the argument byte
• The meaning of bytes 0--1 in the VIEW resource header
• Canonical names of commands 170--181
• Canonical variable and flag names
• More information about differences of AGI in other platforms (Amiga, Apple II, CoCo, etc)
• Any information about Donald Duck's Playground

Change Log

Version 3.2 (17 July 2007)

• Added info about AGI256 and AGI256-2 fan made extensions

Version 3.1 (6 January 2007)

• Added note about control lines and priority screen pixel scanning.

Version 3.0 (22 May 1999)

• Documentation converted to SGML, to allow easy conversion to other formats such as HTML, LaTeX, GNU info or plain text.
• Typos fixed.
• Removed redundant pieces of information.
• Re-organized and re-ordered sections; added credits, audience and notation subsections.
• Adopted uniform notation (all code examples and function names in fixed width font, hexadecimal numbers, characters and strings in C format, case sensitive file names)
• "Version control" section renamed "AGI interpreter versions".
• Removed sort-by-date and interpreter version cross-reference from "AGI interpreter versions".
• Added cross-references in the LOGIC commands description.
• Added unknown170--unknown181 command descriptions written by Dark Minister.
• Added IIgs SOUND resource format
• Added some bits of information to addn, step.size and other commands.

Version 2.0 (11 July 1998)

• Date corrected in section "Game IDs".
• Added a note on the main page explaining what AGI specs is for. Hopefully this will reduce the confusion that some people have been having when using this to learn the logic programming language.

3 March 1998

• Updated section "Game IDs" with some more info about game IDs and interpreter encryption.
• Corrected put and put.v commands in section Command list (the second argument of put and the first argument of put.v are supposed to be a vars).

27 January 1998

• Removed sections 4.2 (logic structure), 3.4 (dir/vol file format), 6.2 (view format), 8.2 (OBJECT format) and 8.3 (WORDS.TOK format). These were sections from the AGDS documentation which contained basically the same information as other more recent documentation in AGI specs. Section numbers above those removed have been moved down.
• Added sections "LOGIC syntax" and "Command list and argument types".
• Replaced sections "How the interpreter works" and "PICTURE resource format" with a better translations.
• Added more info about the AGDS package in section "The AGDS package".
• Updated section "Websites and people"
• Corrected the title of section "Version 3 resource storage".
• Updated the URL for the windows help version of AGI specs in section "Introduction".
• Fixed up a small formatting error in section "Version differences" (the header for one of the tables was repeated so it was removed).

5 December 1997

• Info about windows help version added to section 1.1.
• Corrections made to info on brush patterns in picture documentation (section 5.1).
• Fixed up some small formatting errors in sections 3.4, 3.5, 4.3 and 8.4.

5 October 1997

• Section 2.7 (version control) updated.
• Section 6.1 (View format) updated.

16 September 1997

• I forgot to add the version differences section when I converted all the documentation to HTML. It's there now.
• Fixed some problems in the index in section 3.x.

31 August 1997

• AGI specs is now available!
• A not about the dates on documents: almost all of the original ASCII text versions of these documents did not have a date on them, so I have put the "last updated" date to be 31 August 1997, which is when they first appeared in the HTML version of AGI Specs.

Credits

The following people (and probably more) have contributed to this document. Please contact the document maintainer to add more names to this list.

• Peter Kelly
• Lance Ewing
• Alex Simkin
• Vassili Bykov
• Anders M. Olsson
• Jeremy Hayes
• Joakim Möller
• Martin Tillenius
• Stuart George
• Dark Minister
• Kevin A. Lee
• Jens Christian Restemeier
• Paul Lunga
• Ian Schmidt
• David Symonds
• Claudio Matsuoka
• Kari Salminen