Document render/update objects (#565)

* Document objects related code.
  * Including render/update objects code
* Various renamings

4 files changed, 104 insertions, 92 deletions

diff --git a/include/actor_types.h b/include/actor_types.h
index ccf405c72..1579a5300 100644
--- a/include/actor_types.h
+++ b/include/actor_types.h
@@ -9,70 +9,71 @@
 //#pragma GCC diagnostic ignored "-Wmicrosoft-extension"
 //#pragma GCC diagnostic ignored "-Wmissing-member-name-in-structure-/-union"
 
-/*
-gActorList should be understood to be populated by generic Actor structs.
-However, for human readability, many functions interacting with actor list elements expect one of the many
-specialized types found in this file.
-
-Note that specialized types must be the same size as a plain Actor. Don't be mislead into thinking that
-because its a separate type that it can modified separately from plain Actor. If you modify/add an actor type
-and its size is different from plain Actor's, you WILL run into buggy (potentially crash inducing) behaviour.
-
-Specialized structs are customizable so long as the following member specifications are met:
-
-In general:
-    0x00 -> s16 type
-    0x02 -> s16 flags
-    0x30 -> Collision unk30
-
-If player can collide with the actor:
-    0x0C -> f32 boundingBoxSize
-
-If the actor makes sound (necessary for doppler/volume stuff):
-    0x18 -> Vec3f pos
-    0x24 -> Vec3f velocity
-
-Other members are more flexible, and even the non-general specifications can be ignored IF AND ONLY IF you know
-exactly what you're doing.
-*/
-
-#define ACTOR_TREE_MARIO_RACEWAY       0x02
-#define ACTOR_TREE_YOSHI_VALLEY        0x03
-#define ACTOR_TREE_ROYAL_RACEWAY       0x04
-#define ACTOR_FALLING_ROCK             0x05
-#define ACTOR_BANANA                   0x06
-#define ACTOR_GREEN_SHELL              0x07
-#define ACTOR_RED_SHELL                0x08
-#define ACTOR_YOSHI_VALLEY_EGG         0x09
-#define ACTOR_PIRANHA_PLANT            0x0A
-#define ACTOR_ITEM_BOX                 0x0C
-#define ACTOR_FAKE_ITEM_BOX            0x0D
-#define ACTOR_BANANA_BUNCH             0x0E
-#define ACTOR_TRAIN_ENGINE             0x0F
-#define ACTOR_TRAIN_TENDER             0x10
-#define ACTOR_TRAIN_PASSENGER_CAR      0x11
-#define ACTOR_COW                      0x12
-#define ACTOR_TREE_MOO_MOO_FARM        0x13
-#define ACTOR_TRIPLE_GREEN_SHELL       0x15
-#define ACTOR_TRIPLE_RED_SHELL         0x16
-#define ACTOR_MARIO_RACEWAY_SIGN       0x17
-#define ACTOR_PALM_TREE                0x19
-#define ACTOR_TREE_BOWSERS_CASTLE      0x1C
-#define ACTOR_TREE_FRAPPE_SNOWLAND     0x1D
-#define ACTOR_CACTUS1_KALAMARI_DESERT  0x1E
-#define ACTOR_CACTUS2_KALAMARI_DESERT  0x1F
-#define ACTOR_CACTUS3_KALAMARI_DESERT  0x20
-#define ACTOR_BUSH_BOWSERS_CASTLE      0x21
-#define ACTOR_WARIO_STADIUM_SIGN       0x23
-#define ACTOR_BOX_TRUCK                0x25
-#define ACTOR_PADDLE_WHEEL_BOAT        0x26
-#define ACTOR_RAILROAD_CROSSING        0x27
-#define ACTOR_SCHOOL_BUS               0x28
-#define ACTOR_TANKER_TRUCK             0x29
-#define ACTOR_BLUE_SPINY_SHELL         0x2A
-#define ACTOR_HOT_AIR_BALLOON_ITEM_BOX 0x2B
-#define ACTOR_CAR                      0x2C
-#define ACTOR_KIWANO_FRUIT             0x2D
+/**
+ * gActorList should be understood to be populated by generic Actor structs.
+ * However, for human readability, many functions interacting with actor list elements expect one of the many
+ * specialized types found in this file.
+ * 
+ * Note that specialized types must be the same size as a plain Actor. Don't be mislead into thinking that
+ * because its a separate type that it can modified separately from plain Actor. If you modify/add an actor type
+ * and its size is different from plain Actor's, you WILL run into buggy (potentially crash inducing) behaviour.
+ * 
+ * Specialized structs are customizable so long as the following member specifications are met:
+ * 
+ * In general:
+ *     0x00 -> s16 type
+ *     0x02 -> s16 flags
+ *     0x30 -> Collision unk30
+ * 
+ * If player can collide with the actor:
+ *     0x0C -> f32 boundingBoxSize
+ * 
+ * If the actor makes sound (necessary for doppler/volume stuff):
+ *     0x18 -> Vec3f pos
+ *     0x24 -> Vec3f velocity
+ * 
+ * Other members are more flexible, and even the non-general specifications can be ignored IF AND ONLY IF you know
+ * exactly what you're doing.
+ */
+enum ActorType {
+    ACTOR_TREE_MARIO_RACEWAY = 0x02,
+    ACTOR_TREE_YOSHI_VALLEY,
+    ACTOR_TREE_ROYAL_RACEWAY,
+    ACTOR_FALLING_ROCK,
+    ACTOR_BANANA,
+    ACTOR_GREEN_SHELL,
+    ACTOR_RED_SHELL,
+    ACTOR_YOSHI_VALLEY_EGG,
+    ACTOR_PIRANHA_PLANT,
+    ACTOR_ITEM_BOX = 0x0C,
+    ACTOR_FAKE_ITEM_BOX,
+    ACTOR_BANANA_BUNCH,
+    ACTOR_TRAIN_ENGINE,
+    ACTOR_TRAIN_TENDER,
+    ACTOR_TRAIN_PASSENGER_CAR,
+    ACTOR_COW,
+    ACTOR_TREE_MOO_MOO_FARM,
+    ACTOR_TRIPLE_GREEN_SHELL = 0x15,
+    ACTOR_TRIPLE_RED_SHELL,
+    ACTOR_MARIO_SIGN,
+    ACTOR_PALM_TREE = 0x19,
+    ACTOR_TREE_BOWSERS_CASTLE = 0x1C,
+    ACTOR_TREE_FRAPPE_SNOWLAND,
+    ACTOR_CACTUS1_KALAMARI_DESERT,
+    ACTOR_CACTUS2_KALAMARI_DESERT,
+    ACTOR_CACTUS3_KALAMARI_DESERT,
+    ACTOR_BUSH_BOWSERS_CASTLE,
+    ACTOR_WARIO_SIGN = 0x23,
+    ACTOR_BOX_TRUCK = 0x25,
+    ACTOR_PADDLE_BOAT,
+    ACTOR_RAILROAD_CROSSING,
+    ACTOR_SCHOOL_BUS,
+    ACTOR_TANKER_TRUCK,
+    ACTOR_BLUE_SPINY_SHELL,
+    ACTOR_HOT_AIR_BALLOON_ITEM_BOX,
+    ACTOR_CAR,
+    ACTOR_KIWANO_FRUIT,
+};
 
 #define ACTOR_LIST_SIZE 100
 
@@ -80,23 +81,29 @@ exactly what you're doing.
 #define ACTOR_IS_NOT_EXPIRED 0xF // The actor possesses some kind of collision and can be removed
 
 // Actor shell->state (green, red and blue)
-#define HELD_SHELL 0 // Single shell that has not been dropped. (probably holding Z).
-#define RELEASED_SHELL 1 // This is the short window where single shells aren't being held or launched.
-#define MOVING_SHELL 2 // Moving towards its target after being shot.
-#define RED_SHELL_LOCK_ON 3 // Red shell is targeting.
-#define TRIPLE_GREEN_SHELL 4 // Loses triple shell state when shot.
-#define GREEN_SHELL_HIT_A_RACER 5 // A racer has been hit by a green shell.
-#define TRIPLE_RED_SHELL 6 // Loses triple shell state when shot.
-#define DESTROYED_SHELL 7 // Collision with the shell.
-#define BLUE_SHELL_LOCK_ON 8 // A blue shell has found a target and is hastily approaching it.
-#define BLUE_SHELL_TARGET_ELIMINATED 9 // Mission completed, well done boss.
+enum ShellState {
+    HELD_SHELL,                   // Single shell that has not been dropped. (probably holding Z).
+    RELEASED_SHELL,               // This is the short window where single shells aren't being held or launched.
+    MOVING_SHELL,                 // Moving towards its target after being shot.
+    RED_SHELL_LOCK_ON,            // Red shell is targeting.
+    TRIPLE_GREEN_SHELL,           // Loses triple shell state when shot.
+    GREEN_SHELL_HIT_A_RACER,      // A racer has been hit by a green shell.
+    TRIPLE_RED_SHELL,             // Loses triple shell state when shot.
+    DESTROYED_SHELL,              // Collision with the shell.
+    BLUE_SHELL_LOCK_ON,           // A blue shell has found a target and is hastily approaching it.
+    BLUE_SHELL_TARGET_ELIMINATED, // Mission completed, well done boss.
+};
+
 // Actor banana->state
-#define HELD_BANANA 0 // Single banana that has not been dropped.
-#define DROPPED_BANANA 1 // A banana in the state of being dropped on the ground (it only last for a few frames).
-#define FIRST_BANANA_BUNCH_BANANA 2 // The first banana of the banana bunch
-#define BANANA_BUNCH_BANANA 3 // Every banana of the banana bunch except the first one.
-#define BANANA_ON_GROUND 4 // A banana sitting on the ground.
-#define DESTROYED_BANANA 5 // Collision with the banana.
+enum BananaState {
+    HELD_BANANA,               // Single banana that has not been dropped.
+    DROPPED_BANANA,            // A banana in the state of being dropped on the ground (it only last for a few frames).
+    FIRST_BANANA_BUNCH_BANANA, // The first banana of the banana bunch
+    BANANA_BUNCH_BANANA,       // Every banana of the banana bunch except the first one.
+    BANANA_ON_GROUND,          // A banana sitting on the ground.
+    DESTROYED_BANANA,          // Collision with the banana.
+};
+
 // Actor fakeItemBox->state
 #define HELD_FAKE_ITEM_BOX 0 // Item box is being held be Z.
 #define FAKE_ITEM_BOX_ON_GROUND 1 // Item box is on the ground.
diff --git a/include/bomb_kart.h b/include/bomb_kart.h
index df8fa073f..9987099af 100644
--- a/include/bomb_kart.h
+++ b/include/bomb_kart.h
@@ -52,7 +52,7 @@ typedef struct {
 } BombKart; // size = 0x54
 
 //! Indexes for the objects associated with the Bomb Karts
-extern s32 D_80183DD8[NUM_BOMB_KARTS_MAX];
+extern s32 gIndexObjectBombKart[NUM_BOMB_KARTS_MAX];
 
 extern BombKart gBombKarts[NUM_BOMB_KARTS_MAX];
 extern Collision D_80164038[NUM_BOMB_KARTS_MAX];
diff --git a/include/objects.h b/include/objects.h
index 84d71873d..88dc9a7a8 100644
--- a/include/objects.h
+++ b/include/objects.h
@@ -13,14 +13,14 @@ typedef struct
     /* 0x04 */ Vec3f pos;
     /* 0x10 */ Vec3f origin_pos;
     /* 0x1C */ Vec3f unk_01C;
-    /* 0x28 */ Vec3f unk_028;
+    /* 0x28 */ Vec3f offset;
     /* 0x34 */ f32 unk_034;
-    /* 0x38 */ Vec3f velocity;
+    /* 0x38 */ Vec3f velocity; // acceleration
     /* 0x44 */ f32 unk_044;
     /* 0x48 */ s32 unk_048;
     /* 0x4C */ s32 unk_04C;
     /* 0x50 */ s32 unk_050;
-    /* 0x54 */ s32 unk_054;
+    /* 0x54 */ s32 status;
     /* 0x58 */ s32 unk_058;
     /* 0x5C */ s32 unk_05C;
     /* 0x60 */ u8 *activeTLUT;
@@ -42,7 +42,7 @@ typedef struct
     /* 0x9A */ u16 unk_09A;
     /* 0x9C */ s16 unk_09C;
     /* 0x9E */ s16 unk_09E;
-    /* 0xA0 */ s16 unk_0A0;
+    /* 0xA0 */ s16 primAlpha;
     /* 0xA2 */ s16 unk_0A2;
     /* 0xA4 */ s16 type;
     /* 0xA6 */ s16 state;
@@ -89,14 +89,14 @@ typedef struct
     /* 0x04 */ Vec3f pos;
     /* 0x10 */ Vec3f origin_pos;
     /* 0x1C */ Vec3f unk_01C;
-    /* 0x28 */ Vec3f unk_028;
+    /* 0x28 */ Vec3f offset;
     /* 0x34 */ f32 unk_034;
     /* 0x38 */ Vec3f velocity;
     /* 0x44 */ f32 unk_044;
     /* 0x48 */ s32 unk_048;
     /* 0x4C */ s32 unk_04C;
     /* 0x50 */ s32 unk_050;
-    /* 0x54 */ s32 unk_054;
+    /* 0x54 */ s32 status;
     /* 0x58 */ s32 unk_058;
     /* 0x5C */ s32 unk_05C;
     /* 0x60 */ u8 *activeTLUT;
@@ -118,7 +118,7 @@ typedef struct
     /* 0x9A */ u16 unk_09A;
     /* 0x9C */ s16 unk_09C;
     /* 0x9E */ s16 unk_09E;
-    /* 0xA0 */ s16 unk_0A0;
+    /* 0xA0 */ s16 primAlpha;
     /* 0xA2 */ s16 unk_0A2;
     /* 0xA4 */ s16 currentItem;
     /* 0xA6 */ s16 itemDisplayState; // Usually a state tracker
@@ -160,6 +160,11 @@ typedef struct
 // This are other lists of indices in gObjectList.
 
 /**
+ * @brief Status flags for objects
+ */
+#define VISIBLE 0x00040000
+
+/**
  * Use unknown. An object is reserved and its index is saved to
  * this variable, but it appears to go unreferenced
  **/
diff --git a/include/vehicles.h b/include/vehicles.h
index 8c8bf2ef5..ff1fa3b35 100644
--- a/include/vehicles.h
+++ b/include/vehicles.h
@@ -11,8 +11,8 @@
 #define LOCOMOTIVE_ONLY           0
 
 // It seems like there's room for 2 Ferries, but only 1 is ever active
-#define NUM_ACTIVE_PADDLE_WHEEL_BOATS 1
-#define NUM_PADDLE_WHEEL_BOATS 2
+#define NUM_ACTIVE_PADDLE_BOATS 1
+#define NUM_PADDLE_BOATS 2
 
 #define NUM_RACE_BOX_TRUCKS    7
 #define NUM_RACE_SCHOOL_BUSES  7
@@ -59,7 +59,7 @@ typedef struct {
 	 * Probably audio related
 	 **/
 	/* 0x28 */ s32 someFlags;
-} PaddleWheelBoatStuff; // size = 0x2C
+} PaddleBoatStuff; // size = 0x2C
 
 typedef struct {
 	/* 0x00 */ s16 unused; // Gets set to 0, but doesn't seem to have any purpose
@@ -85,7 +85,7 @@ typedef struct {
 extern TrainStuff gTrainList[];
 
 // This is an array, maybe they intended to have multiple boats at some point in development?
-extern PaddleWheelBoatStuff gFerries[];
+extern PaddleBoatStuff gPaddleBoats[];
 
 // Lists for different vehicles in Toad's Turnpike
 extern VehicleStuff gBoxTruckList[];