Screen object

The screen object data type (sometimes called a VIEW object; not to be confused with a view resource) represents the animated sprites that are controlled by AGI. Unlike variables and flags, screen objects must be explicitly created in order to access them in AGI. Each screen object must be initialized, assigned a loaded view resource, positioned on the screen and then drawn in order to appear on screen.

Screen objects are represented in source code by the letter 'o' and their index number (i.e. o0, o1, etc.)

Screen Object Table

Each screen object is represented by a structured block of memory that contains all the data associated with the object. AGI creates a table of screen object structures on start up which is then accessed as needed while AGI is running. See the Screen Object Data Structure Topic for details on the information stored in AGI for each screen object.

Maximum Screen Objects

The size of the screen object table is set by the Maximum Screen Objects property of the game's OBJECT file. AGI allocates memory for the screen object table based on the Maximum Screen Objects value when the game starts. The size of the table cannot be adjusted after that.

The screen object table size is always one plus the actual value of Maximum Screen Objects, i.e. if maximum is set to 10, the table will actually hold 11 objects. This is because the first object (o0, known as ego) is always allocated a space in the screen object table. Due to memory limitations, you should try to limit the Maximum Screen Objects to as low a value as possible. You can even use a value of zero, which would mean that the only object that would be usable would be the ego object. A common value in many Sierra games for Maximum Screen Objects was 16.

Ego Object

The first screen object in the table (o0) is reserved by AGI to function as the character that represents the player in the game. This is the screen object which the player can control, moving around the screen as they progress through the game.

In AGI, this screen object (o0) is referred to as "ego". AGI provides commands and functionality specifically for ego that is unique from other screen objects. It is the only screen object that can be set to allow player control via the keyboard, joystick and/or mouse. None of the other objects can be controlled directly by the player.

Loop Assignment to Screen Objects

In order to actually display an object on screen, a view must be assigned using the set.view command. In each interpreter cycle, AGI displays each cel in the currently assigned loop successively, which creates the illusion of movement. See the Working with Screen Objects topic for additional information.

Auto Loop Feature

If the view assigned to an object has 2, 3 or 4 loops, AGI will automatically assign a loop based on the direction an object is moving. For example, when walking to the right, show a right facing loop, when walking toward the horizon, show a rear view loop, etc. When an object's direction changes, AGI assigns a loop as follows:

Direction	New Loop (2,3 loops)	New Loop (4 loops)
0 - STOPPED	no change	no change
1 - UP	no change	3
2 - UP_RIGHT	0	0
3 - RIGHT	0	0
4 - DOWN_RIGHT	0	0
5 - DOWN	no change	2
6 - DOWN_LEFT	1	1
7 - LEFT	1	1
8 - UP_LEFT	1	1

If the view has only one or more than four loops, AGI will not automatically assign loops based on direction. However, in AGI version 3.002.098 and above, reserved flag f20 (force auto-loop) can be set to force the auto-loop behavior even if there are more than four loops in the view. (There is a bug in version 3.002.086 that makes all views automatically update no matter how many loops they have.)

The auto-loop feature can be disabled by using the fix.loop command. Also, there is a bug in all versions of AGI that will disable the auto-loop feature if step size is set to 0.

Screen Object Number Validation

It is important to be aware that AGI is notorious for failing to validate values passed to commands. In the case of screen objects, beginning in version 2.272, most of the AGI commands no longer verify that the value passed for screen objects is less than or equal to the maximum (exceptions are the erase, animate.obj, and draw commands).

This means that when an invalid screen object value is passed to a command, AGI will attempt to read or write data in memory that is outside the screen object table. This will most certainly result in wildly unpredictable results, and usually ends up crashing AGI.

As a game programmer it is extremely important that you verify all commands involving screen objects are passed a valid value. See the Internal Error Handling topic for additional information on how AGI handles errors in logic code.