Document Crawlspaces (#1286)

* Crawlspace docs, first draft

* Add wall docs

* OnePointDemo, fix

* format

* More player docs

* Document bgCamData

* Magic docs WIP

* More docs, first round finished

* Better docs

* More renaming

* Simpler name

* Another small adjustment

* rm if(1)

* Better names again after in-game testing

* Change comments

* change comment

* Big rename based on all the suggestions

* Small touch-up

* More PR Suggestions

* RESTORE_IDLE -> RESET

* More docs

* Capitalization

* PR suggestions

* Make declaration consistent

* Health_ChangeBy (amount)

* cleanup

* Document bgCamData

* More changes and cleanup

* More docs

* Clarify comments

* PR Suggestions

* Missed one

* More PR Suggestions

* Change comment

* Add another clarity comment

* format

* PR Feedback, rename bgcheck functions

* remove fallthrough cleanup (other pr that deals with that)

* PR Suggestions

* bug report

* sync with bgCamData PR

* small cleanup

* Another comment

* bgCamDataIndexBeforeUnderwater

* PR/Discord Discussions

* Missed some

* sync function header args

* Another suggestion

* cleanup

* Comments

* Change bgCamData to s16 for now

* PR suggestions

* the

* use "info"

* Missed a suggestion

* Discord Discussion

* Document playerFlag

* typo

* Revert bgCamFuncData to Vec3s

* format

* format

* First PR suggestion

* Some PR Suggestions, still need to test

* followup docs

* small cleanup

* target offset

* more PR

* forwardYaw

* crawlspace func/flag

* comment

* format

* Update include/z64player.h

Co-authored-by: Dragorn421 <Dragorn421@users.noreply.github.com>

* More PR Suggestions

* Update src/overlays/actors/ovl_player_actor/z_player.c

Co-authored-by: EllipticEllipsis <elliptic.ellipsis@gmail.com>

Co-authored-by: Dragorn421 <Dragorn421@users.noreply.github.com>
Co-authored-by: EllipticEllipsis <elliptic.ellipsis@gmail.com>

6 files changed, 130 insertions, 95 deletions

diff --git a/src/code/z_bgcheck.c b/src/code/z_bgcheck.c
index 69c6cd7ae..22cc9c782 100644
--- a/src/code/z_bgcheck.c
+++ b/src/code/z_bgcheck.c
@@ -63,8 +63,8 @@ s32 D_80119D90[WALL_TYPE_MAX] = {
     WALL_FLAG_0 | WALL_FLAG_1, // WALL_TYPE_2
     WALL_FLAG_0 | WALL_FLAG_2, // WALL_TYPE_3
     WALL_FLAG_3,               // WALL_TYPE_4
-    WALL_FLAG_4,               // WALL_TYPE_5
-    WALL_FLAG_5,               // WALL_TYPE_6
+    WALL_FLAG_CRAWLSPACE_1,    // WALL_TYPE_5
+    WALL_FLAG_CRAWLSPACE_2,    // WALL_TYPE_6
     WALL_FLAG_6,               // WALL_TYPE_7
 };
 
diff --git a/src/code/z_camera.c b/src/code/z_camera.c
index 035d25706..a31cfd43a 100644
--- a/src/code/z_camera.c
+++ b/src/code/z_camera.c
@@ -4372,21 +4372,25 @@ s32 Camera_Subj4(Camera* camera) {
     Vec3f* at = &camera->at;
     u16 crawlspaceNumPoints;
     Vec3s* crawlspacePoints;
-    Vec3f sp98;
-    Vec3f sp8C;
-    f32 sp88;
-    s16 pad2;
-    f32 temp_f16;
-    PosRot sp6C;
-    VecGeo sp64;
-    VecGeo sp5C;
-    s16 temp_a0;
-    f32 tx;
+    Vec3f temp1;
+    Vec3f zoomAtTarget;
+    f32 temp2;
     Player* player;
-    PosRot* playerPosRot = &camera->playerPosRot;
+    f32 eyeLerp;
+    PosRot playerPosRot;
+    VecGeo targetOffset;
+    VecGeo atEyeOffset;
+    s16 eyeToAtYaw;
+    s32 pad[2];
+    f32 temp;
     Subj4ReadOnlyData* roData = &camera->paramData.subj4.roData;
     Subj4ReadWriteData* rwData = &camera->paramData.subj4.rwData;
 
+#define vCrawlSpaceBackPos temp1
+#define vEyeTarget temp1
+#define vPlayerDistToFront temp2
+#define vZoomTimer temp2
+
     if (RELOAD_PARAMS(camera) || R_RELOAD_CAM_PARAMS) {
         CameraModeValue* values = sCameraSettings[camera->setting].cameraModes[camera->mode].values;
 
@@ -4398,99 +4402,126 @@ s32 Camera_Subj4(Camera* camera) {
     }
 
     if (camera->play->view.unk_124 == 0) {
-        camera->play->view.unk_124 = (camera->camId | 0x50);
-        rwData->unk_24 = camera->xzSpeed;
+        camera->play->view.unk_124 = camera->camId | 0x50;
+        rwData->xzSpeed = camera->xzSpeed;
         return true;
     }
 
-    Actor_GetWorldPosShapeRot(&sp6C, &camera->player->actor);
+    Actor_GetWorldPosShapeRot(&playerPosRot, &camera->player->actor);
+    OLib_Vec3fDiffToVecGeo(&atEyeOffset, at, eye);
 
-    OLib_Vec3fDiffToVecGeo(&sp5C, at, eye);
     sCameraInterfaceFlags = roData->interfaceFlags;
+
+    // Crawlspace setup (runs for only 1 frame)
     if (camera->animState == 0) {
         crawlspacePoints = (Vec3s*)Camera_GetBgCamFuncDataUnderPlayer(camera, &crawlspaceNumPoints);
-        Camera_Vec3sToVec3f(&rwData->unk_00.point, &crawlspacePoints[1]);
-        Camera_Vec3sToVec3f(&sp98, &crawlspacePoints[crawlspaceNumPoints - 2]);
-
-        sp64.r = 10.0f;
-        // 0x238C ~ 50 degrees
-        sp64.pitch = 0x238C;
-        sp64.yaw = Camera_XZAngle(&sp98, &rwData->unk_00.point);
-        sp88 = OLib_Vec3fDist(&playerPosRot->pos, &rwData->unk_00.point);
-        if (OLib_Vec3fDist(&playerPosRot->pos, &sp98) < sp88) {
-            rwData->unk_00.dir.x = rwData->unk_00.point.x - sp98.x;
-            rwData->unk_00.dir.y = rwData->unk_00.point.y - sp98.y;
-            rwData->unk_00.dir.z = rwData->unk_00.point.z - sp98.z;
-            rwData->unk_00.point = sp98;
+        // Second entry of crawlspacePoints contains the front position
+        Camera_Vec3sToVec3f(&rwData->crawlspaceLine.point, &crawlspacePoints[1]);
+        // Second last entry of crawlspacePoints contains the back position
+        Camera_Vec3sToVec3f(&vCrawlSpaceBackPos, &crawlspacePoints[crawlspaceNumPoints - 2]);
+
+        targetOffset.r = 10.0f;
+        targetOffset.pitch = 0x238C; // ~50 degrees
+        targetOffset.yaw = Camera_XZAngle(&vCrawlSpaceBackPos, &rwData->crawlspaceLine.point);
+
+        vPlayerDistToFront = OLib_Vec3fDist(&camera->playerPosRot.pos, &rwData->crawlspaceLine.point);
+        if (OLib_Vec3fDist(&camera->playerPosRot.pos, &vCrawlSpaceBackPos) < vPlayerDistToFront) {
+            // Player is entering the crawlspace from the back
+            rwData->crawlspaceLine.dir.x = rwData->crawlspaceLine.point.x - vCrawlSpaceBackPos.x;
+            rwData->crawlspaceLine.dir.y = rwData->crawlspaceLine.point.y - vCrawlSpaceBackPos.y;
+            rwData->crawlspaceLine.dir.z = rwData->crawlspaceLine.point.z - vCrawlSpaceBackPos.z;
+            rwData->crawlspaceLine.point = vCrawlSpaceBackPos;
         } else {
-            rwData->unk_00.dir.x = sp98.x - rwData->unk_00.point.x;
-            rwData->unk_00.dir.y = sp98.y - rwData->unk_00.point.y;
-            rwData->unk_00.dir.z = sp98.z - rwData->unk_00.point.z;
-            sp64.yaw = sp64.yaw - 0x7FFF;
-        }
-        rwData->unk_30 = sp64.yaw;
-        rwData->unk_32 = 0xA;
-        rwData->unk_2C = 0;
-        rwData->unk_2E = false;
-        rwData->unk_28 = 0.0f;
+            // Player is entering the crawlspace from the front
+            rwData->crawlspaceLine.dir.x = vCrawlSpaceBackPos.x - rwData->crawlspaceLine.point.x;
+            rwData->crawlspaceLine.dir.y = vCrawlSpaceBackPos.y - rwData->crawlspaceLine.point.y;
+            rwData->crawlspaceLine.dir.z = vCrawlSpaceBackPos.z - rwData->crawlspaceLine.point.z;
+            targetOffset.yaw -= 0x7FFF;
+        }
+
+        rwData->forwardYaw = targetOffset.yaw;
+        rwData->zoomTimer = 10;
+        rwData->eyeLerpPhase = 0;
+        rwData->isSfxOff = false;
+        rwData->eyeLerp = 0.0f;
         camera->animState++;
     }
 
-    if (rwData->unk_32 != 0) {
-        sp64.r = 10.0f;
-        sp64.pitch = 0x238C;
-        sp64.yaw = rwData->unk_30;
-        Camera_AddVecGeoToVec3f(&sp8C, &sp6C.pos, &sp64);
-        sp88 = (rwData->unk_32 + 1.0f);
-        at->x += (sp8C.x - at->x) / sp88;
-        at->y += (sp8C.y - at->y) / sp88;
-        at->z += (sp8C.z - at->z) / sp88;
-        sp5C.r -= (sp5C.r / sp88);
-        sp5C.yaw = BINANG_LERPIMPINV(sp5C.yaw, (s16)(sp6C.rot.y - 0x7FFF), rwData->unk_32);
-        sp5C.pitch = BINANG_LERPIMPINV(sp5C.pitch, sp6C.rot.x, rwData->unk_32);
-        Camera_AddVecGeoToVec3f(eyeNext, at, &sp5C);
+    // Camera zooms in from third person to first person over 10 frames
+    if (rwData->zoomTimer != 0) {
+        targetOffset.r = 10.0f;
+        targetOffset.pitch = 0x238C; // ~50 degrees
+        targetOffset.yaw = rwData->forwardYaw;
+        Camera_AddVecGeoToVec3f(&zoomAtTarget, &playerPosRot.pos, &targetOffset);
+
+        vZoomTimer = rwData->zoomTimer + 1.0f;
+        at->x = F32_LERPIMPINV(at->x, zoomAtTarget.x, vZoomTimer);
+        at->y = F32_LERPIMPINV(at->y, zoomAtTarget.y, vZoomTimer);
+        at->z = F32_LERPIMPINV(at->z, zoomAtTarget.z, vZoomTimer);
+
+        atEyeOffset.r -= (atEyeOffset.r / vZoomTimer);
+        atEyeOffset.yaw = BINANG_LERPIMPINV(atEyeOffset.yaw, (s16)(playerPosRot.rot.y - 0x7FFF), rwData->zoomTimer);
+        atEyeOffset.pitch = BINANG_LERPIMPINV(atEyeOffset.pitch, playerPosRot.rot.x, rwData->zoomTimer);
+        Camera_AddVecGeoToVec3f(eyeNext, at, &atEyeOffset);
         *eye = *eyeNext;
-        rwData->unk_32--;
+        rwData->zoomTimer--;
         return false;
-    } else if (rwData->unk_24 < 0.5f) {
+    }
+
+    if (rwData->xzSpeed < 0.5f) {
         return false;
     }
 
-    Actor_GetWorldPosShapeRot(&sp6C, &camera->player->actor);
-    Math3D_LineClosestToPoint(&rwData->unk_00, &sp6C.pos, eyeNext);
-    at->x = eyeNext->x + rwData->unk_00.dir.x;
-    at->y = eyeNext->y + rwData->unk_00.dir.y;
-    at->z = eyeNext->z + rwData->unk_00.dir.z;
+    Actor_GetWorldPosShapeRot(&playerPosRot, &camera->player->actor);
+    Math3D_LineClosestToPoint(&rwData->crawlspaceLine, &playerPosRot.pos, eyeNext);
+
+    // *at is unused before getting overwritten later this function
+    at->x = eyeNext->x + rwData->crawlspaceLine.dir.x;
+    at->y = eyeNext->y + rwData->crawlspaceLine.dir.y;
+    at->z = eyeNext->z + rwData->crawlspaceLine.dir.z;
+
     *eye = *eyeNext;
-    sp64.yaw = rwData->unk_30;
-    sp64.r = 5.0f;
-    sp64.pitch = 0x238C;
-    Camera_AddVecGeoToVec3f(&sp98, eyeNext, &sp64);
-    rwData->unk_2C += 0xBB8;
-    temp_f16 = Math_CosS(rwData->unk_2C);
-    eye->x += (sp98.x - eye->x) * fabsf(temp_f16);
-    eye->y += (sp98.y - eye->y) * fabsf(temp_f16);
-    eye->z += (sp98.z - eye->z) * fabsf(temp_f16);
-
-    if ((rwData->unk_28 < temp_f16) && !rwData->unk_2E) {
+
+    targetOffset.yaw = rwData->forwardYaw;
+    targetOffset.r = 5.0f;
+    targetOffset.pitch = 0x238C; // ~50 degrees
+
+    Camera_AddVecGeoToVec3f(&vEyeTarget, eyeNext, &targetOffset);
+
+    rwData->eyeLerpPhase += 0xBB8;
+    eyeLerp = Math_CosS(rwData->eyeLerpPhase);
+
+    // VEC3F_LERPIMPDST(eye, eye, &vEyeTarget, fabsf(eyeLerp))
+    eye->x += (vEyeTarget.x - eye->x) * fabsf(eyeLerp);
+    eye->y += (vEyeTarget.y - eye->y) * fabsf(eyeLerp);
+    eye->z += (vEyeTarget.z - eye->z) * fabsf(eyeLerp);
+
+    // When camera reaches the peak of offset and starts to move down
+    // && alternating cycles (sfx plays only every 2nd cycle)
+    if ((eyeLerp > rwData->eyeLerp) && !rwData->isSfxOff) {
         player = camera->player;
-        rwData->unk_2E = true;
-        func_800F4010(&player->actor.projectedPos, player->unk_89E + 0x8B0, 4.0f);
-    } else if (rwData->unk_28 > temp_f16) {
-        rwData->unk_2E = false;
+        rwData->isSfxOff = true;
+        func_800F4010(&player->actor.projectedPos, NA_SE_PL_CRAWL + player->unk_89E, 4.0f);
+    } else if (eyeLerp < rwData->eyeLerp) {
+        rwData->isSfxOff = false;
     }
 
-    rwData->unk_28 = temp_f16;
+    rwData->eyeLerp = eyeLerp;
+
     camera->player->actor.world.pos = *eyeNext;
     camera->player->actor.world.pos.y = camera->playerGroundY;
-    camera->player->actor.shape.rot.y = sp64.yaw;
-    temp_f16 = ((240.0f * temp_f16) * (rwData->unk_24 * 0.416667f));
-    temp_a0 = temp_f16 + rwData->unk_30;
-    at->x = eye->x + (Math_SinS(temp_a0) * 10.0f);
+    camera->player->actor.shape.rot.y = targetOffset.yaw;
+
+    eyeLerp = (240.0f * eyeLerp) * (rwData->xzSpeed * 0.416667f);
+    eyeToAtYaw = rwData->forwardYaw + eyeLerp;
+
+    at->x = eye->x + (Math_SinS(eyeToAtYaw) * 10.0f);
     at->y = eye->y;
-    at->z = eye->z + (Math_CosS(temp_a0) * 10.0f);
+    at->z = eye->z + (Math_CosS(eyeToAtYaw) * 10.0f);
+
     camera->roll = Camera_LERPCeilS(0, camera->roll, 0.5f, 0xA);
-    return 1;
+
+    return true;
 }
 
 s32 Camera_Subj0(Camera* camera) {
diff --git a/src/code/z_onepointdemo.c b/src/code/z_onepointdemo.c
index dc3a67531..76d353418 100644
--- a/src/code/z_onepointdemo.c
+++ b/src/code/z_onepointdemo.c
@@ -331,14 +331,18 @@ s32 OnePointCutscene_SetInfo(PlayState* play, s16 subCamId, s16 csId, Actor* act
             Play_SetCameraRoll(play, subCamId, childCam->roll);
             break;
         case 9601:
+            // Leaving a crawlspace forwards
             Play_CameraChangeSetting(play, subCamId, CAM_SET_CS_3);
             Play_CameraChangeSetting(play, CAM_ID_MAIN, mainCam->prevSetting);
-            OnePointCutscene_SetCsCamPoints(subCam, D_80120430 | 0x1000, D_8012042C, D_80120308, D_80120398);
+            OnePointCutscene_SetCsCamPoints(subCam, sCrawlspaceActionParam | 0x1000, sCrawlspaceTimer,
+                                            sCrawlspaceAtPoints, sCrawlspaceForwardsEyePoints);
             break;
         case 9602:
+            // Leaving a crawlspace backwards
             Play_CameraChangeSetting(play, subCamId, CAM_SET_CS_3);
             Play_CameraChangeSetting(play, CAM_ID_MAIN, mainCam->prevSetting);
-            OnePointCutscene_SetCsCamPoints(subCam, D_80120430 | 0x1000, D_8012042C, D_80120308, D_80120434);
+            OnePointCutscene_SetCsCamPoints(subCam, sCrawlspaceActionParam | 0x1000, sCrawlspaceTimer,
+                                            sCrawlspaceAtPoints, sCrawlspaceBackwardsEyePoints);
             break;
         case 4175:
             csInfo->keyFrames = D_8012147C;
diff --git a/src/code/z_onepointdemo_data.inc.c b/src/code/z_onepointdemo_data.inc.c
index 1d1838b05..c3dc20494 100644
--- a/src/code/z_onepointdemo_data.inc.c
+++ b/src/code/z_onepointdemo_data.inc.c
@@ -29,24 +29,24 @@ static s16 D_801202FC = 13;
 static s16 D_80120300 = 210;
 static s16 D_80120304 = 0;
 
-static CutsceneCameraPoint D_80120308[9] = {
+static CutsceneCameraPoint sCrawlspaceAtPoints[9] = {
     { CS_CMD_CONTINUE, 0, 10, 40.0f, { 0, 4, 0 } },  { CS_CMD_CONTINUE, 0, 10, 40.000004f, { 0, 4, 0 } },
     { CS_CMD_CONTINUE, 0, 10, 50.0f, { 0, 9, 0 } },  { CS_CMD_CONTINUE, 0, 12, 55.0f, { 0, 12, 0 } },
     { CS_CMD_CONTINUE, 0, 15, 61.0f, { 0, 18, 0 } }, { CS_CMD_CONTINUE, 0, 20, 65.0f, { 0, 29, 0 } },
     { CS_CMD_CONTINUE, 0, 40, 60.0f, { 0, 34, 0 } }, { CS_CMD_STOP, 0, 40, 60.0f, { 0, 34, 0 } },
     { CS_CMD_STOP, 0, 10, 60.0f, { 0, 34, 0 } },
 };
-static CutsceneCameraPoint D_80120398[9] = {
+static CutsceneCameraPoint sCrawlspaceForwardsEyePoints[9] = {
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 9, 45 } },   { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 8, 50 } },
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 17, 58 } },  { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 21, 78 } },
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 46, 109 } }, { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 58, 118 } },
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 63, 119 } }, { CS_CMD_STOP, 0, 0, 60.0f, { 0, 62, 119 } },
     { CS_CMD_STOP, 0, 0, 60.0f, { 0, 62, 119 } },
 };
-static s16 D_80120428 = 9;
-static s16 D_8012042C = 90;
-static s16 D_80120430 = 1;
-static CutsceneCameraPoint D_80120434[10] = {
+static s16 sCrawlspaceUnused = 9;
+static s16 sCrawlspaceTimer = 90;
+static s16 sCrawlspaceActionParam = 1;
+static CutsceneCameraPoint sCrawlspaceBackwardsEyePoints[10] = {
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 9, -45 } },   { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 9, -45 } },
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 8, -50 } },   { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 17, -58 } },
     { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 21, -78 } },  { CS_CMD_CONTINUE, 0, 0, 60.0f, { 0, 46, -109 } },
diff --git a/src/code/z_parameter.c b/src/code/z_parameter.c
index 416ff89cd..a120332d5 100644
--- a/src/code/z_parameter.c
+++ b/src/code/z_parameter.c
@@ -759,7 +759,7 @@ void func_80083108(PlayState* play) {
                 }
 
                 Interface_ChangeAlpha(50);
-            } else if ((player->stateFlags1 & PLAYER_STATE1_21) || (player->stateFlags2 & PLAYER_STATE2_18)) {
+            } else if ((player->stateFlags1 & PLAYER_STATE1_21) || (player->stateFlags2 & PLAYER_STATE2_CRAWLING)) {
                 if (gSaveContext.buttonStatus[0] != BTN_DISABLED) {
                     gSaveContext.buttonStatus[0] = BTN_DISABLED;
                     gSaveContext.buttonStatus[1] = BTN_DISABLED;
@@ -2803,7 +2803,7 @@ void Interface_DrawItemButtons(PlayState* play) {
             if ((gSaveContext.unk_13EA == 1) || (gSaveContext.unk_13EA == 2) || (gSaveContext.unk_13EA == 5)) {
                 temp = 0;
             } else if ((player->stateFlags1 & PLAYER_STATE1_21) || (func_8008F2F8(play) == 4) ||
-                       (player->stateFlags2 & PLAYER_STATE2_18)) {
+                       (player->stateFlags2 & PLAYER_STATE2_CRAWLING)) {
                 temp = 70;
             } else {
                 temp = interfaceCtx->healthAlpha;
diff --git a/src/code/z_player_lib.c b/src/code/z_player_lib.c
index be8e2a40d..8a3ab9563 100644
--- a/src/code/z_player_lib.c
+++ b/src/code/z_player_lib.c
@@ -899,7 +899,7 @@ void Player_DrawImpl(PlayState* play, void** skeleton, Vec3s* jointTable, s32 dL
     SkelAnime_DrawFlexLod(play, skeleton, jointTable, dListCount, overrideLimbDraw, postLimbDraw, data, lod);
 
     if ((overrideLimbDraw != Player_OverrideLimbDrawGameplayFirstPerson) &&
-        (overrideLimbDraw != Player_OverrideLimbDrawGameplay_80090440) &&
+        (overrideLimbDraw != Player_OverrideLimbDrawGameplayCrawling) &&
         (gSaveContext.gameMode != GAMEMODE_END_CREDITS)) {
         if (LINK_IS_ADULT) {
             s32 strengthUpgrade = CUR_UPG_VALUE(UPG_STRENGTH);
@@ -1198,8 +1198,8 @@ s32 Player_OverrideLimbDrawGameplayFirstPerson(PlayState* play, s32 limbIndex, G
     return false;
 }
 
-s32 Player_OverrideLimbDrawGameplay_80090440(PlayState* play, s32 limbIndex, Gfx** dList, Vec3f* pos, Vec3s* rot,
-                                             void* thisx) {
+s32 Player_OverrideLimbDrawGameplayCrawling(PlayState* play, s32 limbIndex, Gfx** dList, Vec3f* pos, Vec3s* rot,
+                                            void* thisx) {
     if (!Player_OverrideLimbDrawGameplayCommon(play, limbIndex, dList, pos, rot, thisx)) {
         *dList = NULL;
     }