Document pause page switching

include/regs.h

@@ -109,6 +109,7 @@
 #define R_C_UP_ICON_Y                            YREG(89)
 #define R_EPONAS_SONG_PLAYED                     DREG(53)
 #define R_MAGIC_FILL_COLOR(i)                    ZREG(0 + (i))
+#define R_PAUSE_PAGE_SWITCH_FRAME_ADVANCE_ON     ZREG(13)
 #define R_C_BTN_COLOR(i)                         ZREG(39 + (i))
 #define R_B_BTN_COLOR(i)                         ZREG(43 + (i))
 #define R_START_LABEL_DD(i)                      ZREG(48 + (i))

include/z64pause.h

@@ -20,6 +20,33 @@ typedef enum {
     /* 0x04 */ PAUSE_WORLD_MAP
 } PauseMenuPage;
 
+// The XZ coordinates in which direction each pause page is at
+// e.g. the item page is in the -z direction
+/*
+ *      <   item   >
+ *
+ *   ^                ^
+ *              x
+ * equip     o-->    map
+ *           |
+ *   v     z v        v
+ *
+ *      <   quest  >
+ */
+#define PAUSE_ITEM_X (0)
+#define PAUSE_ITEM_Z (-1)
+#define PAUSE_MAP_X (1)
+#define PAUSE_MAP_Z (0)
+#define PAUSE_QUEST_X (0)
+#define PAUSE_QUEST_Z (1)
+#define PAUSE_EQUIP_X (-1)
+#define PAUSE_EQUIP_Z (0)
+
+// The pause camera looks at x=0,z=0,
+// with the eye being PAUSE_EYE_DIST away in the direction opposite to the active page,
+// which results in the camera being pointed (through x=0,z=0) towards the active page.
+#define PAUSE_EYE_DIST (64.0f)
+
 #define PAUSE_EQUIP_PLAYER_WIDTH 64
 #define PAUSE_EQUIP_PLAYER_HEIGHT 112
 
@@ -58,7 +85,7 @@ typedef enum {
 // Sub-states of PAUSE_STATE_MAIN
 typedef enum {
     /* 0 */ PAUSE_MAIN_STATE_IDLE,
-    /* 1 */ PAUSE_MAIN_STATE_1,
+    /* 1 */ PAUSE_MAIN_STATE_SWITCHING_PAGE,
     /* 2 */ PAUSE_MAIN_STATE_2,
     /* 3 */ PAUSE_MAIN_STATE_3,
     /* 4 */ PAUSE_MAIN_STATE_4,
@@ -98,9 +125,9 @@ typedef struct {
     /* 0x01D6 */ u16 debugState;
     /* 0x01D8 */ Vec3f eye;
     /* 0x01E4 */ u16 mainState;
-    /* 0x01E6 */ u16 mode;
+    /* 0x01E6 */ u16 nextPageMode; // During a page switch, indicates the page before switching and the direction to scroll in. Value is `(2 * prev pageIndex) + (scroll left ? 1 : 0)`
     /* 0x01E8 */ u16 pageIndex; // "kscp_pos"
-    /* 0x01EA */ u16 unk_1EA;
+    /* 0x01EA */ u16 pageSwitchTimer;
     /* 0x01EC */ u16 unk_1EC;
     /* 0x01F0 */ f32 unk_1F0;
     /* 0x01F4 */ f32 unk_1F4;

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;