Updated function names in ovl_En_Bom & added documentation from OoT (#1219)

* Updated function names in ovl_En_Bom & added documentation from OoT

* Renamed BombType struct members

* Updated instances of BOMB_BODY

* Updated more instances of BombType

---------

Co-authored-by: swinginman <swinginman@DESKTOP-V7R1DTC.localdomain>

4 files changed, 59 insertions, 47 deletions

diff --git a/src/overlays/actors/ovl_En_Bom/z_en_bom.c b/src/overlays/actors/ovl_En_Bom/z_en_bom.c
index 8532f8be9..bdc59540b 100644
--- a/src/overlays/actors/ovl_En_Bom/z_en_bom.c
+++ b/src/overlays/actors/ovl_En_Bom/z_en_bom.c
@@ -17,11 +17,12 @@ void EnBom_Destroy(Actor* thisx, PlayState* play);
 void EnBom_Update(Actor* thisx, PlayState* play);
 void EnBom_Draw(Actor* thisx, PlayState* play);
 
-void func_80871058(EnBom* this, PlayState* play);
-void func_808714D4(EnBom* this, PlayState* play);
+void EnBom_Move(EnBom* this, PlayState* play);
+void EnBom_WaitForRelease(EnBom* this, PlayState* play);
+
 void func_80872648(PlayState* play, Vec3f* arg1);
 void func_808726DC(PlayState* play, Vec3f* arg1, Vec3f* arg2, Vec3f* arg3, s32 arg4);
-void func_80872BC0(PlayState* play, s32 arg1);
+void EnBom_DrawKeg(PlayState* play, s32 arg1);
 
 typedef struct {
     /* 0x00 */ Vec3f pos;
@@ -173,11 +174,11 @@ void EnBom_Init(Actor* thisx, PlayState* play) {
     this->actor.flags |= ACTOR_FLAG_100000;
 
     if (Actor_HasParent(&this->actor, play)) {
-        this->actionFunc = func_808714D4;
+        this->actionFunc = EnBom_WaitForRelease;
         this->actor.room = -1;
         Actor_SetScale(&this->actor, enBomScales[this->isPowderKeg]);
     } else {
-        this->actionFunc = func_80871058;
+        this->actionFunc = EnBom_Move;
         gSaveContext.powderKegTimer = 0;
     }
 }
@@ -192,15 +193,16 @@ void EnBom_Destroy(Actor* thisx, PlayState* play) {
     }
 }
 
-void func_80871058(EnBom* this, PlayState* play) {
+void EnBom_Move(EnBom* this, PlayState* play) {
     static Vec3f D_80872E68[] = {
         { 2.0f, -6.0f, -0.3f },
         { 1.5f, -5.0f, -0.6f },
         { 0.2f, -6.0f, -0.1f },
     };
 
+    // if bomb has a parent actor, the bomb hasnt been released yet
     if (Actor_HasParent(&this->actor, play)) {
-        this->actionFunc = func_808714D4;
+        this->actionFunc = EnBom_WaitForRelease;
         this->actor.room = -1;
         return;
     }
@@ -209,6 +211,7 @@ void func_80871058(EnBom* this, PlayState* play) {
         this->actor.velocity.y = -this->actor.velocity.y;
     }
 
+    // rebound bomb off the wall it hits
     if ((this->actor.speed != 0.0f) && (this->actor.bgCheckFlags & BGCHECKFLAG_WALL)) {
         s16 yDiff = BINANG_SUB(this->actor.wallYaw, this->actor.world.rot.y);
 
@@ -298,9 +301,10 @@ void func_80871058(EnBom* this, PlayState* play) {
     Actor_MoveWithGravity(&this->actor);
 }
 
-void func_808714D4(EnBom* this, PlayState* play) {
+void EnBom_WaitForRelease(EnBom* this, PlayState* play) {
+    // if parent is NULL bomb has been released
     if (Actor_HasNoParent(&this->actor, play)) {
-        this->actionFunc = func_80871058;
+        this->actionFunc = EnBom_Move;
         this->actor.room = play->roomCtx.curRoom.num;
         this->actor.flags &= ~ACTOR_FLAG_100000;
         this->actor.bgCheckFlags &= ~BGCHECKFLAG_GROUND;
@@ -308,7 +312,7 @@ void func_808714D4(EnBom* this, PlayState* play) {
         if (this->isPowderKeg) {
             gSaveContext.powderKegTimer = 0;
         }
-        func_80871058(this, play);
+        EnBom_Move(this, play);
     } else {
         Math_Vec3f_ToVec3s(&this->actor.home.rot, &this->actor.parent->world.pos);
         if (this->isPowderKeg) {
@@ -318,7 +322,7 @@ void func_808714D4(EnBom* this, PlayState* play) {
     Math_ScaledStepToS(&this->unk_1FA, 0, 2000);
 }
 
-void func_808715B8(EnBom* this, PlayState* play) {
+void EnBom_Explode(EnBom* this, PlayState* play) {
     static s16 D_80872E8C[] = { 100, 200 };
     static Color_RGBA8 D_80872E90 = { 185, 140, 70, 255 };
     static Color_RGBA8 D_80872E94 = { 255, 255, 255, 255 };
@@ -347,7 +351,7 @@ void func_808715B8(EnBom* this, PlayState* play) {
         this->collider2.base.atFlags &= ~OC1_TYPE_1;
     }
 
-    if (this->actor.params == ENBOM_1) {
+    if (this->actor.params == BOMB_TYPE_EXPLOSION) {
         CollisionCheck_SetAT(play, &play->colChkCtx, &this->collider2.base);
     }
 
@@ -423,12 +427,12 @@ static s16 D_80872E98[] = { 3, 5 };
 static s16 D_80872E9C[] = { 10, 15 };
 
 void EnBom_Update(Actor* thisx, PlayState* play) {
-    Vec3f spA4 = { 0.0f, 0.0f, 0.0f };
-    Vec3f sp98 = { 0.0f, 0.1f, 0.0f };
-    Vec3f sp8C = { 0.0f, 0.0f, 0.0f };
-    Vec3f sp80;
-    Vec3f sp74 = { 0.0f, 0.6f, 0.0f };
-    Color_RGBA8 sp70 = { 255, 255, 255, 255 };
+    Vec3f effVelocity = { 0.0f, 0.0f, 0.0f };
+    Vec3f bomb2Accel = { 0.0f, 0.1f, 0.0f }; // unused
+    Vec3f effAccel = { 0.0f, 0.0f, 0.0f };
+    Vec3f effPos;
+    Vec3f dustAccel = { 0.0f, 0.6f, 0.0f };
+    Color_RGBA8 dustColor = { 255, 255, 255, 255 };
     EnBom* this = THIS;
     s32 pad;
     Player* player = GET_PLAYER(play);
@@ -456,7 +460,7 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
     } else {
         thisx->gravity = -1.2f;
         if (this->timer != 0) {
-            if (!this->isPowderKeg || (func_808715B8 == this->actionFunc) || !Play_InCsMode(play)) {
+            if (!this->isPowderKeg || (EnBom_Explode == this->actionFunc) || !Play_InCsMode(play)) {
                 this->timer--;
             }
         }
@@ -473,17 +477,18 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
         this->actionFunc(this, play);
 
         Actor_UpdateBgCheckInfo(play, thisx, 35.0f, 10.0f, 36.0f, 0x1F);
-        if (thisx->params == ENBOM_0) {
+        if (thisx->params == BOMB_TYPE_BODY) {
             static Vec3us D_80872ED4[] = {
                 { 40, 20, 100 },
                 { 300, 60, 600 },
             };
             Vec3us* sp60 = &D_80872ED4[this->isPowderKeg];
 
-            sp74.y = 0.2f;
-            Math_Vec3f_Copy(&sp80, &thisx->home.pos);
+            // spawn spark effect on even frames
+            dustAccel.y = 0.2f;
+            Math_Vec3f_Copy(&effPos, &thisx->home.pos);
             if ((play->gameplayFrames % 2) == 0) {
-                EffectSsGSpk_SpawnFuse(play, thisx, &sp80, &spA4, &sp8C);
+                EffectSsGSpk_SpawnFuse(play, thisx, &effPos, &effVelocity, &effAccel);
             }
             if (this->isPowderKeg) {
                 func_801A0810(&thisx->projectedPos, NA_SE_IT_BIG_BOMB_IGNIT - SFX_FLAG,
@@ -494,22 +499,27 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
                 Actor_PlaySfx(thisx, NA_SE_IT_BOMB_IGNIT - SFX_FLAG);
             }
 
-            sp80.y += 3.0f;
-            func_800B0DE0(play, &sp80, &spA4, &sp74, &sp70, &sp70, 50, 5);
+            effPos.y += 3.0f;
+            func_800B0DE0(play, &effPos, &effVelocity, &dustAccel, &dustColor, &dustColor, 50, 5);
 
             if ((this->collider1.base.acFlags & AC_HIT) ||
                 ((this->collider1.base.ocFlags1 & OC1_HIT) && ((this->collider1.base.oc->category == ACTORCAT_ENEMY) ||
                                                                (this->collider1.base.oc->category == ACTORCAT_BOSS)))) {
                 this->timer = 0;
                 thisx->shape.rot.z = 0;
-            } else if ((this->timer > 100) && (Player_IsBurningStickInRange(play, &thisx->world.pos, 30.0f, 50.0f))) {
-                this->timer = 100;
+            } else {
+                // if a lit stick touches the bomb, set timer to 100
+                // these bombs never have a timer over 70, so this isn't used
+                if ((this->timer > 100) && Player_IsBurningStickInRange(play, &thisx->world.pos, 30.0f, 50.0f)) {
+                    this->timer = 100;
+                }
             }
 
-            sp74.y = 0.2f;
-            sp80 = thisx->world.pos;
-            sp80.y += 10.0f;
+            dustAccel.y = 0.2f;
+            effPos = thisx->world.pos;
+            effPos.y += 10.0f;
 
+            // double bomb flash speed and adjust red color at certain times during the countdown
             if ((this->timer == sp60->x) || (this->timer == sp60->y) || (this->timer == 3)) {
                 thisx->shape.rot.z = 0;
                 this->flashSpeedScale >>= 1;
@@ -526,12 +536,12 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
             }
 
             if (this->timer == 0) {
-                sp80 = thisx->world.pos;
-                sp80.y += 10.0f;
+                effPos = thisx->world.pos;
+                effPos.y += 10.0f;
                 if (Actor_HasParent(thisx, play)) {
-                    sp80.y += 30.0f;
+                    effPos.y += 30.0f;
                 }
-                Actor_Spawn(&play->actorCtx, play, ACTOR_EN_CLEAR_TAG, sp80.x, sp80.y - 10.0f, sp80.z, 0, 0, 0,
+                Actor_Spawn(&play->actorCtx, play, ACTOR_EN_CLEAR_TAG, effPos.x, effPos.y - 10.0f, effPos.z, 0, 0, 0,
                             this->isPowderKeg);
                 func_800BC848(thisx, play, D_80872E98[this->isPowderKeg], D_80872E9C[this->isPowderKeg]);
                 play->envCtx.lightSettings.diffuseColor1[0] = play->envCtx.lightSettings.diffuseColor1[1] =
@@ -539,10 +549,10 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
                 play->envCtx.lightSettings.ambientColor[0] = play->envCtx.lightSettings.ambientColor[1] =
                     play->envCtx.lightSettings.ambientColor[2] = 250;
                 Camera_AddQuake(&play->mainCamera, 2, 11, 8);
-                thisx->params = ENBOM_1;
+                thisx->params = BOMB_TYPE_EXPLOSION;
                 this->timer = 10;
                 thisx->flags |= (ACTOR_FLAG_20 | ACTOR_FLAG_100000);
-                this->actionFunc = func_808715B8;
+                this->actionFunc = EnBom_Explode;
                 if (this->isPowderKeg) {
                     gSaveContext.powderKegTimer = 0;
                     Actor_PlaySfx(thisx, NA_SE_IT_BIG_BOMB_EXPLOSION);
@@ -554,15 +564,17 @@ void EnBom_Update(Actor* thisx, PlayState* play) {
 
         Actor_SetFocus(thisx, 20.0f);
 
-        if (thisx->params <= ENBOM_0) {
+        if (thisx->params <= BOMB_TYPE_BODY) {
             Collider_UpdateCylinder(thisx, &this->collider1);
+
+            // if link is not holding the bomb anymore and bump conditions are met, subscribe to OC
             if (!Actor_HasParent(thisx, play) && (this->unk_1F8 != 0)) {
                 CollisionCheck_SetOC(play, &play->colChkCtx, &this->collider1.base);
             }
             CollisionCheck_SetAC(play, &play->colChkCtx, &this->collider1.base);
         }
 
-        if ((enBomScales[this->isPowderKeg] <= thisx->scale.x) && (thisx->params != ENBOM_1)) {
+        if ((enBomScales[this->isPowderKeg] <= thisx->scale.x) && (thisx->params != BOMB_TYPE_EXPLOSION)) {
             if (thisx->depthInWater >= 20.0f) {
                 Vec3f sp54;
 
@@ -600,7 +612,7 @@ void EnBom_Draw(Actor* thisx, PlayState* play) {
 
     OPEN_DISPS(play->state.gfxCtx);
 
-    if (this->actor.params == ENBOM_0) {
+    if (this->actor.params == BOMB_TYPE_BODY) {
         func_8012C28C(play->state.gfxCtx);
 
         Collider_UpdateSpheres(0, &this->collider2);
@@ -644,7 +656,7 @@ void EnBom_Draw(Actor* thisx, PlayState* play) {
             gSPDisplayList(POLY_OPA_DISP++, gPowderKegGoronSkullDL);
 
             func_808726DC(play, &this->actor.home.pos, &sp58, &sp4C, this->timer);
-            func_80872BC0(play, this->timer);
+            EnBom_DrawKeg(play, this->timer);
         }
     }
 
@@ -768,7 +780,7 @@ void func_808726DC(PlayState* play, Vec3f* arg1, Vec3f* arg2, Vec3f* arg3, s32 a
     Math_Vec3f_Copy(arg1, &fuseSegmentPtr->pos);
 }
 
-void func_80872BC0(PlayState* play, s32 arg1) {
+void EnBom_DrawKeg(PlayState* play, s32 arg1) {
     s32 temp_s5;
     s32 i;
     PowderKegFuseSegment* fuseSegmentPtr = &sPowderKegFuseSegments[0];
diff --git a/src/overlays/actors/ovl_En_Bom/z_en_bom.h b/src/overlays/actors/ovl_En_Bom/z_en_bom.h
index 23218a183..bf568cd6a 100644
--- a/src/overlays/actors/ovl_En_Bom/z_en_bom.h
+++ b/src/overlays/actors/ovl_En_Bom/z_en_bom.h
@@ -11,10 +11,10 @@ typedef void (*EnBomActionFunc)(struct EnBom*, PlayState*);
 #define ENBOM_GETZ_80(thisx) ((thisx)->shape.rot.z & 0x80)
 #define ENBOM_GETZ_FF00(thisx) (((thisx)->shape.rot.z & 0xFF00) >> 8)
 
-enum {
-    /* 0 */ ENBOM_0,
-    /* 1 */ ENBOM_1,
-};
+typedef enum {
+    /* 0 */ BOMB_TYPE_BODY,
+    /* 1 */ BOMB_TYPE_EXPLOSION,
+} BombType;
 
 typedef struct EnBom {
     /* 0x000 */ Actor actor;
diff --git a/src/overlays/actors/ovl_En_Famos/z_en_famos.c b/src/overlays/actors/ovl_En_Famos/z_en_famos.c
index 1be1d1700..932d937ee 100644
--- a/src/overlays/actors/ovl_En_Famos/z_en_famos.c
+++ b/src/overlays/actors/ovl_En_Famos/z_en_famos.c
@@ -691,7 +691,7 @@ void EnFamos_DeathExplosion(EnFamos* this, PlayState* play) {
     if (this->stateTimer == 1) {
         EnBom* explosion =
             (EnBom*)Actor_Spawn(&play->actorCtx, play, ACTOR_EN_BOM, this->actor.world.pos.x,
-                                this->actor.world.pos.y + 40.0f, this->actor.world.pos.z, 0, 0, 0, ENBOM_0);
+                                this->actor.world.pos.y + 40.0f, this->actor.world.pos.z, 0, 0, 0, BOMB_TYPE_BODY);
         if (explosion != NULL) {
             explosion->timer = 0; // instant explosion
         }
diff --git a/src/overlays/actors/ovl_En_Rat/z_en_rat.c b/src/overlays/actors/ovl_En_Rat/z_en_rat.c
index 85df7e9d2..63ef35aab 100644
--- a/src/overlays/actors/ovl_En_Rat/z_en_rat.c
+++ b/src/overlays/actors/ovl_En_Rat/z_en_rat.c
@@ -740,7 +740,7 @@ void EnRat_Bounced(EnRat* this, PlayState* play) {
 
 void EnRat_Explode(EnRat* this, PlayState* play) {
     EnBom* bomb = (EnBom*)Actor_Spawn(&play->actorCtx, play, ACTOR_EN_BOM, this->actor.world.pos.x,
-                                      this->actor.world.pos.y, this->actor.world.pos.z, 0, 0, 0, ENBOM_0);
+                                      this->actor.world.pos.y, this->actor.world.pos.z, 0, 0, 0, BOMB_TYPE_BODY);
 
     if (bomb != NULL) {
         bomb->timer = 0;