Rename `ANIM_FLAG_NO_MOVE` to `ANIM_FLAG_ADJUST_STARTING_POS` (#1981)

* rename flag and draft 1 of comment

* draft 2

* tweak wording

* format

* format

1 files changed, 21 insertions, 1 deletions

diff --git a/include/z64animation.h b/include/z64animation.h
index 2365db14b..782380ad2 100644
--- a/include/z64animation.h
+++ b/include/z64animation.h
@@ -112,8 +112,28 @@ typedef enum {
 // (player-only) Call AnimTaskQueue_AddActorMove
 #define ANIM_FLAG_PLAYER_SETMOVE (1 << 3)
 
+// When this flag is set, movement in all axes will not be applied for one frame. The flag
+// is unset automatically after one use, so movement can resume. The intent is for this flag to be used
+// when changing between two different animations.
+// In some contexts, disabling the first frame of movement is necessary for a seamless transition.
 //
-#define ANIM_FLAG_NO_MOVE (1 << 4)
+// Depending on specific implementations, an actor may choose to reset `prevTransl` to `baseTransl` when
+// starting a new animation. This is helpful when an animation's translation data starts at the "origin"
+// (in this case, the origin refers to `baseTransl`, in model space).
+// Some animations have translation data that does not begin at the "origin". This is common when a
+// longer sequence of animation is broken up into different parts as seperate animations.
+// In this case, when one animation starts its translation at the same position where a different animation
+// left off, resetting `prevTransl` is not desireable. This will cause the actor's position to noticeably change
+// when the translation data from the first frame of the new animation is applied.
+//
+// When this flag is used during a transition between two animations, the first frame of movement is not applied.
+// This allows the actor's world postiion to stay at the same location as where the previous animation ended.
+// Because translations are calculated as a difference from the current and previous frame, all subsequent
+// frames have their translation occur relative to this new starting point.
+//
+// Note that for Player, this flag is only relevant when transitioning from an animation that was also using
+// animation translation. This is because of how `prevTransl` gets reset in `Player_AnimReplaceApplyFlags`.
+#define ANIM_FLAG_ADJUST_STARTING_POS (1 << 4)
 
 // Disables "normal" movement from sources like speed/velocity and collisions, which allows the
 // animation to have full control over the actor's movement.