Document a bug involving quick-killing the Wizrobe (#1233)

* Document a bug involving quick-killing the Wizrobe

* Update wording in EnWiz_SelectPlatform

* Add missing "it" to comment

1 files changed, 16 insertions, 2 deletions

diff --git a/src/overlays/actors/ovl_En_Wiz/z_en_wiz.c b/src/overlays/actors/ovl_En_Wiz/z_en_wiz.c
index 125be5056..d6cc0e9e6 100644
--- a/src/overlays/actors/ovl_En_Wiz/z_en_wiz.c
+++ b/src/overlays/actors/ovl_En_Wiz/z_en_wiz.c
@@ -37,8 +37,8 @@ void EnWiz_SetupDead(EnWiz* this);
 void EnWiz_Dead(EnWiz* this, PlayState* play);
 
 // This number is almost-entirely arbirary, with the only requirement being
-// that cannot be a valid curPlatformIndex. Any negative number, or any number
-// larger than 10, would work just as well.
+// that it cannot be a valid curPlatformIndex. Any negative number, or any
+// number larger than 10, would work just as well.
 #define INITIAL_PLATFORM_INDEX 777
 
 typedef enum {
@@ -601,6 +601,9 @@ void EnWiz_SelectPlatform(EnWiz* this, PlayState* play) {
                 break;
 
             case EN_WIZ_FIGHT_STATE_SECOND_PHASE_CUTSCENE:
+                //! @bug: Setting the Wizrobe's position to the first platform *without* updating
+                //! this->curPlatformIndex can cause a bug later in EnWiz_Damaged. One way to fix
+                //! this is to set this->curPlatformIndex to 0 here.
                 Math_Vec3f_Copy(&this->actor.world.pos, &this->platforms[0]->world.pos);
                 for (i = 0, ghostAlpha = 128; i < this->platformCount; i++, ghostAlpha -= 10) {
                     Math_Vec3f_Copy(&this->ghostPos[i], &this->actor.world.pos);
@@ -1120,6 +1123,17 @@ void EnWiz_Damaged(EnWiz* this, PlayState* play) {
         this->ghostRot[i].y += this->rotationalVelocity;
     }
 
+    //! @bug: When the Wizrobe is defeated, it is launched into the air by the code above, and the
+    //! last check in this conditional is intended to check that the Wizrobe is standing on its
+    //! platform before transitioning to a different state. However, when the fight is in the
+    //! EN_WIZ_FIGHT_STATE_SECOND_PHASE_CUTSCENE state, the Wizrobe will always appear on top of
+    //! the first platform, while its curPlatformIndex is allowed to randomly choose any other
+    //! platform in the room. If the Wizrobe is defeated in this state (which is possible with a
+    //! well-timed attack before the cutscene starts), and if the first platform is elevated above
+    //! other platforms in the room (as it is in the Secret Shrine), then it is possible for
+    //! this->platforms[this->curPlatformIndex]->world.pos.y to be under the floor compared to the
+    //! Wizrobe's current position, causing it to get stuck here and never actually die. This can
+    //! be fixed by addressing the bug in EnWiz_SelectPlatform.
     if ((this->timer == 1) ||
         ((this->actor.velocity.y < 0.0f) &&
          (this->actor.world.pos.y < (this->platforms[this->curPlatformIndex]->world.pos.y + 11.0f)))) {