Document Player's Face and z_actor FaceChange functions (#1928)

* create some enums

* gonna try struct instead of array

* struct works. add docs too

* inline function comments

* fix function comment

* name faces, move enums

* rename textures

* outnames

* remove comments

* change comment slightly

* fixup face comments

* review

* offset comments

* add and use PLAYER_FACE_MAX

* typo

* more comment on blinkDuration

* another change to the comment

4 files changed, 61 insertions, 3 deletions

diff --git a/include/face_change.h b/include/face_change.h
new file mode 100644
index 000000000..6a5573765
--- /dev/null
+++ b/include/face_change.h
@@ -0,0 +1,12 @@
+#ifndef FACE_CHANGE_H
+#define FACE_CHANGE_H
+
+typedef struct {
+    /* 0x00 */ s16 face;
+    /* 0x02 */ s16 timer;
+} FaceChange; // size = 0x4
+
+s16 FaceChange_UpdateBlinking(FaceChange* faceChange, s16 blinkIntervalBase, s16 blinkIntervalRandRange, s16 blinkDuration);
+s16 FaceChange_UpdateRandomSet(FaceChange* faceChange, s16 changeTimerBase, s16 changeTimerRandRange, s16 faceSetRange);
+
+#endif
diff --git a/include/functions.h b/include/functions.h
index 9b3e0bf72..35b378a7a 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -443,7 +443,6 @@ Actor* Actor_Delete(ActorContext* actorCtx, Actor* actor, PlayState* play);
 Actor* func_80032AF0(PlayState* play, ActorContext* actorCtx, Actor** actorPtr, Player* player);
 Actor* Actor_Find(ActorContext* actorCtx, s32 actorId, s32 actorCategory);
 void Enemy_StartFinishingBlow(PlayState* play, Actor* actor);
-s16 func_80032CB4(s16* arg0, s16 arg1, s16 arg2, s16 arg3);
 void BodyBreak_Alloc(BodyBreak* bodyBreak, s32 count, PlayState* play);
 void BodyBreak_SetInfo(BodyBreak* bodyBreak, s32 limbIndex, s32 minLimbIndex, s32 maxLimbIndex, u32 count, Gfx** dList,
                        s16 objectSlot);
diff --git a/include/z64actor.h b/include/z64actor.h
index 088a90ab7..73643c350 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -134,7 +134,7 @@ typedef struct {
 
 typedef struct {
     /* 0x00 */ Vec3s rot; // Current actor shape rotation
-    /* 0x06 */ s16 face; // Used to index eyebrow/eye/mouth textures. Only used by player
+    /* 0x06 */ s16 face; // Used to index eyes and mouth textures. Only used by player
     /* 0x08 */ f32 yOffset; // Model y axis offset. Represents model space units
     /* 0x0C */ ActorShadowFunc shadowDraw; // Shadow draw function
     /* 0x10 */ f32 shadowScale; // Changes the size of the shadow
diff --git a/include/z64player.h b/include/z64player.h
index f47160bdb..099476ac2 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -3,6 +3,7 @@
 
 #include "z64actor.h"
 #include "alignment.h"
+#include "face_change.h"
 
 struct Player;
 
@@ -229,6 +230,52 @@ typedef enum {
 } PlayerDoorType;
 
 typedef enum {
+    /* 0 */ PLAYER_FACEPART_EYES,
+    /* 1 */ PLAYER_FACEPART_MOUTH,
+    /* 2 */ PLAYER_FACEPART_MAX
+} PlayerFacePart;
+
+typedef enum {
+    /* 0 */ PLAYER_EYES_OPEN,
+    /* 1 */ PLAYER_EYES_HALF,
+    /* 2 */ PLAYER_EYES_CLOSED,
+    /* 3 */ PLAYER_EYES_LEFT,
+    /* 4 */ PLAYER_EYES_RIGHT,
+    /* 5 */ PLAYER_EYES_WIDE,
+    /* 6 */ PLAYER_EYES_DOWN,
+    /* 7 */ PLAYER_EYES_WINCING,
+    /* 8 */ PLAYER_EYES_MAX
+} PlayerEyes;
+
+typedef enum {
+    /* 0 */ PLAYER_MOUTH_CLOSED,
+    /* 1 */ PLAYER_MOUTH_HALF,
+    /* 2 */ PLAYER_MOUTH_OPEN,
+    /* 3 */ PLAYER_MOUTH_SMILE,
+    /* 4 */ PLAYER_MOUTH_MAX
+} PlayerMouth;
+
+typedef enum {
+    /*  0 */ PLAYER_FACE_NEUTRAL,                   // eyes open and mouth closed
+    /*  1 */ PLAYER_FACE_NEUTRAL_BLINKING_HALF,     // eyes half open and mouth closed
+    /*  2 */ PLAYER_FACE_NEUTRAL_BLINKING_CLOSED,   // eyes and mouth closed
+    /*  3 */ PLAYER_FACE_NEUTRAL_2,                 // same as `PLAYER_FACE_NEUTRAL`
+    /*  4 */ PLAYER_FACE_NEUTRAL_BLINKING_HALF_2,   // same as `PLAYER_FACE_NEUTRAL_BLINKING_HALF`
+    /*  5 */ PLAYER_FACE_NEUTRAL_BLINKING_CLOSED_2, // same as `PLAYER_FACE_NEUTRAL_BLINKING_CLOSED`
+    /*  6 */ PLAYER_FACE_LOOK_RIGHT,                // eyes looking right and mouth closed
+    /*  7 */ PLAYER_FACE_SURPRISED,                 // wide eyes and grimacing mouth
+    /*  8 */ PLAYER_FACE_HURT,                      // eyes wincing in pain and mouth open
+    /*  9 */ PLAYER_FACE_GASP,                      // eyes and mouth open
+    /* 10 */ PLAYER_FACE_LOOK_LEFT,                 // eyes looking left and mouth closed
+    /* 11 */ PLAYER_FACE_LOOK_RIGHT_2,              // duplicate of `PLAYER_FACE_LOOK_RIGHT`
+    /* 12 */ PLAYER_FACE_EYES_CLOSED_MOUTH_OPEN,    // eyes closed and mouth open
+    /* 13 */ PLAYER_FACE_OPENING,                   // eyes and mouth both halfway open
+    /* 14 */ PLAYER_FACE_EYES_AND_MOUTH_OPEN,       // eyes and mouth open
+    /* 15 */ PLAYER_FACE_NEUTRAL_3,                 // same as `PLAYER_FACE_NEUTRAL` and `PLAYER_FACE_NEUTRAL_2`
+    /* 16 */ PLAYER_FACE_MAX
+} PlayerFace;
+
+typedef enum {
     /* 0x00 */ PLAYER_MODELGROUP_0, // unused (except for a bug in `Player_OverrideLimbDrawPause`)
     /* 0x01 */ PLAYER_MODELGROUP_CHILD_HYLIAN_SHIELD,  //hold sword only. used for holding sword only as child link with hylian shield equipped
     /* 0x02 */ PLAYER_MODELGROUP_SWORD_AND_SHIELD, // hold sword and shield or just sword if no shield is equipped
@@ -705,7 +752,7 @@ typedef struct Player {
     /* 0x01F8 */ Vec3s jointTable[PLAYER_LIMB_BUF_COUNT];
     /* 0x0288 */ Vec3s morphTable[PLAYER_LIMB_BUF_COUNT];
     /* 0x0318 */ Vec3s blendTable[PLAYER_LIMB_BUF_COUNT];
-    /* 0x03A8 */ s16 unk_3A8[2];
+    /* 0x03A8 */ FaceChange faceChange;
     /* 0x03AC */ Actor* heldActor;
     /* 0x03B0 */ Vec3f leftHandPos;
     /* 0x03BC */ Vec3s unk_3BC;