From 49759e42d7f5da9e3b0c25aa62355c7482165964 Mon Sep 17 00:00:00 2001
From: fig02 <fig02srl@gmail.com>
Date: Tue, 1 Oct 2024 18:27:29 -0400
Subject: [PATCH] Actor flag: `ACTOR_FLAG_CARRY_X_ROT_INFLUENCE` (#2237)

* document x rot carry flag

* tweak comment

* typo

* review

* flag tweak
---
 include/z64actor.h                            |  6 +++--
 src/code/z_player_lib.c                       | 26 +++++++++----------
 .../ovl_Bg_Heavy_Block/z_bg_heavy_block.c     |  2 +-
 3 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/include/z64actor.h b/include/z64actor.h
index ea6acb198a..aab5f1039f 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -165,8 +165,10 @@ typedef struct ActorShape {
 // Player still has to meet all conditions to be able to receive a talk offer (for example, being in range).
 #define ACTOR_FLAG_TALK_OFFER_AUTO_ACCEPTED (1 << 16)
 
-//
-#define ACTOR_FLAG_17 (1 << 17)
+// Actor will be influenced by the pitch (x rot) of Player's left hand when being carried,
+// instead of Player's yaw which is the default actor carry behavior.
+// This flag is helpful for something like the `BG_HEAVY_BLOCK` actor which Player carries underhanded.
+#define ACTOR_FLAG_CARRY_X_ROT_INFLUENCE (1 << 17)
 
 // When locked onto an actor with this flag set, the C-Up button can be used to talk to this actor.
 // A C-Up button labeled "Navi" will appear on the HUD when locked on which indicates the actor can be checked with Navi.
diff --git a/src/code/z_player_lib.c b/src/code/z_player_lib.c
index ca4952c57f..c9815c3137 100644
--- a/src/code/z_player_lib.c
+++ b/src/code/z_player_lib.c
@@ -1625,8 +1625,8 @@ void Player_PostLimbDrawGameplay(PlayState* play, s32 limbIndex, Gfx** dList, Ve
     }
 
     if (limbIndex == PLAYER_LIMB_L_HAND) {
-        MtxF sp14C;
-        Actor* hookedActor;
+        MtxF leftHandMtx;
+        Actor* heldActor;
 
         Math_Vec3f_Copy(&this->leftHandPos, sCurBodyPartPos);
 
@@ -1682,25 +1682,25 @@ void Player_PostLimbDrawGameplay(PlayState* play, s32 limbIndex, Gfx** dList, Ve
         }
 
         if (this->actor.scale.y >= 0.0f) {
-            if (!Player_HoldsHookshot(this) && ((hookedActor = this->heldActor) != NULL)) {
+            if (!Player_HoldsHookshot(this) && ((heldActor = this->heldActor) != NULL)) {
                 if (this->stateFlags1 & PLAYER_STATE1_9) {
                     static Vec3f D_80126128 = { 398.0f, 1419.0f, 244.0f };
 
-                    Matrix_MultVec3f(&D_80126128, &hookedActor->world.pos);
+                    Matrix_MultVec3f(&D_80126128, &heldActor->world.pos);
                     Matrix_RotateZYX(0x69E8, -0x5708, 0x458E, MTXMODE_APPLY);
-                    Matrix_Get(&sp14C);
-                    Matrix_MtxFToYXZRotS(&sp14C, &hookedActor->world.rot, 0);
-                    hookedActor->shape.rot = hookedActor->world.rot;
+                    Matrix_Get(&leftHandMtx);
+                    Matrix_MtxFToYXZRotS(&leftHandMtx, &heldActor->world.rot, 0);
+                    heldActor->shape.rot = heldActor->world.rot;
                 } else if (this->stateFlags1 & PLAYER_STATE1_CARRYING_ACTOR) {
-                    Vec3s spB8;
+                    Vec3s leftHandRot;
 
-                    Matrix_Get(&sp14C);
-                    Matrix_MtxFToYXZRotS(&sp14C, &spB8, 0);
+                    Matrix_Get(&leftHandMtx);
+                    Matrix_MtxFToYXZRotS(&leftHandMtx, &leftHandRot, 0);
 
-                    if (hookedActor->flags & ACTOR_FLAG_17) {
-                        hookedActor->world.rot.x = hookedActor->shape.rot.x = spB8.x - this->unk_3BC.x;
+                    if (heldActor->flags & ACTOR_FLAG_CARRY_X_ROT_INFLUENCE) {
+                        heldActor->world.rot.x = heldActor->shape.rot.x = leftHandRot.x - this->unk_3BC.x;
                     } else {
-                        hookedActor->world.rot.y = hookedActor->shape.rot.y = this->actor.shape.rot.y + this->unk_3BC.y;
+                        heldActor->world.rot.y = heldActor->shape.rot.y = this->actor.shape.rot.y + this->unk_3BC.y;
                     }
                 }
             } else {
diff --git a/src/overlays/actors/ovl_Bg_Heavy_Block/z_bg_heavy_block.c b/src/overlays/actors/ovl_Bg_Heavy_Block/z_bg_heavy_block.c
index b433b51b99..ab1b72b4d1 100644
--- a/src/overlays/actors/ovl_Bg_Heavy_Block/z_bg_heavy_block.c
+++ b/src/overlays/actors/ovl_Bg_Heavy_Block/z_bg_heavy_block.c
@@ -77,7 +77,7 @@ void BgHeavyBlock_InitPiece(BgHeavyBlock* this, f32 scale) {
 void BgHeavyBlock_SetupDynapoly(BgHeavyBlock* this, PlayState* play) {
     s32 pad[2];
     CollisionHeader* colHeader = NULL;
-    this->dyna.actor.flags |= ACTOR_FLAG_4 | ACTOR_FLAG_5 | ACTOR_FLAG_17;
+    this->dyna.actor.flags |= ACTOR_FLAG_4 | ACTOR_FLAG_5 | ACTOR_FLAG_CARRY_X_ROT_INFLUENCE;
     DynaPolyActor_Init(&this->dyna, 0);
     CollisionHeader_GetVirtual(&gHeavyBlockCol, &colHeader);
     this->dyna.bgId = DynaPoly_SetBgActor(play, &play->colCtx.dyna, &this->dyna.actor, colHeader);