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

src/code/z_actor.c

@@ -1878,14 +1878,38 @@ s32 Actor_ProcessTalkRequest(Actor* actor, GameState* gameState) {
     return false;
 }
 
-// Actor_OfferTalk / Actor_OfferGetItemExchange? Seems to be called with PLAYER_IA_MINUS1 if the same actor used
-// Actor_OfferGetItem.
-// This function is also used to toggle the "Speak" action on the A button
-s32 func_800B8500(Actor* actor, PlayState* play, f32 xzRange, f32 yRange, PlayerItemAction exchangeItemId) {
+/**
+ * This function covers offering the ability to `Talk` with the player.
+ * Passing an exchangeItemAction (see `PlayerItemAction`) allows the player to also use the item to initiate the
+ * conversation.
+ *
+ * This function carries a talk exchange request to the player actor if context allows it (e.g. the player is in range
+ * and not busy with certain things). The player actor performs the requested action itself.
+ *
+ * The following description of what the `exchangeItemAction` values can do is provided here for completeness, but these
+ * behaviors are entirely out of the scope of this function. All behavior is defined by the player actor.
+ *
+ * - Positive values (`PLAYER_IA_NONE < exchangeItemAction < PLAYER_IA_MAX`):
+ *    Offers the ability to initiate the conversation with an item from the player.
+ *    Not all positive values are implemented properly for this to work.
+ *    Working ones are PLAYER_IA_PICTO_BOX and PLAYER_IA_BOTTLE_MIN <= exchangeItemAction < PLAYER_IA_MASK_MIN
+ *    Note: While PLAYER_IA_BEANS works, it is special cased to just plant the bean with no talking.
+ * - `PLAYER_IA_NONE`:
+ *    Allows the player to speak to or check the actor (by pressing A).
+ * - `PLAYER_IA_MINUS1`:
+ *    Used by actors/player to continue the current conversation after a textbox is closed.
+ *
+ * @return true If the player actor is capable of accepting the offer.
+ *
+ * Note: There is only one instance of using this for actually using an item to start the conversation with the player.
+ * Every other instance is to either offer to speak, or continue the current conversation.
+ */
+s32 Actor_OfferTalkExchange(Actor* actor, PlayState* play, f32 xzRange, f32 yRange,
+                            PlayerItemAction exchangeItemAction) {
     Player* player = GET_PLAYER(play);
 
     if ((player->actor.flags & ACTOR_FLAG_TALK_REQUESTED) ||
-        ((exchangeItemId > PLAYER_IA_NONE) && Player_InCsMode(play)) ||
+        ((exchangeItemAction > PLAYER_IA_NONE) && Player_InCsMode(play)) ||
         (!actor->isTargeted &&
          ((fabsf(actor->playerHeightRel) > fabsf(yRange)) || (actor->xzDistToPlayer > player->talkActorDistance) ||
           (xzRange < actor->xzDistToPlayer)))) {
@@ -1894,24 +1918,35 @@ s32 func_800B8500(Actor* actor, PlayState* play, f32 xzRange, f32 yRange, Player
 
     player->talkActor = actor;
     player->talkActorDistance = actor->xzDistToPlayer;
-    player->exchangeItemId = exchangeItemId;
+    player->exchangeItemAction = exchangeItemAction;
 
     CutsceneManager_Queue(CS_ID_GLOBAL_TALK);
     return true;
 }
 
-s32 func_800B85E0(Actor* actor, PlayState* play, f32 radius, PlayerItemAction exchangeItemId) {
-    return func_800B8500(actor, play, radius, radius, exchangeItemId);
+/**
+ * Offers a talk exchange request within an equilateral cylinder with the radius specified.
+ */
+s32 Actor_OfferTalkExchangeEquiCylinder(Actor* actor, PlayState* play, f32 radius,
+                                        PlayerItemAction exchangeItemAction) {
+    return Actor_OfferTalkExchange(actor, play, radius, radius, exchangeItemAction);
 }
 
-s32 func_800B8614(Actor* actor, PlayState* play, f32 radius) {
-    return func_800B85E0(actor, play, radius, PLAYER_IA_NONE);
+/**
+ * Offers a talk request within an equilateral cylinder with the radius specified.
+ */
+s32 Actor_OfferTalk(Actor* actor, PlayState* play, f32 radius) {
+    return Actor_OfferTalkExchangeEquiCylinder(actor, play, radius, PLAYER_IA_NONE);
 }
 
-s32 func_800B863C(Actor* actor, PlayState* play) {
+/**
+ * Offers a talk request within an equilateral cylinder whose radius is determined by the actor's collision check
+ * cylinder's radius.
+ */
+s32 Actor_OfferTalkNearColChkInfoCylinder(Actor* actor, PlayState* play) {
     f32 cylRadius = actor->colChkInfo.cylRadius + 50.0f;
 
-    return func_800B8614(actor, play, cylRadius);
+    return Actor_OfferTalk(actor, play, cylRadius);
 }
 
 s32 Actor_TextboxIsClosing(Actor* actor, PlayState* play) {
@@ -1942,10 +1977,10 @@ s32 Actor_ChangeFocus(Actor* actor1, PlayState* play, Actor* actor2) {
     return false;
 }
 
-PlayerItemAction Player_GetExchangeItemId(PlayState* play) {
+PlayerItemAction Player_GetExchangeItemAction(PlayState* play) {
     Player* player = GET_PLAYER(play);
 
-    return player->exchangeItemId;
+    return player->exchangeItemAction;
 }
 
 s32 func_800B8718(Actor* actor, GameState* gameState) {
@@ -1957,7 +1992,7 @@ s32 func_800B8718(Actor* actor, GameState* gameState) {
     return false;
 }
 
-// Similar to func_800B8500
+// Similar to Actor_OfferTalkExchange
 s32 func_800B874C(Actor* actor, PlayState* play, f32 xzRange, f32 yRange) {
     Player* player = GET_PLAYER(play);
 
@@ -4127,7 +4162,7 @@ s32 Npc_UpdateTalking(PlayState* play, Actor* actor, s16* talkState, f32 interac
         return false;
     }
 
-    if (!func_800B8614(actor, play, interactRange)) {
+    if (!Actor_OfferTalk(actor, play, interactRange)) {
         return false;
     }