document code_8008E6A0 (frame advance) (#737)

* OK

* fixes

* format

* remove gotos, thanks petrie

7 files changed, 43 insertions, 50 deletions

diff --git a/src/code/code_8008E6A0.c b/src/code/code_8008E6A0.c
deleted file mode 100644
index a04598b53..000000000
--- a/src/code/code_8008E6A0.c
+++ /dev/null
@@ -1,36 +0,0 @@
-#include "global.h"
-
-void func_8008E6A0(SubGlobalContext7B8* this) {
-    this->counter = 0;
-    this->toggle = false;
-}
-
-u32 func_8008E6AC(SubGlobalContext7B8* this, Input* input) {
-    if (CHECK_BTN_ALL(input->cur.button, BTN_R) && CHECK_BTN_ALL(input->press.button, BTN_DDOWN)) {
-        this->toggle = !this->toggle;
-    }
-    if (!this->toggle) {
-        goto ret_true;
-    }
-
-    if (CHECK_BTN_ALL(input->cur.button, BTN_Z)) {
-        if (CHECK_BTN_ALL(input->press.button, BTN_R)) {
-            goto ret_true;
-        }
-        if (CHECK_BTN_ALL(input->cur.button, BTN_R)) {
-            this->counter++;
-            if (this->counter >= 9) {
-                goto ret_true;
-            }
-        }
-    }
-
-    goto ret_false;
-
-ret_true:
-    this->counter = 0;
-    return true;
-
-ret_false:
-    return false;
-}
diff --git a/src/code/z_collision_check.c b/src/code/z_collision_check.c
index b5a8e9f2e..b66aeda0d 100644
--- a/src/code/z_collision_check.c
+++ b/src/code/z_collision_check.c
@@ -1189,7 +1189,7 @@ static ColChkResetFunc sATResetFuncs[] = {
 s32 CollisionCheck_SetAT(GlobalContext* globalCtx, CollisionCheckContext* colChkCtx, Collider* collider) {
     s32 index;
 
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     if (!(collider->shape <= COLSHAPE_QUAD)) {
@@ -1223,7 +1223,7 @@ s32 CollisionCheck_SetAT_SAC(GlobalContext* globalCtx, CollisionCheckContext* co
     if (!(collider->shape <= COLSHAPE_QUAD)) {
         __assert("pcl_obj->data_type <= CL_DATA_LBL_SWRD", "../z_collision_check.c", 3037);
     }
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     sATResetFuncs[collider->shape](globalCtx, collider);
@@ -1263,7 +1263,7 @@ static ColChkResetFunc sACResetFuncs[] = {
 s32 CollisionCheck_SetAC(GlobalContext* globalCtx, CollisionCheckContext* colChkCtx, Collider* collider) {
     s32 index;
 
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     if (!(collider->shape <= COLSHAPE_QUAD)) {
@@ -1296,7 +1296,7 @@ s32 CollisionCheck_SetAC_SAC(GlobalContext* globalCtx, CollisionCheckContext* co
     if (!(collider->shape <= COLSHAPE_QUAD)) {
         __assert("pcl_obj->data_type <= CL_DATA_LBL_SWRD", "../z_collision_check.c", 3153);
     }
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     sACResetFuncs[collider->shape](globalCtx, collider);
@@ -1336,7 +1336,7 @@ static ColChkResetFunc sOCResetFuncs[] = {
 s32 CollisionCheck_SetOC(GlobalContext* globalCtx, CollisionCheckContext* colChkCtx, Collider* collider) {
     s32 index;
 
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     if (!(collider->shape <= COLSHAPE_QUAD)) {
@@ -1366,7 +1366,7 @@ s32 CollisionCheck_SetOC(GlobalContext* globalCtx, CollisionCheckContext* colChk
  */
 s32 CollisionCheck_SetOC_SAC(GlobalContext* globalCtx, CollisionCheckContext* colChkCtx, Collider* collider,
                              s32 index) {
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     if (!(collider->shape <= COLSHAPE_QUAD)) {
@@ -1403,7 +1403,7 @@ s32 CollisionCheck_SetOC_SAC(GlobalContext* globalCtx, CollisionCheckContext* co
 s32 CollisionCheck_SetOCLine(GlobalContext* globalCtx, CollisionCheckContext* colChkCtx, OcLine* collider) {
     s32 index;
 
-    if (func_800C0D28(globalCtx) == 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) == true) {
         return -1;
     }
     Collider_ResetLineOC(globalCtx, collider);
diff --git a/src/code/z_effect.c b/src/code/z_effect.c
index 8bef699ad..391f1c204 100644
--- a/src/code/z_effect.c
+++ b/src/code/z_effect.c
@@ -104,7 +104,7 @@ void Effect_Add(GlobalContext* globalCtx, s32* pIndex, s32 type, u8 arg3, u8 arg
 
     *pIndex = TOTAL_EFFECT_COUNT;
 
-    if (func_800C0D28(globalCtx) != 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) != true) {
         slotFound = false;
         switch (type) {
             case EFFECT_SPARK:
diff --git a/src/code/z_effect_soft_sprite.c b/src/code/z_effect_soft_sprite.c
index 24512194d..7183152f9 100644
--- a/src/code/z_effect_soft_sprite.c
+++ b/src/code/z_effect_soft_sprite.c
@@ -158,7 +158,7 @@ s32 EffectSs_FindSlot(s32 priority, s32* pIndex) {
 void EffectSs_Insert(GlobalContext* globalCtx, EffectSs* effectSs) {
     s32 index;
 
-    if (func_800C0D28(globalCtx) != 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) != true) {
         if (EffectSs_FindSlot(effectSs->priority, &index) == 0) {
             sEffectSsInfo.searchStartIndex = index + 1;
             sEffectSsInfo.table[index] = *effectSs;
diff --git a/src/code/z_frame_advance.c b/src/code/z_frame_advance.c
new file mode 100644
index 000000000..caf33fafb
--- /dev/null
+++ b/src/code/z_frame_advance.c
@@ -0,0 +1,29 @@
+#include "global.h"
+
+void FrameAdvance_Init(FrameAdvanceContext* frameAdvCtx) {
+    frameAdvCtx->timer = 0;
+    frameAdvCtx->enabled = false;
+}
+
+/**
+ * Frame advance allows you to advance through the game one frame at a time on command.
+ * To enable, hold R and press Dpad Down on the provided controller.
+ * To advance a frame, hold Z and press R.
+ * Holding Z and R will advance a frame every half second.
+ *
+ * This function returns true when frame advance is not active (game will run normally)
+ */
+s32 FrameAdvance_Update(FrameAdvanceContext* frameAdvCtx, Input* input) {
+    if (CHECK_BTN_ALL(input->cur.button, BTN_R) && CHECK_BTN_ALL(input->press.button, BTN_DDOWN)) {
+        frameAdvCtx->enabled = !frameAdvCtx->enabled;
+    }
+
+    if (!frameAdvCtx->enabled || (CHECK_BTN_ALL(input->cur.button, BTN_Z) &&
+                                  (CHECK_BTN_ALL(input->press.button, BTN_R) ||
+                                   (CHECK_BTN_ALL(input->cur.button, BTN_R) && (++frameAdvCtx->timer >= 9))))) {
+        frameAdvCtx->timer = 0;
+        return true;
+    }
+    
+    return false;
+}
diff --git a/src/code/z_play.c b/src/code/z_play.c
index 79526d77e..528e2e0b6 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -328,7 +328,7 @@ void Gameplay_Init(GameState* thisx) {
     PreRender_SetValues(&globalCtx->preRenderCtx, SCREEN_WIDTH, SCREEN_HEIGHT, 0, 0);
     gTrnsnUnkState = 0;
     globalCtx->transitionMode = 0;
-    func_8008E6A0(&globalCtx->sub_7B8);
+    FrameAdvance_Init(&globalCtx->frameAdvCtx);
     Rand_Seed((u32)osGetTime());
     Matrix_Init(&globalCtx->state);
     globalCtx->state.main = Gameplay_Main;
@@ -442,7 +442,7 @@ void Gameplay_Update(GlobalContext* globalCtx) {
     gSegments[5] = VIRTUAL_TO_PHYSICAL(globalCtx->objectCtx.status[globalCtx->objectCtx.subKeepIndex].segment);
     gSegments[2] = VIRTUAL_TO_PHYSICAL(globalCtx->sceneSegment);
 
-    if (func_8008E6AC(&globalCtx->sub_7B8, &input[1]) != 0) {
+    if (FrameAdvance_Update(&globalCtx->frameAdvCtx, &input[1])) {
         if ((globalCtx->transitionMode == 0) && (globalCtx->sceneLoadFlag != 0)) {
             globalCtx->transitionMode = 1;
         }
@@ -1773,8 +1773,8 @@ s32 func_800C0CB8(GlobalContext* globalCtx) {
            (YREG(15) != 0x40) && (globalCtx->sceneNum != SCENE_HAIRAL_NIWA);
 }
 
-s32 func_800C0D28(GlobalContext* globalCtx) {
-    return (globalCtx->sub_7B8.toggle != 0);
+s32 FrameAdvance_IsEnabled(GlobalContext* globalCtx) {
+    return !!globalCtx->frameAdvCtx.enabled;
 }
 
 s32 func_800C0D34(GlobalContext* globalCtx, Actor* actor, s16* yaw) {
diff --git a/src/code/z_scene_table.c b/src/code/z_scene_table.c
index b21b43379..df06db515 100644
--- a/src/code/z_scene_table.c
+++ b/src/code/z_scene_table.c
@@ -2327,7 +2327,7 @@ void func_8009FE58(GlobalContext* globalCtx) {
     gDPPipeSync(POLY_XLU_DISP++);
     gDPSetEnvColor(POLY_XLU_DISP++, 128, 128, 128, 128);
 
-    if (func_800C0D28(globalCtx) != 1) {
+    if (FrameAdvance_IsEnabled(globalCtx) != true) {
         D_8012A39C += 1820;
         D_8012A3A0 += 1820;