Document Camera for Elevator Platforms (Camera_Special7) (#1448)

* document camera for vertical platforms

* cleanup

* another rename

* small

* another rename

* add comment

* PR Suggestions

* more cleanup

* oops

* adjust comment

include/z64camera.h

@@ -89,8 +89,8 @@ typedef enum {
     /* 0x2D */ CAM_SET_BEAN_LOST_WOODS, // Lost woods bean "LIFTBEAN"
     /* 0x2E */ CAM_SET_SCENE_UNUSED, // Unused "SCENE0"
     /* 0x2F */ CAM_SET_SCENE_TRANSITION, // Scene Transitions "SCENE1"
-    /* 0x30 */ CAM_SET_FIRE_PLATFORM, // All the fire platforms that rise. Also used in non-mq spirit shortcut "HIDAN1"
+    /* 0x30 */ CAM_SET_ELEVATOR_PLATFORM, // All the fire temple platforms that rise. Also used in non-mq spirit temple entrance shortcut "HIDAN1"
-    /* 0x31 */ CAM_SET_FIRE_STAIRCASE, // Used on fire staircase actor cutscene in shortcut room connecting vanilla hammer chest to the final goron small key "HIDAN2"
+    /* 0x31 */ CAM_SET_FIRE_STAIRCASE, // Used on fire temple staircase actor cutscene in shortcut room connecting vanilla hammer chest to the final goron small key "HIDAN2"
     /* 0x32 */ CAM_SET_FOREST_UNUSED, // Unused "MORI2"
     /* 0x33 */ CAM_SET_FOREST_DEFEAT_POE, // Used when defeating a poe sister "MORI3"
     /* 0x34 */ CAM_SET_BIG_OCTO, // Used by big octo miniboss in Jabu Jabu "TAKO"
@@ -98,7 +98,7 @@ typedef enum {
     /* 0x36 */ CAM_SET_MEADOW_UNUSED, // Unused from Sacred Forest Meadow "SPOT05B"
     /* 0x37 */ CAM_SET_FIRE_BIRDS_EYE, // Used in lower-floor maze in non-mq fire temple "HIDAN3"
     /* 0x38 */ CAM_SET_TURN_AROUND, // Put the camera in front of player and turn around to look at player from the front "ITEM2"
-    /* 0x39 */ CAM_SET_PIVOT_VERTICAL, // Lowering platforms (forest temple bow room, Jabu final shortcut) "CAM_SET_PIVOT_VERTICAL"
+    /* 0x39 */ CAM_SET_PIVOT_VERTICAL, // Lowering platforms (forest temple bow room, Jabu final shortcut) "CIRCLE6"
     /* 0x3A */ CAM_SET_NORMAL2,
     /* 0x3B */ CAM_SET_FISHING, // Fishing pond by the lake
     /* 0x3C */ CAM_SET_CS_C, // Various cutscenes "DEMOC"
@@ -1255,7 +1255,7 @@ typedef struct {
     { flags, CAM_DATA_FLAGS }
 
 typedef struct {
-    /* 0x0 */ s16 index;
+    /* 0x0 */ s16 index; // See `CamElevatorPlatform`
 } Special7ReadWriteData; // size = 0x4
 
 typedef struct {

src/code/z_camera.c

@@ -6634,47 +6634,62 @@ s32 Camera_Special5(Camera* camera) {
 }
 
 /**
- * Camera's eye is fixed at points specified at D_8011DA6C / D_8011DA9C
+ * Camera's eye is fixed at points specified at lower or upper points depending on the player's position.
- * depending on the player's position
+ * Designed around 4 specific elevator platforms, 1 in spirit temple and 3 in fire temple.
+ * Used by `CAM_SET_ELEVATOR_PLATFORM`
  */
 s32 Camera_Special7(Camera* camera) {
     Special7ReadWriteData* rwData = &camera->paramData.spec7.rwData;
     PosRot* playerPosRot = &camera->playerPosRot;
     Vec3f atTarget;
-    f32 yOffset;
+    f32 yOffset = Player_GetHeight(camera->player);
-    f32 temp_f0;
+    f32 fovRollParam;
 
-    yOffset = Player_GetHeight(camera->player);
     if (camera->animState == 0) {
+        // Use sceneIds and hardcoded positions in the fire temple to identify the 4 platforms
         if (camera->play->sceneId == SCENE_SPIRIT_TEMPLE) {
-            // Spirit Temple
+            rwData->index = CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE;
-            rwData->index = 3;
-        } else if (playerPosRot->pos.x < 1500.0f) {
-            rwData->index = 2;
-        } else if (playerPosRot->pos.y < 3000.0f) {
-            rwData->index = 0;
         } else {
-            rwData->index = 1;
+            // Hardcoded positions in the fire temple
+            if (playerPosRot->pos.x < 1500.0f) {
+                rwData->index = CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER;
+            } else if (playerPosRot->pos.y < 3000.0f) {
+                rwData->index = CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR;
+            } else {
+                rwData->index = CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER;
+            }
         }
         camera->animState++;
         camera->roll = 0;
     }
 
-    if (camera->at.y < D_8011DACC[rwData->index]) {
+    if (camera->at.y < sCamElevatorPlatformTogglePosY[rwData->index]) {
+        // Cam at lower position
+
+        // look at player
         atTarget = playerPosRot->pos;
         atTarget.y -= 20.0f;
         Camera_LERPCeilVec3f(&atTarget, &camera->at, 0.4f, 0.4f, 0.10f);
-        camera->eye = camera->eyeNext = D_8011DA6C[rwData->index];
+
-        temp_f0 =
+        // place camera based on hard-coded positions
-            (playerPosRot->pos.y - D_8011DADC[rwData->index]) / (D_8011DACC[rwData->index] - D_8011DADC[rwData->index]);
+        camera->eye = camera->eyeNext = sCamElevatorPlatformLowerEyePoints[rwData->index];
-        camera->roll = D_8011DAEC[rwData->index] * temp_f0;
+
-        camera->fov = (20.0f * temp_f0) + 60.0f;
+        fovRollParam =
+            (playerPosRot->pos.y - sCamElevatorPlatformFovRollParam[rwData->index]) /
+            (sCamElevatorPlatformTogglePosY[rwData->index] - sCamElevatorPlatformFovRollParam[rwData->index]);
+        camera->roll = sCamElevatorPlatformRolls[rwData->index] * fovRollParam;
+        camera->fov = 60.0f + (20.0f * fovRollParam);
     } else {
+        // Cam at upper position
+
+        // look at player
         atTarget = playerPosRot->pos;
         atTarget.y += yOffset;
         Camera_LERPCeilVec3f(&atTarget, &camera->at, 0.4f, 0.4f, 0.1f);
+
         camera->roll = 0;
-        camera->eye = camera->eyeNext = D_8011DA9C[rwData->index];
+        // place camera based on hard-coded positions
+        camera->eye = camera->eyeNext = sCamElevatorPlatformUpperEyePoints[rwData->index];
         camera->fov = 70.0f;
     }
 

src/code/z_camera_data.inc.c

@@ -165,7 +165,7 @@ char sCameraSettingNames[][12] = {
     "LIFTBEAN   ", // CAM_SET_BEAN_LOST_WOODS
     "SCENE0     ", // CAM_SET_SCENE_UNUSED
     "SCENE1     ", // CAM_SET_SCENE_TRANSITION
-    "HIDAN1     ", // CAM_SET_FIRE_PLATFORM
+    "HIDAN1     ", // CAM_SET_ELEVATOR_PLATFORM
     "HIDAN2     ", // CAM_SET_FIRE_STAIRCASE
     "MORI2      ", // CAM_SET_FOREST_UNUSED
     "MORI3      ", // CAM_SET_FOREST_DEFEAT_POE
@@ -1894,7 +1894,7 @@ CameraMode sCamSetSceneTransitionModes[] = {
     CAM_SETTING_MODE_ENTRY(CAM_FUNC_UNIQ2, sSetSceneTransitionModeNormalData), // CAM_MODE_NORMAL
 };
 
-CameraMode sCamSetFirePlatformModes[] = {
+CameraMode sCamSetElevatorPlatformModes[] = {
     CAM_SETTING_MODE_ENTRY(CAM_FUNC_SPEC7, sDataOnlyNullFlags), // CAM_MODE_NORMAL
 };
 
@@ -2177,7 +2177,7 @@ CameraSetting sCameraSettings[] = {
     { { 0x451FFFFF }, sCamSetBeanLostWoodsModes },        // CAM_SET_BEAN_LOST_WOODS
     { { 0xC5000001 }, sCamSetSceneUnusedModes },          // CAM_SET_SCENE_UNUSED
     { { 0x45000001 }, sCamSetSceneTransitionModes },      // CAM_SET_SCENE_TRANSITION
-    { { 0x05000001 }, sCamSetFirePlatformModes },         // CAM_SET_FIRE_PLATFORM
+    { { 0x05000001 }, sCamSetElevatorPlatformModes },     // CAM_SET_ELEVATOR_PLATFORM
     { { 0x45000001 }, sCamSetFireStaircaseModes },        // CAM_SET_FIRE_STAIRCASE
     { { 0x45000001 }, sCamSetForestUnusedModes },         // CAM_SET_FOREST_UNUSED
     { { 0x45000001 }, sCamSetForestDefeatPoeModes },      // CAM_SET_FOREST_DEFEAT_POE
@@ -2565,22 +2565,52 @@ OnePointCsFull D_8011D9F4[] = {
     { 0x12, 0xFF, 0x0000, 0x0001, 0x0000, 60.0f, 1.0f, { -1.0f, -1.0f, -1.0f }, { -1.0f, -1.0f, -1.0f } },
 };
 
-Vec3f D_8011DA6C[] = {
+typedef enum {
-    { 3050.0f, 700.0f, 0.0f }, { 1755.0f, 3415.0f, -380.0f }, { -3120.0f, 3160.0f, 245.0f }, { 0.0f, -10.0f, 240.0f }
+    /* 0 */ CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR, // ACTOR_BG_HIDAN_ROCK
+    /* 1 */ CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER,  // ACTOR_BG_HIDAN_FSLIFT
+    /* 2 */ CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER,  // ACTOR_BG_HIDAN_SYOKU
+    /* 3 */ CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE   // ACTOR_BG_JYA_1FLIFT
+} CamElevatorPlatform;
+
+Vec3f sCamElevatorPlatformLowerEyePoints[] = {
+    { 3050.0f, 700.0f, 0.0f },     // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR
+    { 1755.0f, 3415.0f, -380.0f }, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER
+    { -3120.0f, 3160.0f, 245.0f }, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER
+    { 0.0f, -10.0f, 240.0f },      // CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE
 };
 
-Vec3f D_8011DA9C[] = {
+Vec3f sCamElevatorPlatformUpperEyePoints[] = {
-    { 3160.0f, 2150.0f, 0.0f },
+    { 3160.0f, 2150.0f, 0.0f },    // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR
-    { 1515.0f, 4130.0f, -835.0f },
+    { 1515.0f, 4130.0f, -835.0f }, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER
-    { -3040.0f, 4135.0f, 230.0f },
+    { -3040.0f, 4135.0f, 230.0f }, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER
-    { -50.0f, 600.0f, -75.0f },
+    { -50.0f, 600.0f, -75.0f },    // CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE
 };
 
-f32 D_8011DACC[] = { 1570.0f, 3680.0f, 3700.0f, 395.0f };
+// Trigger player y position to swap eye points
+f32 sCamElevatorPlatformTogglePosY[] = {
+    1570.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR
+    3680.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER
+    3700.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER
+    395.0f,  // CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE
+};
 
-f32 D_8011DADC[] = { 320.0f, 320.0f, 320.0f, 0.0f };
+f32 sCamElevatorPlatformFovRollParam[] = {
+    320.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR
+    320.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER
+    320.0f, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER
+    0.0f,   // CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE
+};
+
+s16 sCamElevatorPlatformRolls[] = {
+    -2000, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_LOWER_FLOOR
+    -1000, // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_EAST_TOWER
+    0,     // CAM_ELEVATOR_PLATFORM_FIRE_TEMPLE_WEST_TOWER
+    0      // CAM_ELEVATOR_PLATFORM_SPIRIT_TEMPLE_ENTRANCE
+};
 
-s16 D_8011DAEC[] = { -2000, -1000, 0, 0, 0, 0, 0, 0 };
+// unused
+s32 D_8011DAF4 = 0;
+s32 D_8011DAF8 = 0;
 
 s16 D_8011DAFC[] = {
     CAM_SET_NORMAL0, CAM_SET_NORMAL1, CAM_SET_NORMAL2, CAM_SET_DUNGEON0, CAM_SET_DUNGEON1, CAM_SET_DUNGEON2,

src/overlays/actors/ovl_Bg_Hidan_Fslift/z_bg_hidan_fslift.c

@@ -129,7 +129,7 @@ void BgHidanFslift_Update(Actor* thisx, PlayState* play) {
         if (this->unk_16A == 0) {
             this->unk_16A = 3;
         }
-        Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_FIRE_PLATFORM);
+        Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_ELEVATOR_PLATFORM);
     } else if (!DynaPolyActor_IsPlayerOnTop(&this->dyna)) {
         if (this->unk_16A != 0) {
             Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_DUNGEON0);

src/overlays/actors/ovl_Bg_Hidan_Rock/z_bg_hidan_rock.c

@@ -264,7 +264,7 @@ void func_8088B79C(BgHidanRock* this, PlayState* play) {
             if (this->unk_169 == 0) {
                 this->unk_169 = 3;
             }
-            Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_FIRE_PLATFORM);
+            Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_ELEVATOR_PLATFORM);
         } else if (!DynaPolyActor_IsPlayerOnTop(&this->dyna)) {
             if (this->unk_169 != 0) {
                 Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_DUNGEON0);
@@ -317,7 +317,7 @@ void func_8088B990(BgHidanRock* this, PlayState* play) {
             if (this->unk_169 == 0) {
                 this->unk_169 = 3;
             }
-            Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_FIRE_PLATFORM);
+            Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_ELEVATOR_PLATFORM);
         } else if (!DynaPolyActor_IsPlayerOnTop(&this->dyna)) {
             if (this->unk_169 != 0) {
                 Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_DUNGEON0);

src/overlays/actors/ovl_Bg_Hidan_Syoku/z_bg_hidan_syoku.c

@@ -112,7 +112,7 @@ void BgHidanSyoku_Update(Actor* thisx, PlayState* play) {
         if (this->unk_168 == 0) {
             this->unk_168 = 3;
         }
-        Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_FIRE_PLATFORM);
+        Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_ELEVATOR_PLATFORM);
     } else if (!DynaPolyActor_IsPlayerOnTop(&this->dyna)) {
         if (this->unk_168 != 0) {
             Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_DUNGEON0);

src/overlays/actors/ovl_Bg_Jya_1flift/z_bg_jya_1flift.c

@@ -189,7 +189,7 @@ void BgJya1flift_Update(Actor* thisx, PlayState* play2) {
         tempIsRiding = DynaPolyActor_IsPlayerOnTop(&this->dyna) ? true : false;
         if ((this->actionFunc == BgJya1flift_Move) || (this->actionFunc == BgJya1flift_DelayMove)) {
             if (tempIsRiding) {
-                Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_FIRE_PLATFORM);
+                Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_ELEVATOR_PLATFORM);
             } else if (!tempIsRiding && this->isLinkRiding) {
                 Camera_ChangeSetting(play->cameraPtrs[CAM_ID_MAIN], CAM_SET_DUNGEON0);
             }