Further Attention Docs (#1732)

* more attention docs

* more docs

* cleanup

* more cleanup

* spacing

* more attention docs

* small cleanup

* consistency

1 files changed, 46 insertions, 19 deletions

diff --git a/include/z64actor.h b/include/z64actor.h
index 7a0e9db53..0fe152ede 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -109,7 +109,7 @@ typedef struct Actor {
     /* 0x039 */ u8 audioFlags; // Another set of flags? Seems related to sfx or bgm
     /* 0x03C */ PosRot focus; // Target reticle focuses on this position. For player this represents head pos and rot
     /* 0x050 */ u16 sfxId; // Id of sound effect to play. Plays when value is set, then is cleared the following update cycle
-    /* 0x054 */ f32 targetArrowOffset; // Height offset of the target arrow relative to `focus` position
+    /* 0x054 */ f32 lockOnArrowOffset; // Height offset of the lock-on arrow relative to `focus` position
     /* 0x058 */ Vec3f scale; // Scale of the actor in each axis
     /* 0x064 */ Vec3f velocity; // Velocity of the actor in each axis
     /* 0x070 */ f32 speed; // Context dependent speed value. Can be used for XZ or XYZ depending on which move function is used
@@ -280,6 +280,21 @@ typedef enum {
 #define ACTORCTX_FLAG_6 (1 << 6)
 #define ACTORCTX_FLAG_7 (1 << 7)
 
+/**
+ * Attention System
+ *
+ * The Attention System's responsibility is to bring specific actors to the player's attention.
+ * This includes:
+ *     - Making Tatl fly over to certain actors of interest (can be lock-on actors, but may also not be)
+ *     - Displaying an arrow over an actor that can be locked onto
+ *     - Displaying a reticle over the current lock-on actor
+ *     - Playing enemy background music if a hostile actor is nearby
+ *     - Drift the camera towards an actor (unused)
+ *
+ * This system does not handle the actual lock-on implementation.
+ * That is the responsibility of Player via `player->focusActor` and the camera.
+ */
+
 // A set of 4 triangles which appear as a ring around an actor when locked-on
 typedef struct LockOnReticle {
     /* 0x00 */ Vec3f pos;
@@ -288,22 +303,22 @@ typedef struct LockOnReticle {
 } LockOnReticle; // size = 0x14
 
 typedef struct Attention {
-    /* 0x00 */ Vec3f fairyPos; // Used by Tatl to indicate a targetable actor or general hint
+    /* 0x00 */ Vec3f tatlHoverPos;  // Tatl's current hover position
     /* 0x0C */ Vec3f reticlePos; // Main reticle pos which each `LockOnReticle` instance can reference
-    /* 0x18 */ Color_RGBAf fairyInnerColor;
-    /* 0x28 */ Color_RGBAf fairyOuterColor;
-    /* 0x38 */ Actor* fairyActor;
+    /* 0x18 */ Color_RGBAf tatlInnerColor; // Tatl inner color, based on actor category
+    /* 0x28 */ Color_RGBAf tatlOuterColor; // Tatl outer color, based on actor category
+    /* 0x38 */ Actor* tatlHoverActor; // The actor that Tatl hovers over
     /* 0x3C */ Actor* reticleActor; // Actor to draw a reticle over
-    /* 0x40 */ f32 fairyMoveProgressFactor; // Controls Tatl so she can smootly transition to the target actor
+    /* 0x40 */ f32 tatlMoveProgressFactor; // Controls Tatl so she can smootly transition to an actor
     /* 0x44 */ f32 reticleRadius; // Main reticle radius value which each `LockOnReticle` instance can reference
     /* 0x48 */ s16 reticleFadeAlphaControl; // Set and fade the reticle alpha; Non-zero values control if it should draw
-    /* 0x4A */ u8 fairyActorCategory;
+    /* 0x4A */ u8 tatlHoverActorCategory; // Category of the actor Tatl is currently hovering over
     /* 0x4B */ u8 reticleSpinCounter; // Counts up when a reticle is active, used for the spinning animation
     /* 0x4C */ s8 curReticle; // Indexes lockOnReticles[]
     /* 0x50 */ LockOnReticle lockOnReticles[3]; // Multiple reticles are used for a motion-blur effect
-    /* 0x8C */ Actor* forcedTargetActor; // Never set to non-NULL
-    /* 0x90 */ Actor* bgmEnemy;
-    /* 0x94 */ Actor* arrowPointedActor;
+    /* 0x8C */ Actor* forcedLockOnActor; // Forces lock-on to this actor when set (never used in practice)
+    /* 0x90 */ Actor* bgmEnemy; // The nearest actor which can trigger enemy background music
+    /* 0x94 */ Actor* arrowHoverActor; // Actor to draw an arrow over
 } Attention; // size = 0x98
 
 // It is difficult to give each type a name because it is numerically based
@@ -325,8 +340,8 @@ typedef enum AttentionRangeType {
 } AttentionRangeType;
 
 typedef struct AttentionRangeParams {
-    /* 0x0 */ f32 rangeSq;
-    /* 0x4 */ f32 leashScale;
+    /* 0x0 */ f32 attentionRangeSq;
+    /* 0x4 */ f32 lockOnLeashScale;
 } AttentionRangeParams; // size = 0x8
 
 typedef struct {
@@ -448,9 +463,10 @@ typedef enum DoorLockType {
     /* 3 */ DOORLOCK_MAX
 } DoorLockType;
 
-// Actor is discoverable by the Attention System. This enables Navi to hover over the actor when it is in range.
+// Actor is discoverable by the Attention System. This enables Tatl to hover over the actor when it is in range.
 // The actor can also be locked onto (as long as `ACTOR_FLAG_LOCK_ON_DISABLED` is not set).
 #define ACTOR_FLAG_ATTENTION_ENABLED    (1 << 0)
+
 // Unused
 #define ACTOR_FLAG_2             (1 << 1)
 
@@ -469,8 +485,10 @@ typedef enum DoorLockType {
 #define ACTOR_FLAG_20            (1 << 5)
 // 
 #define ACTOR_FLAG_40            (1 << 6)
+
 // hidden or revealed by Lens of Truth (depending on room lensMode)
 #define ACTOR_FLAG_REACT_TO_LENS (1 << 7)
+
 // Signals that player has accepted an offer to talk to an actor
 // Player will retain this flag until the player is finished talking
 // Actor will retain this flag until `Actor_TalkOfferAccepted` is called or manually turned off by the actor
@@ -481,6 +499,7 @@ typedef enum DoorLockType {
 #define ACTOR_FLAG_400           (1 << 10)
 // 
 #define ACTOR_FLAG_800           (1 << 11)
+
 // Actor will not shake when a quake occurs
 #define ACTOR_FLAG_IGNORE_QUAKE  (1 << 12)
 // 
@@ -503,19 +522,25 @@ typedef enum DoorLockType {
 // With this flag Player talks directly to the actor with C-Up. It is expected that the resulting dialog should appear
 // to be coming from Tatl, even though she is not involved at all with this interaction.
 #define ACTOR_FLAG_TALK_WITH_C_UP (1 << 18)
-// 
-#define ACTOR_FLAG_80000         (1 << 19)
+
+// Allows for the attention system to refind the focus actor in the search for the next attention actor.
+// Also allows for the next lock-on actor to be the focus actor again.
+// When chosen as the next lock-on actor, this flag is unset.
+#define ACTOR_FLAG_FOCUS_ACTOR_REFINDABLE (1 << 19)
 // 
 #define ACTOR_FLAG_100000        (1 << 20)
 // 
 #define ACTOR_FLAG_200000        (1 << 21)
 // 
 #define ACTOR_FLAG_400000        (1 << 22)
+
 // When Player is carrying this actor, it can only be thrown, not dropped/placed.
 // Typically an actor can only be thrown when moving, but this allows an actor to be thrown when standing still.
 #define ACTOR_FLAG_THROW_ONLY    (1 << 23)
+
 // When colliding with Player's body AC collider, a "thump" sound will play indicating his body has been hit
 #define ACTOR_FLAG_SFX_FOR_PLAYER_BODY_HIT       (1 << 24)
+
 // Actor can update even if Player is currently using the ocarina.
 // Typically an actor will halt while the ocarina is active (depending on category).
 // This flag allows a given actor to be an exception.
@@ -532,8 +557,10 @@ typedef enum DoorLockType {
 #define ACTOR_FLAG_10000000      (1 << 28)
 // 
 #define ACTOR_FLAG_20000000      (1 << 29)
-// 
-#define ACTOR_FLAG_40000000      (1 << 30)
+
+// Camera will slowly drift to the actor while approaching it.
+// Uses the attention system but `ACTOR_FLAG_ATTENTION_ENABLED` is not required.
+#define ACTOR_FLAG_CAMERA_DRIFT_ENABLED (1 << 30)
 // 
 #define ACTOR_FLAG_80000000      (1 << 31)
 
@@ -698,7 +725,7 @@ extern s16 D_801AED48[8];
 extern Gfx D_801AEF88[];
 extern Gfx D_801AEFA0[];
 
-extern Actor* D_801ED920;
+extern Actor* gCameraDriftActor;
 
 void ActorShape_Init(ActorShape* actorShape, f32 yOffset, ActorShadowFunc shadowDraw, f32 shadowScale);
 void ActorShadow_DrawCircle(Actor* actor, struct Lights* lights, struct PlayState* play);
@@ -787,7 +814,7 @@ PosRot Actor_GetFocus(Actor* actor);
 PosRot Actor_GetWorld(Actor* actor);
 PosRot Actor_GetWorldPosShapeRot(Actor* actor);
 
-s32 Attention_OutsideLeashRange(Actor* actor, struct Player* player, s32 ignoreLeash);
+s32 Attention_ShouldReleaseLockOn(Actor* actor, struct Player* player, s32 ignoreLeash);
 s32 Actor_TalkOfferAccepted(Actor* actor, struct GameState* gameState);
 s32 Actor_OfferTalk(Actor* actor, struct PlayState* play, f32 radius);
 s32 Actor_OfferTalkNearColChkInfoCylinder(Actor* actor, struct PlayState* play);