Documentation pass on the pause menu (kaleido_scope)

include/regs.h

@@ -120,6 +120,7 @@
 #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_PAUSE_CURSOR_L_R_SELECTED_PRIM_TIMER   ZREG(28)
 #define R_C_BTN_COLOR(i)                         ZREG(39 + (i))
 #define R_B_BTN_COLOR(i)                         ZREG(43 + (i))
 #if OOT_NTSC
@@ -186,12 +187,19 @@
 #define R_B_LABEL_DD                             WREG(0)
 #define R_PAUSE_PAGES_Y_ORIGIN_2                 WREG(2) // Complements PauseContext.pagesYOrigin1
 #define R_PAUSE_DEPTH_OFFSET                     WREG(3) // Offset position of all pages away from the camera
+#define R_PAUSE_UI_ANIM_ALPHA_ADD_DURATION       WREG(4)
+#define R_PAUSE_UI_ANIMS_DURATION                WREG(6)
 #if OOT_NTSC
 #define R_B_LABEL_SCALE(i)                       WREG(8 + (i))
 #define R_B_LABEL_X(i)                           WREG(10 + (i))
 #define R_B_LABEL_Y(i)                           WREG(12 + (i))
 #define R_A_LABEL_Z(i)                           WREG(14 + (i))
 #endif
+#define R_PAUSE_CURSOR_LEFT_X                    WREG(16)
+#define R_PAUSE_CURSOR_RIGHT_X                   WREG(17)
+#define R_PAUSE_CURSOR_LEFT_RIGHT_Y              WREG(18)
+#define R_PAUSE_CURSOR_LEFT_MOVE_OFFSET_X        WREG(25)
+#define R_PAUSE_CURSOR_RIGHT_MOVE_OFFSET_X       WREG(26)
 #define R_OW_MINIMAP_X                           WREG(29)
 #define R_OW_MINIMAP_Y                           WREG(30)
 #define R_MINIMAP_DISABLED                       WREG(31)
@@ -209,6 +217,8 @@
 #endif
 #define R_DGN_MINIMAP_X                          WREG(68)
 #define R_DGN_MINIMAP_Y                          WREG(69)
+#define R_PAUSE_NAME_DISPLAY_TIMER_MAX_          WREG(88)
+#define R_PAUSE_NAME_DISPLAY_TIMER_THRESHOLD_    WREG(89)
 #define R_TEXTBOX_X                              VREG(0)
 #define R_TEXTBOX_Y                              VREG(1)
 #define R_TEXTBOX_CLEF_XPOS                      VREG(7)

include/z64pause.h

@@ -50,6 +50,8 @@ typedef enum PauseMenuPage {
 
 #define PAUSE_EQUIP_PLAYER_WIDTH 64
 #define PAUSE_EQUIP_PLAYER_HEIGHT 112
+#define PAUSE_EQUIP_PLAYER_FRAG_HEIGHT (TMEM_SIZE / (PAUSE_EQUIP_PLAYER_WIDTH * G_IM_SIZ_16b_BYTES))
+#define PAUSE_EQUIP_PLAYER_FRAG_NUM (((PAUSE_EQUIP_PLAYER_HEIGHT - 1) / PAUSE_EQUIP_PLAYER_FRAG_HEIGHT) + 1)
 
 #define PAUSE_EQUIP_BUFFER_SIZE sizeof(u16[PAUSE_EQUIP_PLAYER_HEIGHT][PAUSE_EQUIP_PLAYER_WIDTH])
 #define PAUSE_PLAYER_SEGMENT_GAMEPLAY_KEEP_BUFFER_SIZE 0x5000
@@ -92,7 +94,7 @@ typedef enum PauseMainState {
     /* 4 */ PAUSE_MAIN_STATE_SONG_PROMPT_INIT, // Start the prompt for the player to play the song.
     /* 5 */ PAUSE_MAIN_STATE_SONG_PROMPT, // Waiting for the player to play the song.
     /* 6 */ PAUSE_MAIN_STATE_SONG_PROMPT_DONE, // The song prompt is done, the player either played the song successfully or made a mistake.
-    /* 7 */ PAUSE_MAIN_STATE_7,
+    /* 7 */ PAUSE_MAIN_STATE_EQUIP_CHANGED,
     /* 8 */ PAUSE_MAIN_STATE_IDLE_CURSOR_ON_SONG, // Like PAUSE_MAIN_STATE_IDLE, but the quest page is active and the cursor is positioned on a song.
     /* 9 */ PAUSE_MAIN_STATE_SONG_PLAYBACK_START // Start playing the song back to the player.
 } PauseMainState;

src/code/z_construct.c

@@ -341,7 +341,7 @@ void Regs_InitDataImpl(void) {
     ZREG(25) = 4;
     ZREG(26) = 20;
     ZREG(27) = 10;
-    ZREG(28) = 20;
+    R_PAUSE_CURSOR_L_R_SELECTED_PRIM_TIMER = 20;
     ZREG(29) = 4;
     ZREG(30) = 20;
     ZREG(31) = 10;
@@ -507,9 +507,9 @@ void Regs_InitDataImpl(void) {
     XREG(95) = 200;
     R_PAUSE_PAGES_Y_ORIGIN_2 = -6080;
     R_PAUSE_DEPTH_OFFSET = 9355;
-    WREG(4) = 8;
+    R_PAUSE_UI_ANIM_ALPHA_ADD_DURATION = 8;
     WREG(5) = 3;
-    WREG(6) = 8;
+    R_PAUSE_UI_ANIMS_DURATION = 8;
     WREG(7) = 0;
 
 #if OOT_NTSC
@@ -533,17 +533,17 @@ void Regs_InitDataImpl(void) {
     WREG(15) = -350;
 #endif
 
-    WREG(16) = -175;
-    WREG(17) = 155;
-    WREG(18) = 10;
+    R_PAUSE_CURSOR_LEFT_X = -175;
+    R_PAUSE_CURSOR_RIGHT_X = 155;
+    R_PAUSE_CURSOR_LEFT_RIGHT_Y = 10;
     WREG(19) = 10;
     WREG(20) = -50;
     WREG(21) = -54;
     WREG(22) = -32;
     WREG(23) = -38;
     WREG(24) = -36;
-    WREG(25) = 40;
-    WREG(26) = -40;
+    R_PAUSE_CURSOR_LEFT_MOVE_OFFSET_X = 40;
+    R_PAUSE_CURSOR_RIGHT_MOVE_OFFSET_X = -40;
     WREG(27) = 0;
     WREG(28) = 0;
     R_OW_MINIMAP_X = 238;
@@ -590,8 +590,8 @@ void Regs_InitDataImpl(void) {
     R_DGN_MINIMAP_X = 204;
     R_DGN_MINIMAP_Y = 140;
     WREG(87) = 80;
-    WREG(88) = 70;
-    WREG(89) = 40;
+    R_PAUSE_NAME_DISPLAY_TIMER_MAX_ = 70;
+    R_PAUSE_NAME_DISPLAY_TIMER_THRESHOLD_ = 40;
     WREG(90) = 320;
     WREG(91) = 40;
     WREG(92) = 3;

src/code/z_debug.c

@@ -1,5 +1,7 @@
 #include "global.h"
 
+#pragma increment_block_number "gc-eu:0 gc-eu-mq:0 gc-jp:0 gc-jp-ce:0 gc-jp-mq:0 gc-us:0 gc-us-mq:0"
+
 typedef struct DebugCamTextBufferEntry {
     /* 0x0 */ u8 x;
     /* 0x1 */ u8 y;

src/code/z_kaleido_setup.c

@@ -79,8 +79,8 @@ void KaleidoSetup_Update(PlayState* play) {
             // The start button was pressed, pause
             gSaveContext.prevHudVisibilityMode = gSaveContext.hudVisibilityMode;
 
-            WREG(16) = -175;
-            WREG(17) = 155;
+            R_PAUSE_CURSOR_LEFT_X = -175;
+            R_PAUSE_CURSOR_RIGHT_X = 155;
 
             pauseCtx->pageSwitchTimer = 0;
 
@@ -130,8 +130,11 @@ void KaleidoSetup_Init(PlayState* play) {
     pauseCtx->state = PAUSE_STATE_OFF;
     pauseCtx->debugState = 0;
 
+    // Setting the eye xz here is irrelevant, it's set on pausing in KaleidoSetup_Update
+    // x = -PAUSE_EYE_DIST * PAUSE_ITEM_X
     pauseCtx->eye.x = pauseCtx->eye.y = 0.0f;
-    pauseCtx->eye.z = 64.0f;
+    pauseCtx->eye.z = -PAUSE_EYE_DIST * PAUSE_ITEM_Z;
+
     pauseCtx->promptDepthOffset = 936.0f;
     pauseCtx->itemPagePitch = pauseCtx->equipPagePitch = pauseCtx->mapPagePitch = pauseCtx->questPagePitch = 160.0f;
 
@@ -154,8 +157,8 @@ void KaleidoSetup_Init(PlayState* play) {
     pauseCtx->cursorY[PAUSE_MAP] = 0;
     pauseCtx->cursorX[PAUSE_QUEST] = 0;
     pauseCtx->cursorY[PAUSE_QUEST] = 0;
-    pauseCtx->cursorX[PAUSE_EQUIP] = 1;
-    pauseCtx->cursorY[PAUSE_EQUIP] = 0;
+    pauseCtx->cursorX[PAUSE_EQUIP] = EQUIP_VALUE_SWORD_KOKIRI;
+    pauseCtx->cursorY[PAUSE_EQUIP] = EQUIP_TYPE_SWORD;
 
     pauseCtx->cursorItem[PAUSE_ITEM] = PAUSE_ITEM_NONE;
     pauseCtx->cursorItem[PAUSE_MAP] = VREG(30) + 3;

src/overlays/actors/ovl_En_Mag/z_en_mag.c

@@ -82,9 +82,9 @@ void EnMag_Init(Actor* thisx, PlayState* play) {
     this->fadeOutAlphaStep = 10;
 
     VREG(19) = 99;
-    VREG(21) = 9;
-    VREG(23) = 10;
-    VREG(24) = 8;
+    R_PAUSE_SONG_OCA_BTN_Y(OCARINA_BTN_A) = 9;
+    R_PAUSE_SONG_OCA_BTN_Y(OCARINA_BTN_C_RIGHT) = 10;
+    R_PAUSE_SONG_OCA_BTN_Y(OCARINA_BTN_C_LEFT) = 8;
 
     this->effectScroll = 0;
     this->unk_E30C = 0;

src/overlays/misc/ovl_kaleido_scope/z_kaleido_collect.c

@@ -283,10 +283,15 @@ void KaleidoScope_DrawQuestStatus(PlayState* play, GraphicsContext* gfxCtx) {
 
             KaleidoScope_SetCursorPos(pauseCtx, cursor * 4, pauseCtx->questVtx);
 
+            // Handle part of the ocarina songs playback
+
             if ((pauseCtx->state == PAUSE_STATE_MAIN) && (pauseCtx->mainState == PAUSE_MAIN_STATE_IDLE) &&
                 (pauseCtx->cursorSpecialPos == 0)) {
                 if ((cursor >= QUEST_SONG_MINUET) && (cursor < QUEST_KOKIRI_EMERALD)) {
                     if (CHECK_QUEST_ITEM(pauseCtx->cursorPoint[PAUSE_QUEST])) {
+                        // The cursor is on a learned song
+                        // Set some things up for song playback
+
                         cursor = pauseCtx->cursorSlot[PAUSE_QUEST];
                         pauseCtx->ocarinaSongIdx = gOcarinaSongItemMap[cursor - QUEST_SONG_MINUET];
                         sPlaybackSongStartDelayTimer = 10;
@@ -297,6 +302,9 @@ void KaleidoScope_DrawQuestStatus(PlayState* play, GraphicsContext* gfxCtx) {
                         }
                         sPlayedSongBtnsNum = 0;
 
+                        // Have the player play a song, immediately cancelled below
+                        // Also clear the playback staff
+                        // This has no purpose (?)
                         AudioOcarina_SetInstrument(OCARINA_INSTRUMENT_DEFAULT);
                         AudioOcarina_Start((1 << pauseCtx->ocarinaSongIdx) + 0x8000);
                         pauseCtx->ocarinaStaff = AudioOcarina_GetPlaybackStaff();
@@ -311,6 +319,7 @@ void KaleidoScope_DrawQuestStatus(PlayState* play, GraphicsContext* gfxCtx) {
 
                         pauseCtx->mainState = PAUSE_MAIN_STATE_IDLE_CURSOR_ON_SONG;
 
+                        // Stop having the player play a song as done above
                         AudioOcarina_SetInstrument(OCARINA_INSTRUMENT_OFF);
                     }
                 }