Introduction to Agi Designer: Sierra Adventure Game Development Suite

See the Introduction to Agi for common information on what Agi games are and the technology behind them.

Internally, Sierra developed some tools to assist with creating the AGI game resources. The game scripts needed to be compiled to an intermediate binary format (p-code). The backgrounds were created using a vector drawing program. They also needed to create the music, animations, etc. Then all of the game resources had to be packaged and compressed into volume files.

Agi Designer is a set of tools that allows the creation of AGI games using modern technology. They are the equivalent of what Sierra would have used internally to create their popular adventure games.

Anatomy of an AGI game

What is an AGI game?

An AGI game consists of a series of graphical screens where the player interacts with objects and characters, completing a series of quests. The player moves the main characters around in a 3D screen displayed as 2D objects with a Z order. Interactions are done by typing commands such as "take key". There is background music and sounds, as well as animated objects. There is no speech, but text is displayed on screen, typically as a response to the user input. A few AGI games do not use a parser, and so don't require text input. In those games, the player performs actions by pressing appropriate keys instead.

Structure of an AGI game

An AGI game is made of 2 major parts: the game resources and the game interpreter. The game resources include the logic, graphics, views, sounds, inventory, vocabulary. The resources are stored in separate files from the game interpreter. The interpreter takes care of loading resources from disk, and executing the game logic scripts which are stored as resources. With this simple structure, any AGI game can be run on a platform for which someone has created a compatible interpreter. For example, Sierra has created interpreters for MS-DOS, Amiga, Atari ST, Apple IIe, Apple IIgs, Macintosh, Tandy Color Computer 3.

AGI game resources

Logic

The logic resource describes the script that executes for a room.

Picture

The picture resource describes the instructions used to draw a room. Each room has a visual and priority picture, where the visual is what is drawn on the screen, and the priority is the boundaries and Z order for the room.

View

The view resource describes animation loops and cels that are added dynamically to each room.

Sound

The sound resource describes the notes that are played by the sound chip.

Inventory

The inventory resource is the simplest of all resources. It describes the items that can be acquired by the player. Each item has a name and a start room. Only one inventory resource is used in a game project.

Vocabulary

The vocabulary resource describes the words that are recognized by the parser. Words that are synonyms of each other are grouped together via a family id. The game logic and parser refer to the family ids. Words are never referenced individually.

AGI game interpreters

IBM PC/MS-DOS was the main development platform for new AGI games. There were 2 popular revisions of the AGI interpreter which put together support most the games that have been released. Interpreters created for the other platforms were based on these 2 MS-DOS interpreters, with minor differences.

MS-DOS AGI v2

This is the most common interpreter. The game resources are stored in files as follows.

MS-DOS AGI v3

The resource files are similar to v2, but the directory files have been merged into one file instead of one per resource type. Another difference is that the resources a compressed differently inside the volume files. ? is replaced with the game identifier. For example, the game King's Quest IV has an identifier of KQ4, so the files are named KQ4DIR, KQ4VOL.0, KQ4VOL.1, etc.

Supported Games

Sierra developed several games during the years 1985-1989 using the AGI system. There were 4 major revisions of the system for the PC platform.

• Version 0: Unsupported. Original PC booter version of King's Quest I.
• Version 1: Unsupported. Original PC booter version of King's Quest II and The Black Cauldron.
• Version 2: Supported. Donald Duck's Playground, Christmas Card, King's Quest I, II, III, Leisure Suit Larry I, Police Quest I, Space Quest I and II, Mixed-Up Mother Goose.
• Version 3: Supported. King's Quest IV, Gold Rush!, Manhunter I and II.

On the Atari ST, Amiga and Apple IIgs platforms, only the version 2 and 3 interpreters were used as the games were ported to these systems later on.

Features

Decompiler

Agi Designer includes a command line decompiler which can be used to create an AGI game project by decompiling an existing game.

Compiler

Agi Designer includes a command line compiler which can be used to compile an AGI game project into a game compatible with existing AGI interpreters. This is an alternative to using msbuild.exe, it produces the same result without using the MSBuild engine.

MSBuild Support

An AGI game project is described in an MSBuild project file. This file includes compile options and resources that are included in the game. A .targets file and its associated MSBuild task assembly are installed by Agi Designer in the standard MSBuild directory.

Here is an example AGI game project file opened inside of Visual Studio. Note that Visual Studio is not required to use MSBuild, it is only used here for the coloring the standard XML editor provides.

Here is an example of compiling an AGI game project using msbuild.exe, where a compiler error is reported for one of the logic resources.

Visual Studio Tools

Agi Designer integrates several of its features inside Visual Studio. These features include a custom project system, item and project templates, language service, custom editors.

New Project Templates

Agi Designer has 3 different wizards for creating a new AGI project. Here is the new project dialog showing the different project templates.

Project System

An AGI project works similar to other code based project in Visual Studio.

Project properties can be edited through the project property pages, much like in C++ projects.

Resource Editors

An AGI game consists of 6 different type of resources.

• Inventory
• Vocabulary
• Picture
• View
• Sound
• Logic

Most of these resources are stored in XML format, and can be edited using the standard XML editor. For some of the resources, specialized editors are supplied by Agi Designer which allow an easy to use interface to modifying the resources.

Inventory Resource

Here is an inventory resource in the standard XML editor.

Here is an inventory resource in the specialized editor.

Vocabulary Resource

Here is a vocabulary resource in the standard XML editor.

Here is a vocabulary resource in the specialized editor.

Picture Resource

Here is a picture resource in the standard XML editor.

Here is a picture resource in the specialized editor.

View Resource

Here is a view resource in the standard XML editor.

Here is a view resource in the specialized editor.

Sound Resource

Here is a sound resource in the standard XML editor.

There is currently no specialized editor for sound resource.

Logic Resource

Agi Designer supports 2 languages for logic resource: XML and C-like.

Here is a logic resource in the standard XML editor.

Here is an example of using Agi Designer XML preprocessor.

Here is a logic resource in the standard code editor, where a specialized language service provides coloring, code completion, etc.

Here is an example of a help tooltip.

Here is an example of code completion.

Here is the error list window showing an example of a compiler error where the expected parameter should be of type controller but the supplied parameter was of type flag. Note that red squigglies are currently not implemented in the Agi Designer language service.

Requirements

Command Line Tools

The compiler, decompiler and MSBuild support require .NET Framework 2.0 or later.

Visual Studio Tools

The integration into Visual Studio requires Visual Studio 2010 (the free Express editions are not supported).

Development

The application consists of several modules:

• Object model: Definition of the different classes describing the game resources.
• Serialization: Loading and saving of the game resources in Sierra binary resource format, or custom format (XML, Script).
• MSBuild: MSBuild .targets and tasks.
• Visual Studio project system: Implementation of a custom project type, project settings, building and execute support.
• Visual Studio custom editors: Custom document windows for the different resource types.
• Visual Studio language service: Intellisense, coloring, tooltips for the logic scripting language.
• Visual Studio wizards: Wizards to create game from scratch or by decompiling an existing AGI game.

Build requirements (not included):

• Visual Studio 2010
• Visual Studio 2010 SDK

Build requirements (included):

• MPF library (in source form) is used to assist with the implementation of the project system, and is included in the Agi Designer source.
• NUnit is used for unit testing and is included in the Agi Designer source.
• Wix is used for MSI generation and is included in the Agi Designer source.

Conclusion

Agi Designer allows the creation or modification of AGI games by building on the latest Microsoft technologies such as MSBuild and Visual Studio.