Major documentation pass

1 files changed, 77 insertions, 65 deletions

diff --git a/src/code/z_map_exp.c b/src/code/z_map_exp.c
index 89f83f390..0e4849f3a 100644
--- a/src/code/z_map_exp.c
+++ b/src/code/z_map_exp.c
@@ -1,20 +1,23 @@
 #include "global.h"
 #include "overlays/kaleido_scope/ovl_kaleido_scope/z_kaleido_scope.h"
 
-s16 sMinimapInitPosX = 0;
-s16 sMinimapInitPosZ = 0;
-s16 sMinimapInitDir = 0;
-
-s32 sDungeonAndBossSceneIds[] = {
-    SCENE_MITURIN,    SCENE_HAKUGIN,    SCENE_SEA,    SCENE_INISIE_N,  SCENE_INISIE_R,
-    SCENE_MITURIN_BS, SCENE_HAKUGIN_BS, SCENE_SEA_BS, SCENE_INISIE_BS,
-};
+s16 sPlayerInitPosX = 0;
+s16 sPlayerInitPosZ = 0;
+s16 sPlayerInitDir = 0;
 
 /**
- * If the current scene is a dungeon or boss scene, this function returns an index
- * indicating which one it is. Otherwise, it returns -1.
+ * Gets the mapIndex for the current dungeon or boss scene
+ * @return the current scene's mapIndex, or -1 if it isn't a dungeon or boss scene.
  */
 s32 Map_GetDungeonOrBossAreaIndex(PlayState* play) {
+    static s32 sDungeonAndBossSceneIds[] = {
+        SCENE_MITURIN,  // DUNGEON_INDEX_WOODFALL_TEMPLE
+        SCENE_HAKUGIN,  // DUNGEON_INDEX_SNOWHEAD_TEMPLE
+        SCENE_SEA,      // DUNGEON_INDEX_GREAT_BAY_TEMPLE
+        SCENE_INISIE_N, // DUNGEON_INDEX_STONE_TOWER_TEMPLE
+        SCENE_INISIE_R, // DUNGEON_INDEX_STONE_TOWER_TEMPLE
+        SCENE_MITURIN_BS, SCENE_HAKUGIN_BS, SCENE_SEA_BS, SCENE_INISIE_BS,
+    };
     s32 i;
 
     for (i = 0; i < ARRAY_COUNT(sDungeonAndBossSceneIds); i++) {
@@ -27,7 +30,8 @@ s32 Map_GetDungeonOrBossAreaIndex(PlayState* play) {
 }
 
 /**
- * Returns true if the current scene is a dungeon or boss scene, false otherwise.
+ * Tests if the current scene is in a dungeon or boss scene.
+ * @return true if the current scene is a dungeon or boss scene, false otherwise.
  */
 s32 Map_IsInDungeonOrBossArea(PlayState* play) {
     if (Map_GetDungeonOrBossAreaIndex(play) == -1) {
@@ -37,23 +41,26 @@ s32 Map_IsInDungeonOrBossArea(PlayState* play) {
     return true;
 }
 
-s32 func_8010A0A4(PlayState* play) {
-    if ((Map_GetDungeonOrBossAreaIndex(play) == -1) || !func_80102EF0(play)) {
+s32 MapExp_CurRoomHasMapI(PlayState* play) {
+    if ((Map_GetDungeonOrBossAreaIndex(play) == -1) || !MapDisp_CurRoomHasMapI(play)) {
         return false;
     }
 
     return true;
 }
 
-s32 sDungeonSceneIds[] = {
-    SCENE_MITURIN, SCENE_HAKUGIN, SCENE_SEA, SCENE_INISIE_N, SCENE_INISIE_R,
-};
-
 /**
- * If the current scene is a dungeon scene, this function returns an index
- * indicating which one it is. Otherwise, it returns -1.
+ * Tests if the current scene is a dungeon scene, excluding boss scenes.
+ * @return -1 if not a dungeon scene, else returns the dungeonIndex of the dungeon scene
  */
 s32 Map_GetDungeonAreaIndex(PlayState* play) {
+    static s32 sDungeonSceneIds[] = {
+        SCENE_MITURIN,  // DUNGEON_INDEX_WOODFALL_TEMPLE
+        SCENE_HAKUGIN,  // DUNGEON_INDEX_SNOWHEAD_TEMPLE
+        SCENE_SEA,      // DUNGEON_INDEX_GREAT_BAY_TEMPLE
+        SCENE_INISIE_N, // DUNGEON_INDEX_STONE_TOWER_TEMPLE
+        SCENE_INISIE_R, // DUNGEON_INDEX_STONE_TOWER_TEMPLE
+    };
     s32 i;
 
     for (i = 0; i < ARRAY_COUNT(sDungeonSceneIds); i++) {
@@ -66,9 +73,10 @@ s32 Map_GetDungeonAreaIndex(PlayState* play) {
 }
 
 /**
- * Returns true if the current scene is a dungeon scene, false otherwise.
+ * Test if the current scene is a dungeon scene, excluding boss rooms
+ * @return true if the current scene is a dungeon scene, false otherwise.
  */
-s32 Map_IsInDungeonArea(PlayState* play) {
+s32 Map_IsInDungeonScene(PlayState* play) {
     if (Map_GetDungeonAreaIndex(play) == -1) {
         return false;
     }
@@ -76,18 +84,17 @@ s32 Map_IsInDungeonArea(PlayState* play) {
     return true;
 }
 
-s32 sBossSceneIds[] = {
-    SCENE_MITURIN_BS, // DUNGEON_INDEX_WOODFALL_TEMPLE
-    SCENE_HAKUGIN_BS, // DUNGEON_INDEX_SNOWHEAD_TEMPLE
-    SCENE_SEA_BS,     // DUNGEON_INDEX_GREAT_BAY_TEMPLE
-    SCENE_INISIE_BS,  // DUNGEON_INDEX_STONE_TOWER_TEMPLE
-};
-
 /**
- * If the current scene is a boss scene, this function returns an index
- * indicating which one it is. Otherwise, it returns -1.
+ * Tests if the current scene is a boss scene.
+ * @return -1 if not a boss scene, else returns the dungeonIndex of the boss scene
  */
 s32 Map_GetBossAreaIndex(PlayState* play) {
+    static s32 sBossSceneIds[] = {
+        SCENE_MITURIN_BS, // DUNGEON_INDEX_WOODFALL_TEMPLE
+        SCENE_HAKUGIN_BS, // DUNGEON_INDEX_SNOWHEAD_TEMPLE
+        SCENE_SEA_BS,     // DUNGEON_INDEX_GREAT_BAY_TEMPLE
+        SCENE_INISIE_BS,  // DUNGEON_INDEX_STONE_TOWER_TEMPLE
+    };
     s32 i;
 
     for (i = 0; i < ARRAY_COUNT(sBossSceneIds); i++) {
@@ -100,9 +107,10 @@ s32 Map_GetBossAreaIndex(PlayState* play) {
 }
 
 /**
- * Returns true if the current scene is a boss scene, false otherwise.
+ * Checks if the current scene is a boss scene.
+ * @return true if the current scene is a boss scene, false otherwise.
  */
-s32 Map_IsInBossArea(PlayState* play) {
+s32 Map_IsInBossScene(PlayState* play) {
     if (Map_GetBossAreaIndex(play) == -1) {
         return false;
     }
@@ -110,13 +118,16 @@ s32 Map_IsInBossArea(PlayState* play) {
     return true;
 }
 
-s32 D_801BF5A4[] = {
-    SCENE_22DEKUCITY,
-    SCENE_KOEPONARACE,
-    SCENE_F01,
-};
-
-s32 func_8010A238(PlayState* play) {
+/**
+ * Test if the current scene is in a set of overworld scenes.
+ * @return -1 if not in the set, else returns the mapIndex of the overworld scene
+ */
+s32 Map_GetUnkOverworldAreaIndex(PlayState* play) {
+    static s32 D_801BF5A4[] = {
+        SCENE_22DEKUCITY,
+        SCENE_KOEPONARACE,
+        SCENE_F01,
+    };
     s32 i;
 
     for (i = 0; i < ARRAY_COUNT(D_801BF5A4); i++) {
@@ -128,8 +139,12 @@ s32 func_8010A238(PlayState* play) {
     return -1;
 }
 
-s32 func_8010A2AC(PlayState* play) {
-    if (func_8010A238(play) == -1) {
+/**
+ * Checks if the current scene is in a set of overworld scenes.
+ * @return true if the current scene is in the set, false otherwise.
+ */
+s32 Map_IsInUnkOverworldArea(PlayState* play) {
+    if (Map_GetUnkOverworldAreaIndex(play) == -1) {
         return false;
     }
 
@@ -137,15 +152,15 @@ s32 func_8010A2AC(PlayState* play) {
 }
 
 /**
- * When a room is loaded, this function is used to save the player's position and rotation
- * so that the red arrow on the minimap can be drawn correctly.
+ * Sets the position and rotation of where the player has entered the area.
+ * Used to draw the red marker on the minimap.
  */
-void Minimap_SavePlayerRoomInitInfo(PlayState* play) {
+void Map_SetAreaEntrypoint(PlayState* play) {
     Player* player = GET_PLAYER(play);
 
-    sMinimapInitPosX = player->actor.world.pos.x;
-    sMinimapInitPosZ = player->actor.world.pos.z;
-    sMinimapInitDir = (0x7FFF - player->actor.shape.rot.y) / 0x400;
+    sPlayerInitPosX = player->actor.world.pos.x;
+    sPlayerInitPosZ = player->actor.world.pos.z;
+    sPlayerInitDir = (0x7FFF - player->actor.shape.rot.y) / 0x400;
 }
 
 void Map_InitRoomData(PlayState* play, s16 room) {
@@ -156,8 +171,7 @@ void Map_InitRoomData(PlayState* play, s16 room) {
 
     if (room >= 0) {
         if (Map_IsInDungeonOrBossArea(play)) {
-            gSaveContext.save.saveInfo.permanentSceneFlags[Play_GetOriginalSceneId(play->sceneId)].rooms |=
-                gBitFlags[room];
+            SET_ROOM_VISITED(Play_GetOriginalSceneId(play->sceneId), room);
             interfaceCtx->mapRoomNum = room;
             interfaceCtx->dungeonOrBossAreaMapIndex = mapIndex;
         }
@@ -182,14 +196,13 @@ void Map_Init(PlayState* play) {
     interfaceCtx->unk_278 = -1;
     interfaceCtx->dungeonOrBossAreaMapIndex = -1;
     interfaceCtx->mapSegment = THA_AllocTailAlign16(&play->state.tha, 0x1000);
-    if (func_8010A2AC(play)) {
-        gSaveContext.mapIndex = func_8010A238(play);
+    if (Map_IsInUnkOverworldArea(play)) {
+        gSaveContext.mapIndex = Map_GetUnkOverworldAreaIndex(play);
         return;
     }
 
     if (Map_IsInDungeonOrBossArea(play)) {
-        dungeonIndex = Map_GetDungeonOrBossAreaIndex(play);
-        gSaveContext.mapIndex = dungeonIndex;
+        gSaveContext.mapIndex = dungeonIndex = Map_GetDungeonOrBossAreaIndex(play);
         switch (play->sceneId) {
             case SCENE_MITURIN_BS:
                 dungeonIndex = DUNGEON_INDEX_WOODFALL_TEMPLE;
@@ -213,8 +226,8 @@ void Map_Init(PlayState* play) {
     }
 }
 
-void Minimap_Draw(PlayState* play) {
-    func_80106644(play, sMinimapInitPosX, sMinimapInitPosZ, sMinimapInitDir);
+void Map_DrawMinimap(PlayState* play) {
+    MapDisp_DrawMinimap(play, sPlayerInitPosX, sPlayerInitPosZ, sPlayerInitDir);
 }
 
 s16 sLastRoomNum = 99;
@@ -228,7 +241,7 @@ void Map_Update(PlayState* play) {
     s32 pad2;
 
     if ((play->pauseCtx.state <= PAUSE_STATE_OPENING_2) && (CHECK_BTN_ALL(controller->press.button, BTN_L)) &&
-        !Play_InCsMode(play) && !func_80106530(play)) {
+        !Play_InCsMode(play) && !MapDisp_IsMinimapToggleBlocked(play)) {
         if (!R_MINIMAP_DISABLED) {
             Audio_PlaySfx(NA_SE_SY_CAMERA_ZOOM_UP);
         } else {
@@ -238,22 +251,21 @@ void Map_Update(PlayState* play) {
         R_MINIMAP_DISABLED ^= 1;
     }
 
-    func_80105B34(play);
+    MapDisp_Update(play);
 
     if ((play->pauseCtx.state == PAUSE_STATE_OFF) && (play->pauseCtx.debugEditor == DEBUG_EDITOR_NONE)) {
-        if (Map_IsInDungeonArea(play)) {
-            floor = func_80109124(player->actor.world.pos.y);
+        if (Map_IsInDungeonScene(play)) {
+            floor = MapDisp_GetPlayerStorey(player->actor.world.pos.y);
             if (floor != -1) {
-                gSaveContext.save.saveInfo.permanentSceneFlags[Play_GetOriginalSceneId(play->sceneId)].unk_14 |=
-                    gBitFlags[FLOOR_INDEX_MAX - floor];
-                R_REVERSE_FLOOR_INDEX = FLOOR_INDEX_MAX - floor;
+                SET_DUNGEON_FLOOR_VISITED(Play_GetOriginalSceneId(play->sceneId), FLOOR_INDEX_MAX - floor);
+                R_PLAYER_FLOOR_REVERSE_INDEX = FLOOR_INDEX_MAX - floor;
                 if (interfaceCtx->mapRoomNum != sLastRoomNum) {
                     sLastRoomNum = interfaceCtx->mapRoomNum;
                 }
             }
-        } else if (Map_IsInBossArea(play)) {
-            func_80105294();
-            R_REVERSE_FLOOR_INDEX = FLOOR_INDEX_MAX - func_80105318();
+        } else if (Map_IsInBossScene(play)) {
+            MapDisp_GetBossIconY();
+            R_PLAYER_FLOOR_REVERSE_INDEX = FLOOR_INDEX_MAX - MapDisp_GetBossRoomStorey();
         }
     }
 }