From c91e62f000b56f9a109b3e8ac5e2b8d370949136 Mon Sep 17 00:00:00 2001
From: fig02 <fig02srl@gmail.com>
Date: Mon, 16 Sep 2024 12:34:23 -0400
Subject: [PATCH] Document `zTargetActiveTimer` (#2200)

* document zTargetActiveTimer

* edit comments

* Update src/overlays/actors/ovl_player_actor/z_player.c

Co-authored-by: cadmic <cadmic24@gmail.com>

* capitalization

---------

Co-authored-by: cadmic <cadmic24@gmail.com>
---
 include/z64player.h                           |  2 +-
 src/code/z_actor.c                            |  2 +-
 .../actors/ovl_player_actor/z_player.c        | 34 +++++++++++++------
 3 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/include/z64player.h b/include/z64player.h
index ebd5220e88..0ae8e0e431 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -797,7 +797,7 @@ typedef struct Player {
     /* 0x05E4 */ ColliderQuad shieldQuad;
     /* 0x0664 */ Actor* focusActor; // Actor that Player and the camera are looking at; Used for lock-on, talking, and more
     /* 0x0668 */ char unk_668[0x004];
-    /* 0x066C */ s32 unk_66C;
+    /* 0x066C */ s32 zTargetActiveTimer; // Non-zero values indicate Z-Targeting should update; Values under 5 indicate lock-on is releasing
     /* 0x0670 */ s32 meleeWeaponEffectIndex;
     /* 0x0674 */ PlayerActionFunc actionFunc;
     /* 0x0678 */ PlayerAgeProperties* ageProperties;
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index b7b9e31b01..5785d62a1f 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -2413,7 +2413,7 @@ void Actor_UpdateAll(PlayState* play, ActorContext* actorCtx) {
         func_8008EDF0(player);
     }
 
-    if ((actor == NULL) || (player->unk_66C < 5)) {
+    if ((actor == NULL) || (player->zTargetActiveTimer < 5)) {
         actor = NULL;
 
         if (actorCtx->attention.reticleSpinCounter != 0) {
diff --git a/src/overlays/actors/ovl_player_actor/z_player.c b/src/overlays/actors/ovl_player_actor/z_player.c
index 65deb1994c..83c88e5601 100644
--- a/src/overlays/actors/ovl_player_actor/z_player.c
+++ b/src/overlays/actors/ovl_player_actor/z_player.c
@@ -3609,26 +3609,39 @@ void func_80836BEC(Player* this, PlayState* play) {
     if ((play->csCtx.state != CS_STATE_IDLE) || (this->csAction != PLAYER_CSACTION_NONE) ||
         (this->stateFlags1 & (PLAYER_STATE1_7 | PLAYER_STATE1_29)) ||
         (this->stateFlags3 & PLAYER_STATE3_FLYING_WITH_HOOKSHOT)) {
-        this->unk_66C = 0;
+        // Don't allow Z-Targeting in various states
+        this->zTargetActiveTimer = 0;
     } else if (zButtonHeld || (this->stateFlags2 & PLAYER_STATE2_LOCK_ON_WITH_SWITCH) || (this->unk_684 != NULL)) {
-        if (this->unk_66C <= 5) {
-            this->unk_66C = 5;
+        // While a lock-on is active, decrement the timer and hold it at 5.
+        // Values under 5 indicate a lock-on has ended and will make the reticle release.
+        // See usage toward the end of `Actor_UpdateAll`.
+        //
+        // `zButtonHeld` will also be true for Parallel. This is necessary because the timer
+        // needs to be non-zero for `Player_SetParallel` to be able to run below.
+        if (this->zTargetActiveTimer <= 5) {
+            this->zTargetActiveTimer = 5;
         } else {
-            this->unk_66C--;
+            this->zTargetActiveTimer--;
         }
     } else if (this->stateFlags1 & PLAYER_STATE1_PARALLEL) {
-        this->unk_66C = 0;
-    } else if (this->unk_66C != 0) {
-        this->unk_66C--;
+        // If the above code block which checks `zButtonHeld` is not taken, that means Z has been released.
+        // In that case, setting `zTargetActiveTimer` to 0 will stop Parallel if it is currently active.
+        this->zTargetActiveTimer = 0;
+    } else if (this->zTargetActiveTimer != 0) {
+        this->zTargetActiveTimer--;
     }
 
-    if (this->unk_66C >= 6) {
+    if (this->zTargetActiveTimer >= 6) {
+        // When a lock-on is started, `zTargetActiveTimer` will be set to 15 and then immediately start decrementing
+        // down to 5. During this 10 frame period, set `ignoreLeash` so that the lock-on will temporarily
+        // have an infinite leash distance.
+        // This gives time for the reticle to settle while it locks on, even if the player leaves the leash range.
         ignoreLeash = true;
     }
 
     isTalking = func_8083224C(play);
 
-    if (isTalking || (this->unk_66C != 0) ||
+    if (isTalking || (this->zTargetActiveTimer != 0) ||
         (this->stateFlags1 & (PLAYER_STATE1_12 | PLAYER_STATE1_BOOMERANG_THROWN))) {
         if (!isTalking) {
             if (!(this->stateFlags1 & PLAYER_STATE1_BOOMERANG_THROWN) &&
@@ -3666,7 +3679,7 @@ void func_80836BEC(Player* this, PlayState* play) {
                         }
 
                         this->focusActor = nextLockOnActor;
-                        this->unk_66C = 15;
+                        this->zTargetActiveTimer = 15;
                         this->stateFlags2 &= ~(PLAYER_STATE2_1 | PLAYER_STATE2_21);
                     } else {
                         if (!usingHoldTargeting) {
@@ -3676,6 +3689,7 @@ void func_80836BEC(Player* this, PlayState* play) {
 
                     this->stateFlags1 &= ~PLAYER_STATE1_LOCK_ON_FORCED_TO_RELEASE;
                 } else {
+                    // Lock-on was not started above. Set Parallel Mode.
                     if (!(this->stateFlags1 & (PLAYER_STATE1_PARALLEL | PLAYER_STATE1_LOCK_ON_FORCED_TO_RELEASE))) {
                         Player_SetParallel(this);
                     }