From d60a032b114484a67add15bbfd6ba6a958a5bee3 Mon Sep 17 00:00:00 2001 From: engineer124 <47598039+engineer124@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:44:44 +1100 Subject: Further Attention Docs (#1732) * more attention docs * more docs * cleanup * more cleanup * spacing * more attention docs * small cleanup * consistency --- include/z64actor.h | 65 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 19 deletions(-) (limited to 'include') 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); -- cgit v1.2.3