Player Docs: First 8 Start Modes (#1749)

* start mode docs

* better comments

* improve owl docs

* reorder comment to more important first

* brief comment

include/z64player.h

@@ -17,14 +17,14 @@ struct PlayState;
 #define PLAYER_GET_START_MODE(thisx) (((thisx)->params & 0xF00) >> 8)
 
 typedef enum PlayerStartMode {
-    /*  0x0 */ PLAYER_START_MODE_0,
+    /*  0x0 */ PLAYER_START_MODE_NOTHING, // Update is empty and draw function is NULL, nothing occurs. Useful in cutscenes, for example.
-    /*  0x1 */ PLAYER_START_MODE_1, // Spawning after pulling/putting-back Master sword // OoT leftover
+    /*  0x1 */ PLAYER_START_MODE_TIME_TRAVEL, // OoT Leftover. Arriving from time travel. Automatically adjusts by age.
-    /*  0x2 */ PLAYER_START_MODE_2,
+    /*  0x2 */ PLAYER_START_MODE_BLUE_WARP, // Arriving from a blue warp.
-    /*  0x3 */ PLAYER_START_MODE_3,
+    /*  0x3 */ PLAYER_START_MODE_DOOR, // Unused. Use a door immediately if one is nearby. If no door is in usable range, a softlock occurs.
-    /*  0x4 */ PLAYER_START_MODE_4,
+    /*  0x4 */ PLAYER_START_MODE_GROTTO, // Arriving from a grotto, launched upward from the ground.
-    /*  0x5 */ PLAYER_START_MODE_5,
+    /*  0x5 */ PLAYER_START_MODE_WARP_SONG, // OoT Leftover. Arriving from a warp song.
-    /*  0x6 */ PLAYER_START_MODE_6,
+    /*  0x6 */ PLAYER_START_MODE_OWL, // Arriving from an Owl Save or Song of Soaring (both overworld and dungeon warps).
-    /*  0x7 */ PLAYER_START_MODE_7,
+    /*  0x7 */ PLAYER_START_MODE_KNOCKED_OVER, // Knocked over on the ground and flashing red.
     /*  0x8 */ PLAYER_START_MODE_8,
     /*  0x9 */ PLAYER_START_MODE_9,
     /*  0xA */ PLAYER_START_MODE_A,
@@ -33,7 +33,7 @@ typedef enum PlayerStartMode {
     /*  0xD */ PLAYER_START_MODE_D,
     /*  0xE */ PLAYER_START_MODE_E,
     /*  0xF */ PLAYER_START_MODE_F,
-    /* 0x10 */ PLAYER_START_MODE_MAX // Must not exceed 0x10 as `PLAYER_GET_START_MODE` is limited to a nibble in player params
+    /* 0x10 */ PLAYER_START_MODE_MAX // Note: By default, this param has 4 bits allocated. The max value is 16.
 } PlayerStartMode;
 
 #define PLAYER_PARAMS(startBgCamIndex, startMode) ((startBgCamIndex & 0xFF) | ((startMode & 0xF) << 8))
@@ -623,8 +623,8 @@ typedef struct PlayerAgeProperties {
     /* 0x98 */ f32 unk_98;
     /* 0x9C */ f32 unk_9C;
     /* 0xA0 */ PlayerAnimationHeader* openChestAnim;
-    /* 0xA4 */ PlayerAnimationHeader* unk_A4; // OoT leftovers to interact with the Master Sword
+    /* 0xA4 */ PlayerAnimationHeader* timeTravelStartAnim; // OoT leftovers to interact with the Master Sword
-    /* 0xA8 */ PlayerAnimationHeader* unk_A8; // OoT leftovers to interact with the Master Sword
+    /* 0xA8 */ PlayerAnimationHeader* timeTravelEndAnim; // OoT leftovers to interact with the Master Sword
     /* 0xAC */ PlayerAnimationHeader* unk_AC;
     /* 0xB0 */ PlayerAnimationHeader* unk_B0;
     /* 0xB4 */ PlayerAnimationHeader* unk_B4[4];
@@ -1261,10 +1261,14 @@ typedef struct Player {
     /* 0xAE3 */ s8 controlStickDirections[4]; // Stores the control stick direction (relative to shape yaw) for the last 4 frames. See `PlayerStickDirection`.
     /* 0xAE7 */ union {
         s8 actionVar1;
+        s8 startedAnim; // Player_Action_TimeTravelEnd: Started playing the animation that was previously frozen
     } av1; // "Action Variable 1": context dependent variable that has different meanings depending on what action is currently running
     /* 0xAE8 */ union {
         s16 actionVar2;
         s16 fallDamageStunTimer; // Player_Action_Idle: Prevents any movement and shakes model up and down quickly to indicate fall damage stun
+        s16 animDelayTimer; // Player_Action_TimeTravelEnd: Delays playing animation until finished counting down
+        s16 csDelayTimer; // Player_Action_WaitForCutscene: Number of frames to wait before responding to a cutscene
+        s16 playedLandingSfx; // Player_Action_BlueWarpArrive: Played sfx when landing on the ground
     } av2; // "Action Variable 2": context dependent variable that has different meanings depending on what action is currently running
     /* 0xAEC */ f32 unk_AEC;
     /* 0xAF0 */ union {
@@ -1380,7 +1384,7 @@ s32 Player_InitOverrideInput(struct PlayState* play, PlayerOverrideInputEntry* i
 s32 Player_UpdateOverrideInput(struct PlayState* play, PlayerOverrideInputEntry* inputEntry, f32 distXZRange);
 void func_80122868(struct PlayState* play, Player* player);
 void func_801229A0(struct PlayState* play, Player* player);
-void func_801229EC(Actor* thisx, struct PlayState* play);
+void Player_DoNothing(Actor* thisx, struct PlayState* play);
 void func_801229FC(Player* player);
 void func_80122BA4(struct PlayState* play, struct_80122D44_arg1* arg1, s32 arg2, s32 alpha);
 void func_80122C20(struct PlayState* play, struct_80122D44_arg1* arg1);

src/code/z_player_lib.c

@@ -155,7 +155,7 @@ void func_801229A0(PlayState* play, Player* player) {
 }
 
 // Update function
-void func_801229EC(Actor* thisx, PlayState* play) {
+void Player_DoNothing(Actor* thisx, PlayState* play) {
 }
 
 s16 sMaskObjectIds[PLAYER_MASK_MAX - 1] = {

src/overlays/actors/ovl_Door_Ana/z_door_ana.c

@@ -141,7 +141,7 @@ void DoorAna_WaitOpen(DoorAna* this, PlayState* play) {
             } else {
                 s32 destinationIdx = DOORANA_GET_ENTRANCE(&this->actor);
 
-                Play_SetupRespawnPoint(play, RESPAWN_MODE_UNK_3, PLAYER_PARAMS(0xFF, PLAYER_START_MODE_4));
+                Play_SetupRespawnPoint(play, RESPAWN_MODE_UNK_3, PLAYER_PARAMS(0xFF, PLAYER_START_MODE_GROTTO));
 
                 gSaveContext.respawn[RESPAWN_MODE_UNK_3].pos.y = this->actor.world.pos.y;
                 gSaveContext.respawn[RESPAWN_MODE_UNK_3].yaw = this->actor.home.rot.y;

src/overlays/actors/ovl_En_Test3/z_en_test3.c

@@ -161,9 +161,9 @@ static PlayerAgeProperties sAgeProperties = {
     29.4343f,
     // openChestAnim
     &gPlayerAnim_clink_demo_Tbox_open,
-    // unk_A4
+    // timeTravelStartAnim
     &gPlayerAnim_clink_demo_goto_future,
-    // unk_A8
+    // timeTravelEndAnim
     &gPlayerAnim_clink_demo_return_to_future,
     // unk_AC
     &gPlayerAnim_clink_normal_climb_startA,

src/overlays/actors/ovl_En_Test7/z_en_test7.c

@@ -662,7 +662,7 @@ void EnTest7_WarpCsWarp(EnTest7* this, PlayState* play) {
     } else if (OWL_WARP_CS_GET_OCARINA_MODE(&this->actor) == OCARINA_MODE_WARP_TO_ENTRANCE) {
         func_80169F78(play);
         gSaveContext.respawn[RESPAWN_MODE_TOP].playerParams =
-            PLAYER_PARAMS(gSaveContext.respawn[RESPAWN_MODE_TOP].playerParams, PLAYER_START_MODE_6);
+            PLAYER_PARAMS(gSaveContext.respawn[RESPAWN_MODE_TOP].playerParams, PLAYER_START_MODE_OWL);
         gSaveContext.respawnFlag = -6;
     } else {
         play->nextEntrance =

src/overlays/actors/ovl_Obj_Mure/z_obj_mure.c

@@ -60,11 +60,11 @@ static s16 sSpawnActorIds[OBJMURE_TYPE_MAX] = {
 };
 
 static s16 sSpawnParams[OBJMURE_TYPE_MAX] = {
-    KUSA_BUSH_PARAMS(false, 0, false),     // OBJMURE_TYPE_GRASS
+    KUSA_BUSH_PARAMS(false, 0, false),           // OBJMURE_TYPE_GRASS
-    PLAYER_PARAMS(2, PLAYER_START_MODE_0), // OBJMURE_TYPE_UNDEFINED
+    PLAYER_PARAMS(2, PLAYER_START_MODE_NOTHING), // OBJMURE_TYPE_UNDEFINED
-    FISH_PARAMS(ENFISH_MINUS1),            // OBJMURE_TYPE_FISH
+    FISH_PARAMS(ENFISH_MINUS1),                  // OBJMURE_TYPE_FISH
-    ENINSECT_PARAMS(false),                // OBJMURE_TYPE_BUGS
+    ENINSECT_PARAMS(false),                      // OBJMURE_TYPE_BUGS
-    BUTTERFLY_PARAMS(BUTTERFLY_MINUS1),    // OBJMURE_TYPE_BUTTERFLY
+    BUTTERFLY_PARAMS(BUTTERFLY_MINUS1),          // OBJMURE_TYPE_BUTTERFLY
 };
 
 static InitChainEntry sInitChain[] = {

src/overlays/actors/ovl_player_actor/z_player.c

@@ -80,6 +80,8 @@ void func_80838A20(PlayState* play, Player* this);
 void func_80839978(PlayState* play, Player* this);
 void func_80839A10(PlayState* play, Player* this);
 
+void func_80859CE0(PlayState* play, Player* this, s32 arg2);
+
 typedef enum AnimSfxType {
     /*  1 */ ANIMSFX_TYPE_GENERAL = 1,
     /*  2 */ ANIMSFX_TYPE_FLOOR,
@@ -113,7 +115,7 @@ typedef struct AnimSfxEntry {
 } AnimSfxEntry;          // size = 0x4
 
 /* action funcs */
-void Player_Action_0(Player* this, PlayState* play);
+void Player_Action_OwlSaveArrive(Player* this, PlayState* play);
 void Player_Action_1(Player* this, PlayState* play);
 void Player_Action_2(Player* this, PlayState* play);
 void Player_Action_3(Player* this, PlayState* play);
@@ -179,7 +181,7 @@ void Player_Action_62(Player* this, PlayState* play);
 void Player_Action_63(Player* this, PlayState* play);
 void Player_Action_64(Player* this, PlayState* play);
 void Player_Action_65(Player* this, PlayState* play);
-void Player_Action_66(Player* this, PlayState* play);
+void Player_Action_TimeTravelEnd(Player* this, PlayState* play);
 void Player_Action_67(Player* this, PlayState* play);
 void Player_Action_68(Player* this, PlayState* play);
 void Player_Action_69(Player* this, PlayState* play);
@@ -187,12 +189,12 @@ void Player_Action_70(Player* this, PlayState* play);
 void Player_Action_ExchangeItem(Player* this, PlayState* play);
 void Player_Action_72(Player* this, PlayState* play);
 void Player_Action_73(Player* this, PlayState* play);
-void Player_Action_74(Player* this, PlayState* play);
+void Player_Action_WaitForCutscene(Player* this, PlayState* play);
-void Player_Action_75(Player* this, PlayState* play);
+void Player_Action_StartWarpSongArrive(Player* this, PlayState* play);
-void Player_Action_76(Player* this, PlayState* play);
+void Player_Action_BlueWarpArrive(Player* this, PlayState* play);
 void Player_Action_77(Player* this, PlayState* play);
-void Player_Action_78(Player* this, PlayState* play);
+void Player_Action_TryOpeningDoor(Player* this, PlayState* play);
-void Player_Action_79(Player* this, PlayState* play);
+void Player_Action_ExitGrotto(Player* this, PlayState* play);
 void Player_Action_80(Player* this, PlayState* play);
 void Player_Action_81(Player* this, PlayState* play);
 void Player_Action_82(Player* this, PlayState* play);
@@ -801,9 +803,9 @@ PlayerAgeProperties sPlayerAgeProperties[PLAYER_FORM_MAX] = {
         44.15145f,
         // openChestAnim
         &gPlayerAnim_link_demo_Tbox_open,
-        // unk_A4
+        // timeTravelStartAnim
         &gPlayerAnim_link_demo_back_to_past,
-        // unk_A8
+        // timeTravelEndAnim
         &gPlayerAnim_link_demo_return_to_past,
         // unk_AC
         &gPlayerAnim_link_normal_climb_startA,
@@ -897,9 +899,9 @@ PlayerAgeProperties sPlayerAgeProperties[PLAYER_FORM_MAX] = {
         42.0f,
         // openChestAnim
         &gPlayerAnim_pg_Tbox_open,
-        // unk_A4
+        // timeTravelStartAnim
         &gPlayerAnim_link_demo_back_to_past,
-        // unk_A8
+        // timeTravelEndAnim
         &gPlayerAnim_link_demo_return_to_past,
         // unk_AC
         &gPlayerAnim_pg_climb_startA,
@@ -993,9 +995,9 @@ PlayerAgeProperties sPlayerAgeProperties[PLAYER_FORM_MAX] = {
         36.0f,
         // openChestAnim
         &gPlayerAnim_pz_Tbox_open,
-        // unk_A4
+        // timeTravelStartAnim
         &gPlayerAnim_link_demo_back_to_past,
-        // unk_A8
+        // timeTravelEndAnim
         &gPlayerAnim_link_demo_return_to_past,
         // unk_AC
         &gPlayerAnim_pz_climb_startA,
@@ -1089,9 +1091,9 @@ PlayerAgeProperties sPlayerAgeProperties[PLAYER_FORM_MAX] = {
         33.0f,
         // openChestAnim
         &gPlayerAnim_pn_Tbox_open,
-        // unk_A4
+        // timeTravelStartAnim
         &gPlayerAnim_link_demo_back_to_past,
-        // unk_A8
+        // timeTravelEndAnim
         &gPlayerAnim_link_demo_return_to_past,
         // unk_AC
         &gPlayerAnim_clink_normal_climb_startA,
@@ -1185,9 +1187,9 @@ PlayerAgeProperties sPlayerAgeProperties[PLAYER_FORM_MAX] = {
         29.4343f,
         // openChestAnim
         &gPlayerAnim_clink_demo_Tbox_open,
-        // unk_A4
+        // timeTravelStartAnim
         &gPlayerAnim_clink_demo_goto_future,
-        // unk_A8
+        // timeTravelEndAnim
         &gPlayerAnim_clink_demo_return_to_future,
         // unk_AC
         &gPlayerAnim_clink_normal_climb_startA,
@@ -6797,8 +6799,9 @@ s32 Player_ActionHandler_1(Player* this, PlayState* play) {
             ((((this->doorType <= PLAYER_DOORTYPE_TALKING) && CutsceneManager_IsNext(CS_ID_GLOBAL_TALK)) ||
               ((this->doorType >= PLAYER_DOORTYPE_HANDLE) && CutsceneManager_IsNext(CS_ID_GLOBAL_DOOR))) &&
              (!(this->stateFlags1 & PLAYER_STATE1_CARRYING_ACTOR) &&
-              (CHECK_BTN_ALL(sPlayerControlInput->press.button, BTN_A) || (Player_Action_78 == this->actionFunc) ||
+              (CHECK_BTN_ALL(sPlayerControlInput->press.button, BTN_A) ||
-               (this->doorType == PLAYER_DOORTYPE_STAIRCASE) || (this->doorType == PLAYER_DOORTYPE_PROXIMITY))))) {
+               (Player_Action_TryOpeningDoor == this->actionFunc) || (this->doorType == PLAYER_DOORTYPE_STAIRCASE) ||
+               (this->doorType == PLAYER_DOORTYPE_PROXIMITY))))) {
             Actor* doorActor = this->doorActor;
             Actor* var_v0_3;
 
@@ -10856,89 +10859,103 @@ s32 func_808411D4(PlayState* play, Player* this, f32* arg2, s32 arg3) {
     return sp2C;
 }
 
-void Player_StartMode_0(PlayState* play, Player* this) {
+void Player_StartMode_Nothing(PlayState* play, Player* this) {
-    this->actor.update = func_801229EC;
+    this->actor.update = Player_DoNothing;
     this->actor.draw = NULL;
 }
 
-void Player_StartMode_2(PlayState* play, Player* this) {
+void Player_StartMode_BlueWarp(PlayState* play, Player* this) {
-    Player_SetAction(play, this, Player_Action_76, 0);
+    Player_SetAction(play, this, Player_Action_BlueWarpArrive, 0);
+
     this->stateFlags1 |= PLAYER_STATE1_20000000;
     PlayerAnimation_Change(play, &this->skelAnime, &gPlayerAnim_link_okarina_warp_goal, PLAYER_ANIM_ADJUSTED_SPEED,
                            0.0f, 24.0f, ANIMMODE_ONCE, 0.0f);
+
+    // Start high up in the air
     this->actor.world.pos.y += 800.0f;
 }
 
-u8 D_8085D2B0[] = {
+/**
-    ITEM_SWORD_RAZOR,
+ * Put the sword item in hand. If `playSfx` is true, the sword unsheathing sound will play.
-    ITEM_SWORD_KOKIRI,
+ * Sword will depend on transformation, but due to improper carryover from OoT,
-};
+ * this will lead to OoB for goron, deku or human.
-
+ *
-// OoT leftover?
+ * Note: This will not play an animation, the sword instantly appears in hand.
-void func_80841358(PlayState* play, Player* this, s32 arg2) {
+ *       It is expected that this function is called while an appropriate animation
-    ItemId item;
+ *       is already playing, for example in a cutscene.
-    PlayerItemAction itemAction;
+ */
-
+void Player_PutSwordInHand(PlayState* play, Player* this, s32 playSfx) {
+    static u8 sSwordItemIds[] = { ITEM_SWORD_RAZOR, ITEM_SWORD_KOKIRI };
     //! @bug OoB read if player is goron, deku or human
-    item = D_8085D2B0[this->transformation];
+    ItemId swordItemId = sSwordItemIds[this->transformation];
-    itemAction = sItemItemActions[item];
+    PlayerItemAction swordItemAction = sItemItemActions[swordItemId];
+
     Player_DestroyHookshot(this);
     Player_DetachHeldActor(play, this);
-    this->heldItemId = item;
+
-    this->nextModelGroup = Player_ActionToModelGroup(this, itemAction);
+    this->heldItemId = swordItemId;
-    Player_InitItemAction(play, this, itemAction);
+    this->nextModelGroup = Player_ActionToModelGroup(this, swordItemAction);
+
+    Player_InitItemAction(play, this, swordItemAction);
     func_808309CC(play, this);
-    if (arg2) {
+
+    if (playSfx) {
         Player_PlaySfx(this, NA_SE_IT_SWORD_PICKOUT);
     }
 }
 
-Vec3f D_8085D2B4 = { -1.0f, 69.0f, 20.0f };
+void Player_StartMode_TimeTravel(PlayState* play, Player* this) {
+    static Vec3f sPedestalPos = { -1.0f, 69.0f, 20.0f };
 
-void Player_StartMode_1(PlayState* play, Player* this) {
+    Player_SetAction(play, this, Player_Action_TimeTravelEnd, 0);
-    Player_SetAction(play, this, Player_Action_66, 0);
     this->stateFlags1 |= PLAYER_STATE1_20000000;
-    Math_Vec3f_Copy(&this->actor.world.pos, &D_8085D2B4);
+
+    Math_Vec3f_Copy(&this->actor.world.pos, &sPedestalPos);
     this->yaw = this->actor.shape.rot.y = -0x8000;
-    PlayerAnimation_Change(play, &this->skelAnime, this->ageProperties->unk_A8, PLAYER_ANIM_ADJUSTED_SPEED, 0.0f, 0.0f,
+
-                           ANIMMODE_ONCE, 0.0f);
+    // The start frame and end frame are both set to 0 so that that the animation is frozen.
+    // `Player_Action_TimeTravelEnd` will play the animation after `animDelayTimer` completes.
+    PlayerAnimation_Change(play, &this->skelAnime, this->ageProperties->timeTravelEndAnim, PLAYER_ANIM_ADJUSTED_SPEED,
+                           0.0f, 0.0f, ANIMMODE_ONCE, 0.0f);
     Player_AnimReplace_Setup(
         play, this, ANIM_FLAG_1 | ANIM_FLAG_UPDATE_Y | ANIM_FLAG_4 | ANIM_FLAG_8 | ANIM_FLAG_80 | ANIM_FLAG_200);
+
     if (this->transformation == PLAYER_FORM_FIERCE_DEITY) {
-        func_80841358(play, this, false);
+        Player_PutSwordInHand(play, this, false);
     }
-    this->av2.actionVar2 = 20;
+
+    this->av2.animDelayTimer = 20;
 }
 
-void Player_StartMode_3(PlayState* play, Player* this) {
+void Player_StartMode_Door(PlayState* play, Player* this) {
-    Player_SetAction(play, this, Player_Action_78, 0);
+    Player_SetAction(play, this, Player_Action_TryOpeningDoor, 0);
     Player_AnimReplace_Setup(play, this,
                              ANIM_FLAG_1 | ANIM_FLAG_UPDATE_Y | ANIM_FLAG_8 | ANIM_FLAG_NOMOVE | ANIM_FLAG_80);
 }
 
-void Player_StartMode_4(PlayState* play, Player* this) {
+void Player_StartMode_Grotto(PlayState* play, Player* this) {
     func_80834DB8(this, &gPlayerAnim_link_normal_jump, 12.0f, play);
-    Player_SetAction(play, this, Player_Action_79, 0);
+    Player_SetAction(play, this, Player_Action_ExitGrotto, 0);
     this->stateFlags1 |= PLAYER_STATE1_20000000;
     this->fallStartHeight = this->actor.world.pos.y;
 }
 
-void Player_StartMode_7(PlayState* play, Player* this) {
+void Player_StartMode_KnockedOver(PlayState* play, Player* this) {
     func_80833B18(play, this, 1, 2.0f, 2.0f, this->actor.shape.rot.y + 0x8000, 0);
 }
 
-void Player_StartMode_5(PlayState* play, Player* this) {
+void Player_StartMode_WarpSong(PlayState* play, Player* this) {
-    Player_SetAction(play, this, Player_Action_75, 0);
+    Player_SetAction(play, this, Player_Action_StartWarpSongArrive, 0);
-    this->actor.draw = NULL;
+    this->actor.draw = NULL; // Start invisible
     this->stateFlags1 |= PLAYER_STATE1_20000000;
 }
 
-void Player_StartMode_6(PlayState* play, Player* this) {
+void Player_StartMode_Owl(PlayState* play, Player* this) {
     if (gSaveContext.save.isOwlSave) {
-        Player_SetAction(play, this, Player_Action_0, 0);
+        Player_SetAction(play, this, Player_Action_OwlSaveArrive, 0);
         Player_Anim_PlayLoopMorph(play, this, D_8085BE84[PLAYER_ANIMGROUP_nwait][this->modelAnimType]);
         this->stateFlags1 |= PLAYER_STATE1_20000000;
-        this->av2.actionVar2 = 0x28;
+        this->av2.actionVar2 = 40;
         gSaveContext.save.isOwlSave = false;
     } else {
         Player_SetAction(play, this, Player_Action_Idle, 0);
@@ -11017,22 +11034,22 @@ typedef void (*PlayerStartModeFunc)(PlayState*, Player*);
 // Initialisation functions for various gameplay modes depending on spawn params.
 // There may be at most 0x10 due to it using a single nybble.
 PlayerStartModeFunc sStartModeFuncs[PLAYER_START_MODE_MAX] = {
-    Player_StartMode_0,         // PLAYER_START_MODE_0
+    Player_StartMode_Nothing,     // PLAYER_START_MODE_NOTHING
-    Player_StartMode_1,         // PLAYER_START_MODE_1
+    Player_StartMode_TimeTravel,  // PLAYER_START_MODE_TIME_TRAVEL
-    Player_StartMode_2,         // PLAYER_START_MODE_2
+    Player_StartMode_BlueWarp,    // PLAYER_START_MODE_BLUE_WARP
-    Player_StartMode_3,         // PLAYER_START_MODE_3
+    Player_StartMode_Door,        // PLAYER_START_MODE_DOOR
-    Player_StartMode_4,         // PLAYER_START_MODE_4
+    Player_StartMode_Grotto,      // PLAYER_START_MODE_GROTTO
-    Player_StartMode_5,         // PLAYER_START_MODE_5
+    Player_StartMode_WarpSong,    // PLAYER_START_MODE_WARP_SONG
-    Player_StartMode_6,         // PLAYER_START_MODE_6
+    Player_StartMode_Owl,         // PLAYER_START_MODE_OWL
-    Player_StartMode_7,         // PLAYER_START_MODE_7
+    Player_StartMode_KnockedOver, // PLAYER_START_MODE_KNOCKED_OVER
-    Player_StartMode_WarpTag,   // PLAYER_START_MODE_8
+    Player_StartMode_WarpTag,     // PLAYER_START_MODE_8
-    Player_StartMode_WarpTag,   // PLAYER_START_MODE_9
+    Player_StartMode_WarpTag,     // PLAYER_START_MODE_9
-    Player_StartMode_E,         // PLAYER_START_MODE_A
+    Player_StartMode_E,           // PLAYER_START_MODE_A
-    Player_StartMode_B,         // PLAYER_START_MODE_B
+    Player_StartMode_B,           // PLAYER_START_MODE_B
-    Player_StartMode_Telescope, // PLAYER_START_MODE_TELESCOPE
+    Player_StartMode_Telescope,   // PLAYER_START_MODE_TELESCOPE
-    Player_StartMode_D,         // PLAYER_START_MODE_D
+    Player_StartMode_D,           // PLAYER_START_MODE_D
-    Player_StartMode_E,         // PLAYER_START_MODE_E
+    Player_StartMode_E,           // PLAYER_START_MODE_E
-    Player_StartMode_F,         // PLAYER_START_MODE_F
+    Player_StartMode_F,           // PLAYER_START_MODE_F
 };
 
 // sBlureInit
@@ -11277,7 +11294,7 @@ void Player_Init(Actor* thisx, PlayState* play) {
 
     startMode = PLAYER_GET_START_MODE(&this->actor);
 
-    if (((startMode == PLAYER_START_MODE_5) || (startMode == PLAYER_START_MODE_6)) &&
+    if (((startMode == PLAYER_START_MODE_WARP_SONG) || (startMode == PLAYER_START_MODE_OWL)) &&
         (gSaveContext.save.cutsceneIndex >= 0xFFF0)) {
         startMode = PLAYER_START_MODE_D;
     }
@@ -14099,7 +14116,7 @@ s32 Player_UpperAction_16(Player* this, PlayState* play) {
     return true;
 }
 
-void Player_Action_0(Player* this, PlayState* play) {
+void Player_Action_OwlSaveArrive(Player* this, PlayState* play) {
     PlayerAnimation_Update(play, &this->skelAnime);
     func_808323C0(this, play->playerCsIds[PLAYER_CS_ID_ITEM_BOTTLE]);
 
@@ -17600,16 +17617,14 @@ void Player_Action_65(Player* this, PlayState* play) {
     }
 }
 
-AnimSfxEntry D_8085D75C[] = {
+void Player_Action_TimeTravelEnd(Player* this, PlayState* play) {
-    ANIMSFX(ANIMSFX_TYPE_VOICE, 5, NA_SE_VO_LI_AUTO_JUMP, CONTINUE),
-    ANIMSFX(ANIMSFX_TYPE_FLOOR_LAND, 15, NA_SE_NONE, STOP),
-};
-
-void Player_Action_66(Player* this, PlayState* play) {
     if (PlayerAnimation_Update(play, &this->skelAnime)) {
-        if (this->av1.actionVar1 == 0) {
+        if (!this->av1.startedAnim) {
-            if (DECR(this->av2.actionVar2) == 0) {
+            if (DECR(this->av2.animDelayTimer) == 0) {
-                this->av1.actionVar1 = 1;
+                this->av1.startedAnim = true;
+
+                // endFrame was previously set to 0 to freeze the animation.
+                // Set it properly to allow the animation to play.
                 this->skelAnime.endFrame = this->skelAnime.animLength - 1.0f;
             }
         } else {
@@ -17619,7 +17634,12 @@ void Player_Action_66(Player* this, PlayState* play) {
                PlayerAnimation_OnFrame(&this->skelAnime, 158.0f)) {
         Player_AnimSfx_PlayVoice(this, NA_SE_VO_LI_SWORD_N);
     } else if (this->transformation != PLAYER_FORM_FIERCE_DEITY) {
-        Player_PlayAnimSfx(this, D_8085D75C);
+        static AnimSfxEntry sJumpOffPedestalAnimSfxList[] = {
+            ANIMSFX(ANIMSFX_TYPE_VOICE, 5, NA_SE_VO_LI_AUTO_JUMP, CONTINUE),
+            ANIMSFX(ANIMSFX_TYPE_FLOOR_LAND, 15, NA_SE_NONE, STOP),
+        };
+
+        Player_PlayAnimSfx(this, sJumpOffPedestalAnimSfxList);
     } else {
         func_808484CC(this);
     }
@@ -18057,32 +18077,39 @@ void Player_Action_73(Player* this, PlayState* play) {
     Math_ScaledStepToS(&this->actor.shape.rot.y, var_v0, 0x7D0);
 }
 
-void func_80859CE0(PlayState* play, Player* this, s32 arg2);
+/**
-
+ * Waits to start processing a Cutscene Action.
-void Player_Action_74(Player* this, PlayState* play) {
+ * First, the timer `csDelayTimer` much reach 0.
-    if ((DECR(this->av2.actionVar2) == 0) && Player_StartCsAction(play, this)) {
+ * Then, there must be a CS action available to start processing.
+ *
+ * When starting the cutscene action, `draw` will be set to make
+ * Player appear, if he was invisible.
+ */
+void Player_Action_WaitForCutscene(Player* this, PlayState* play) {
+    if ((DECR(this->av2.csDelayTimer) == 0) && Player_StartCsAction(play, this)) {
         func_80859CE0(play, this, 0);
         Player_SetAction(play, this, Player_Action_CsAction, 0);
         Player_Action_CsAction(this, play);
     }
 }
 
-void Player_Action_75(Player* this, PlayState* play) {
+void Player_Action_StartWarpSongArrive(Player* this, PlayState* play) {
-    Player_SetAction(play, this, Player_Action_74, 0);
+    Player_SetAction(play, this, Player_Action_WaitForCutscene, 0);
-    this->av2.actionVar2 = 0x28;
+    this->av2.csDelayTimer = 40;
+
     Actor_Spawn(&play->actorCtx, play, ACTOR_DEMO_KANKYO, 0.0f, 0.0f, 0.0f, 0, 0, 0, 0x10);
 }
 
 void Player_Cutscene_SetPosAndYawToStart(Player* this, CsCmdActorCue* cue);
 
-void Player_Action_76(Player* this, PlayState* play) {
+void Player_Action_BlueWarpArrive(Player* this, PlayState* play) {
     if (sPlayerYDistToFloor < 150.0f) {
         if (PlayerAnimation_Update(play, &this->skelAnime)) {
-            if (this->av2.actionVar2 == 0) {
+            if (!this->av2.playedLandingSfx) {
                 if (this->actor.bgCheckFlags & BGCHECKFLAG_GROUND) {
                     this->skelAnime.endFrame = this->skelAnime.animLength - 1.0f;
                     Player_AnimSfx_PlayFloorLand(this);
-                    this->av2.actionVar2 = 1;
+                    this->av2.playedLandingSfx = true;
                 }
             } else {
                 func_8085B384(this, play);
@@ -18095,10 +18122,10 @@ void Player_Action_76(Player* this, PlayState* play) {
     if (play->csCtx.state != CS_STATE_IDLE) {
         if (play->csCtx.playerCue != NULL) {
             s32 pad;
-            f32 sp28 = this->actor.world.pos.y;
+            f32 savedYPos = this->actor.world.pos.y;
 
             Player_Cutscene_SetPosAndYawToStart(this, play->csCtx.playerCue);
-            this->actor.world.pos.y = sp28;
+            this->actor.world.pos.y = savedYPos;
         }
     }
 }
@@ -18139,12 +18166,17 @@ void Player_Action_77(Player* this, PlayState* play) {
     }
 }
 
-void Player_Action_78(Player* this, PlayState* play) {
+/**
+ * Automatically open a door (no need for the A button).
+ * Note: If no door is in useable range, a softlock will occur.
+ */
+void Player_Action_TryOpeningDoor(Player* this, PlayState* play) {
     Player_ActionHandler_1(this, play);
 }
 
-void Player_Action_79(Player* this, PlayState* play) {
+void Player_Action_ExitGrotto(Player* this, PlayState* play) {
     this->actor.gravity = -1.0f;
+
     PlayerAnimation_Update(play, &this->skelAnime);
 
     if (this->actor.velocity.y < 0.0f) {
@@ -20512,7 +20544,7 @@ void func_80859CE0(PlayState* play, Player* this, s32 arg2) {
 }
 
 void Player_CsAction_17(PlayState* play, Player* this, CsCmdActorCue* cue) {
-    func_80841358(play, this, false);
+    Player_PutSwordInHand(play, this, false);
     Player_Anim_PlayOnceAdjusted(play, this, &gPlayerAnim_link_demo_return_to_past);
 }
 
@@ -20563,7 +20595,7 @@ void Player_CsAction_20(PlayState* play, Player* this, CsCmdActorCue* cue) {
         Player_CsAction_End(play, this, cue);
     } else if (this->av2.actionVar2 == 0) {
         Item_Give(play, ITEM_SWORD_RAZOR);
-        func_80841358(play, this, false);
+        Player_PutSwordInHand(play, this, false);
     } else {
         func_808484CC(this);
     }
@@ -20574,7 +20606,7 @@ void Player_CsAction_21(PlayState* play, Player* this, CsCmdActorCue* cue) {
         func_8083FCF0(play, this, 0.0f, 99.0f, this->skelAnime.endFrame - 8.0f);
     }
     if (this->heldItemAction != PLAYER_IA_SWORD_GILDED) {
-        func_80841358(play, this, true);
+        Player_PutSwordInHand(play, this, true);
     }
 }
 

tools/disasm/functions.txt

@@ -2177,7 +2177,7 @@
     0x80122760:("Player_UpdateOverrideInput",),
     0x80122868:("func_80122868",),
     0x801229A0:("func_801229A0",),
-    0x801229EC:("func_801229EC",),
+    0x801229EC:("Player_DoNothing",),
     0x801229FC:("func_801229FC",),
     0x80122BA4:("func_80122BA4",),
     0x80122C20:("func_80122C20",),
@@ -4590,15 +4590,15 @@
     0x80840F34:("func_80840F34",),
     0x80840F90:("func_80840F90",),
     0x808411D4:("func_808411D4",),
-    0x808412A0:("Player_StartMode_0",),
+    0x808412A0:("Player_StartMode_Nothing",),
-    0x808412BC:("Player_StartMode_2",),
+    0x808412BC:("Player_StartMode_BlueWarp",),
-    0x80841358:("func_80841358",),
+    0x80841358:("Player_PutSwordInHand",),
-    0x80841408:("Player_StartMode_1",),
+    0x80841408:("Player_StartMode_TimeTravel",),
-    0x808414E0:("Player_StartMode_3",),
+    0x808414E0:("Player_StartMode_Door",),
-    0x80841528:("Player_StartMode_4",),
+    0x80841528:("Player_StartMode_Grotto",),
-    0x808415A0:("Player_StartMode_7",),
+    0x808415A0:("Player_StartMode_KnockedOver",),
-    0x808415E4:("Player_StartMode_5",),
+    0x808415E4:("Player_StartMode_WarpSong",),
-    0x80841624:("Player_StartMode_6",),
+    0x80841624:("Player_StartMode_Owl",),
     0x80841744:("Player_StartMode_WarpTag",),
     0x8084182C:("Player_InitCommon",),
     0x80841A50:("func_80841A50",),
@@ -4661,7 +4661,7 @@
     0x8084933C:("Player_UpperAction_14",),
     0x80849570:("Player_UpperAction_15",),
     0x80849620:("Player_UpperAction_16",),
-    0x808496AC:("Player_Action_0",),
+    0x808496AC:("Player_Action_OwlSaveArrive",),
     0x808497A0:("Player_Action_1",),
     0x80849A9C:("Player_Action_2",),
     0x80849DD0:("Player_Action_3",),
@@ -4744,7 +4744,7 @@
     0x8085269C:("Player_Action_63",),
     0x80852B28:("Player_Action_64",),
     0x80852C04:("Player_Action_65",),
-    0x80852FD4:("Player_Action_66",),
+    0x80852FD4:("Player_Action_TimeTravelEnd",),
     0x808530E0:("func_808530E0",),
     0x80853194:("Player_Action_67",),
     0x808534C0:("Player_Action_68",),
@@ -4753,12 +4753,12 @@
     0x80853A5C:("Player_Action_ExchangeItem",),
     0x80853CC0:("Player_Action_72",),
     0x80853D68:("Player_Action_73",),
-    0x80854010:("Player_Action_74",),
+    0x80854010:("Player_Action_WaitForCutscene",),
-    0x808540A0:("Player_Action_75",),
+    0x808540A0:("Player_Action_StartWarpSongArrive",),
-    0x80854118:("Player_Action_76",),
+    0x80854118:("Player_Action_BlueWarpArrive",),
     0x8085421C:("Player_Action_77",),
-    0x8085437C:("Player_Action_78",),
+    0x8085437C:("Player_Action_TryOpeningDoor",),
-    0x8085439C:("Player_Action_79",),
+    0x8085439C:("Player_Action_ExitGrotto",),
     0x80854430:("Player_Action_80",),
     0x80854614:("Player_Action_81",),
     0x808546D0:("Player_Action_82",),

tools/disasm/variables.txt

@@ -4896,8 +4896,8 @@
     0x8085D288:("D_8085D288","Vec3f","",0xC),
     0x8085D294:("D_8085D294","UNK_TYPE1","",0x1),
     0x8085D2A4:("D_8085D2A4","UNK_TYPE1","",0x1),
-    0x8085D2B0:("D_8085D2B0","UNK_TYPE1","",0x1),
+    0x8085D2B0:("sSwordItemIds","UNK_TYPE1","",0x1),
-    0x8085D2B4:("D_8085D2B4","UNK_TYPE1","",0x1),
+    0x8085D2B4:("sPedestalPos","UNK_TYPE1","",0x1),
     0x8085D2C0:("sInitChain","ActorInitVar","",0x4),
     0x8085D2C4:("sPlayerSkeletonBaseTransl","UNK_TYPE4","",0x4),
     0x8085D2CC:("sStartModeFuncs","UNK_PTR","",0x4),
@@ -4968,7 +4968,7 @@
     0x8085D714:("D_8085D714","UNK_TYPE1","",0x1),
     0x8085D73C:("D_8085D73C","UNK_TYPE1","",0x1),
     0x8085D74C:("D_8085D74C","UNK_TYPE1","",0x1),
-    0x8085D75C:("D_8085D75C","UNK_TYPE1","",0x1),
+    0x8085D75C:("sJumpOffPedestalAnimSfxList","UNK_TYPE1","",0x1),
     0x8085D764:("D_8085D764","Vec3f","",0xC),
     0x8085D770:("D_8085D770","UNK_TYPE1","",0x1),
     0x8085D77C:("D_8085D77C","UNK_TYPE1","",0x1),

tools/sizes/code_functions.csv

@@ -1691,7 +1691,7 @@ asm/non_matchings/code/z_player_lib/Player_InitOverrideInput.s,Player_InitOverri
 asm/non_matchings/code/z_player_lib/Player_UpdateOverrideInput.s,Player_UpdateOverrideInput,0x80122760,0x42
 asm/non_matchings/code/z_player_lib/func_80122868.s,func_80122868,0x80122868,0x4E
 asm/non_matchings/code/z_player_lib/func_801229A0.s,func_801229A0,0x801229A0,0x13
-asm/non_matchings/code/z_player_lib/func_801229EC.s,func_801229EC,0x801229EC,0x4
+asm/non_matchings/code/z_player_lib/Player_DoNothing.s,Player_DoNothing,0x801229EC,0x4
 asm/non_matchings/code/z_player_lib/func_801229FC.s,func_801229FC,0x801229FC,0x6A
 asm/non_matchings/code/z_player_lib/func_80122BA4.s,func_80122BA4,0x80122BA4,0x1F
 asm/non_matchings/code/z_player_lib/func_80122C20.s,func_80122C20,0x80122C20,0x49