Doc misc 5 (#1223)

* Annotate global equip and upgrade masks data

* Trivial respawn doc stuff

Move the respawn mode enum up to use the _MAX enum value in the save context struct

* Comment on the `sceneFlags[127]` debug-strings-suggested out-of-bounds access

* Reword `room_inf[127]` comments (attempt)

src/overlays/actors/ovl_Demo_Kankyo/z_demo_kankyo.c

@@ -874,7 +874,7 @@ void DemoKankyo_DrawWarpSparkles(Actor* thisx, GlobalContext* globalCtx) {
                                sWarpSparkleEnvColors[globalCtx->msgCtx.lastPlayedSong].g,
                                sWarpSparkleEnvColors[globalCtx->msgCtx.lastPlayedSong].b, 255);
             } else {
-                s8 respawnData = gSaveContext.respawn[1].data;
+                s8 respawnData = gSaveContext.respawn[RESPAWN_MODE_RETURN].data;
 
                 gDPSetEnvColor(POLY_XLU_DISP++, sWarpSparkleEnvColors[respawnData].r,
                                sWarpSparkleEnvColors[respawnData].g, sWarpSparkleEnvColors[respawnData].b, 255);

src/overlays/actors/ovl_En_Elf/z_en_elf.c

@@ -1406,8 +1406,14 @@ void func_80A053F0(Actor* thisx, GlobalContext* globalCtx) {
     } else {
         this->actionFunc(this, globalCtx);
         thisx->shape.rot.y = this->unk_2BC;
-        nREG(80) = HIGH_SCORE(HS_HBA);
 
+        // `gSaveContext.sceneFlags[127].chest` (like in the debug string) instead of `HIGH_SCORE(HS_HBA)` matches too,
+        // but, with how the `SaveContext` struct is currently defined, it is an out-of-bounds read in the `sceneFlags`
+        // array.
+        // It is theorized the original `room_inf` (currently `sceneFlags`) was an array of length 128, not broken up
+        // like currently into structs. Structs are currently used because they're easier to work with and still match.
+        // There is another occurrence of this elsewhere.
+        nREG(80) = HIGH_SCORE(HS_HBA);
         if ((nREG(81) != 0) && (HIGH_SCORE(HS_HBA) != 0)) {
             LOG_NUM("z_common_data.memory.information.room_inf[127][ 0 ]", HIGH_SCORE(HS_HBA), "../z_en_elf.c", 2595);
         }

src/overlays/actors/ovl_En_Ge1/z_en_ge1.c

@@ -629,6 +629,8 @@ void EnGe1_TalkNoPrize_Archery(EnGe1* this, GlobalContext* globalCtx) {
 void EnGe1_TalkAfterGame_Archery(EnGe1* this, GlobalContext* globalCtx) {
     CLEAR_EVENTINF(EVENTINF_HORSES_08);
     LOG_NUM("z_common_data.yabusame_total", gSaveContext.minigameScore, "../z_en_ge1.c", 1110);
+    // With the current `SaveContext` struct definition, the expression in the debug string is an out-of-bounds read,
+    // see the other occurrence of this for more details.
     LOG_NUM("z_common_data.memory.information.room_inf[127][ 0 ]", HIGH_SCORE(HS_HBA), "../z_en_ge1.c", 1111);
     this->actor.flags |= ACTOR_FLAG_16;
 

src/overlays/actors/ovl_player_actor/z_player.c

@@ -8913,7 +8913,7 @@ void func_80845EF8(Player* this, GlobalContext* globalCtx) {
                 func_80097534(globalCtx, &globalCtx->roomCtx);
             }
             func_8005B1A4(Gameplay_GetCamera(globalCtx, CAM_ID_MAIN));
-            Gameplay_SetupRespawnPoint(globalCtx, 0, 0xDFF);
+            Gameplay_SetupRespawnPoint(globalCtx, RESPAWN_MODE_DOWN, 0xDFF);
         }
         return;
     }
@@ -9296,8 +9296,8 @@ void Player_Init(Actor* thisx, GlobalContext* globalCtx2) {
     SceneTableEntry* scene = globalCtx->loadedScene;
     u32 titleFileSize;
     s32 initMode;
-    s32 sp50;
-    s32 sp4C;
+    s32 respawnFlag;
+    s32 respawnMode;
 
     globalCtx->shootingGalleryStatus = globalCtx->bombchuBowlingStatus = 0;
 
@@ -9322,34 +9322,34 @@ void Player_Init(Actor* thisx, GlobalContext* globalCtx2) {
     Player_InitCommon(this, globalCtx, gPlayerSkelHeaders[((void)0, gSaveContext.linkAge)]);
     this->giObjectSegment = (void*)(((u32)ZeldaArena_MallocDebug(0x3008, "../z_player.c", 17175) + 8) & ~0xF);
 
-    sp50 = gSaveContext.respawnFlag;
+    respawnFlag = gSaveContext.respawnFlag;
 
-    if (sp50 != 0) {
-        if (sp50 == -3) {
+    if (respawnFlag != 0) {
+        if (respawnFlag == -3) {
             thisx->params = gSaveContext.respawn[RESPAWN_MODE_RETURN].playerParams;
         } else {
-            if ((sp50 == 1) || (sp50 == -1)) {
+            if ((respawnFlag == 1) || (respawnFlag == -1)) {
                 this->unk_A86 = -2;
             }
 
-            if (sp50 < 0) {
-                sp4C = 0;
+            if (respawnFlag < 0) {
+                respawnMode = RESPAWN_MODE_DOWN;
             } else {
-                sp4C = sp50 - 1;
-                Math_Vec3f_Copy(&thisx->world.pos, &gSaveContext.respawn[sp50 - 1].pos);
+                respawnMode = respawnFlag - 1;
+                Math_Vec3f_Copy(&thisx->world.pos, &gSaveContext.respawn[respawnMode].pos);
                 Math_Vec3f_Copy(&thisx->home.pos, &thisx->world.pos);
                 Math_Vec3f_Copy(&thisx->prevPos, &thisx->world.pos);
                 this->fallStartHeight = thisx->world.pos.y;
-                this->currentYaw = thisx->shape.rot.y = gSaveContext.respawn[sp4C].yaw;
-                thisx->params = gSaveContext.respawn[sp4C].playerParams;
+                this->currentYaw = thisx->shape.rot.y = gSaveContext.respawn[respawnMode].yaw;
+                thisx->params = gSaveContext.respawn[respawnMode].playerParams;
             }
 
-            globalCtx->actorCtx.flags.tempSwch = gSaveContext.respawn[sp4C].tempSwchFlags & 0xFFFFFF;
-            globalCtx->actorCtx.flags.tempCollect = gSaveContext.respawn[sp4C].tempCollectFlags;
+            globalCtx->actorCtx.flags.tempSwch = gSaveContext.respawn[respawnMode].tempSwchFlags & 0xFFFFFF;
+            globalCtx->actorCtx.flags.tempCollect = gSaveContext.respawn[respawnMode].tempCollectFlags;
         }
     }
 
-    if ((sp50 == 0) || (sp50 < -1)) {
+    if ((respawnFlag == 0) || (respawnFlag < -1)) {
         titleFileSize = scene->titleFile.vromEnd - scene->titleFile.vromStart;
         if ((titleFileSize != 0) && gSaveContext.showTitleCard) {
             if ((gSaveContext.sceneSetupIndex < 4) &&
@@ -9364,7 +9364,7 @@ void Player_Init(Actor* thisx, GlobalContext* globalCtx2) {
         gSaveContext.showTitleCard = true;
     }
 
-    if (func_80845C68(globalCtx, (sp50 == 2) ? 1 : 0) == 0) {
+    if (func_80845C68(globalCtx, (respawnFlag == 2) ? 1 : 0) == 0) {
         gSaveContext.respawn[RESPAWN_MODE_DOWN].playerParams = (thisx->params & 0xFF) | 0xD00;
     }
 

src/overlays/gamestates/ovl_file_choose/z_file_choose.c

@@ -1458,7 +1458,7 @@ void FileChoose_LoadGame(GameState* thisx) {
         this->state.running = false;
     }
 
-    gSaveContext.respawn[0].entranceIndex = ENTR_LOAD_OPENING;
+    gSaveContext.respawn[RESPAWN_MODE_DOWN].entranceIndex = ENTR_LOAD_OPENING;
     gSaveContext.respawnFlag = 0;
     gSaveContext.seqId = (u8)NA_BGM_DISABLED;
     gSaveContext.natureAmbienceId = 0xFF;