Object

From Crash Bandicoot Hacking Wiki
Revision as of 16:49, 20 April 2020 by Mddass (talk | contribs) (Free and Existing Objects: Fix color fields-)
Jump to navigation Jump to search

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 it may be.

General

When the game wishes to create an object, it first specifies a source GOOL executable, and an object is created as an instance of that executable-much like how a process is created in relation to its source executable in an operating system. Probably the most important part of a GOOL executable is its compiled GOOL bytecode; the compiled GOOL bytecode of an executable that any given object is an instance of-or more simply the bytecode for that object-will be 'interpreted' by the GOOL bytecode interpreter routine. The GOOL bytecode interpreter routine will then operate according to the instructions it sees in the bytecode for that 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 Diffuse Color LR1 2 bytes *
0x4A Diffuse Color LG1 2 bytes *
0x4C Diffuse Color LB1 2 bytes *
0x4E Diffuse Color LR2 2 bytes *
0x50 Diffuse Color LG2 2 bytes *
0x52 Diffuse Color LB2 2 bytes *
0x54 Diffuse Color LR3 2 bytes *
0x56 Diffuse Color LG3 2 bytes *
0x58 Diffuse Color LB3 2 bytes *
0x5A Ambient Color R 2 bytes *
0x5C Ambient Color G 2 bytes *
0x5E Ambient Color 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 *

Crash 2

All objects in Crash 2, with the exception of the player object, are 572 (0x23C) bytes in size. The player object, 828 (0x33C) 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 Current Animation Entry 4 bytes *
0xC Source GOOL Executable 4 bytes *
0x10 Main GOOL Executable 4 bytes *
0x14 External GOOL Executable 4 bytes *
0x18 Parent Zone 4 bytes *
0x1C State 4 bytes *
0x20 Color Modifier 1 2 bytes *
0x22 Color Modifier 2 2 bytes *
0x24 Color Modifier 3 2 bytes *
0x26 Color Modifier 4 2 bytes *
0x28 Color Matrix LR1 2 bytes *
0x2A Color Matrix LG1 2 bytes *
0x2C Color Matrix LB1 2 bytes *
0x2E Color Matrix LR2 2 bytes *
0x30 Color Matrix LG2 2 bytes *
0x32 Color Matrix LB2 2 bytes *
0x34 Color Matrix LR3 2 bytes *
0x36 Color Matrix LG3 2 bytes *
0x38 Color Matrix LB3 2 bytes *
0x3A Color Vector AR 2 bytes *
0x3C Color Vector AG 2 bytes *
0x3E Color Vector AB 2 bytes *
0x40 Self Link 4 bytes this
0x44 Parent 4 bytes *
0x48 Sibling 4 bytes *
0x4C Children (head child) 4 bytes *
0x50 Creator 4 bytes *
0x54 Player 4 bytes *
0x58 Collider 4 bytes *
0x5C Interrupter 4 bytes *
0x60 Trans x 4 bytes *
0x64 Trans y 4 bytes *
0x68 Trans z 4 bytes *
0x6C Rotation y 4 bytes *
0x70 Rotation x 4 bytes *
0x74 Rotation z 4 bytes *
0x78 Scale x 4 bytes *
0x7C Scale y 4 bytes *
0x80 Scale z 4 bytes *
0x84 Velocity x 4 bytes *
0x88 Velocity y 4 bytes *
0x8C Velocity z 4 bytes *
0x90 Target Rotation y 4 bytes *
0x94 Target Rotation x 4 bytes *
0x98 Target Rotation z 4 bytes *
0x9C Multi-Purpose Vector X 4 bytes *
0xA0 Multi-Purpose Vector Y 4 bytes *
0xA4 Multi-Purpose Vector Z 4 bytes *
0xA8 Status Flags A 4 bytes *
0xAC Status Flags B 4 bytes *
0xB0 Status Flags C 4 bytes *
0xB4 Subtype/Initial State 4 bytes *
0xB8 ID 4 bytes *
0xBC Stack Pointer 4 bytes *
0xC0 Program Counter (ins. pointer) 4 bytes *
0xC4 Frame Pointer 4 bytes *
0xC8 Trans Block Program Counter 4 bytes *
0xCC Event Block Program Counter 4 bytes *
0xD0 Head Block Program Counter 4 bytes *
0xD4 Various 4 bytes *
0xD8 Unknown 4 bytes *
0xDC Frame Change Timestamp 4 bytes *
0xE0 State Change Timestamp 4 bytes *
0xE4 Animation Lag Counter 4 bytes *
0xE8 Animation Sequence 4 bytes *
0xEC Animation Frame 4 bytes *
0xF0 Entity Spawned From 4 bytes *
0xF4 Path Progress 4 bytes *
0xF8 Path Length (point count) 4 bytes *
0xFC Ground y 4 bytes *
0x100 State Flags 4 bytes *
0x104 Speed 4 bytes *
0x108 Display Mode 4 bytes *
0x10C Unknown 4 bytes *
0x110 Timestamp of Most Recent Landing 4 bytes *
0x114 Velocity y at Most Recent Landing 4 bytes *
0x118 Z-Index 4 bytes *
0x11C Event Received 4 bytes *
0x120 Camera Zoom Factor 4 bytes *
0x124 Target Rotation Angle YZ plane 4 bytes *
0x128 Collision Hot-Spot Clip Amount 4 bytes *
0x12C Unknown 4 bytes *
0x130 Unknown 4 bytes *
0x134 Unknown 4 bytes *
0x138 Collision Node 4 bytes *
0x13C 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
0x1
object has been stopped by solid ground
2
0x2
?
3
0x4
0 = object is progressing forward along its path

1 = object is progressing backward along its path

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

1 = object was rotating clockwise

rotating objects only
5
0x10
object is transitioning from travelling forward to backward/vice versa along its path path travelling objects only
6
0x20
object has changed animation [i.e. first frame of animation] state change also assumes change in animation by setting this
7
0x40
?
8
0x80
object has been hit from the bottom set when collision check does not pass?
9
0x100
object is moving and not stopped by a wall
10
0x200
overrides the effect of displacement caused when bits 7 and 16 of status flags b are set, allowing the object to remain stationary
11
0x400
set when colliding with an octree node and it triggers event
12
0x800
cleared when spinning or changing direction, reset by sub_243A0
13
0x1000
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
0x2000
object is hitting a bounce box (for setting a higher acceleration)
15
0x4000
collider is crash
16
0x8000
object's bounding box needs recalculating
17
0x10000
? recipient process sets this bit when sent event 'crushed by boulder (and ?)' (0x1800, 0x1900)
18
0x20000
object has changed state
19
0x40000
object is on the ground
20
0x80000
? boxes set this at the end of their init routine
21
0x100000
set right after bounce from box/enemy?
22
0x200000
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
0x1
object rotates in XZ plane based on target rot angle (cleared during spin?)
2
0x2
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
0x4
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
0x8
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
0x10
object is collide-able (records space occupied by object and pointer to object in a pair during this frame)
6
0x20
object y velocity is affected by gravity
7
0x40
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
0x80
object [speed, velocity, and angular velocity] is controlled with the controller
9
0x100
object does not render ex. HUD offscreen, dying in water
10
0x200
object is 2 dimensional
11
0x400
text object has a backdrop
12
0x800
object auto banks along path curves path traveling objects only
13
0x1000
object has air resistance? (causes angvelocity to act as a velocity cap on both pos and neg velocities of its [absolute] value)
14
0x2000
object rotates in YZ plane to approach its target rot angle
15
0x4000
object treats XZ plane at Y given by field groundy as solid ground
16
0x8000
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
0x10000
object is solid at the sides
18
0x20000
object is solid at the top?
19
0x40000
disable frustum culling?
20
0x80000
object optionally rotates in XZ plane to approach its target rot angle
21
0x100000
object is shaded based on its parent zone, using the zone's color matrices
22
0x200000
?
23
0x400000
overrides an initial test in determining the highest object below the source? adds an additional 0x19000 in ground offset calculation? guess: stacked object
24
0x800000
?
25
0x1000000
object can not be terminated
26
0x2000000
always display and animate object
27
0x4000000
?
28
0x8000000
?
29
0x10000000
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
0x20000000
?
31
0x40000000
32
0x80000000
object is solid at the bottom? forces more elaborate screen culling check (based on object projected 2d area rather than projected 2d midpt)