Code_800E8EA0 Docs (#832)

* Start

* Add notes from OOT

* D_801D0D50 -> gDbgCamEnabled

* Rotation Functions

* Text function

* RotateBack -> RotateForward

* Flags functions

* Document rotation func returns

* Remove comment from play

* Rename play function, add notes about Flags, add notes about focus

* Update notes a little

* Update src/code/code_800E8EA0.c

Co-authored-by: engineer124 <47598039+engineer124@users.noreply.github.com>

* Fix apostrophes

* Bring over OoT changes

* TurnTo -> Track in SubS systesm

* format and remove OoT specific comment

* Remove old comments

* namefixer

Co-authored-by: engineer124 <47598039+engineer124@users.noreply.github.com>

5 files changed, 125 insertions, 87 deletions

diff --git a/src/code/code_800E8EA0.c b/src/code/code_800E8EA0.c
index d95f53269..6fb787451 100644
--- a/src/code/code_800E8EA0.c
+++ b/src/code/code_800E8EA0.c
@@ -1,107 +1,148 @@
 #include "global.h"
 
-void func_800E8EA0(GlobalContext* globalCtx, Actor* actor, u16 textId) {
+void Actor_ContinueText(GlobalContext* globalCtx, Actor* actor, u16 textId) {
     func_80151938(globalCtx, textId);
     actor->textId = textId;
 }
 
-s32 nop_800E8ED0(UNK_TYPE4 param_1) {
-    return 0;
+/**
+ * EventCheckInf does not exist, so this always returns false
+ */
+s32 Flags_GetEventChkInf(s32 flag) {
+    return false;
 }
 
-void nop_800E8EE0(UNK_TYPE4 param_1) {
+/**
+ * EventCheckInf does not exist, so this does nothing
+ */
+void Flags_SetEventChkInf(s32 flag) {
 }
 
-s32 nop_800E8EEC(UNK_TYPE4 param_1) {
-    return 0;
+/**
+ * InfTable does not exist, so this always returns false
+ */
+s32 Flags_GetInfTable(s32 flag) {
+    return false;
 }
 
-void nop_800E8EFC(UNK_TYPE4 param_1) {
+/**
+ * InfTable does not exist, so this does nothing
+ */
+void Flags_SetInfTable(s32 flag) {
 }
 
-s32 func_800E8F08(Vec3s* param_1, Vec3s* param_2) {
-    Math_SmoothStepToS(&param_1->y, 0, 6, 6200, 100);
-    Math_SmoothStepToS(&param_1->x, 0, 6, 6200, 100);
-    Math_SmoothStepToS(&param_2->y, 0, 6, 6200, 100);
-    Math_SmoothStepToS(&param_2->x, 0, 6, 6200, 100);
-    return 1;
+s32 Actor_TrackNone(Vec3s* headRot, Vec3s* torsoRot) {
+    Math_SmoothStepToS(&headRot->y, 0, 6, 0x1838, 0x64);
+    Math_SmoothStepToS(&headRot->x, 0, 6, 0x1838, 0x64);
+    Math_SmoothStepToS(&torsoRot->y, 0, 6, 0x1838, 0x64);
+    Math_SmoothStepToS(&torsoRot->x, 0, 6, 0x1838, 0x64);
+    return true;
 }
 
-s32 func_800E8FA4(Actor* actor, Vec3f* param_2, Vec3s* param_3, Vec3s* param_4) {
+s32 Actor_TrackPoint(Actor* actor, Vec3f* target, Vec3s* headRot, Vec3s* torsoRot) {
     s16 targetPitch;
     s16 targetYaw;
-    s16 yawDiffFromTarget;
+    s16 yawDiff;
 
-    targetPitch = Math_Vec3f_Pitch(&actor->focus.pos, param_2);
-    targetYaw = Math_Vec3f_Yaw(&actor->focus.pos, param_2) - actor->world.rot.y;
+    targetPitch = Math_Vec3f_Pitch(&actor->focus.pos, target);
+    targetYaw = Math_Vec3f_Yaw(&actor->focus.pos, target) - actor->world.rot.y;
 
-    Math_SmoothStepToS(&param_3->x, targetPitch, 6, 2000, 1);
-    param_3->x = CLAMP(param_3->x, -6000, 6000);
+    Math_SmoothStepToS(&headRot->x, targetPitch, 6, 0x7D0, 1);
+    headRot->x = CLAMP(headRot->x, -0x1770, 0x1770);
 
-    yawDiffFromTarget = Math_SmoothStepToS(&param_3->y, targetYaw, 6, 2000, 1);
-    param_3->y = CLAMP(param_3->y, -8000, 8000);
+    yawDiff = Math_SmoothStepToS(&headRot->y, targetYaw, 6, 0x7D0, 1);
+    headRot->y = CLAMP(headRot->y, -0x1F40, 0x1F40);
 
-    if (yawDiffFromTarget != 0) {
-        if (ABS_ALT(param_3->y) < 8000) {
-            return 0;
-        }
+    if ((yawDiff != 0) && (ABS_ALT(headRot->y) < 0x1F40)) {
+        return false;
     }
 
-    Math_SmoothStepToS(&param_4->y, targetYaw - param_3->y, 4, 2000, 1);
-    param_4->y = CLAMP(param_4->y, -12000, 12000);
+    Math_SmoothStepToS(&torsoRot->y, targetYaw - headRot->y, 4, 0x7D0, 1);
+    torsoRot->y = CLAMP(torsoRot->y, -0x2EE0, 0x2EE0);
 
-    return 1;
+    return true;
 }
 
-s32 func_800E9138(GlobalContext* globalCtx, Actor* actor, Vec3s* param_3, Vec3s* param_4, f32 param_5) {
+/**
+ * Same as Actor_TrackPlayer, except use the actor's world position as the focus point, with the height
+ * specified.
+ *
+ * @param play
+ * @param actor
+ * @param headRot the computed actor's head's rotation step
+ * @param torsoRot the computed actor's torso's rotation step
+ * @param focusHeight the height of the focus point relative to their world position
+ *
+ * @return true if rotated towards player, false if rotations were stepped back to zero.
+ *
+ * @note same note as Actor_TrackPlayer
+ */
+s32 Actor_TrackPlayerSetFocusHeight(GlobalContext* globalCtx, Actor* actor, Vec3s* headRot, Vec3s* torsoRot,
+                                    f32 focusHeight) {
     Player* player = GET_PLAYER(globalCtx);
-    s16 sVar3;
-    Vec3f local_14;
+    s16 yaw;
+    Vec3f target;
 
     actor->focus.pos = actor->world.pos;
-    actor->focus.pos.y += param_5;
+    actor->focus.pos.y += focusHeight;
 
-    if (((globalCtx->csCtx).state == 0) && (D_801D0D50 == 0)) {
-        sVar3 = ABS_ALT(BINANG_SUB(actor->yawTowardsPlayer, actor->shape.rot.y));
-        if (sVar3 >= 0x4300) {
-            func_800E8F08(param_3, param_4);
-            return 0;
+    if (!((globalCtx->csCtx.state != 0) || gDbgCamEnabled)) {
+        yaw = ABS_ALT(BINANG_SUB(actor->yawTowardsPlayer, actor->shape.rot.y));
+        if (yaw >= 0x4300) {
+            Actor_TrackNone(headRot, torsoRot);
+            return false;
         }
     }
 
-    if (((globalCtx->csCtx).state != 0) || (D_801D0D50 != 0)) {
-        local_14 = globalCtx->view.eye;
+    if ((globalCtx->csCtx.state != 0) || gDbgCamEnabled) {
+        target = globalCtx->view.eye;
     } else {
-        local_14 = player->actor.focus.pos;
+        target = player->actor.focus.pos;
     }
 
-    func_800E8FA4(actor, &local_14, param_3, param_4);
+    Actor_TrackPoint(actor, &target, headRot, torsoRot);
 
-    return 1;
+    return true;
 }
 
-s32 func_800E9250(GlobalContext* globalCtx, Actor* actor, Vec3s* param_3, Vec3s* param_4, Vec3f param_5) {
+/**
+ * Computes the necessary HeadRot and TorsoRot steps to be added to the normal rotation to smoothly turn an actors's
+ * head and torso towards the player if within a certain yaw, else smoothly returns the rotations back to zero.
+ * Also sets the focus position with the specified point.
+ *
+ * @param play
+ * @param actor
+ * @param headRot the computed actor's head's rotation step
+ * @param torsoRot the computed actor's torso's rotation step
+ * @param focusPos the point to set as the actor's focus position
+ *
+ * @return true if rotated towards player, false if rotations were stepped back to zero.
+ *
+ * @note if in a cutscene or debug camera is enabled, the computed rotation will instead turn towards the view eye no
+ * matter the yaw.
+ */
+s32 Actor_TrackPlayer(GlobalContext* globalCtx, Actor* actor, Vec3s* headRot, Vec3s* torsoRot, Vec3f focusPos) {
     Player* player = GET_PLAYER(globalCtx);
-    s16 sVar3;
-    Vec3f local_14;
+    s16 yaw;
+    Vec3f target;
 
-    actor->focus.pos = param_5;
+    actor->focus.pos = focusPos;
 
-    if (((globalCtx->csCtx).state == 0) && (D_801D0D50 == 0)) {
-        sVar3 = ABS_ALT(BINANG_SUB(actor->yawTowardsPlayer, actor->shape.rot.y));
-        if (sVar3 >= 0x4300) {
-            func_800E8F08(param_3, param_4);
-            return 0;
+    if (!((globalCtx->csCtx.state != 0) || gDbgCamEnabled)) {
+        yaw = ABS_ALT(BINANG_SUB(actor->yawTowardsPlayer, actor->shape.rot.y));
+        if (yaw >= 0x4300) {
+            Actor_TrackNone(headRot, torsoRot);
+            return false;
         }
     }
 
-    if (((globalCtx->csCtx).state != 0) || (D_801D0D50 != 0)) {
-        local_14 = globalCtx->view.eye;
+    if ((globalCtx->csCtx.state != 0) || gDbgCamEnabled) {
+        target = globalCtx->view.eye;
     } else {
-        local_14 = player->actor.focus.pos;
+        target = player->actor.focus.pos;
     }
 
-    func_800E8FA4(actor, &local_14, param_3, param_4);
+    Actor_TrackPoint(actor, &target, headRot, torsoRot);
 
-    return 1;
+    return true;
 }
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 4e1e641de..ddc22949b 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -4281,7 +4281,7 @@ s16 func_800BDB6C(Actor* actor, GlobalContext* globalCtx, s16 arg2, f32 arg3) {
     Player* player = GET_PLAYER(globalCtx);
     f32 phi_f2;
 
-    if ((globalCtx->csCtx.state != 0) || (D_801D0D50 != 0)) {
+    if ((globalCtx->csCtx.state != 0) || gDbgCamEnabled) {
         phi_f2 = Math_Vec3f_DistXYZ(&actor->world.pos, &globalCtx->view.eye) * 0.25f;
     } else {
         phi_f2 = Math_Vec3f_DistXYZ(&actor->world.pos, &player->actor.world.pos);
diff --git a/src/code/z_demo.c b/src/code/z_demo.c
index 01ed87e70..67a4d5608 100644
--- a/src/code/z_demo.c
+++ b/src/code/z_demo.c
@@ -917,7 +917,7 @@ s32 Cutscene_Command_Camera(GlobalContext* globalCtx, u8* cmd) {
 
     bcopy(cmd, &sp1C, sizeof(s32));
     cmd += sizeof(s32);
-    if (func_8016A168() == 0) {
+    if (!Play_IsDebugCamEnabled()) {
         func_80161998(cmd, &sCutsceneCameraInfo);
     }
     return sp1C + sizeof(s32);
diff --git a/src/code/z_play.c b/src/code/z_play.c
index aa360934e..7d13ee8ee 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -309,10 +309,8 @@ s32 Play_IsUnderwater(GlobalContext* globalCtx, Vec3f* pos) {
     }
 }
 
-// z_demo and EnTest4
-// This data appears to be a boolean. It is only set by Play_Init.
-s32 func_8016A168(void) {
-    return D_801D0D50;
+s32 Play_IsDebugCamEnabled(void) {
+    return gDbgCamEnabled;
 }
 
 // A mapping from playerActorCsIds to sGlobalCamDataSettings indices.
diff --git a/src/code/z_sub_s.c b/src/code/z_sub_s.c
index d5b4f33b2..4968185d0 100644
--- a/src/code/z_sub_s.c
+++ b/src/code/z_sub_s.c
@@ -1010,7 +1010,7 @@ void SubS_DrawShadowTex(Actor* actor, GameState* gameState, u8* tex) {
  * @param[in] stepMin the minimun step in degrees
  * @param[in] stepMax the maximum step in degrees
  */
-s16 SubS_ComputeTurnToPointRot(s16* rot, s16 rotMax, s16 target, f32 slowness, f32 stepMin, f32 stepMax) {
+s16 SubS_ComputeTrackPointRot(s16* rot, s16 rotMax, s16 target, f32 slowness, f32 stepMin, f32 stepMax) {
     s16 prevRot = *rot;
     f32 step;
     f32 prevRotStep;
@@ -1046,42 +1046,42 @@ s16 SubS_ComputeTurnToPointRot(s16* rot, s16 rotMax, s16 target, f32 slowness, f
 /**
  * Computes the necessary HeadRot and TorsoRot to smoothly turn an actors's head and torso to a point
  *
- * @param[in] point the point to turn to
+ * @param[in] target the point to turn to
  * @param[in] focusPos the actor's focus postion
  * @param[in] shapeRot the actor's shape rotation
- * @param[in,out] turnTarget the intermediate target step that headRot and torsoRot step towards
+ * @param[in,out] trackTarget the intermediate target step that headRot and torsoRot step towards
  * @param[in,out] headRot the computed head rotation
  * @param[in,out] torsoRot the computed torso rotation
- * @param[in] options various options to adjust how the actor turns, see SubS_ComputeTurnToPointRot()
+ * @param[in] options various options to adjust how the actor turns, see SubS_ComputeTrackPointRot()
  */
-s32 SubS_TurnToPoint(Vec3f* point, Vec3f* focusPos, Vec3s* shapeRot, Vec3s* turnTarget, Vec3s* headRot, Vec3s* torsoRot,
-                     TurnOptionsSet* options) {
+s32 SubS_TrackPoint(Vec3f* target, Vec3f* focusPos, Vec3s* shapeRot, Vec3s* trackTarget, Vec3s* headRot,
+                    Vec3s* torsoRot, TrackOptionsSet* options) {
     s16 pitch;
     s16 yaw;
     s16 pad;
     s16 targetY;
-    f32 diffX = point->x - focusPos->x;
+    f32 diffX = target->x - focusPos->x;
     s16 targetX;
-    f32 diffZ = point->z - focusPos->z;
+    f32 diffZ = target->z - focusPos->z;
 
     yaw = Math_FAtan2F(diffZ, diffX);
-    pitch = Math_FAtan2F(sqrtf(SQ(diffX) + SQ(diffZ)), point->y - focusPos->y);
-    Math_SmoothStepToS(&turnTarget->x, pitch, 4, 0x2710, 0);
-    Math_SmoothStepToS(&turnTarget->y, yaw, 4, 0x2710, 0);
+    pitch = Math_FAtan2F(sqrtf(SQ(diffX) + SQ(diffZ)), target->y - focusPos->y);
+    Math_SmoothStepToS(&trackTarget->x, pitch, 4, 0x2710, 0);
+    Math_SmoothStepToS(&trackTarget->y, yaw, 4, 0x2710, 0);
 
     targetX =
-        SubS_ComputeTurnToPointRot(&headRot->x, options->headRotX.rotMax, turnTarget->x, options->headRotX.slowness,
-                                   options->headRotX.rotStepMin, options->headRotX.rotStepMax);
+        SubS_ComputeTrackPointRot(&headRot->x, options->headRotX.rotMax, trackTarget->x, options->headRotX.slowness,
+                                  options->headRotX.rotStepMin, options->headRotX.rotStepMax);
     //! @bug: torsoRotX uses headRotX slowness
-    SubS_ComputeTurnToPointRot(&torsoRot->x, options->torsoRotX.rotMax, targetX, options->headRotX.slowness,
-                               options->torsoRotX.rotStepMin, options->torsoRotX.rotStepMax);
+    SubS_ComputeTrackPointRot(&torsoRot->x, options->torsoRotX.rotMax, targetX, options->headRotX.slowness,
+                              options->torsoRotX.rotStepMin, options->torsoRotX.rotStepMax);
 
-    targetY = turnTarget->y - shapeRot->y;
-    SubS_ComputeTurnToPointRot(&headRot->y, options->headRotY.rotMax, targetY - torsoRot->y, options->headRotY.slowness,
-                               options->headRotY.rotStepMin, options->headRotY.rotStepMax);
-    SubS_ComputeTurnToPointRot(&torsoRot->y, options->torsoRotY.rotMax, targetY - headRot->y,
-                               options->torsoRotY.slowness, options->torsoRotY.rotStepMin,
-                               options->torsoRotY.rotStepMax);
+    targetY = trackTarget->y - shapeRot->y;
+    SubS_ComputeTrackPointRot(&headRot->y, options->headRotY.rotMax, targetY - torsoRot->y, options->headRotY.slowness,
+                              options->headRotY.rotStepMin, options->headRotY.rotStepMax);
+    SubS_ComputeTrackPointRot(&torsoRot->y, options->torsoRotY.rotMax, targetY - headRot->y,
+                              options->torsoRotY.slowness, options->torsoRotY.rotStepMin,
+                              options->torsoRotY.rotStepMax);
 
     return true;
 }
@@ -1438,7 +1438,6 @@ s32 SubS_FillCutscenesList(Actor* actor, s16 cutscenes[], s16 numCutscenes) {
  * @param[out] plane the computed plane
  *
  * @note the unit input vector is expected to already be normalized (only uses are with the z unit vector)
- *
  */
 void SubS_ConstructPlane(Vec3f* point, Vec3f* unitVec, Vec3s* rot, Plane* plane) {
     f32 sin;
@@ -1561,9 +1560,9 @@ s32 func_8013E8F8(Actor* actor, GlobalContext* globalCtx, f32 xzRange, f32 yRang
  * @param[in] torsoZRotStepMax the max torso's Z rotation step
  * @param[in] torsoXRotStepMax the max torso's X rotation step
  */
-s32 SubS_TurnToPointStep(Vec3f* worldPos, Vec3f* focusPos, s16 shapeYRot, Vec3f* yawTarget, Vec3f* pitchTarget,
-                         s16* headZRotStep, s16* headXRotStep, s16* torsoZRotStep, s16* torsoXRotStep,
-                         u16 headZRotStepMax, u16 headXRotStepMax, u16 torsoZRotStepMax, u16 torsoXRotStepMax) {
+s32 SubS_TrackPointStep(Vec3f* worldPos, Vec3f* focusPos, s16 shapeYRot, Vec3f* yawTarget, Vec3f* pitchTarget,
+                        s16* headZRotStep, s16* headXRotStep, s16* torsoZRotStep, s16* torsoXRotStep,
+                        u16 headZRotStepMax, u16 headXRotStepMax, u16 torsoZRotStepMax, u16 torsoXRotStepMax) {
     s16 yaw = Math_Vec3f_Yaw(worldPos, yawTarget) - shapeYRot;
     s16 pad;
     s16 pad2;