Documentation pass for the Target system (#1281)

* cleanup

* import bss

* sActorHiliteMtx

* some cleanups on func_800BB604

* Actor_IsInTargetableRange

* rematch func_800BB604

Co-authored-by: engineer124 <engineer124engineer124@gmail.com>

* Name ACTOR_FLAG_UNFRIENDLY and ACTOR_FLAG_FRIENDLY

* Rename some Target_ functions

* cleanusp

* TargetMode enum

* Target_800B82EC

* sNaming

* more

* more naming

* fairyHintPos

* rotation

* ACTOR_FLAG_TARGETABLE

* update namefixer

* remove trailing comma

* bss

* Wall of text for Target_800BB604

* function naming

* cleanups

* Target_GetAdjustedDistSq

* NotLeash

* more comments

* minor comment

* review

* fix

* rotZTick

* review

* name last members

* fix

* review

* review

* more namefixer

* swap members

* comment

* Update src/code/z_actor.c

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

* Update src/code/z_actor.c

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

* review

* format

* Update src/code/z_actor.c

Co-authored-by: engineer124 <47598039+engineer124@users.noreply.github.com>

* Update include/z64actor.h

Co-authored-by: engineer124 <47598039+engineer124@users.noreply.github.com>

* review

* review

* fix

* fix

---------

Co-authored-by: engineer124 <engineer124engineer124@gmail.com>
Co-authored-by: Derek Hensley <hensley.derek58@gmail.com>
Co-authored-by: engineer124 <47598039+engineer124@users.noreply.github.com>

4 files changed, 50 insertions, 48 deletions

diff --git a/include/functions.h b/include/functions.h
index ff803000d..6c7bc067a 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -477,7 +477,7 @@ void func_800B4AEC(PlayState* play, Actor* actor, f32 y);
 void func_800B4B50(Actor* actor, Lights* mapper, PlayState* play);
 void Actor_GetProjectedPos(PlayState* play, Vec3f* worldPos, Vec3f* projectedPos, f32* invW);
 
-void Actor_DrawZTarget(TargetContext* targetCtx, PlayState* play);
+void Target_Draw(TargetContext* targetCtx, PlayState* play);
 
 s32 Flags_GetSwitch(PlayState* play, s32 flag);
 void Flags_SetSwitch(PlayState* play, s32 flag);
@@ -558,7 +558,7 @@ PosRot* Actor_GetFocus(PosRot* dest, Actor* actor);
 PosRot* Actor_GetWorld(PosRot* dest, Actor* actor);
 PosRot* Actor_GetWorldPosShapeRot(PosRot* dest, Actor* actor);
 
-s32 func_800B83F8(Actor* actor, Player* player, s32 flag);
+s32 Target_OutsideLeashRange(Actor* actor, Player* player, s32 ignoreLeash);
 s32 Actor_ProcessTalkRequest(Actor* actor, GameState* gameState);
 s32 Actor_OfferTalkExchange(Actor* actor, PlayState* play, f32 xzRange, f32 yRange, PlayerItemAction exchangeItemAction);
 s32 Actor_OfferTalkExchangeEquiCylinder(Actor* actor, PlayState* play, f32 radius, PlayerItemAction exchangeItemAction);
@@ -1119,7 +1119,7 @@ void Player_SetModelGroup(Player* player, PlayerModelGroup modelGroup);
 void func_80123C58(Player* player);
 void Player_SetEquipmentData(PlayState* play, Player* player);
 void Player_UpdateBottleHeld(PlayState* play, Player* player, ItemId itemId, PlayerItemAction itemAction);
-void func_80123DA4(Player* player);
+void Player_Untarget(Player* player);
 void func_80123DC0(Player* player);
 void func_80123E90(PlayState* play, Actor* actor);
 s32 func_80123F2C(PlayState* play, s32 ammo);
diff --git a/include/variables.h b/include/variables.h
index 8a46bdbf5..1614d922b 100644
--- a/include/variables.h
+++ b/include/variables.h
@@ -1907,20 +1907,6 @@ extern u8 gSampleBankTable[];
 
 // bss
 // extern UNK_TYPE1 D_801ED894;
-extern CollisionPoly* D_801ED8B0;
-extern s32 D_801ED8B4;
-// extern UNK_TYPE1 D_801ED8B8;
-// extern UNK_TYPE1 D_801ED8BC;
-// extern UNK_TYPE1 D_801ED8C0;
-// extern UNK_TYPE1 D_801ED8C4;
-extern f32 D_801ED8C8;
-extern f32 sBgmEnemyDistSq;
-extern f32 D_801ED8D0;
-// extern UNK_TYPE1 D_801ED8D4;
-// extern UNK_TYPE1 D_801ED8D8;
-// extern UNK_TYPE1 D_801ED8DC;
-extern Mtx D_801ED8E0;
-extern Actor* D_801ED920;
 
 extern Vec3f D_801EDE00;
 extern Vec3f D_801EDE10;
diff --git a/include/z64actor.h b/include/z64actor.h
index d757117fb..d794b8dd1 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -150,7 +150,7 @@ typedef struct Actor {
     /* 0x100 */ f32 uncullZoneScale; // Amount to increase the uncull zone scale by (in projected space)
     /* 0x104 */ f32 uncullZoneDownward; // Amount to increase uncull zone downward by (in projected space)
     /* 0x108 */ Vec3f prevPos; // World position from the previous update cycle
-    /* 0x114 */ u8 isTargeted; // Set to true if the actor is currently being targeted by the player
+    /* 0x114 */ u8 isLockedOn; // Set to true if the actor is currently being targeted by the player
     /* 0x115 */ u8 targetPriority; // Lower values have higher priority. Resets to 0 when player stops targeting
     /* 0x116 */ u16 textId; // Text ID to pass to link/display when interacting with the actor
     /* 0x118 */ u16 freezeTimer; // Actor does not update when set. Timer decrements automatically
@@ -296,33 +296,47 @@ typedef enum {
 #define ACTORCTX_FLAG_6 (1 << 6)
 #define ACTORCTX_FLAG_7 (1 << 7)
 
-
-typedef struct {
+// A set of 4 triangles which appear around an actor when the player Z-Targets it
+typedef struct LockOnTriangleSet {
     /* 0x00 */ Vec3f pos;
-    /* 0x0C */ f32 unkC;
+    /* 0x0C */ f32 radius; // distance towards the center of the locked on
     /* 0x10 */ Color_RGBA8 color;
-} TargetContextEntry; // size = 0x14
+} LockOnTriangleSet; // size = 0x14
 
 typedef struct TargetContext {
-    /* 0x00 */ Vec3f unk0;
-    /* 0x0C */ Vec3f targetCenterPos;
-    /* 0x18 */ Color_RGBAf fairyInner;
-    /* 0x28 */ Color_RGBAf fairyOuter;
-    /* 0x38 */ Actor* arrowPointedActor;
-    /* 0x3C */ Actor* targetedActor;
-    /* 0x40 */ f32 unk40;
-    /* 0x44 */ f32 unk44;
-    /* 0x48 */ s16 unk48; // alpha
-    /* 0x4A */ u8 unk4A;
-    /* 0x4B */ u8 unk4B;
-    /* 0x4C */ s8 unk4C;
-    /* 0x4D */ UNK_TYPE1 pad4D[0x3];
-    /* 0x50 */ TargetContextEntry unk50[3];
-    /* 0x8C */ Actor* unk8C;
+    /* 0x00 */ Vec3f fairyPos; // Used by Tatl to indicate a targetable actor or general hint
+    /* 0x0C */ Vec3f lockOnPos;
+    /* 0x18 */ Color_RGBAf fairyInnerColor;
+    /* 0x28 */ Color_RGBAf fairyOuterColor;
+    /* 0x38 */ Actor* fairyActor;
+    /* 0x3C */ Actor* lockOnActor;
+    /* 0x40 */ f32 fairyMoveProgressFactor; // Controls Tatl so she can smootly transition to the target actor
+    /* 0x44 */ f32 lockOnRadius; // Control the circle lock-on triangles coming in from offscreen when you first target
+    /* 0x48 */ s16 lockOnAlpha;
+    /* 0x4A */ u8 fairyActorCategory;
+    /* 0x4B */ u8 rotZTick;
+    /* 0x4C */ s8 lockOnIndex;
+    /* 0x50 */ LockOnTriangleSet lockOnTriangleSets[3];
+    /* 0x8C */ Actor* forcedTargetActor; // Never set to non-NULL
     /* 0x90 */ Actor* bgmEnemy;
-    /* 0x94 */ Actor* unk_94;
+    /* 0x94 */ Actor* arrowPointedActor;
 } TargetContext; // size = 0x98
 
+typedef enum TargetMode {
+    /*  0 */ TARGET_MODE_0,
+    /*  1 */ TARGET_MODE_1,
+    /*  2 */ TARGET_MODE_2,
+    /*  3 */ TARGET_MODE_3,
+    /*  4 */ TARGET_MODE_4,
+    /*  5 */ TARGET_MODE_5,
+    /*  6 */ TARGET_MODE_6,
+    /*  7 */ TARGET_MODE_7,
+    /*  8 */ TARGET_MODE_8,
+    /*  9 */ TARGET_MODE_9,
+    /* 10 */ TARGET_MODE_10,
+    /* 11 */ TARGET_MODE_MAX
+} TargetMode;
+
 typedef struct {
     /* 0x0 */ TexturePtr texture;
     /* 0x4 */ s16 x;
@@ -407,7 +421,7 @@ typedef struct ActorContext {
     /* 0x00F */ u8 numLensActors;
     /* 0x010 */ ActorListEntry actorLists[ACTORCAT_MAX];
     /* 0x0A0 */ Actor* lensActors[LENS_ACTOR_MAX]; // Draws up to LENS_ACTOR_MAX number of invisible actors
-    /* 0x120 */ TargetContext targetContext;
+    /* 0x120 */ TargetContext targetCtx;
     /* 0x1B8 */ ActorContextSceneFlags sceneFlags;
     /* 0x1E4 */ TitleCardContext titleCtxt;
     /* 0x1F4 */ PlayerImpact playerImpact;
@@ -454,14 +468,14 @@ typedef enum {
     /* 3 */ DOORLOCK_MAX
 } DoorLockType;
 
-// Targetability / ACTOR_FLAG_TARGETABLE?
-#define ACTOR_FLAG_1             (1 << 0)
-// 
+// Allows Tatl to fly over the actor and lock-on it (using the Z-target)
+#define ACTOR_FLAG_TARGETABLE    (1 << 0)
+// Unused
 #define ACTOR_FLAG_2             (1 << 1)
-// 
-#define ACTOR_FLAG_4             (1 << 2)
-// 
-#define ACTOR_FLAG_8             (1 << 3)
+// Changes the targeting behaviour for unfriendly actors (sound effects, Player's stance, etc)
+#define ACTOR_FLAG_UNFRIENDLY    (1 << 2)
+// Opposite of the UNFRIENDLY flag. It is not checked explictly in the original game.
+#define ACTOR_FLAG_FRIENDLY      (1 << 3)
 // 
 #define ACTOR_FLAG_10            (1 << 4)
 // 
@@ -680,9 +694,11 @@ typedef struct BlinkInfo {
     /* 0x2 */ s16 blinkTimer;
 } BlinkInfo; // size = 0x4
 
-extern TargetRangeParams gTargetRanges[];
+extern TargetRangeParams gTargetRanges[TARGET_MODE_MAX];
 extern s16 D_801AED48[8];
 extern Gfx D_801AEF88[];
 extern Gfx D_801AEFA0[];
 
+extern Actor* D_801ED920;
+
 #endif
diff --git a/include/z64player.h b/include/z64player.h
index 5974defc5..03bb71d94 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -1168,7 +1168,7 @@ typedef struct Player {
     /* 0x564 */ ColliderQuad meleeWeaponQuads[2];
     /* 0x664 */ ColliderQuad shieldQuad;
     /* 0x6E4 */ ColliderCylinder shieldCylinder;
-    /* 0x730 */ Actor* targetedActor; // Z/L-Targeted actor
+    /* 0x730 */ Actor* lockOnActor; // Z/L-Targeted actor
     /* 0x734 */ char unk_734[4];
     /* 0x738 */ s32 unk_738;
     /* 0x73C */ s32 meleeWeaponEffectIndex[3];