Player Docs: speedXZ and yaw (#1724)

* rename struct members

* PR

include/z64player.h

@@ -1241,9 +1241,9 @@ typedef struct Player {
     /* 0xACC */ s16 unk_ACC;
     /* 0xACE */ s8 unk_ACE;
     /* 0xACF */ u8 putAwayCountdown; // Frames to wait before showing "Put Away" on A
-    /* 0xAD0 */ f32 linearVelocity;
+    /* 0xAD0 */ f32 speedXZ; // Controls horizontal speed, used for `actor.speed`. Current or target value depending on context.
-    /* 0xAD4 */ s16 currentYaw;
+    /* 0xAD4 */ s16 yaw; // General yaw value, used both for world and shape rotation. Current or target value depending on context.
-    /* 0xAD6 */ s16 targetYaw;
+    /* 0xAD6 */ s16 parallelYaw; // yaw in "parallel" mode, Z-Target without an actor lock-on
     /* 0xAD8 */ u16 underwaterTimer;
     /* 0xADA */ s8 meleeWeaponAnimation;
     /* 0xADB */ s8 meleeWeaponState;

src/code/z_bg_collect.c

@@ -54,7 +54,7 @@ void DynaPolyActor_UpdateCarriedActorRotY(CollisionContext* colCtx, s32 bgId, Ac
     rotY = colCtx->dyna.bgActors[bgId].curTransform.rot.y - colCtx->dyna.bgActors[bgId].prevTransform.rot.y;
 
     if (carriedActor->id == ACTOR_PLAYER) {
-        ((Player*)carriedActor)->currentYaw += rotY;
+        ((Player*)carriedActor)->yaw += rotY;
     }
 
     carriedActor->shape.rot.y += rotY;

src/code/z_player_lib.c

@@ -224,7 +224,7 @@ void func_801229FC(Player* player) {
         s32 i;
 
         for (i = 0; i < D_801F59B0_LEN; i++) {
-            D_801F59C8[i] += Rand_S16Offset(4, 23) + (s32)(fabsf(player->linearVelocity) * 50.0f);
+            D_801F59C8[i] += Rand_S16Offset(4, 23) + (s32)(fabsf(player->speedXZ) * 50.0f);
         }
     }
 }
@@ -716,7 +716,7 @@ s32 func_801235DC(PlayState* play, f32 arg1, s16 arg2) {
     if (player->stateFlags3 & PLAYER_STATE3_1000) {
         player->unk_B08 = arg1;
         player->unk_B0C += arg1 * 0.05f;
-        player->currentYaw = arg2;
+        player->yaw = arg2;
         player->actor.home.rot.y = arg2;
         player->actor.shape.rot.y = arg2;
         player->unk_B8C = 4;

src/overlays/actors/ovl_Bg_Ingate/z_bg_ingate.c

@@ -164,7 +164,7 @@ void func_80953F14(BgIngate* this, PlayState* play) {
 
     player->actor.shape.rot.y = this->dyna.actor.shape.rot.y;
     player->actor.world.rot.y = player->actor.shape.rot.y;
-    player->currentYaw = player->actor.shape.rot.y;
+    player->yaw = player->actor.shape.rot.y;
     player->actor.focus.rot.y = player->actor.shape.rot.y;
     this->unk160 |= 0x10;
     func_80953DA8(this, play);

src/overlays/actors/ovl_Boss_Hakugin/z_boss_hakugin.c

@@ -783,7 +783,7 @@ void BossHakugin_ApplyGoronSpikeBoost(BossHakugin* this, Player* player) {
     if (!this->hasAppliedGoronSpikeBoost && (player->stateFlags3 & PLAYER_STATE3_80000) &&
         !(player->actor.bgCheckFlags & BGCHECKFLAG_GROUND) && (player->actor.velocity.y > 5.0f)) {
         player->actor.velocity.y *= 1.3f;
-        player->linearVelocity *= 1.3f;
+        player->speedXZ *= 1.3f;
         this->hasAppliedGoronSpikeBoost = true;
     } else if (player->actor.bgCheckFlags & BGCHECKFLAG_GROUND) {
         this->hasAppliedGoronSpikeBoost = false;
@@ -1724,7 +1724,7 @@ void BossHakugin_SetupIntroCutsceneWakeUp(BossHakugin* this, PlayState* play) {
     player->actor.world.pos.x = 250.0f;
     player->actor.world.pos.z = -1560.0f;
     player->actor.shape.rot.y = this->actor.yawTowardsPlayer + 0x8000;
-    player->currentYaw = player->actor.world.rot.y = player->actor.shape.rot.y;
+    player->yaw = player->actor.world.rot.y = player->actor.shape.rot.y;
     Player_SetCsActionWithHaltedActors(play, &this->actor, PLAYER_CSACTION_131);
     this->actionFunc = BossHakugin_IntroCutsceneWakeUp;
 }
@@ -2628,11 +2628,11 @@ void BossHakugin_CheckForBodyColliderHit(BossHakugin* this, PlayState* play) {
             //! @bug This block is unreachable. This is trying to check if the player curled up as a Goron without
             //! spikes, but if the player gets hit in this state, they will be forcibly uncurled before this function
             //! gets called; it's impossible to have the state flags necessary to end up here in the final game.
-            player->unk_B08 = player->linearVelocity = -5.0f;
+            player->unk_B08 = player->speedXZ = -5.0f;
             player->unk_B0C += player->unk_B08 * 0.05f;
             player->actor.velocity.y = 10.0f;
             player->unk_B8C = 4;
-            player->actor.shape.rot.y = player->actor.home.rot.y = player->currentYaw = player->actor.world.rot.y;
+            player->actor.shape.rot.y = player->actor.home.rot.y = player->yaw = player->actor.world.rot.y;
         } else if (!(this->bodyCollider.base.atFlags & AT_BOUNCED)) {
             s16 knockbackYaw = this->actor.yawTowardsPlayer - this->actor.shape.rot.y;
 

src/overlays/actors/ovl_En_Dg/z_en_dg.c

@@ -997,7 +997,7 @@ void EnDg_ApproachPlayer(EnDg* this, PlayState* play) {
         EnDg_ChangeAnim(&this->skelAnime, sAnimationInfo, DOG_ANIM_SIT_DOWN);
         this->actionFunc = EnDg_SitNextToPlayer;
     } else if (player->stateFlags3 & PLAYER_STATE3_20000000) {
-        if ((this->actor.xzDistToPlayer > 40.0f) && (player->linearVelocity == 0.0f)) {
+        if ((this->actor.xzDistToPlayer > 40.0f) && (player->speedXZ == 0.0f)) {
             Math_ApproachF(&this->actor.speed, 1.5f, 0.2f, 1.0f);
         } else {
             Math_ApproachF(&this->actor.speed, player->actor.speed, 0.2f, 1.0f);

src/overlays/actors/ovl_En_Hakurock/z_en_hakurock.c

@@ -338,12 +338,11 @@ void EnHakurock_Stalactite_StuckInGround(EnHakurock* this, PlayState* play) {
             EnHakurock_SpawnEffect(this, EN_HAKUROCK_EFFECT_TYPE_STALACTITE_DESTROYED);
             EnHakurock_SetupWaitForSignal(this);
         } else if ((&player->actor == this->collider.base.oc) &&
-                   (player->stateFlags3 & (PLAYER_STATE3_1000 | PLAYER_STATE3_80000)) &&
+                   (player->stateFlags3 & (PLAYER_STATE3_1000 | PLAYER_STATE3_80000)) && (player->speedXZ > 8.0f)) {
-                   (player->linearVelocity > 8.0f)) {
+            player->unk_B08 = player->speedXZ = -5.0f;
-            player->unk_B08 = player->linearVelocity = -5.0f;
+            player->unk_B0C += player->speedXZ * 0.05f;
-            player->unk_B0C += (player->linearVelocity * 0.05f);
             player->actor.velocity.y = 5.0f;
-            player->currentYaw = player->actor.world.rot.y;
+            player->yaw = player->actor.world.rot.y;
             player->actor.home.rot.y = player->actor.world.rot.y;
             player->actor.shape.rot.y = player->actor.world.rot.y;
             player->unk_B8C = 4;

src/overlays/actors/ovl_En_Rg/z_en_rg.c

@@ -448,10 +448,10 @@ s32 func_80BF47AC(EnRg* this, PlayState* play) {
     f32 phi_f0;
     f32 phi_f2;
 
-    if (player->linearVelocity < 20.0f) {
+    if (player->speedXZ < 20.0f) {
         phi_f2 = 20.0f;
     } else {
-        phi_f2 = player->linearVelocity;
+        phi_f2 = player->speedXZ;
     }
 
     if ((this->unk_310 & 0x400) || (this->unk_310 & 0x1000)) {
@@ -574,13 +574,13 @@ void func_80BF4AB8(EnRg* this, PlayState* play) {
             } else if (this->collider2.base.at->id == ACTOR_PLAYER) {
                 this->unk_326 = 0x28;
                 if (player->stateFlags3 & PLAYER_STATE3_1000) {
-                    player->linearVelocity *= 0.5f;
+                    player->speedXZ *= 0.5f;
-                    player->unk_B08 = player->linearVelocity;
+                    player->unk_B08 = player->speedXZ;
-                    player->unk_B0C += player->linearVelocity * 0.05f;
+                    player->unk_B0C += player->speedXZ * 0.05f;
-                    if (BINANG_SUB(this->actor.yawTowardsPlayer, player->currentYaw) > 0) {
+                    if (BINANG_SUB(this->actor.yawTowardsPlayer, player->yaw) > 0) {
-                        player->currentYaw += 0x2000;
+                        player->yaw += 0x2000;
                     } else {
-                        player->currentYaw -= 0x2000;
+                        player->yaw -= 0x2000;
                     }
                     player->unk_B8C = 4;
                     player->invincibilityTimer = 20;

src/overlays/actors/ovl_En_Sellnuts/z_en_sellnuts.c

@@ -735,7 +735,7 @@ void func_80ADC5A4(EnSellnuts* this, PlayState* play) {
     Player* player = GET_PLAYER(play);
 
     if (Actor_TalkOfferAccepted(&this->actor, &play->state)) {
-        player->linearVelocity = 0.0f;
+        player->speedXZ = 0.0f;
         this->actor.flags &= ~ACTOR_FLAG_10000;
         Message_StartTextbox(play, this->unk_340, &this->actor);
         if (this->unk_340 == 0x625) {

src/overlays/actors/ovl_En_Test3/z_en_test3.c

@@ -532,11 +532,11 @@ s32 func_80A3F15C(EnTest3* this, PlayState* play, struct_80A41828* arg2) {
             Math_Vec3f_Copy(&this->player.actor.world.pos, &curPathPos);
             Math_Vec3f_Copy(&this->player.actor.home.pos, &curPathPos);
             Math_Vec3f_Copy(&this->player.actor.prevPos, &curPathPos);
-            this->player.currentYaw = Math_Vec3f_Yaw(&this->player.actor.world.pos, &nextPathPos);
+            this->player.yaw = Math_Vec3f_Yaw(&this->player.actor.world.pos, &nextPathPos);
             if (arg2->unk_1_0 < 0) {
-                this->player.currentYaw += 0x8000;
+                this->player.yaw += 0x8000;
             }
-            this->player.actor.shape.rot.y = this->player.currentYaw;
+            this->player.actor.shape.rot.y = this->player.yaw;
             return true;
         }
     }
@@ -671,7 +671,7 @@ s32 func_80A3F8D4(EnTest3* this, PlayState* play, struct_80A41828* arg2, Schedul
 
 s32 func_80A3F9A4(EnTest3* this, PlayState* play) {
     Math_ScaledStepToS(&this->player.actor.shape.rot.y, this->player.actor.home.rot.y, 0x320);
-    this->player.currentYaw = this->player.actor.shape.rot.y;
+    this->player.yaw = this->player.actor.shape.rot.y;
     return false;
 }
 
@@ -806,7 +806,7 @@ s32 func_80A3FF10(EnTest3* this, PlayState* play, struct_80A41828* arg2, Schedul
 
         this->player.actor.home.rot.y = -0x2AAB;
         this->player.actor.shape.rot.y = -0x2AAB;
-        this->player.currentYaw = -0x2AAB;
+        this->player.yaw = -0x2AAB;
         //! FAKE:
         if (1) {}
         return true;
@@ -925,9 +925,9 @@ s32 func_80A40230(EnTest3* this, PlayState* play) {
     Math_Vec3f_Copy(&D_80A41D50, &this->player.actor.world.pos);
     dx = this->player.actor.world.pos.x - this->player.actor.prevPos.x;
     dy = this->player.actor.world.pos.z - this->player.actor.prevPos.z;
-    this->player.linearVelocity = sqrtf(SQ(dx) + SQ(dy));
+    this->player.speedXZ = sqrtf(SQ(dx) + SQ(dy));
-    this->player.linearVelocity *= 1.0f + (1.05f * fabsf(Math_SinS(this->player.floorPitch)));
+    this->player.speedXZ *= 1.0f + (1.05f * fabsf(Math_SinS(this->player.floorPitch)));
-    sKafeiControlStickMagnitude = (this->player.linearVelocity * 10.0f) + 20.0f;
+    sKafeiControlStickMagnitude = (this->player.speedXZ * 10.0f) + 20.0f;
     sKafeiControlStickMagnitude = CLAMP_MAX(sKafeiControlStickMagnitude, 60.0f);
     sKafeiControlStickAngle = this->player.actor.world.rot.y;
     this->player.actor.world.pos.x = this->player.actor.prevPos.x;
@@ -1068,7 +1068,7 @@ void EnTest3_Update(Actor* thisx, PlayState* play2) {
     if (D_80A41D48) {
         this->player.actor.world.pos.x = D_80A41D50.x;
         this->player.actor.world.pos.z = D_80A41D50.z;
-        this->player.linearVelocity = 0.0f;
+        this->player.speedXZ = 0.0f;
     }
 }
 

src/overlays/actors/ovl_En_Test6/z_en_test6.c

@@ -891,7 +891,7 @@ void EnTest6_DoubleSoTCutscene(EnTest6* this, PlayState* play) {
             player->actor.world.pos = player->actor.home.pos = this->actor.home.pos;
             player->actor.shape.rot = this->actor.home.rot;
             player->actor.focus.rot.y = player->actor.shape.rot.y;
-            player->currentYaw = player->actor.shape.rot.y;
+            player->yaw = player->actor.shape.rot.y;
             player->unk_ABC = 0.0f;
             player->unk_AC0 = 0.0f;
             player->actor.shape.yOffset = 0.0f;

src/overlays/actors/ovl_En_Toto/z_en_toto.c

@@ -503,7 +503,7 @@ s32 func_80BA4530(EnToto* this, PlayState* play) {
         if (func_80BA44D4(temp_s0, player)) {
             Math_Vec3s_ToVec3f(&player->actor.world.pos, &temp_s0->unk6);
             player->actor.shape.rot.y = 0;
-            player->currentYaw = 0;
+            player->yaw = 0;
             return func_80BA407C(this, play);
         }
         if (!ENTOTO_WEEK_EVENT_FLAGS) {

src/overlays/actors/ovl_En_Wood02/z_en_wood02.c

@@ -438,10 +438,10 @@ void EnWood02_Update(Actor* thisx, PlayState* play2) {
     } else if ((thisx->params < WOOD_LEAF_GREEN) || (thisx->params == WOOD_TREE_SPECIAL)) { // not leaves
         Player* player = GET_PLAYER(play);
 
-        if ((this->unk_146 >= -1) && (((player->rideActor == NULL) && (sqrtf(thisx->xyzDistToPlayerSq) < 20.0f) &&
+        if ((this->unk_146 >= -1) &&
-                                       (player->linearVelocity != 0.0f)) ||
+            (((player->rideActor == NULL) && (sqrtf(thisx->xyzDistToPlayerSq) < 20.0f) && (player->speedXZ != 0.0f)) ||
-                                      ((player->rideActor != NULL) && (sqrtf(thisx->xyzDistToPlayerSq) < 60.0f) &&
+             ((player->rideActor != NULL) && (sqrtf(thisx->xyzDistToPlayerSq) < 60.0f) &&
-                                       (player->rideActor->speed != 0.0f)))) {
+              (player->rideActor->speed != 0.0f)))) {
             func_808C4458(this, play, &thisx->world.pos, 1);
             this->unk_146 = -0x15;
             Actor_PlaySfx(thisx, NA_SE_EV_TREE_SWING);

src/overlays/actors/ovl_Obj_Hunsui/z_obj_hunsui.c

@@ -173,7 +173,7 @@ void func_80B9C5E8(ObjHunsui* this, PlayState* play) {
                     sp38 = sp34;
                 }
 
-                player->linearVelocity *= sp38;
+                player->speedXZ *= sp38;
 
                 if ((this->unk_160 == OBJHUNSUI_F000_5) || (this->unk_160 == OBJHUNSUI_F000_6)) {
                     Math_ApproachF(&this->unk_1A0, 4.5f, 2.0f, 1.0f);
@@ -184,7 +184,7 @@ void func_80B9C5E8(ObjHunsui* this, PlayState* play) {
                 }
             } else {
                 this->unk_1A4 = player->actor.world.rot.y;
-                player->linearVelocity *= 0.5f;
+                player->speedXZ *= 0.5f;
                 Math_ApproachF(&this->unk_1A0, 3.0f, 1.0f, 1.0f);
                 Math_ApproachF(&this->unk_19C, this->unk_1A0, 1.0f, 0.1f);
             }
@@ -193,8 +193,8 @@ void func_80B9C5E8(ObjHunsui* this, PlayState* play) {
         }
     } else {
         if (this->unk_172 & 8) {
-            player->linearVelocity = this->unk_19C + player->linearVelocity;
+            player->speedXZ = this->unk_19C + player->speedXZ;
-            player->currentYaw = this->unk_1A4;
+            player->yaw = this->unk_1A4;
         }
         this->unk_1A0 = 0.0f;
         this->unk_19C = 0.0f;

src/overlays/actors/ovl_Obj_Nozoki/z_obj_nozoki.c

@@ -192,7 +192,7 @@ void func_80BA27C4(ObjNozoki* this, PlayState* play) {
                 play->actorCtx.flags |= ACTORCTX_FLAG_4;
             }
         }
-        GET_PLAYER(play)->linearVelocity = 0.0f;
+        GET_PLAYER(play)->speedXZ = 0.0f;
     }
 }
 

src/overlays/actors/ovl_Obj_Switch/z_obj_switch.c

@@ -324,7 +324,7 @@ void ObjSwitch_FloorSwitchSnapPlayerToSwitchEdge(ObjSwitch* this, PlayState* pla
                 player->actor.world.pos.z =
                     Math_CosS(this->dyna.actor.yawTowardsPlayer) * centerDisplacement + this->dyna.actor.world.pos.z;
             }
-            player->linearVelocity = 0.0f;
+            player->speedXZ = 0.0f;
         }
     }
 }

src/overlays/actors/ovl_Obj_Um/z_obj_um.c

@@ -606,7 +606,7 @@ void ObjUm_SetPlayerPosition(ObjUm* this, PlayState* play) {
 void ObjUm_RotatePlayer(ObjUm* this, PlayState* play, s16 angle) {
     Player* player = GET_PLAYER(play);
 
-    player->actor.shape.rot.y = player->actor.world.rot.y = player->currentYaw = this->dyna.actor.shape.rot.y + angle;
+    player->actor.shape.rot.y = player->actor.world.rot.y = player->yaw = this->dyna.actor.shape.rot.y + angle;
 }
 
 void func_80B78EBC(ObjUm* this, PlayState* play) {
@@ -624,7 +624,7 @@ void func_80B78EBC(ObjUm* this, PlayState* play) {
     player->upperLimbRot.y = 0;
     player->upperLimbRot.z = 0;
 
-    player->currentYaw = player->actor.focus.rot.y;
+    player->yaw = player->actor.focus.rot.y;
 }
 
 void ObjUm_RotatePlayerView(ObjUm* this, PlayState* play, s16 angle) {