`z_parameter`: Hud Visibility (#942)

* Begin interface alpha docs

* More Interface Alpha

* cleanup docs

* Minor fixes

* Apply Discord Discussions

* More discussions

* More suggestions from OoT

* fix merge

3 files changed, 38 insertions, 13 deletions

diff --git a/include/functions.h b/include/functions.h
index 05db21f4f..f04ab1981 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -1823,10 +1823,7 @@ void func_8010EA9C(s32 arg0, s32 arg1);
 // void func_8010EBA0(void);
 // void func_8010EC54(void);
 void func_8010EE74(PlayState* play, s32 day);
-void Interface_ChangeAlpha(u16 param_1);
-// void func_8010EF9C(void);
-// void func_8010F0D4(void);
-// void func_8010F1A8(void);
+void Interface_SetHudVisibility(u16 hudVisibility);
 // void func_80110038(void);
 // void func_80111CB4(void);
 // void func_801129E4(void);
diff --git a/include/z64save.h b/include/z64save.h
index 12b525f4d..57801684f 100644
--- a/include/z64save.h
+++ b/include/z64save.h
@@ -54,6 +54,34 @@ typedef enum {
 #define MAGIC_NORMAL_METER 0x30
 #define MAGIC_DOUBLE_METER (2 * MAGIC_NORMAL_METER)
 
+typedef enum {
+    /*  0 */ HUD_VISIBILITY_IDLE,
+    /*  1 */ HUD_VISIBILITY_NONE,
+    /*  2 */ HUD_VISIBILITY_NONE_ALT, // Identical to HUD_VISIBILITY_NONE
+    /*  3 */ HUD_VISIBILITY_HEARTS_WITH_OVERWRITE, // Uses Interface_UpdateButtonAlphas so gives the opportunity to dim only disabled buttons
+    /*  4 */ HUD_VISIBILITY_A,
+    /*  5 */ HUD_VISIBILITY_A_HEARTS_MAGIC_WITH_OVERWRITE, // Uses Interface_UpdateButtonAlphas so gives the opportunity to dim only disabled buttons
+    /*  6 */ HUD_VISIBILITY_A_HEARTS_MAGIC_MINIMAP_WITH_OVERWRITE, // Uses Interface_UpdateButtonAlphas so gives the opportunity to dim only disabled buttons
+    /*  7 */ HUD_VISIBILITY_ALL_NO_MINIMAP_W_DISABLED, // Only raises button alphas if not disabled
+    /*  8 */ HUD_VISIBILITY_B,
+    /*  9 */ HUD_VISIBILITY_HEARTS_MAGIC,
+    /* 10 */ HUD_VISIBILITY_B_ALT,
+    /* 11 */ HUD_VISIBILITY_HEARTS,
+    /* 12 */ HUD_VISIBILITY_A_B_MINIMAP,
+    /* 13 */ HUD_VISIBILITY_HEARTS_MAGIC_WITH_OVERWRITE, // Uses Interface_UpdateButtonAlphas so gives the opportunity to dim only disabled buttons
+    /* 14 */ HUD_VISIBILITY_HEARTS_MAGIC_C,
+    /* 15 */ HUD_VISIBILITY_ALL_NO_MINIMAP,
+    /* 16 */ HUD_VISIBILITY_A_B_C,
+    /* 17 */ HUD_VISIBILITY_B_MINIMAP,
+    /* 18 */ HUD_VISIBILITY_HEARTS_MAGIC_MINIMAP,
+    /* 19 */ HUD_VISIBILITY_A_HEARTS_MAGIC_MINIMAP,
+    /* 20 */ HUD_VISIBILITY_B_MAGIC,
+    /* 21 */ HUD_VISIBILITY_A_B,
+    /* 22 */ HUD_VISIBILITY_A_B_HEARTS_MAGIC_MINIMAP,
+    /* 50 */ HUD_VISIBILITY_ALL = 50,
+    /* 52 */ HUD_VISIBILITY_NONE_INSTANT = 52
+} HudVisibility;
+
 typedef struct SramContext {
     /* 0x00 */ u8* readBuff;
     /* 0x04 */ u8 *saveBuf;
@@ -251,11 +279,11 @@ typedef struct SaveContext {
     /* 0x3F16 */ u8 seqIndex;                           // "old_bgm"
     /* 0x3F17 */ u8 nightSeqIndex;                      // "old_env"
     /* 0x3F18 */ u8 buttonStatus[6];                    // "button_item"
-    /* 0x3F1E */ u8 unk_3F1E;                           // "ck_fg"
-    /* 0x3F20 */ u16 unk_3F20;                          // "alpha_type"
-    /* 0x3F22 */ u16 unk_3F22;                          // "prev_alpha_type"
-    /* 0x3F24 */ u16 unk_3F24;                          // "alpha_count"
-    /* 0x3F26 */ u16 unk_3F26;                          // "last_time_type"
+    /* 0x3F1E */ u8 hudVisibilityForceButtonAlphasByStatus; // if btn alphas are updated through Interface_UpdateButtonAlphas, instead update them through Interface_UpdateButtonAlphasByStatus "ck_fg"
+    /* 0x3F20 */ u16 nextHudVisibility; // triggers the hud to change visibility to the requested value. Reset to HUD_VISIBILITY_IDLE when target is reached "alpha_type"
+    /* 0x3F22 */ u16 hudVisibility; // current hud visibility "prev_alpha_type"
+    /* 0x3F24 */ u16 hudVisibilityTimer; // number of frames in the transition to a new hud visibility. Used to step alpha "alpha_count"
+    /* 0x3F26 */ u16 prevHudVisibility; // used to store and recover hud visibility for pause menu and text boxes "last_time_type"
     /* 0x3F28 */ s16 magicState; // determines magic meter behavior on each frame "magic_flag"
     /* 0x3F2A */ s16 isMagicRequested; // a request to add magic has been given "recovery_magic_flag"
     /* 0x3F2C */ s16 magicFlag; // Set to 0 in func_80812D94(), otherwise unused "keep_magic_flag"
diff --git a/include/z64scene.h b/include/z64scene.h
index 649a4e011..180405f30 100644
--- a/include/z64scene.h
+++ b/include/z64scene.h
@@ -271,7 +271,7 @@ typedef struct {
 } Room; // size = 0x14
 
 typedef struct {
-    /* 0x00 */ Room currRoom;
+    /* 0x00 */ Room curRoom;
     /* 0x14 */ Room prevRoom;
     /* 0x28 */ void* roomMemPages[2]; // In a scene with transitions, roomMemory is split between two pages that toggle each transition. This is one continuous range, as the second page allocates from the end
     /* 0x30 */ u8 activeMemPage; // 0 - First page in memory, 1 - Second page
@@ -843,11 +843,11 @@ typedef enum {
 #define SCENE_CMD_SPECIAL_FILES(elfMessageFile, keepObjectId) \
     { SCENE_CMD_ID_SPECIAL_FILES, elfMessageFile, CMD_W(keepObjectId) }
 
-#define SCENE_CMD_ROOM_BEHAVIOR(currRoomUnk3, currRoomUnk2, currRoomUnk5, msgCtxunk12044, enablePosLights,  \
+#define SCENE_CMD_ROOM_BEHAVIOR(curRoomUnk3, curRoomUnk2, curRoomUnk5, msgCtxunk12044, enablePosLights,  \
                                 kankyoContextUnkE2)                                                         \
     {                                                                                                       \
-        SCENE_CMD_ID_ROOM_BEHAVIOR, currRoomUnk3,                                                           \
-            currRoomUnk2 | _SHIFTL(currRoomUnk5, 8, 1) | _SHIFTL(msgCtxunk12044, 10, 1) | \
+        SCENE_CMD_ID_ROOM_BEHAVIOR, curRoomUnk3,                                                           \
+            curRoomUnk2 | _SHIFTL(curRoomUnk5, 8, 1) | _SHIFTL(msgCtxunk12044, 10, 1) | \
                 _SHIFTL(enablePosLights, 11, 1) | _SHIFTL(kankyoContextUnkE2, 12, 1)                        \
     }