Difference between revisions of "Object"

From Crash Bandicoot Hacking Wiki
Jump to navigation Jump to search
(Status Flags B)
Line 1: Line 1:
 +
In technical terms, an Object is an instance of a GOOL executable. From the player's point of view, it is an in-game entity with specific appearance, behavior, location, state, and a variety of other characteristics. For each frame, or approximately every 1/60th of a second of gameplay, an object's executable bytecode is interpreted by the GOOL interpreter. This bytecode instructs the interpreter to perform a specific sequence of operations that will ultimately render the object according to its changing characteristics. As a result, the player observes a lively, animated, and interactive enemy, box, collectible item, or whatever other kind of in-game object.
 +
 
== Format ==
 
== Format ==
  

Revision as of 02:03, 29 July 2015

In technical terms, an Object is an instance of a GOOL executable. From the player's point of view, it is an in-game entity with specific appearance, behavior, location, state, and a variety of other characteristics. For each frame, or approximately every 1/60th of a second of gameplay, an object's executable bytecode is interpreted by the GOOL interpreter. This bytecode instructs the interpreter to perform a specific sequence of operations that will ultimately render the object according to its changing characteristics. As a result, the player observes a lively, animated, and interactive enemy, box, collectible item, or whatever other kind of in-game object.

Format

Crash 1

All objects in Crash 1, with the exception of the player object, are 604 (0x25C) bytes in size. The player object, 860 (0x35C) bytes in size, includes an additional 0x100 bytes of object memory to account for the higher number of activation records and local 'registers' created by its lengthier, more complex code.

Free and Existing Objects

Free Objects have a header value of 0. They are placed into a 'free object pool' until the game requests to create or spawn them into existence.

Existing Objects have a header value of 1. They are the actual objects 'in use' by the game and are created or spawned into existence from a free object.

Both variations have the following format:

Offset Field Size Value
0x0 Header 4 bytes !=2
0x4 Process Type 4 bytes *
0x8 Bounding Box x1 4 bytes *
0xC Bounding Box y1 4 bytes *
0x10 Bounding Box z1 4 bytes *
0x14 Bounding Box x2 4 bytes *
0x18 Bounding Box y2 4 bytes *
0x1C Bounding Box z2 4 bytes *
0x20 Source GOOL Executable 4 bytes *
0x24 External GOOL Executable 4 bytes *
0x28 Parent Zone 4 bytes *
0x2C State 4 bytes *
0x30 Light Source Matrix L11 2 bytes *
0x32 Light Source Matrix L12 2 bytes *
0x34 Light Source Matrix L13 2 bytes *
0x36 Light Source Matrix L21 2 bytes *
0x38 Light Source Matrix L22 2 bytes *
0x3A Light Source Matrix L23 2 bytes *
0x3C Light Source Matrix L31 2 bytes *
0x3E Light Source Matrix L32 2 bytes *
0x40 Light Source Matrix L33 2 bytes *
0x42 Background Color R 2 bytes *
0x44 Background Color G 2 bytes *
0x46 Background Color B 2 bytes *
0x48 Light Color Matrix LR1 2 bytes *
0x4A Light Color Matrix LR2 2 bytes *
0x4C Light Color Matrix LR3 2 bytes *
0x4E Light Color Matrix LG1 2 bytes *
0x50 Light Color Matrix LG2 2 bytes *
0x52 Light Color Matrix LG3 2 bytes *
0x54 Light Color Matrix LB1 2 bytes *
0x56 Light Color Matrix LB2 2 bytes *
0x58 Light Color Matrix LB3 2 bytes *
0x5A Background Color Intensity R 2 bytes *
0x5C Background Color Intensity G 2 bytes *
0x5E Background Color Intensity B 2 bytes *
0x60 Self Link 4 bytes this
0x64 Parent 4 bytes *
0x68 Sibling 4 bytes *
0x6C Children (head child) 4 bytes *
0x70 Creator 4 bytes *
0x74 Player 4 bytes *
0x78 Collider 4 bytes *
0x7C Interrupter 4 bytes *
0x80 Trans x 4 bytes *
0x84 Trans y 4 bytes *
0x88 Trans z 4 bytes *
0x8C Rotation y 4 bytes *
0x90 Rotation x 4 bytes *
0x94 Rotation z 4 bytes *
0x98 Scale x 4 bytes *
0x9C Scale y 4 bytes *
0xA0 Scale z 4 bytes *
0xA4 Velocity x 4 bytes *
0xA8 Velocity y 4 bytes *
0xAC Velocity z 4 bytes *
0xB0 Target Rotation y 4 bytes *
0xB4 Target Rotation x 4 bytes *
0xB8 Target Rotation z 4 bytes *
0xBC Mode Flags A

or Angular Velocity y

4 bytes *
0xC0 Mode Flags B

or Angular Velocity x

4 bytes *
0xC4 Mode Flags C

or Angular Velocity z

4 bytes *
0xC8 Status Flags A 4 bytes *
0xCC Status Flags B 4 bytes *
0xD0 Status Flags C 4 bytes *
0xD4 Subtype/Initial State 4 bytes *
0xD8 ID 4 bytes *
0xDC Stack Pointer 4 bytes *
0xE0 Program Counter (ins. pointer) 4 bytes *
0xE4 Frame Pointer 4 bytes *
0xE8 Trans Block Program Counter 4 bytes *
0xEC Event Block Program Counter 4 bytes *
0xF0 Head Block Program Counter 4 bytes *
0xF4 Various 4 bytes *
0xF8 Unknown 4 bytes *
0xFC Frame Change Timestamp 4 bytes *
0x100 State Change Timestamp 4 bytes *
0x104 Animation Lag Counter 4 bytes *
0x108 Animation Sequence 4 bytes *
0x10C Animation Frame 4 bytes *
0x110 Entity Spawned From 4 bytes *
0x114 Path Progress 4 bytes *
0x118 Path Length (point count) 4 bytes *
0x11C Ground y 4 bytes *
0x120 State Flags 4 bytes *
0x124 Speed 4 bytes *
0x128 Display Mode 4 bytes *
0x12C Unknown 4 bytes *
0x130 Timestamp of Most Recent Landing 4 bytes *
0x134 Velocity y at Most Recent Landing 4 bytes *
0x138 Z-Index 4 bytes *
0x13C Event Received 4 bytes *
0x140 Camera Zoom Factor 4 bytes *
0x144 Target Rotation Angle YZ plane 4 bytes *
0x148 Collision Hot-Spot Clip Amount 4 bytes *
0x14C Unknown 4 bytes *
0x150 Unknown 4 bytes *
0x154 Unknown 4 bytes *
0x158 Collision Node 4 bytes *
0x15C Object Memory 64 x 4 bytes *

List Handle Objects

List Handle Objects have a header value of 2. They are not actual objects and instead used only to point to the head object in a list of (children) objects. For this reason their structure contains only 2 fields: the object header and a pointer to the list head object.

Offset Field Size Value
0x0 Header 4 bytes 2
0x4 Head Object of List 4 bytes *

Structure

Crash 1

struct object;
struct dbllink
{
  object *prev;
  object *next;
  unsigned long unk_8;
};

struct object
{
  unsigned long header;
  union
  {
    unsigned long proctype;
    object *listchildren;
  };
  struct bound bound;
  entry *local;
  entry *external;
  entry *zone;
  unsigned long state;
  
  union { struct slightmatrix colors;
  struct slightmatrix lightmatrix; };
  struct scolor color;
  struct scolormatrix colormatrix;
  struct scolor intensity;
  
  object *self;
  object *parent;
  object *sibling;
  object *children;
  object *creator;
  object *player;
  object *collider;
  object *interrupter;
  
  union { struct vector vectors;
  struct vector trans; };
  struct angle rot;        
  struct vector scale;     
  union
  {
    struct vector velocity;
    struct dbllink link;
  };
  struct angle targetrot;  
  union
  {  
    struct angle angvelocity;     
    struct
    {
      unsigned long modeflagsa;
      unsigned long modeflagsb;
      unsigned long modeflagsc;
    };
  };
  
  unsigned long statusa;       
  unsigned long statusb;       
  unsigned long statusc;       
  unsigned long subtype;         
  unsigned long id;           
  unsigned long *sp;    
  unsigned long *pc;    
  unsigned long *fp;    
  unsigned long *pctrans;
  unsigned long *pcevent;
  unsigned long *pchead;
  union
  {
    unsigned long misc_flag;
    object *misc_child;
    entry *misc_entry;
    unsigned long misc_memcard;
  };
  unsigned long unk_F8;
  unsigned long stampanim;
  unsigned long stampstate;
  unsigned long animcounter;
  unsigned long *animseq;
  unsigned long animframe;
  
  unsigned char *entity;
  signed long pathprogress;
  unsigned long pathcount;
  signed long groundy;
  unsigned long stateflags;
  signed long speed;
  unsigned long displaymode;
  unsigned long unk_12C;
  unsigned long stampland; 
  signed long landyvel;    
  unsigned long zindex;    
  unsigned long event;     
  signed long camzoom;     
  unsigned long approachyz;
  signed long hotspotclip; 
  signed long unk_14C;
  unsigned long unk_150;  
  unsigned long unk_154;
  signed long node;
  unsigned long memory[0x40];
};

Field Information

Header

The header field determines whether the object is free, existing, or a list handle:

Value Type Description
0 Free Object An empty or previously terminated object that doesn't actually exist in the game. It has been placed into a 'free object pool' until created or spawned into existence.
1 Existing Object An actual object 'in use' by the game and created or spawned into existence from a free object.
2 List Handle Object Not an actual object; used only to point to the head object in a list of (children) objects.

Process Type or List Head

  • When the object is a List Handle, this field points to the head object in its referenced list.
  • When the object is not a List Handle, this field is set to 3 after it is successfully created or spawned.
    • note: after successful spawning, this field is actually set to the source entity's proctype. However, all entities appear to have a proctype of 3 (not confirmed**).

Bounding Box

An object's bounding box specifies the rectangular region of 3-dimensional space which it occupies. It encompasses the geometry rendered for the object's current frame of animation. It is specified by the 3-dimensional fixed-point coordinates of its upper left and lower right points relative to the object's location (which is typically positioned at the center point of the object's animation frame model), and is recalculated for each change in frame of animation.

Fields at offsets 0x8, 0xC, and 0x10, respectively, specify the relative x, y, and z coordinates of the object's upper left bounding box point. Fields at offsets 0x14, 0x18, and 0x1C, respectively, specify the relative x, y, and z coordinates of the object's lower right bounding box point.

Other fields...

TODO

Status Flags A

This field is the first bitfield in a sequence of 3 object status flag bitfields

Bit Indication/Purpose Additional
1 object has been stopped by solid ground
2 ?
3 0 = object is progressing forward along its path

1 = object is progressing backward along its path

path travelling objects only
4 0 = object was rotating counter-clockwise

1 = object was rotating clockwise

rotating objects only
5 object is transitioning from travelling forward to backward/vice versa along its path path travelling objects only
6 object has changed animation [i.e. first frame of animation] state change also assumes change in animation by setting this
7 ?
8 object has been hit from the bottom set when collision check does not pass?
9 object is moving and not stopped by a wall
10 overrides the effect of displacement caused when bits 7 and 16 of status flags b are set, allowing the object to remain stationary
11 set when colliding with an octree node and it triggers event
12 cleared when spinning or changing direction, reset by sub_243A0
13 object has a collider [collider = object that collides with the object's bound volume, specifically after it is clipped of hotspotclip units from each of its faces] this bit tested by an object's GOOL code to determine whether another object [i.e. crash] collides with it, so it can send the 'kill' event (0x300)
14 object is hitting a bounce box (for setting a higher acceleration)
15 set when bouncing on and breaking a box?
16 object's bounding box needs recalculating
17 ? recipient process sets this bit when sent event 'crushed by boulder (and ?)' (0x1800, 0x1900)
18 object has changed state
19 object is on the ground
20 ? boxes set this at the end of their init routine
21 set right after bounce from box/enemy?
22 object is a solid object (or supported by a solid object?)
23 to 32 ?

Status Flags B

This field is the second bitfield in a sequence of 3 object status flag bitfields

Bit Indication/Purpose Additional
1 object rotates in XZ plane based on target rot angle (cleared during spin?)
2 object rotates in XZ plane and approaches the opposite direction when travelling backwards along its path (i.e. spins 180 degrees when reaching either end of its path) for path travelling objects;

bit 3 must be set for this to take effect

3 auto rotate mode

0 = auto banking along curves is outward

1 = a) auto banking along curves is inward

b) object rotates in XZ plane to face the direction of its path (if bit 2 is set, the object will additionally 'reverse' this direction when travelling its path backwards)

path curve auto banking does not take effect unless bit 12 is set
4 0 = object position is only affected by velocity

1 = object is stopped by solid surfaces: floor, ceiling, walls, and tops/bottoms and sides of solid objects

**NOTE: see bit 7
5 object is collide-able (records space occupied by object and pointer to object in a pair during this frame)
6 object y velocity is affected by gravity
7 object displacement is handled by the physics engine:

if bit 4 = 0: displacement is handled by only adding velocity to location (ex. of this is when enemies are killed and spun off into the distance); effect of this may be overridden if bit 10 of status flags a is set and object assumes the ground is at its initial y location (see bit 16)

if bit 4 = 1: displacement is handled with the main collision routine (Crash object is the only object to ever have bit 4 set)

bit 7 also allows bit 13, 15, and 16 to take effect

when bit 7 is clear, object displacement should be handled manually by the object's GOOL code

8 object [speed, velocity, and angular velocity] is controlled with the controller
9 object does not render ex. HUD offscreen, dying in water
10 object is 2 dimensional
11 text object has a backdrop
12 object auto banks along path curves path travelling objects only
13 object has air resistance? (causes angvelocity to act as a velocity cap on both pos and neg velocities of its [absolute] value)
14 object rotates in YZ plane to approach its target rot angle
15 object treats XZ plane at Y given by field groundy as solid ground
16 object assumes the ground is at, and field groundy is set to, its initial y location NOTE: object is not effectively 'stopped' at the ground without bits 7 and 15 set
17 object is solid at the sides
18 object is solid at the top?
19 disable frustum culling?
20 object optionally rotates in XZ plane to approach its target rot angle
21 object is shaded based on its parent zone, using the zone's color matrices
22 ?
23 overrides an initial test in determining the highest object below the source? adds an additional 0x19000 in ground offset calculation? guess: stacked object
24 ?
25 object can not be terminated
26 always display and animate object
27 ?
28 ?
29 object waits a number of frames until its next animation change/code block burst: may take precedence over 'wait' value from most recent suspending frame primitive (i.e. GOOL ANIM operation) also prevents the object from changing state
30 ?
31
32 object is solid at the bottom? forces more elaborate screen culling check (based on object projected 2d area rather than projected 2d midpt)