Document EnGoroiwa and BgJyaGoroiwa (#860)

* Document EnGoroiwa and BgJyaGoroiwa

* Run format.sh

* Add renamed functions to actorfixer script

* no more calling out "the devs" for bad code

* `EnGoroiwa#flags` -> `stateFlags`

* `Matrix_MtxFToRotS` -> `Matrix_MtxFToYXZRotS` (and not ZXY oops), `func_800D2264` -> `Matrix_MtxFToZYXRotS`

4 files changed, 63 insertions, 47 deletions

diff --git a/src/code/sys_matrix.c b/src/code/sys_matrix.c
index 6427ccbb9..c0c668771 100644
--- a/src/code/sys_matrix.c
+++ b/src/code/sys_matrix.c
@@ -680,7 +680,7 @@ void Matrix_MultVec3fExt(Vec3f* src, Vec3f* dest, MtxF* mf) {
     dest->z = mf->wz + (mf->xz * src->x + mf->yz * src->y + mf->zz * src->z);
 }
 
-void Matrix_Reverse(MtxF* mf) {
+void Matrix_Transpose(MtxF* mf) {
     f32 temp;
 
     temp = mf->xy;
@@ -739,7 +739,11 @@ void func_800D1FD4(MtxF* mf) {
     cmf->zz = mf->zz * temp3;
 }
 
-void func_800D20CC(MtxF* mf, Vec3s* vec, s32 flag) {
+/**
+ * Gets the rotation the specified matrix represents, using Euler YXZ.
+ * The flag value doesn't matter for a rotation matrix. Not 0 does extra calculation.
+ */
+void Matrix_MtxFToYXZRotS(MtxF* mf, Vec3s* rotDest, s32 flag) {
     f32 temp;
     f32 temp2;
     f32 temp3;
@@ -748,17 +752,17 @@ void func_800D20CC(MtxF* mf, Vec3s* vec, s32 flag) {
     temp = mf->zx;
     temp *= temp;
     temp += SQ(mf->zz);
-    vec->x = Math_FAtan2F(-mf->zy, sqrtf(temp)) * (32768 / M_PI);
+    rotDest->x = Math_FAtan2F(-mf->zy, sqrtf(temp)) * (0x8000 / M_PI);
 
-    if ((vec->x == 0x4000) || (vec->x == -0x4000)) {
-        vec->z = 0;
+    if ((rotDest->x == 0x4000) || (rotDest->x == -0x4000)) {
+        rotDest->z = 0;
 
-        vec->y = Math_FAtan2F(-mf->xz, mf->xx) * (32768 / M_PI);
+        rotDest->y = Math_FAtan2F(-mf->xz, mf->xx) * (0x8000 / M_PI);
     } else {
-        vec->y = Math_FAtan2F(mf->zx, mf->zz) * (32768 / M_PI);
+        rotDest->y = Math_FAtan2F(mf->zx, mf->zz) * (0x8000 / M_PI);
 
         if (!flag) {
-            vec->z = Math_FAtan2F(mf->xy, mf->yy) * (32768 / M_PI);
+            rotDest->z = Math_FAtan2F(mf->xy, mf->yy) * (0x8000 / M_PI);
         } else {
             temp = mf->xx;
             temp2 = mf->xz;
@@ -768,6 +772,7 @@ void func_800D20CC(MtxF* mf, Vec3s* vec, s32 flag) {
             temp += SQ(temp2);
             temp2 = mf->xy;
             temp += SQ(temp2);
+            /* temp = xx^2+xz^2+xy^2 == 1 for a rotation matrix */
             temp = sqrtf(temp);
             temp = temp2 / temp;
 
@@ -776,15 +781,22 @@ void func_800D20CC(MtxF* mf, Vec3s* vec, s32 flag) {
             temp2 += SQ(temp3);
             temp3 = mf->yy;
             temp2 += SQ(temp3);
+            /* temp2 = yx^2+yz^2+yy^2 == 1 for a rotation matrix */
             temp2 = sqrtf(temp2);
             temp2 = temp3 / temp2;
 
-            vec->z = Math_FAtan2F(temp, temp2) * (32768 / M_PI);
+            /* for a rotation matrix, temp == xy and temp2 == yy
+             * which is the same as in the !flag branch */
+            rotDest->z = Math_FAtan2F(temp, temp2) * (0x8000 / M_PI);
         }
     }
 }
 
-void func_800D2264(MtxF* mf, Vec3s* vec, s32 flag) {
+/**
+ * Gets the rotation the specified matrix represents, using Euler ZYX.
+ * The flag value doesn't matter for a rotation matrix. Not 0 does extra calculation.
+ */
+void Matrix_MtxFToZYXRotS(MtxF* mf, Vec3s* rotDest, s32 flag) {
     f32 temp;
     f32 temp2;
     f32 temp3;
@@ -793,43 +805,47 @@ void func_800D2264(MtxF* mf, Vec3s* vec, s32 flag) {
     temp = mf->xx;
     temp *= temp;
     temp += SQ(mf->xy);
-    vec->y = Math_FAtan2F(-mf->xz, sqrtf(temp)) * (32768 / M_PI);
+    rotDest->y = Math_FAtan2F(-mf->xz, sqrtf(temp)) * (0x8000 / M_PI);
 
-    if ((vec->y == 0x4000) || (vec->y == -0x4000)) {
-        vec->x = 0;
-        vec->z = Math_FAtan2F(-mf->yx, mf->yy) * (32768 / M_PI);
-        return;
-    }
+    if ((rotDest->y == 0x4000) || (rotDest->y == -0x4000)) {
+        rotDest->x = 0;
+        rotDest->z = Math_FAtan2F(-mf->yx, mf->yy) * (0x8000 / M_PI);
+    } else {
+        rotDest->z = Math_FAtan2F(mf->xy, mf->xx) * (0x8000 / M_PI);
 
-    vec->z = Math_FAtan2F(mf->xy, mf->xx) * (32768 / M_PI);
+        if (!flag) {
+            rotDest->x = Math_FAtan2F(mf->yz, mf->zz) * (0x8000 / M_PI);
+        } else {
+            // see Matrix_MtxFToYXZRotS
+            temp = mf->yx;
+            temp2 = mf->yy;
+            temp3 = mf->zy;
 
-    if (!flag) {
-        vec->x = Math_FAtan2F(mf->yz, mf->zz) * (32768 / M_PI);
-    } else {
-        temp = mf->yx;
-        temp2 = mf->yy;
-        temp3 = mf->zy;
-
-        temp *= temp;
-        temp += SQ(temp2);
-        temp2 = mf->yz;
-        temp += SQ(temp2);
-        temp = sqrtf(temp);
-        temp = temp2 / temp;
-
-        temp2 = mf->zx;
-        temp2 *= temp2;
-        temp2 += SQ(temp3);
-        temp3 = mf->zz;
-        temp2 += SQ(temp3);
-        temp2 = sqrtf(temp2);
-        temp2 = temp3 / temp2;
-
-        vec->x = Math_FAtan2F(temp, temp2) * (32768 / M_PI);
+            temp *= temp;
+            temp += SQ(temp2);
+            temp2 = mf->yz;
+            temp += SQ(temp2);
+            temp = sqrtf(temp);
+            temp = temp2 / temp;
+
+            temp2 = mf->zx;
+            temp2 *= temp2;
+            temp2 += SQ(temp3);
+            temp3 = mf->zz;
+            temp2 += SQ(temp3);
+            temp2 = sqrtf(temp2);
+            temp2 = temp3 / temp2;
+
+            rotDest->x = Math_FAtan2F(temp, temp2) * (0x8000 / M_PI);
+        }
     }
 }
 
-void func_800D23FC(f32 f, Vec3f* vec, u8 mode) {
+/*
+ * Rotate the matrix by `f` radians around a unit vector `vec`.
+ * NB: vec is assumed to be a unit vector.
+ */
+void Matrix_RotateAxis(f32 f, Vec3f* vec, u8 mode) {
     MtxF* cmf;
     f32 sin;
     f32 cos;
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 20282d003..2140efce6 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -3150,7 +3150,7 @@ s32 BodyBreak_SpawnParts(Actor* actor, BodyBreak* bodyBreak, GlobalContext* glob
                                                     mtx->wy, mtx->wz, 0, 0, objBankIndex, type);
 
         if (spawnedEnPart != NULL) {
-            func_800D20CC(&bodyBreak->matrices[bodyBreak->count], &spawnedEnPart->actor.shape.rot, 0);
+            Matrix_MtxFToYXZRotS(&bodyBreak->matrices[bodyBreak->count], &spawnedEnPart->actor.shape.rot, 0);
             spawnedEnPart->displayList = bodyBreak->dLists[bodyBreak->count];
             spawnedEnPart->actor.scale = actor->scale;
         }
diff --git a/src/code/z_play.c b/src/code/z_play.c
index f1fffbd1b..2fa25e093 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -1094,7 +1094,7 @@ void Gameplay_Draw(GlobalContext* globalCtx) {
         globalCtx->mf_11DA0.mf[2][3] = 0.0f;
         globalCtx->mf_11DA0.mf[1][3] = 0.0f;
         globalCtx->mf_11DA0.mf[0][3] = 0.0f;
-        Matrix_Reverse(&globalCtx->mf_11DA0);
+        Matrix_Transpose(&globalCtx->mf_11DA0);
         globalCtx->unk_11DE0 = Matrix_MtxFToMtx(Matrix_CheckFloats(&globalCtx->mf_11DA0, "../z_play.c", 4005),
                                                 Graph_Alloc(gfxCtx, sizeof(Mtx)));
 
diff --git a/src/code/z_player_lib.c b/src/code/z_player_lib.c
index 8540caeb8..0ec34898f 100644
--- a/src/code/z_player_lib.c
+++ b/src/code/z_player_lib.c
@@ -1244,13 +1244,13 @@ void func_80090D20(GlobalContext* globalCtx, s32 limbIndex, Gfx** dList, Vec3s*
                     Matrix_MultVec3f(&D_80126128, &hookedActor->world.pos);
                     Matrix_RotateRPY(0x69E8, -0x5708, 0x458E, MTXMODE_APPLY);
                     Matrix_Get(&sp14C);
-                    func_800D20CC(&sp14C, &hookedActor->world.rot, 0);
+                    Matrix_MtxFToYXZRotS(&sp14C, &hookedActor->world.rot, 0);
                     hookedActor->shape.rot = hookedActor->world.rot;
                 } else if (this->stateFlags1 & 0x800) {
                     Vec3s spB8;
 
                     Matrix_Get(&sp14C);
-                    func_800D20CC(&sp14C, &spB8, 0);
+                    Matrix_MtxFToYXZRotS(&sp14C, &spB8, 0);
 
                     if (hookedActor->flags & 0x20000) {
                         hookedActor->world.rot.x = hookedActor->shape.rot.x = spB8.x - this->unk_3BC.x;
@@ -1260,7 +1260,7 @@ void func_80090D20(GlobalContext* globalCtx, s32 limbIndex, Gfx** dList, Vec3s*
                 }
             } else {
                 Matrix_Get(&this->mf_9E0);
-                func_800D20CC(&this->mf_9E0, &this->unk_3BC, 0);
+                Matrix_MtxFToYXZRotS(&this->mf_9E0, &this->unk_3BC, 0);
             }
         }
     } else if (limbIndex == PLAYER_LIMB_R_HAND) {
@@ -1326,7 +1326,7 @@ void func_80090D20(GlobalContext* globalCtx, s32 limbIndex, Gfx** dList, Vec3s*
                     Matrix_MultVec3f(&D_80126190, &heldActor->world.pos);
                     Matrix_RotateRPY(0, -0x4000, -0x4000, MTXMODE_APPLY);
                     Matrix_Get(&sp44);
-                    func_800D20CC(&sp44, &heldActor->world.rot, 0);
+                    Matrix_MtxFToYXZRotS(&sp44, &heldActor->world.rot, 0);
                     heldActor->shape.rot = heldActor->world.rot;
 
                     if (func_8002DD78(this) != 0) {