Screen Object Table

From AGI Wiki
Jump to: navigation, search

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