Document pause page switching (#1550)

* Document pause page switching

* document initial scroll left setup, when opening the pause menu

* `PAUSE_MAIN_STATE_1` -> `PAUSE_MAIN_STATE_SWITCHING_PAGE`

* try a diagram of the pages layout in world space as a comment

* expand `nextPageMode` comment

* touch up pause camera header comments

* expand comment on irrelevant init `mainState = PAUSE_MAIN_STATE_SWITCHING_PAGE`

* expand doc on `sKaleidoSetup*` data

* expand docs on `gPageSwitchNextButtonStatus`

* add some doc on `sPageSwitch*` arrays

* SwitchPage -> PageSwitch

* add `PAGE_SWITCH_NSTEPS`

* `SWITCH_PAGE_*_PT` -> `PAGE_SWITCH_PT_*`

* peepoArtist

---------

Co-authored-by: fig02 <fig02srl@gmail.com>

1 files changed, 75 insertions, 20 deletions

diff --git a/src/code/z_kaleido_setup.c b/src/code/z_kaleido_setup.c
index 871adabf1..36a01c123 100644
--- a/src/code/z_kaleido_setup.c
+++ b/src/code/z_kaleido_setup.c
@@ -1,12 +1,58 @@
 #include "global.h"
 
-s16 sKaleidoSetupKscpPos0[] = { PAUSE_QUEST, PAUSE_EQUIP, PAUSE_ITEM, PAUSE_MAP };
-f32 sKaleidoSetupEyeX0[] = { 0.0f, 64.0f, 0.0f, -64.0f };
-f32 sKaleidoSetupEyeZ0[] = { -64.0f, 0.0f, 64.0f, 0.0f };
-
-s16 sKaleidoSetupKscpPos1[] = { PAUSE_MAP, PAUSE_QUEST, PAUSE_EQUIP, PAUSE_ITEM };
-f32 sKaleidoSetupEyeX1[] = { -64.0f, 0.0f, 64.0f, 0.0f };
-f32 sKaleidoSetupEyeZ1[] = { 0.0f, -64.0f, 0.0f, 64.0f };
+/*
+ * The following three arrays are effectively unused.
+ * They are partly equivalent to the `sKaleidoSetupRightPage*` arrays below,
+ * but make each page correspond to the opposite page instead of the page to the right.
+ */
+
+s16 sKaleidoSetupUnusedPageIndex[] = {
+    PAUSE_QUEST, // PAUSE_ITEM
+    PAUSE_EQUIP, // PAUSE_MAP
+    PAUSE_ITEM,  // PAUSE_QUEST
+    PAUSE_MAP,   // PAUSE_EQUIP
+};
+
+f32 sKaleidoSetupUnusedEyeX[] = {
+    PAUSE_EYE_DIST * -PAUSE_QUEST_X, // PAUSE_ITEM
+    PAUSE_EYE_DIST * -PAUSE_EQUIP_X, // PAUSE_MAP
+    PAUSE_EYE_DIST * -PAUSE_ITEM_X,  // PAUSE_QUEST
+    PAUSE_EYE_DIST * -PAUSE_MAP_X,   // PAUSE_EQUIP
+};
+
+f32 sKaleidoSetupUnusedEyeZ[] = {
+    PAUSE_EYE_DIST * -PAUSE_QUEST_Z, // PAUSE_ITEM
+    PAUSE_EYE_DIST * -PAUSE_EQUIP_Z, // PAUSE_MAP
+    PAUSE_EYE_DIST * -PAUSE_ITEM_Z,  // PAUSE_QUEST
+    PAUSE_EYE_DIST * -PAUSE_MAP_Z,   // PAUSE_EQUIP
+};
+
+/*
+ * The following three arrays are used when opening the pause menu to set up a page switch such that scrolling left
+ * brings to the initial page.
+ * For example to open the menu on page PAUSE_ITEM, the menu would open on PAUSE_MAP and scroll left to PAUSE_ITEM.
+ */
+
+s16 sKaleidoSetupRightPageIndex[] = {
+    PAUSE_MAP,   // PAUSE_ITEM
+    PAUSE_QUEST, // PAUSE_MAP
+    PAUSE_EQUIP, // PAUSE_QUEST
+    PAUSE_ITEM,  // PAUSE_EQUIP
+};
+
+f32 sKaleidoSetupRightPageEyeX[] = {
+    PAUSE_EYE_DIST * -PAUSE_MAP_X,   // PAUSE_ITEM
+    PAUSE_EYE_DIST * -PAUSE_QUEST_X, // PAUSE_MAP
+    PAUSE_EYE_DIST * -PAUSE_EQUIP_X, // PAUSE_QUEST
+    PAUSE_EYE_DIST * -PAUSE_ITEM_X,  // PAUSE_EQUIP
+};
+
+f32 sKaleidoSetupRightPageEyeZ[] = {
+    PAUSE_EYE_DIST * -PAUSE_MAP_Z,   // PAUSE_ITEM
+    PAUSE_EYE_DIST * -PAUSE_QUEST_Z, // PAUSE_MAP
+    PAUSE_EYE_DIST * -PAUSE_EQUIP_Z, // PAUSE_QUEST
+    PAUSE_EYE_DIST * -PAUSE_ITEM_Z,  // PAUSE_EQUIP
+};
 
 void KaleidoSetup_Update(PlayState* play) {
     PauseContext* pauseCtx = &play->pauseCtx;
@@ -30,24 +76,33 @@ void KaleidoSetup_Update(PlayState* play) {
             WREG(16) = -175;
             WREG(17) = 155;
 
-            pauseCtx->unk_1EA = 0;
-            pauseCtx->mainState = PAUSE_MAIN_STATE_1;
+            pauseCtx->pageSwitchTimer = 0;
+
+            // Setting mainState here is irrelevant, mainState is only used under PAUSE_STATE_MAIN,
+            // which isn't involved in the initial pause menu opening page scrolling animation.
+            // mainState is also overwritten later before being used.
+            pauseCtx->mainState = PAUSE_MAIN_STATE_SWITCHING_PAGE;
 
-            if (ZREG(48) == 0) {
-                pauseCtx->eye.x = sKaleidoSetupEyeX0[pauseCtx->pageIndex];
-                pauseCtx->eye.z = sKaleidoSetupEyeZ0[pauseCtx->pageIndex];
-                pauseCtx->pageIndex = sKaleidoSetupKscpPos0[pauseCtx->pageIndex];
+            //! @bug REG collision
+            if (R_START_LABEL_DD(0) == 0) {
+                // Never reached, unused, and the data would be wrong anyway
+                // (scrolling left from this would not bring to the initial page)
+                pauseCtx->eye.x = sKaleidoSetupUnusedEyeX[pauseCtx->pageIndex];
+                pauseCtx->eye.z = sKaleidoSetupUnusedEyeZ[pauseCtx->pageIndex];
+                pauseCtx->pageIndex = sKaleidoSetupUnusedPageIndex[pauseCtx->pageIndex];
             } else {
-                pauseCtx->eye.x = sKaleidoSetupEyeX1[pauseCtx->pageIndex];
-                pauseCtx->eye.z = sKaleidoSetupEyeZ1[pauseCtx->pageIndex];
-                pauseCtx->pageIndex = sKaleidoSetupKscpPos1[pauseCtx->pageIndex];
+                // Set eye position and pageIndex such that scrolling left brings to the desired page
+                pauseCtx->eye.x = sKaleidoSetupRightPageEyeX[pauseCtx->pageIndex];
+                pauseCtx->eye.z = sKaleidoSetupRightPageEyeZ[pauseCtx->pageIndex];
+                pauseCtx->pageIndex = sKaleidoSetupRightPageIndex[pauseCtx->pageIndex];
             }
 
-            pauseCtx->mode = (u16)(pauseCtx->pageIndex * 2) + 1;
+            // Set next page mode to scroll left
+            pauseCtx->nextPageMode = (u16)(pauseCtx->pageIndex * 2) + 1;
             pauseCtx->state = PAUSE_STATE_WAIT_LETTERBOX;
 
-            PRINTF("Ｍｏｄｅ=%d  eye.x=%f,  eye.z=%f  kscp_pos=%d\n", pauseCtx->mode, pauseCtx->eye.x, pauseCtx->eye.z,
-                   pauseCtx->pageIndex);
+            PRINTF("Ｍｏｄｅ=%d  eye.x=%f,  eye.z=%f  kscp_pos=%d\n", pauseCtx->nextPageMode, pauseCtx->eye.x,
+                   pauseCtx->eye.z, pauseCtx->pageIndex);
         }
 
         if (pauseCtx->state == PAUSE_STATE_WAIT_LETTERBOX) {
@@ -77,7 +132,7 @@ void KaleidoSetup_Init(PlayState* play) {
     pauseCtx->alpha = 0;
 
     // mainState = PAUSE_MAIN_STATE_IDLE , pageIndex = PAUSE_ITEM
-    pauseCtx->unk_1EA = pauseCtx->mainState = pauseCtx->mode = pauseCtx->pageIndex = 0;
+    pauseCtx->pageSwitchTimer = pauseCtx->mainState = pauseCtx->nextPageMode = pauseCtx->pageIndex = 0;
 
     pauseCtx->unk_204 = -314.0f;