Talk Exchange System Docs (#1312)

* Fix typo

* PLAYER_IA_HELD

* Actor offer exchange item functions

* SubS_OfferExchangeItemCustom

* SubS_OfferItem + enum

* Actors that use Subs_OfferItem

* SubS_OfferExchangeItemFacing

* Comments

* Format

* Better comment

* EnRg

* function names and comments

* Split enum

* exchangeItemId -> exchangeItemAction

* namefixer

* PR comments

* Missed a comment

* Max -> Mask

* SubS_SetOfferMode

* Some more comments updating

* rg comment

* PLAYER_IA_CONTINUE

* Revert back to PLAYER_IA_MINUS1

* Comment typos/grammar

* Verify functions

* yawRange

* Actor_OfferTalkNearby

* Actor_OfferTalkExchangeEquiCylinder

* format

* Actor_OfferTalkNearColChkInfoCylinder

* OfferTalk comments

* Actor_OfferTalkExchange comment enum

* format

4 files changed, 52 insertions, 28 deletions

diff --git a/include/functions.h b/include/functions.h
index 66265e454..622830246 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -560,13 +560,13 @@ PosRot* Actor_GetWorldPosShapeRot(PosRot* dest, Actor* actor);
 
 s32 func_800B83F8(Actor* actor, Player* player, s32 flag);
 s32 Actor_ProcessTalkRequest(Actor* actor, GameState* gameState);
-s32 func_800B8500(Actor* actor, PlayState* play, f32 xzRange, f32 yRange, PlayerItemAction exchangeItemId);
-s32 func_800B85E0(Actor* actor, PlayState* play, f32 radius, PlayerItemAction exchangeItemId);
-s32 func_800B8614(Actor* actor, PlayState* play, f32 radius);
-s32 func_800B863C(Actor* actor, PlayState* play);
+s32 Actor_OfferTalkExchange(Actor* actor, PlayState* play, f32 xzRange, f32 yRange, PlayerItemAction exchangeItemAction);
+s32 Actor_OfferTalkExchangeEquiCylinder(Actor* actor, PlayState* play, f32 radius, PlayerItemAction exchangeItemAction);
+s32 Actor_OfferTalk(Actor* actor, PlayState* play, f32 radius);
+s32 Actor_OfferTalkNearColChkInfoCylinder(Actor* actor, PlayState* play);
 s32 Actor_TextboxIsClosing(Actor* actor, PlayState* play);
 s32 Actor_ChangeFocus(Actor* actor1, PlayState* play, Actor* actor2);
-PlayerItemAction Player_GetExchangeItemId(PlayState* play);
+PlayerItemAction Player_GetExchangeItemAction(PlayState* play);
 s32 func_800B8718(Actor* actor, GameState* gameState);
 s32 func_800B874C(Actor* actor, PlayState* play, f32 xzRange, f32 yRange);
 s32 func_800B8804(Actor* actor, PlayState* play, f32 xzRange);
diff --git a/include/z64player.h b/include/z64player.h
index b74b5846a..5974defc5 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -51,8 +51,15 @@ typedef enum {
     /* 4 */ PLAYER_ENV_HAZARD_UNDERWATER_FREE
 } PlayerEnvHazard;
 
+/*
+ * Current known usages for PLAYER_IA_MINUS1:
+ *  1. With TalkExchange requests, used to continue a current conversation after a textbox is closed
+ *  2. In `func_80123810` as a return value representing the offer is declined or invalid
+ *  3. Used as an item action to return the previously held item after player is done shielding
+ */
+
 typedef enum PlayerItemAction {
-    /*   -1 */ PLAYER_IA_MINUS1 = -1,
+    /*   -1 */ PLAYER_IA_MINUS1 = -1, // TODO: determine usages with more player docs, possibly split into seperate values (see known usages above)
     /* 0x00 */ PLAYER_IA_NONE,
     /* 0x01 */ PLAYER_IA_LAST_USED,
     /* 0x02 */ PLAYER_IA_FISHING_ROD,
@@ -1180,7 +1187,7 @@ typedef struct Player {
     /* 0xA80 */ Actor* tatlActor;
     /* 0xA84 */ s16 tatlTextId;
     /* 0xA86 */ s8 csId;
-    /* 0xA87 */ s8 exchangeItemId; // PlayerItemAction enum
+    /* 0xA87 */ s8 exchangeItemAction; // PlayerItemAction enum
     /* 0xA88 */ Actor* talkActor;
     /* 0xA8C */ f32 talkActorDistance;
     /* 0xA90 */ Actor* unk_A90;
diff --git a/include/z64save.h b/include/z64save.h
index d969ff7bf..85a2a62e3 100644
--- a/include/z64save.h
+++ b/include/z64save.h
@@ -1447,16 +1447,17 @@ typedef enum {
     /* 1 */ WEEKEVENTREG_HORSE_RACE_STATE_START,
     /* 2 */ WEEKEVENTREG_HORSE_RACE_STATE_2,
     /* 3 */ WEEKEVENTREG_HORSE_RACE_STATE_3,
-    /* 4 */ WEEKEVENTREG_HORSE_RACE_STATE_4,
-    /* 7 */ WEEKEVENTREG_HORSE_RACE_STATE_MAX = 7
+    /* 4 */ WEEKEVENTREG_HORSE_RACE_STATE_4
 } WeekEventRegHorseRaceState;
 
-#define GET_WEEKEVENTREG_HORSE_RACE_STATE (WEEKEVENTREG(92) & WEEKEVENTREG_HORSE_RACE_STATE_MAX)
+#define WEEKEVENTREG_HORSE_RACE_STATE_MASK 7
+
+#define GET_WEEKEVENTREG_HORSE_RACE_STATE (WEEKEVENTREG(92) & WEEKEVENTREG_HORSE_RACE_STATE_MASK)
 
 #define SET_WEEKEVENTREG_HORSE_RACE_STATE(state)                                                                       \
     {                                                                                                                  \
-        WEEKEVENTREG(92) &= (u8)~WEEKEVENTREG_HORSE_RACE_STATE_MAX;                                                    \
-        WEEKEVENTREG(92) = WEEKEVENTREG(92) | (u8)((WEEKEVENTREG(92) & ~WEEKEVENTREG_HORSE_RACE_STATE_MAX) | (state)); \
+        WEEKEVENTREG(92) &= (u8)~WEEKEVENTREG_HORSE_RACE_STATE_MASK;                                                    \
+        WEEKEVENTREG(92) = WEEKEVENTREG(92) | (u8)((WEEKEVENTREG(92) & ~WEEKEVENTREG_HORSE_RACE_STATE_MASK) | (state)); \
     }                                                                                                                  \
     (void)0
 
@@ -1561,22 +1562,23 @@ typedef enum {
 typedef enum {
     /* 0 */ EVENTINF_DOG_RACE_STATE_NOT_STARTED,
     /* 2 */ EVENTINF_DOG_RACE_STATE_STARTED = 2,
-    /* 3 */ EVENTINF_DOG_RACE_STATE_ENDED,
-    /* 7 */ EVENTINF_DOG_RACE_STATE_MAX = 7
+    /* 3 */ EVENTINF_DOG_RACE_STATE_ENDED
 } EventInfDogRaceState;
 
-#define GET_EVENTINF_DOG_RACE_STATE (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MAX)
+#define EVENTINF_DOG_RACE_STATE_MASK 7
+
+#define GET_EVENTINF_DOG_RACE_STATE (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MASK)
 #define SET_EVENTINF_DOG_RACE_STATE(state) \
-    (gSaveContext.eventInf[0] = ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MAX) | (state)))
+    (gSaveContext.eventInf[0] = ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MASK) | (state)))
 
-#define GET_EVENTINF_DOG_RACE_SELECTED_DOG_INDEX ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MAX) >> 3)
+#define GET_EVENTINF_DOG_RACE_SELECTED_DOG_INDEX ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MASK) >> 3)
 #define SET_EVENTINF_DOG_RACE_SELECTED_DOG_INDEX(selectedDogIndex) \
-    (gSaveContext.eventInf[0] = (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MAX) | (selectedDogIndex << 3))
+    (gSaveContext.eventInf[0] = (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MASK) | (selectedDogIndex << 3))
 
 // This is exactly the same as the selected dog index; they never need both of them at the same time.
-#define GET_EVENTINF_DOG_RACE_RACE_STANDING ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MAX) >> 3)
+#define GET_EVENTINF_DOG_RACE_RACE_STANDING ((gSaveContext.eventInf[0] & (u8)~EVENTINF_DOG_RACE_STATE_MASK) >> 3)
 #define SET_EVENTINF_DOG_RACE_RACE_STANDING(raceStanding) \
-    (gSaveContext.eventInf[0] = (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MAX) | (raceStanding << 3))
+    (gSaveContext.eventInf[0] = (gSaveContext.eventInf[0] & EVENTINF_DOG_RACE_STATE_MASK) | (raceStanding << 3))
 
 typedef enum {
     /* 0 */ DUNGEON_INDEX_WOODFALL_TEMPLE,
diff --git a/include/z64subs.h b/include/z64subs.h
index 0aaf9bcd2..4d365dd14 100644
--- a/include/z64subs.h
+++ b/include/z64subs.h
@@ -10,16 +10,31 @@ extern Vec3f gOneVec3f;
 
 #define SUBS_TIME_PATHING_ORDER 3
 
+// NOTE: all on screen checks are bugged, and always evaluate to true, even if the target is off screen
+typedef enum {
+    /* 0 */ SUBS_OFFER_MODE_NONE,
+    /* 1 */ SUBS_OFFER_MODE_GET_ITEM,
+    // Further modes all deal with offering talk exchange requests
+    /* 2 */ SUBS_OFFER_MODE_NEARBY,
+    /* 3 */ SUBS_OFFER_MODE_ONSCREEN,
+    /* 4 */ SUBS_OFFER_MODE_AUTO,
+    /* 5 */ SUBS_OFFER_MODE_AUTO_TARGETED, // Also checks nearby and on screen
+    /* 6 */ SUBS_OFFER_MODE_AUTO_NEARBY_ONSCREEN
+} SubSOfferMode;
+
+#define SUBS_OFFER_MODE_MASK                                                                               \
+    (SUBS_OFFER_MODE_GET_ITEM | SUBS_OFFER_MODE_NEARBY | SUBS_OFFER_MODE_ONSCREEN | SUBS_OFFER_MODE_AUTO | \
+     SUBS_OFFER_MODE_AUTO_TARGETED | SUBS_OFFER_MODE_AUTO_NEARBY_ONSCREEN)
+
 typedef enum {
     /* 0 */ SUBS_CUTSCENE_WITH_PLAYER,
     /* 1 */ SUBS_CUTSCENE_NORMAL,
     /* 2 */ SUBS_CUTSCENE_WITH_PLAYER_SET_FLAG
 } SubSCutsceneType;
 
-//! TODO: rename based on func_8013E748 and func_800B8500
-typedef s32 (*func_8013E748_VerifyFunc)(struct PlayState*, Actor*, void*);
+typedef s32 (*VerifyTalkExchangeActorFunc)(struct PlayState*, Actor*, void*);
 
-typedef s32 (*VerifyActor)(struct PlayState*, Actor*, Actor*, void*);
+typedef s32 (*VerifyFindActorFunc)(struct PlayState*, Actor*, Actor*, void*);
 
 #define SUBS_SHADOW_TEX_WIDTH 64
 #define SUBS_SHADOW_TEX_HEIGHT 64
@@ -91,7 +106,7 @@ s32 SubS_InCsMode(struct PlayState* play);
 
 s32 SubS_UpdateLimb(s16 newRotZ, s16 newRotY, Vec3f* pos, Vec3s* rot, s32 stepRot, s32 overrideRot);
 
-void SubS_UpdateFlags(u16* flags, u16 setBits, u16 unsetBits);
+void SubS_SetOfferMode(u16* flags, u16 offerMode, u16 mask);
 
 void SubS_TimePathing_FillKnots(f32 knots[], s32 order, s32 numPoints);
 s32 SubS_TimePathing_ComputeProgress(f32* progress, s32 elapsedTime, s32 waypointTime, s32 totalTime, s32 pathCount, s32 order, f32 knots[]);
@@ -115,7 +130,7 @@ s32 SubS_WeightPathing_Move(Actor* actor, Path* path, s32* waypoint, f32* progre
 
 s32 SubS_CopyPointFromPathCheckBounds(Path* path, s32 pointIndex, Vec3f* dst);
 
-s32 func_8013C964(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 itemId, s32 type);
+s32 SubS_Offer(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 itemId, SubSOfferMode mode);
 
 void SubS_FillShadowTex(s32 startCol, s32 startRow, u8* tex, s32 size);
 void SubS_GenShadowTex(Vec3f bodyPartsPos[], Vec3f* worldPos, u8* tex, f32 tween, u8 bodyPartsNum, u8 sizes[], s8 parentBodyParts[]);
@@ -159,11 +174,11 @@ s32 SubS_FillCutscenesList(Actor* actor, s16 csIdList[], s16 numCutscenes);
 void SubS_ConstructPlane(Vec3f* point, Vec3f* unitVec, Vec3s* rot, Plane* plane);
 s32 SubS_LineSegVsPlane(Vec3f* point, Vec3s* rot, Vec3f* unitVec, Vec3f* linePointA, Vec3f* linePointB, Vec3f* intersect);
 
-Actor* SubS_FindActorCustom(struct PlayState* play, Actor* actor, Actor* actorListStart, u8 actorCategory, s16 actorId, void* verifyData, VerifyActor verifyActor);
+Actor* SubS_FindActorCustom(struct PlayState* play, Actor* actor, Actor* actorListStart, u8 actorCategory, s16 actorId, void* verifyData, VerifyFindActorFunc verifyActorFunc);
 
-s32 func_8013E748(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 exchangeItemId, void* data, func_8013E748_VerifyFunc verifyFunc);
+s32 SubS_OfferTalkExchangeCustom(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 exchangeItemAction, void* data, VerifyTalkExchangeActorFunc verifyActorFunc);
 s32 SubS_ActorAndPlayerFaceEachOther(struct PlayState* play, Actor* actor, void* data);
-s32 func_8013E8F8(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 exhangeItemId, s16 playerYawTol, s16 actorYawTol);
+s32 SubS_OfferTalkExchangeFacing(Actor* actor, struct PlayState* play, f32 xzRange, f32 yRange, s32 exchangeItemAction, s16 playerYawRange, s16 actorYawRange);
 
 s32 SubS_TrackPointStep(Vec3f* worldPos, Vec3f* focusPos, s16 shapeYRot, Vec3f* yawTarget, Vec3f* pitchTarget, s16* headZRotStep, s16* headXRotStep, s16* torsoZRotStep, s16* torsoXRotStep, u16 headZRotStepMax, u16 headXRotStepMax, u16 torsoZRotStepMax, u16 torsoXRotStepMax);