Screen Object Table

The screen object data structure is comprised of 43 (0x2B) bytes of data that track the object's size and position, view/loop/cel data, motion control information, and a 2 byte bit-field of flags that AGI uses to manage the object's behavior. In each interpreter cycle, various elements of each object in the screen object table are updated. Many AGI logic commands can also modify and/or retrieve various screen object data elements.

The screen object table maintains all the properties of each screen object. Recently uncovered fragments of Sierra's original AGI source code revealed the original name and description for each element of the screen object table. This information is provided along with the terms in general use as originally decompiled by AGI enthusiasts.

Screen Object Data Structure

Byte	Meaning	Original Sierra Name	Original Sierra Description
00 (0x00)	step time: the number of cycles that occur between updates in object's position during motion; if set to 0 or 1, object moves every cycle; if set to 2 or greater, object moves every nth cycle, where n is the step time. Use the step.time command to change an object's step time	movefreq	number of animation cycles between motion
01 (0x01)	step counter: this counter is checked in each interpreter cycle; if the value is one, AGI determines if correct loop is being shown based on object direction (auto-loop feature); after this check, the step counter is decremented; if it reaches zero, the screen object position is updated, and the step counter is reset to step time for the next cycle	moveclk	number of cycles between moves of object
02 (0x02)	object number: the index number of the object; AGI uses this value in several internal procedures; it is not accessible by code and is not of use to game programmers	num	object number
03-04 (0x03-0x04)	current x: this is the current horizontal position of the object	x	current x coordinate
05-06 (0x05-0x06)	current y: this is the current vertical position of the object	y	current y coordinate
07 (0x07)	current view: the number of the view that is currently assigned to the object	view	current view number
08-09 (0x08-0x09)	view data pointer: a pointer to the start of view data assigned to the object	*viewptr	pointer to current view
10 (0x0A)	current loop: number of current loop assigned to the object	loop	current loop in view
11 (0x0B)	number of loops: the number of loops in the assigned view	loopcnt	number of loops in view
12-13 (0x0C-0x0D)	loop data pointer: a pointer to the start of loop data for currently assigned loop	*loopptr	pointer to current loop
14 (0x0E)	current cel: number of current cel assigned to object	cel	current cell in loop
15 (0x0F)	number of cels: the number of cels in the currently assigned loop	celcnt	number of cells in current loop
16-17 (0x10-0x11)	cel data pointer: a pointer to the start of cel data for the currently assigned cel	*celptr	pointer to current cell
18-19 (0x12-0x13)	previous cel data pointer: a pointer to previous cel data; AGI needs this to manage properly drawing cels on screen as objects move about and change cels	*prevcel	pointer to previous cell
20-21 (0x14-0x15)	picture data pointer: a pointer the picture data that is going to be overwritten when a cel is drawn to the screen; the data is stored at the end of the memory heap and is used to restore the background when cels are moved and redrawn as objects move about the screen	save	pointer to background save area
22-23 (0x16-0x17)	previous x: the previous horizontal position of the object; used during object movement to facilitate proper placement	prevx	previous x coordinate
24-25 (0x18-0x19)	previous y: the previous vertical position of the object; used during object movement to facilitate proper placement	prevy	previous y coordinate
26-27 (0x1A-0x1B)	cel width: the width, in pixels, of the current cel)	xsize	x dimension of current cell
28-29 (0x1C-0x1D)	cel height: the height, in pixels, of the current cel	ysize	y dimension of current cell
30 (0x1E)	step size: the number of pixels an object will move during each movement step; if moving diagonally, step size is added to both x and y values	stepsize	distance object can move
31 (0x1F)	cycle time: the number of cycles that occur between updates in object's current cel; if set to 0, the object will never change cels (the same as using the stop.cycling command); if set to 1 or greater, cel changes every nth cycle, where n is the cycle time. Use the cycle.time command to change an object's cycle time	cyclefreq	time interval between cells of object
32 (0x20)	cycle count: internal counter used by AGI to determine when to cycle object cel; decrements on each interpreter cycle; when zero reached, object cel is cycled, and counter is reset to cycle time	cycleclk	counter for determining when object cycles
33 (0x21)	object direction (heading): determines the direction of movement for an object; can be one of nine values:       0 = stationary       1 = up       2 = up-right       3 = right       4 = down-right       5 = down       6 = down-left       7 = left       8 = up-left	dir	object direction
34 (0x22)	object motion: determines the type of motion control for the object; objects can be set to move to a specific location, wander aimlessly, or even set to follow ego; possible values for object motion are:       0 = normal.motion       1 = wander       2 = follow.ego       3 = move.obj       4 = player control (only ego can be set to player control)	motion	object motion type
35 (0x23)	cycling status: determines how the object cycles through cels in the currently assigned loop; the default is to step through cels in order, starting with the first cel, starting over again after the last cel; other settings for cycling status are:       0 = normal.cycle       1 = end.of.loop       2 = reverse.loop       3 = reverse.cycle	cycle	cell cycling type
36 (0x24)	priority: the current assigned priority for an object; normally calculated automatically based on the object's vertical position, but can be manually set using the set.priority command	pri	priority of object
37-38 (0x25-0x26)	object flags: a 16 bit field flags that AGI uses to manage objects; see table below for explanation of each bit flag:	control	object control flag (bit mapped)
39-42 (0x27-2A)	motion and cycling parameters: four bytes that are used as motion control and cycling data; exact purpose depends on object motion or cycle status:	parms[4]	space for various motion parameters
move.obj
39 (0x27)	x: horizontal component of target position
40 (0x28)	y: vertical component of target position
41 (0x29)	saved step size: the original step size of the object that is restored once it reaches its destination
42 (0x2A)	flag: number of flag to set when object reaches target position
follow.ego
39 (0x27)	distance: determines how close the object has to be to ego before the 'caught' flag is set
>40 (0x28)	flag: number of flag to set if object reaches ego
41 (0x29)	count: used to help determine direction of object as it moves toward ego
42 (0x2A)	unused
wander
39 (0x27)	wander_count: decrements on each interpreter cycle; when it reaches zero, another random direction is chosen, and count is set to random number between 7 and 33
40-42 (0x28-0x2A)	unused
end.of.loop, reverse.loop
39 (0x27)	flag: number of flag to set when loop is done cycling
40-42 (0x28-0x2A)	unused

NOTE: because the motion and cycling parameters are shared by motion control commands (wander, follow.ego, move.obj) and cycling commands (end.of.loop, reverse.loop) you will get unexpected results if you use a motion control command and a cycling command on the same object at the same time. See each command for additional information on how motion control and cycling commands interact.

Screen Object Flags]]

Byte	Meaning (bit is set)	Original Sierra Name	Original Sierra Description
0	When set, object will be drawn on screen; if this flag is not set, AGI will not draw the object on the screen; also, all commands affecting object movement and cycling will be ignored; use the draw command to set this flag and draw the object on screen after assigning a view and positioning the object; see the Working with Objects topic in the Logic Command Reference section for details on how to manage screen objects	DRAWN = 0x0001	1 -> object is drawn on screen
1	When set, object ignores blocks/condition lines during movement; unconditional lines will still be observed; use the ignore.blocks command to set this flag, and the observe.blocks command to clear this flag; by default, objects do NOT ignore blocks; see the control line topic for additional information	IGNRBLK = 0x0002	1 -> object ignores blocks
2	This flag is set by the set.priority so AGI knows not to adjust the priority automatically based on screen position; it is cleared by using the release.priority command	FIXEDPRI = 0x0004	1 -> object has fixed priority
3	This flag is set by the ignore.horizon command; when set, AGI will allow the object to move past the horizon, and all the way to the top of the screen; it is cleared by using the observe.horizon command	IGNRHRZ = 0x0008	1 -> object ignores the horizon
4	When set, object will update its position (and loop, if auto-loop is in effect) based on its direction and step.time; use the stop.update command to clear this flag and stop AGI from updating the object; by default, this flag is set to true when an object is initialized	UPDATE = 0x0010	1 -> update the object
5	When set the object will cycle the cels in the object according to current cycle mode; for end.of.loop and reverse.loop, AGI sets this flag to false when the end of the loop is reached, which stops the loop from continuing to cycle	CYCLE = 0x0020	1 -> cycle the object
6	All objects must be initialized (or 'animated' in AGI speak) before they can be displayed on screen and/or manipulated. This flag is used by AGI to determine if an object has been correctly animated; if not, all object related commands are generally ignored. Use the animate.obj command to animate an object and set this flag. By default, all objects are unanimated at start up, and every time a new.room is executed.	ANIMATED = 0x0040	1 -> object can move
7	When updating an object's movement, AGI sets this flag to TRUE if the object's position moves inside a block that is defined by the block command; if movement is outside the block, or there is no defined block, or if the object is set to ignore blocks this flag is reset	BLOCKED = 0x0080	object is blocked
8	If this flag is set to TRUE, AGI will not allow the object to move such that any pixel of it's baseline is NOT on a water pixel (priority value of 3); this flag is set by executing the object.on.water command; it is cleared by executing the object.on.anything command; if both object.on.water and object.on.land commands are executed on the same object, the water restriction takes precedence; the object will not be allowed off water pixels; also, for ego, AGI resets the water restriction flag at the end of every interpreter cycle	PRICTRL1 = 0x0100	1 -> object must be on 'water' priority
9	by default, objects are not allowed to 'pass through' or 'collide' with other objects, to simulate that the objects are three dimensional; when this flag is set, this restriction is lifted, and the object will ignore other objects when it moves; set this flag by executing the ignore.objects command; this flag is cleared by executing the observe.objects command. it's also reset for all objects when the new.room command is executed	IGNROBJ = 0x0200	1 -> object won't collide with objects
10	when an object has been manually moved to a new location by using the reposition or reposition.to commands (or if position is adjusted due to bumping into a screen edge), AGI sets this flag so it doesn't get moved again during the movement check portion of the interpreter cycle; this flag has no practical value to a game programmer	REPOS = 0x0400	1 -> object being reposn'd in this cycle
11	If this flag is set to TRUE, AGI will not allow the object to move such that the entire baseline is on water pixels (priority value of 3); this flag is set by executing the object.on.land command; it is cleared by executing the object.on.anything command; if both object.on.land and object.on.water commands are executed on the same object, the water restriction takes precedence; the object will not be allowed off water pixels; also, for ego, AGI resets the water restriction flag at the end of every interpreter cycle	PRICTRL2 = 0x0800	1 -> object must not be entirely on water
12	skips cel cycling for one interpreter cycle; used by end.of.loop and reverse.loop so object shows the starting cel, otherwise the object would immediately move to second cel in the loop	NOADVANC = 0x1000	1 -> don't advance object's cel in this loop
13	when set, this flag tells AGI not to change the assigned loop based on the object's direction of motion (known as the auto-loop feature); set this flag by executing the fix.loop command, reset it by executing the release.loop command; by default, this flag is reset, and it is also reset for all objects when a new.room command is executed	FIXEDLOOP = 0x2000	1 -> object's loop is fixed
14	This flag is used internally by AGI for the follow.ego and wander commands to manage movement of an object; it has no practical value to a game programmer	STOPPED = 0x4000	1 -> object did not move during last animation cycle
15	Unused in most versions; in later releases of version 3, this flag is used in conjunction with the mouse to provide 'click to move' functionality. See the adj.ego.move.to.x.y command for more information.	unknown	unknown