Document field player functions

13 files changed, 57 insertions, 56 deletions

diff --git a/berry_fix/payload/include/global.fieldmap.h b/berry_fix/payload/include/global.fieldmap.h
index d5ab0812e..e7150b429 100644
--- a/berry_fix/payload/include/global.fieldmap.h
+++ b/berry_fix/payload/include/global.fieldmap.h
@@ -219,14 +219,14 @@ struct EventObjectGraphicsInfo
     /*0x20*/ const union AffineAnimCmd *const *affineAnims;
 };
 
-#define PLAYER_AVATAR_FLAG_ON_FOOT    (1 << 0)
-#define PLAYER_AVATAR_FLAG_MACH_BIKE  (1 << 1)
-#define PLAYER_AVATAR_FLAG_ACRO_BIKE  (1 << 2)
-#define PLAYER_AVATAR_FLAG_SURFING    (1 << 3)
-#define PLAYER_AVATAR_FLAG_UNDERWATER (1 << 4)
-#define PLAYER_AVATAR_FLAG_5          (1 << 5)
-#define PLAYER_AVATAR_FLAG_6          (1 << 6)
-#define PLAYER_AVATAR_FLAG_DASH       (1 << 7)
+#define PLAYER_AVATAR_FLAG_ON_FOOT      (1 << 0)
+#define PLAYER_AVATAR_FLAG_MACH_BIKE    (1 << 1)
+#define PLAYER_AVATAR_FLAG_ACRO_BIKE    (1 << 2)
+#define PLAYER_AVATAR_FLAG_SURFING      (1 << 3)
+#define PLAYER_AVATAR_FLAG_UNDERWATER   (1 << 4)
+#define PLAYER_AVATAR_FLAG_CONTROLLABLE (1 << 5)
+#define PLAYER_AVATAR_FLAG_FORCED_MOVE  (1 << 6)
+#define PLAYER_AVATAR_FLAG_DASH         (1 << 7)
 
 enum
 {
diff --git a/include/field_player_avatar.h b/include/field_player_avatar.h
index 903fe6ef1..e9174d589 100644
--- a/include/field_player_avatar.h
+++ b/include/field_player_avatar.h
@@ -32,10 +32,10 @@ void PlayerOnBikeCollideWithFarawayIslandMew(u8 direction);
 u8 CheckForObjectEventCollision(struct ObjectEvent *a, s16 b, s16 c, u8 d, u8 e);
 u8 PlayerGetZCoord(void);
 void SetPlayerAvatarTransitionFlags(u16 a);
-void sub_808BCE8(void);
+void CancelPlayerForcedMovement(void);
 void InitPlayerAvatar(s16 a, s16 b, u8 c, u8 d);
 void PlayerFreeze(void);
-void sub_808BCF4(void);
+void StopPlayerAvatar(void);
 void SetSpinStartFacingDir(u8);
 void GetXYCoordsOneStepInFrontOfPlayer(s16 *xPtr, s16 *yPtr);
 u8 GetRivalAvatarGraphicsIdByStateIdAndGender(u8, u8);
diff --git a/include/global.fieldmap.h b/include/global.fieldmap.h
index 5d788ddf7..71ccd7068 100644
--- a/include/global.fieldmap.h
+++ b/include/global.fieldmap.h
@@ -246,14 +246,14 @@ enum {
     PLAYER_AVATAR_STATE_WATERING,
 };
 
-#define PLAYER_AVATAR_FLAG_ON_FOOT     (1 << 0)
-#define PLAYER_AVATAR_FLAG_MACH_BIKE   (1 << 1)
-#define PLAYER_AVATAR_FLAG_ACRO_BIKE   (1 << 2)
-#define PLAYER_AVATAR_FLAG_SURFING     (1 << 3)
-#define PLAYER_AVATAR_FLAG_UNDERWATER  (1 << 4)
-#define PLAYER_AVATAR_FLAG_5           (1 << 5)
-#define PLAYER_AVATAR_FLAG_FORCED_MOVE (1 << 6)
-#define PLAYER_AVATAR_FLAG_DASH        (1 << 7)
+#define PLAYER_AVATAR_FLAG_ON_FOOT      (1 << 0)
+#define PLAYER_AVATAR_FLAG_MACH_BIKE    (1 << 1)
+#define PLAYER_AVATAR_FLAG_ACRO_BIKE    (1 << 2)
+#define PLAYER_AVATAR_FLAG_SURFING      (1 << 3)
+#define PLAYER_AVATAR_FLAG_UNDERWATER   (1 << 4)
+#define PLAYER_AVATAR_FLAG_CONTROLLABLE (1 << 5)
+#define PLAYER_AVATAR_FLAG_FORCED_MOVE  (1 << 6)
+#define PLAYER_AVATAR_FLAG_DASH         (1 << 7)
 
 enum
 {
diff --git a/src/apprentice.c b/src/apprentice.c
index f881c3bef..5d1c4287b 100644
--- a/src/apprentice.c
+++ b/src/apprentice.c
@@ -911,7 +911,7 @@ static void Script_PrintApprenticeMessage(void)
     ScriptContext2_Enable();
     FreezeObjectEvents();
     PlayerFreeze();
-    sub_808BCF4();
+    StopPlayerAvatar();
     DrawDialogueFrame(0, 1);
     PrintApprenticeMessage();
 }
diff --git a/src/battle_setup.c b/src/battle_setup.c
index 2a716e08c..90c004b55 100644
--- a/src/battle_setup.c
+++ b/src/battle_setup.c
@@ -399,7 +399,7 @@ static void DoStandardWildBattle(void)
 {
     ScriptContext2_Enable();
     FreezeObjectEvents();
-    sub_808BCF4();
+    StopPlayerAvatar();
     gMain.savedCallback = CB2_EndWildBattle;
     gBattleTypeFlags = 0;
     if (InBattlePyramid())
@@ -418,7 +418,7 @@ void BattleSetup_StartRoamerBattle(void)
 {
     ScriptContext2_Enable();
     FreezeObjectEvents();
-    sub_808BCF4();
+    StopPlayerAvatar();
     gMain.savedCallback = CB2_EndWildBattle;
     gBattleTypeFlags = BATTLE_TYPE_ROAMER;
     CreateBattleStartTask(GetWildBattleTransition(), 0);
@@ -432,7 +432,7 @@ static void DoSafariBattle(void)
 {
     ScriptContext2_Enable();
     FreezeObjectEvents();
-    sub_808BCF4();
+    StopPlayerAvatar();
     gMain.savedCallback = CB2_EndSafariBattle;
     gBattleTypeFlags = BATTLE_TYPE_SAFARI;
     CreateBattleStartTask(GetWildBattleTransition(), 0);
@@ -442,7 +442,7 @@ static void DoBattlePikeWildBattle(void)
 {
     ScriptContext2_Enable();
     FreezeObjectEvents();
-    sub_808BCF4();
+    StopPlayerAvatar();
     gMain.savedCallback = CB2_EndWildBattle;
     gBattleTypeFlags = BATTLE_TYPE_PIKE;
     CreateBattleStartTask(GetWildBattleTransition(), 0);
diff --git a/src/event_object_lock.c b/src/event_object_lock.c
index 179c72813..29575111f 100644
--- a/src/event_object_lock.c
+++ b/src/event_object_lock.c
@@ -34,7 +34,7 @@ bool8 IsFreezePlayerFinished(void)
     }
     else
     {
-        sub_808BCF4();
+        StopPlayerAvatar();
         return TRUE;
     }
 }
@@ -77,7 +77,7 @@ bool8 IsFreezeSelectedObjectAndPlayerFinished(void)
     }
     else
     {
-        sub_808BCF4();
+        StopPlayerAvatar();
         return TRUE;
     }
 }
@@ -198,7 +198,7 @@ bool8 IsFreezeObjectAndPlayerFinished(void)
     }
     else
     {
-        sub_808BCF4();
+        StopPlayerAvatar();
         return TRUE;
     }
 }
diff --git a/src/event_object_movement.c b/src/event_object_movement.c
index 2f7cb9e7a..2616b65e8 100644
--- a/src/event_object_movement.c
+++ b/src/event_object_movement.c
@@ -1770,7 +1770,7 @@ static void SetPlayerAvatarObjectEventIdAndObjectId(u8 objectEventId, u8 spriteI
     gPlayerAvatar.objectEventId = objectEventId;
     gPlayerAvatar.spriteId = spriteId;
     gPlayerAvatar.gender = GetPlayerAvatarGenderByGraphicsId(gObjectEvents[objectEventId].graphicsId);
-    SetPlayerAvatarExtraStateTransition(gObjectEvents[objectEventId].graphicsId, PLAYER_AVATAR_FLAG_5);
+    SetPlayerAvatarExtraStateTransition(gObjectEvents[objectEventId].graphicsId, PLAYER_AVATAR_FLAG_CONTROLLABLE);
 }
 
 void ObjectEventSetGraphicsId(struct ObjectEvent *objectEvent, u8 graphicsId)
diff --git a/src/field_effect.c b/src/field_effect.c
index 88f8065d3..247744b87 100644
--- a/src/field_effect.c
+++ b/src/field_effect.c
@@ -3051,7 +3051,7 @@ static void SurfFieldEffect_End(struct Task *task)
     if (ObjectEventClearHeldMovementIfFinished(objectEvent))
     {
         gPlayerAvatar.preventStep = FALSE;
-        gPlayerAvatar.flags &= ~PLAYER_AVATAR_FLAG_5;
+        gPlayerAvatar.flags &= ~PLAYER_AVATAR_FLAG_CONTROLLABLE;
         ObjectEventSetHeldMovement(objectEvent, GetFaceDirectionMovementAction(objectEvent->movementDirection));
         SetSurfBlob_BobState(objectEvent->fieldEffectSpriteId, BOB_PLAYER_AND_MON);
         UnfreezeObjectEvents();
diff --git a/src/field_player_avatar.c b/src/field_player_avatar.c
index 276fb44b2..158248d17 100644
--- a/src/field_player_avatar.c
+++ b/src/field_player_avatar.c
@@ -69,8 +69,8 @@ static void PlayerNotOnBikeNotMoving(u8, u16);
 static void PlayerNotOnBikeTurningInPlace(u8, u16);
 static void PlayerNotOnBikeMoving(u8, u16);
 static u8 CheckForPlayerAvatarCollision(u8);
-static u8 sub_808B028(u8);
-static u8 sub_808B164(struct ObjectEvent *, s16, s16, u8, u8);
+static u8 CheckForPlayerAvatarSomeCollision(u8);
+static u8 CheckForObjectEventSomeCollision(struct ObjectEvent *, s16, s16, u8, u8);
 static bool8 CanStopSurfing(s16, s16, u8);
 static bool8 ShouldJumpLedge(s16, s16, u8);
 static bool8 TryPushBoulder(s16, s16, u8);
@@ -85,8 +85,8 @@ static void PlayerAvatarTransition_Surfing(struct ObjectEvent *a);
 static void PlayerAvatarTransition_Underwater(struct ObjectEvent *a);
 static void PlayerAvatarTransition_ReturnToField(struct ObjectEvent *a);
 
-static bool8 player_is_anim_in_certain_ranges(void);
-static bool8 sub_808B618(void);
+static bool8 PlayerAnimIsMultiFrameStationary(void);
+static bool8 PlayerAnimIsMultiFrameStationaryAndStateNotTurning(void);
 static bool8 PlayerIsAnimActive(void);
 static bool8 PlayerCheckIfAnimFinishedOrInactive(void);
 
@@ -187,7 +187,7 @@ static bool8 (*const sForcedMovementFuncs[])(void) =
     ForcedMovement_MuddySlope,
 };
 
-static void (*const gUnknown_08497490[])(u8, u16) =
+static void (*const sPlayerNotOnBikeFuncs[])(u8, u16) =
 {
     PlayerNotOnBikeNotMoving,
     PlayerNotOnBikeTurningInPlace,
@@ -359,7 +359,7 @@ static bool8 TryInterruptObjectEventSpecialAnim(struct ObjectEvent *playerObjEve
                 return FALSE;
             }
 
-            if (!sub_808B028(direction))
+            if (CheckForPlayerAvatarSomeCollision(direction) == COLLISION_NONE)
             {
                 ObjectEventClearHeldMovement(playerObjEvent);
                 return FALSE;
@@ -391,7 +391,7 @@ static void MovePlayerAvatarUsingKeypadInput(u8 direction, u16 newKeys, u16 held
 static void PlayerAllowForcedMovementIfMovingSameDirection(void)
 {
     if (gPlayerAvatar.runningState == MOVING)
-        gPlayerAvatar.flags &= ~PLAYER_AVATAR_FLAG_5;
+        gPlayerAvatar.flags &= ~PLAYER_AVATAR_FLAG_CONTROLLABLE;
 }
 
 static bool8 TryDoMetatileBehaviorForcedMovement(void)
@@ -403,7 +403,7 @@ static u8 GetForcedMovementByMetatileBehavior(void)
 {
     u8 i;
 
-    if (!(gPlayerAvatar.flags & PLAYER_AVATAR_FLAG_5))
+    if (!(gPlayerAvatar.flags & PLAYER_AVATAR_FLAG_CONTROLLABLE))
     {
         u8 metatileBehavior = gObjectEvents[gPlayerAvatar.objectEventId].currentMetatileBehavior;
 
@@ -572,7 +572,7 @@ static bool8 ForcedMovement_MuddySlope(void)
 
 static void MovePlayerNotOnBike(u8 direction, u16 heldKeys)
 {
-    gUnknown_08497490[CheckMovementInputNotOnBike(direction)](direction, heldKeys);
+    sPlayerNotOnBikeFuncs[CheckMovementInputNotOnBike(direction)](direction, heldKeys);
 }
 
 static u8 CheckMovementInputNotOnBike(u8 direction)
@@ -660,7 +660,7 @@ static u8 CheckForPlayerAvatarCollision(u8 direction)
     return CheckForObjectEventCollision(playerObjEvent, x, y, direction, MapGridGetMetatileBehaviorAt(x, y));
 }
 
-static u8 sub_808B028(u8 direction)
+static u8 CheckForPlayerAvatarSomeCollision(u8 direction)
 {
     s16 x, y;
     struct ObjectEvent *playerObjEvent = &gObjectEvents[gPlayerAvatar.objectEventId];
@@ -668,7 +668,7 @@ static u8 sub_808B028(u8 direction)
     x = playerObjEvent->currentCoords.x;
     y = playerObjEvent->currentCoords.y;
     MoveCoords(direction, &x, &y);
-    return sub_808B164(playerObjEvent, x, y, direction, MapGridGetMetatileBehaviorAt(x, y));
+    return CheckForObjectEventSomeCollision(playerObjEvent, x, y, direction, MapGridGetMetatileBehaviorAt(x, y));
 }
 
 u8 CheckForObjectEventCollision(struct ObjectEvent *objectEvent, s16 x, s16 y, u8 direction, u8 metatileBehavior)
@@ -694,7 +694,7 @@ u8 CheckForObjectEventCollision(struct ObjectEvent *objectEvent, s16 x, s16 y, u
     return collision;
 }
 
-static u8 sub_808B164(struct ObjectEvent *objectEvent, s16 x, s16 y, u8 direction, u8 metatileBehavior)
+static u8 CheckForObjectEventSomeCollision(struct ObjectEvent *objectEvent, s16 x, s16 y, u8 direction, u8 metatileBehavior)
 {
     u8 collision = GetCollisionAtCoords(objectEvent, x, y, direction);
 
@@ -876,7 +876,7 @@ static void PlayerAvatarTransition_Underwater(struct ObjectEvent *objEvent)
 
 static void PlayerAvatarTransition_ReturnToField(struct ObjectEvent *objEvent)
 {
-    gPlayerAvatar.flags |= PLAYER_AVATAR_FLAG_5;
+    gPlayerAvatar.flags |= PLAYER_AVATAR_FLAG_CONTROLLABLE;
 }
 
 void UpdatePlayerAvatarTransitionState(void)
@@ -886,18 +886,18 @@ void UpdatePlayerAvatarTransitionState(void)
     {
         if (!PlayerCheckIfAnimFinishedOrInactive())
         {
-            if (!player_is_anim_in_certain_ranges())
+            if (!PlayerAnimIsMultiFrameStationary())
                 gPlayerAvatar.tileTransitionState = T_TILE_TRANSITION;
         }
         else
         {
-            if (!sub_808B618())
+            if (!PlayerAnimIsMultiFrameStationaryAndStateNotTurning())
                 gPlayerAvatar.tileTransitionState = T_TILE_CENTER;
         }
     }
 }
 
-static bool8 player_is_anim_in_certain_ranges(void)
+static bool8 PlayerAnimIsMultiFrameStationary(void)
 {
     u8 movementActionId = gObjectEvents[gPlayerAvatar.objectEventId].movementActionId;
 
@@ -911,9 +911,9 @@ static bool8 player_is_anim_in_certain_ranges(void)
         return FALSE;
 }
 
-static bool8 sub_808B618(void)
+static bool8 PlayerAnimIsMultiFrameStationaryAndStateNotTurning(void)
 {
-    if (player_is_anim_in_certain_ranges() && gPlayerAvatar.runningState != TURN_DIRECTION)
+    if (PlayerAnimIsMultiFrameStationary() && gPlayerAvatar.runningState != TURN_DIRECTION)
         return TRUE;
     else
         return FALSE;
@@ -1177,7 +1177,8 @@ u8 PlayerGetZCoord(void)
     return gObjectEvents[gPlayerAvatar.objectEventId].previousElevation;
 }
 
-void sub_808BC90(s16 x, s16 y)
+// unused
+void MovePlayerToMapCoords(s16 x, s16 y)
 {
     MoveObjectEventToMapCoords(&gObjectEvents[gPlayerAvatar.objectEventId], x, y);
 }
@@ -1197,12 +1198,12 @@ u8 GetPlayerAvatarSpriteId(void)
     return gPlayerAvatar.spriteId;
 }
 
-void sub_808BCE8(void)
+void CancelPlayerForcedMovement(void)
 {
     ForcedMovement_None();
 }
 
-void sub_808BCF4(void)
+void StopPlayerAvatar(void)
 {
     struct ObjectEvent *playerObjEvent = &gObjectEvents[gPlayerAvatar.objectEventId];
 
@@ -1323,7 +1324,7 @@ void ClearPlayerAvatarInfo(void)
 
 void SetPlayerAvatarStateMask(u8 flags)
 {
-    gPlayerAvatar.flags &= (PLAYER_AVATAR_FLAG_DASH | PLAYER_AVATAR_FLAG_FORCED_MOVE | PLAYER_AVATAR_FLAG_5);
+    gPlayerAvatar.flags &= (PLAYER_AVATAR_FLAG_DASH | PLAYER_AVATAR_FLAG_FORCED_MOVE | PLAYER_AVATAR_FLAG_CONTROLLABLE);
     gPlayerAvatar.flags |= flags;
 }
 
@@ -1389,7 +1390,7 @@ void InitPlayerAvatar(s16 x, s16 y, u8 direction, u8 gender)
     gPlayerAvatar.objectEventId = objectEventId;
     gPlayerAvatar.spriteId = objectEvent->spriteId;
     gPlayerAvatar.gender = gender;
-    SetPlayerAvatarStateMask(PLAYER_AVATAR_FLAG_5 | PLAYER_AVATAR_FLAG_ON_FOOT);
+    SetPlayerAvatarStateMask(PLAYER_AVATAR_FLAG_CONTROLLABLE | PLAYER_AVATAR_FLAG_ON_FOOT);
 }
 
 void SetPlayerInvisibility(bool8 invisible)
@@ -1542,7 +1543,7 @@ static u8 PlayerAvatar_DoSecretBaseMatJump(struct Task *task, struct ObjectEvent
         if (task->data[1] > 1)
         {
             gPlayerAvatar.preventStep = FALSE;
-            gPlayerAvatar.transitionFlags |= PLAYER_AVATAR_FLAG_5;
+            gPlayerAvatar.transitionFlags |= PLAYER_AVATAR_FLAG_CONTROLLABLE;
             DestroyTask(FindTaskIdByFunc(DoPlayerAvatarSecretBaseMatJump));
         }
     }
diff --git a/src/item_menu.c b/src/item_menu.c
index 8ada7ff62..53f478a31 100755
--- a/src/item_menu.c
+++ b/src/item_menu.c
@@ -2047,7 +2047,7 @@ bool8 UseRegisteredKeyItemOnField(void)
             ScriptContext2_Enable();
             FreezeObjectEvents();
             PlayerFreeze();
-            sub_808BCF4();
+            StopPlayerAvatar();
             gSpecialVar_ItemId = gSaveBlock1Ptr->registeredItem;
             taskId = CreateTask(ItemId_GetFieldFunc(gSaveBlock1Ptr->registeredItem), 8);
             gTasks[taskId].tUsingRegisteredKeyItem = TRUE;
diff --git a/src/match_call.c b/src/match_call.c
index b71fc8322..d6bc5126e 100644
--- a/src/match_call.c
+++ b/src/match_call.c
@@ -1180,7 +1180,7 @@ static void StartMatchCall(void)
         ScriptContext2_Enable();
         FreezeObjectEvents();
         PlayerFreeze();
-        sub_808BCF4();
+        StopPlayerAvatar();
     }
 
     PlaySE(SE_POKENAV_CALL);
diff --git a/src/start_menu.c b/src/start_menu.c
index 9f271b890..59279d6b9 100644
--- a/src/start_menu.c
+++ b/src/start_menu.c
@@ -558,7 +558,7 @@ void ShowStartMenu(void)
     {
         FreezeObjectEvents();
         PlayerFreeze();
-        sub_808BCF4();
+        StopPlayerAvatar();
     }
     CreateStartMenuTask(Task_ShowStartMenu);
     ScriptContext2_Enable();
diff --git a/src/trainer_see.c b/src/trainer_see.c
index ec3dc8123..ce06c5e9c 100644
--- a/src/trainer_see.c
+++ b/src/trainer_see.c
@@ -523,7 +523,7 @@ static bool8 PlayerFaceApproachingTrainer(u8 taskId, struct Task *task, struct O
     if (ObjectEventIsMovementOverridden(playerObj) && !ObjectEventClearHeldMovementIfFinished(playerObj))
         return FALSE;
 
-    sub_808BCE8();
+    CancelPlayerForcedMovement();
     ObjectEventSetHeldMovement(&gObjectEvents[gPlayerAvatar.objectEventId], GetFaceDirectionMovementAction(GetOppositeDirection(trainerObj->facingDirection)));
     task->tFuncId++; // TRSEE_PLAYER_FACE_WAIT
     return FALSE;