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

* player face docs

* more docs

* cleanup

* toto

* more comments

* fix bss, names

* better comment

* PR, fix comment

* fix bss

* sEyeTextures comment

* FaceChange_UpdateBlinkingNonHuman

---------

Co-authored-by: Anghelo Carvajal <angheloalf95@gmail.com>
Co-authored-by: Derek Hensley <hensley.derek58@gmail.com>

3 files changed, 53 insertions, 41 deletions

diff --git a/include/face_change.h b/include/face_change.h
new file mode 100644
index 000000000..2e7010c3e
--- /dev/null
+++ b/include/face_change.h
@@ -0,0 +1,13 @@
+#ifndef FACE_CHANGE_H
+#define FACE_CHANGE_H
+
+typedef struct FaceChange {
+    /* 0x0 */ s16 face;
+    /* 0x2 */ s16 timer;
+} FaceChange; // size = 0x4
+
+s16 FaceChange_UpdateBlinking(FaceChange* faceChange, s16 blinkIntervalBase, s16 blinkIntervalRandRange, s16 blinkDuration);
+s16 FaceChange_UpdateBlinkingNonHuman(FaceChange* faceChange, s16 blinkIntervalBase, s16 blinkIntervalRandRange, s16 blinkDuration);
+s16 FaceChange_UpdateRandomSet(FaceChange* faceChange, s16 changeTimerBase, s16 changeTimerRandRange, s16 faceSetRange);
+
+#endif
diff --git a/include/z64actor.h b/include/z64actor.h
index ef4e11311..abe5ee152 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -54,7 +54,7 @@ typedef void (*ActorShadowFunc)(struct Actor* actor, struct Lights* mapper, stru
 
 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
@@ -759,11 +759,6 @@ typedef struct NpcInteractInfo {
     /* 0x24 */ UNK_TYPE1 unk_24[0x4];
 } NpcInteractInfo; // size = 0x28
 
-typedef struct BlinkInfo {
-    /* 0x0 */ s16 eyeTexIndex;
-    /* 0x2 */ s16 blinkTimer;
-} BlinkInfo; // size = 0x4
-
 extern AttentionRangeParams gAttentionRanges[ATTENTION_RANGE_MAX];
 extern s16 D_801AED48[8];
 extern Gfx D_801AEF88[];
@@ -911,9 +906,6 @@ Actor* Actor_SpawnAsChild(ActorContext* actorCtx, Actor* parent, struct PlayStat
                           f32 posY, f32 posZ, s16 rotX, s16 rotY, s16 rotZ, s32 params);
 void Actor_SpawnTransitionActors(struct PlayState* play, ActorContext* actorCtx);
 void Enemy_StartFinishingBlow(struct PlayState* play, Actor* actor);
-s16 func_800BBAC0(BlinkInfo* info, s16 arg1, s16 arg2, s16 arg3);
-s16 func_800BBB74(BlinkInfo* info, s16 arg1, s16 arg2, s16 arg3);
-s16 func_800BBC20(BlinkInfo* info, s16 arg1, s16 arg2, s16 arg3);
 void Actor_SpawnBodyParts(Actor* actor, struct PlayState* play, s32 partParams, Gfx** dList);
 void Actor_SpawnFloorDustRing(struct PlayState* play, Actor* actor, Vec3f* posXZ, f32 radius, s32 countMinusOne,
                               f32 randAccelWeight, s16 scale, s16 scaleStep, u8 useLighting);
diff --git a/include/z64player.h b/include/z64player.h
index dcc89903e..8a0f2196b 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -9,6 +9,7 @@
 #include "z64interface.h"
 #include "z64item.h"
 #include "z64light.h"
+#include "face_change.h"
 
 struct Player;
 struct PlayState;
@@ -473,44 +474,50 @@ typedef enum PlayerModelGroup {
     /* 15 */ PLAYER_MODELGROUP_MAX
 } PlayerModelGroup;
 
-typedef enum PlayerEyeIndex {
+typedef struct PlayerFaceIndices {
+    /* 0x0 */ u8 eyeIndex;
+    /* 0x1 */ u8 mouthIndex;
+} PlayerFaceIndices; // size = 0x2
+
+typedef enum PlayerEyes {
     /* 0 */ PLAYER_EYES_OPEN,
     /* 1 */ PLAYER_EYES_HALF,
     /* 2 */ PLAYER_EYES_CLOSED,
-    /* 3 */ PLAYER_EYES_ROLL_RIGHT,
-    /* 4 */ PLAYER_EYES_ROLL_LEFT,
-    /* 5 */ PLAYER_EYES_ROLL_UP,
-    /* 6 */ PLAYER_EYES_ROLL_DOWN,
-    /* 7 */ PLAYER_EYES_7,
+    /* 3 */ PLAYER_EYES_RIGHT,
+    /* 4 */ PLAYER_EYES_LEFT,
+    /* 5 */ PLAYER_EYES_UP,
+    /* 6 */ PLAYER_EYES_DOWN,
+    /* 7 */ PLAYER_EYES_WINCING, // For Goron, this is a surprised eye
     /* 8 */ PLAYER_EYES_MAX
-} PlayerEyeIndex;
+} PlayerEyes;
 
-typedef enum PlayerMouthIndex {
+typedef enum PlayerMouth {
     /* 0 */ PLAYER_MOUTH_CLOSED,
-    /* 1 */ PLAYER_MOUTH_TEETH,
-    /* 2 */ PLAYER_MOUTH_ANGRY,
-    /* 3 */ PLAYER_MOUTH_HAPPY,
+    /* 1 */ PLAYER_MOUTH_HALF,
+    /* 2 */ PLAYER_MOUTH_OPEN,
+    /* 3 */ PLAYER_MOUTH_SMILE,
     /* 4 */ PLAYER_MOUTH_MAX
-} PlayerMouthIndex;
-
-typedef enum PlayerFacialExpression {
-    /*  0 */ PLAYER_FACE_0,
-    /*  1 */ PLAYER_FACE_1,
-    /*  2 */ PLAYER_FACE_2,
-    /*  3 */ PLAYER_FACE_3,
-    /*  4 */ PLAYER_FACE_4,
-    /*  5 */ PLAYER_FACE_5,
-    /*  6 */ PLAYER_FACE_6,
-    /*  7 */ PLAYER_FACE_7,
-    /*  8 */ PLAYER_FACE_8,
-    /*  9 */ PLAYER_FACE_9,
-    /* 10 */ PLAYER_FACE_10,
-    /* 11 */ PLAYER_FACE_11,
-    /* 12 */ PLAYER_FACE_12,
-    /* 13 */ PLAYER_FACE_13,
-    /* 14 */ PLAYER_FACE_14,
-    /* 15 */ PLAYER_FACE_15
-} PlayerFacialExpression;
+} PlayerMouth;
+
+typedef enum PlayerFace {
+    /*  0 */ PLAYER_FACE_NEUTRAL,
+    /*  1 */ PLAYER_FACE_NEUTRAL_BLINKING_HALF,
+    /*  2 */ PLAYER_FACE_NEUTRAL_BLINKING_CLOSED,
+    /*  3 */ PLAYER_FACE_NEUTRAL_2,
+    /*  4 */ PLAYER_FACE_NEUTRAL_BLINKING_HALF_2,
+    /*  5 */ PLAYER_FACE_NEUTRAL_BLINKING_CLOSED_2,
+    /*  6 */ PLAYER_FACE_LOOK_LEFT,
+    /*  7 */ PLAYER_FACE_SURPRISED,
+    /*  8 */ PLAYER_FACE_HURT,
+    /*  9 */ PLAYER_FACE_GASP,
+    /* 10 */ PLAYER_FACE_LOOK_RIGHT,
+    /* 11 */ PLAYER_FACE_LOOK_LEFT_2,
+    /* 12 */ PLAYER_FACE_EYES_CLOSED_MOUTH_OPEN,
+    /* 13 */ PLAYER_FACE_OPENING,
+    /* 14 */ PLAYER_FACE_EYES_AND_MOUTH_OPEN,
+    /* 15 */ PLAYER_FACE_SMILE,
+    /* 16 */ PLAYER_FACE_MAX
+} PlayerFace;
 
 typedef enum PlayerLimb {
     /* 0x00 */ PLAYER_LIMB_NONE,
@@ -1165,7 +1172,7 @@ typedef struct Player {
     /* 0x2C8 */ SkelAnime unk_2C8;
     /* 0x30C */ Vec3s jointTable[5];
     /* 0x32A */ Vec3s morphTable[5];
-    /* 0x348 */ BlinkInfo blinkInfo;
+    /* 0x348 */ FaceChange faceChange;
     /* 0x34C */ Actor* heldActor;
     /* 0x350 */ PosRot leftHandWorld;
     /* 0x364 */ Actor* rightHandActor;