From 5625603b56e11a59f5eb36b346c89390f7352fbf Mon Sep 17 00:00:00 2001
From: Isghj <42048411+isghj5@users.noreply.github.com>
Date: Thu, 3 Aug 2023 19:35:59 -0700
Subject: [PATCH] ShotSun: some docs (#1348)

---
 src/overlays/actors/ovl_Shot_Sun/z_shot_sun.c | 25 +++++++++++--------
 src/overlays/actors/ovl_Shot_Sun/z_shot_sun.h | 11 ++++++--
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.c b/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.c
index 491dee5457..e128e72634 100644
--- a/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.c
+++ b/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.c
@@ -55,9 +55,9 @@ void ShotSun_Init(Actor* thisx, PlayState* play) {
     s32 pad;
     ShotSun* this = THIS;
 
-    if ((SHOTSUN_GET_FF(thisx) == SHOTSUN_FAIRY_SPAWNER_SUNS) ||
-        (SHOTSUN_GET_FF(thisx) == SHOTSUN_FAIRY_SPAWNER_STORMS)) {
-        this->unk_19C = 0;
+    if ((SHOTSUN_GET_TYPE(thisx) == SHOTSUN_FAIRY_SPAWNER_SUNS) ||
+        (SHOTSUN_GET_TYPE(thisx) == SHOTSUN_FAIRY_SPAWNER_STORMS)) {
+        this->fairySpawnerState = SPAWNER_OUT_OF_RANGE; // never read after here
         this->actor.flags |= ACTOR_FLAG_10;
         this->actor.flags |= ACTOR_FLAG_2000000;
         this->actionFunc = ShotSun_UpdateForOcarina;
@@ -73,14 +73,14 @@ void ShotSun_Init(Actor* thisx, PlayState* play) {
 void ShotSun_Destroy(Actor* thisx, PlayState* play) {
     ShotSun* this = THIS;
 
-    if ((SHOTSUN_GET_FF(thisx) != SHOTSUN_FAIRY_SPAWNER_SUNS) &&
-        (SHOTSUN_GET_FF(thisx) != SHOTSUN_FAIRY_SPAWNER_STORMS)) {
+    if ((SHOTSUN_GET_TYPE(thisx) != SHOTSUN_FAIRY_SPAWNER_SUNS) &&
+        (SHOTSUN_GET_TYPE(thisx) != SHOTSUN_FAIRY_SPAWNER_STORMS)) {
         Collider_DestroyCylinder(play, &this->collider);
     }
 }
 
 void ShotSun_SpawnFairy(ShotSun* this, PlayState* play2) {
-    s32 params = SHOTSUN_GET_FF(&this->actor);
+    s32 type = SHOTSUN_GET_TYPE(&this->actor);
     s32 fairyType = 0;
     PlayState* play = play2;
 
@@ -88,7 +88,7 @@ void ShotSun_SpawnFairy(ShotSun* this, PlayState* play2) {
         this->timer--;
     } else {
         CutsceneManager_Stop(this->actor.csId);
-        switch (params) {
+        switch (type) {
             case SHOTSUN_FAIRY_SPAWNER_SUNS:
                 fairyType = FAIRY_TYPE_7;
                 break;
@@ -100,6 +100,7 @@ void ShotSun_SpawnFairy(ShotSun* this, PlayState* play2) {
             default:
                 break;
         }
+
         Actor_Spawn(&play->actorCtx, play, ACTOR_EN_ELF, this->actor.home.pos.x, this->actor.home.pos.y,
                     this->actor.home.pos.z, 0, 0, 0, FAIRY_PARAMS(fairyType, false, 0));
         Actor_Kill(&this->actor);
@@ -111,10 +112,14 @@ void ShotSun_TriggerFairy(ShotSun* this, PlayState* play) {
         if (this->actor.csId != CS_ID_NONE) {
             CutsceneManager_Start(this->actor.csId, &this->actor);
         }
+
         this->actionFunc = ShotSun_SpawnFairy;
         this->timer = 50;
+
+        //! @bug: This Demo_Kankyo spawn will crash because parameter 0x11 is an invalid value (type goes up to 4)
         Actor_Spawn(&play->actorCtx, play, ACTOR_DEMO_KANKYO, this->actor.home.pos.x, this->actor.home.pos.y,
                     this->actor.home.pos.z, 0, 0, 0, 0x11);
+
         Audio_PlaySfx_AtPos(&this->actor.projectedPos, NA_SE_EV_TRE_BOX_APPEAR);
     } else {
         CutsceneManager_Queue(this->actor.csId);
@@ -122,18 +127,18 @@ void ShotSun_TriggerFairy(ShotSun* this, PlayState* play) {
 }
 
 void ShotSun_UpdateForOcarina(ShotSun* this, PlayState* play) {
-    s32 params = SHOTSUN_GET_FF(&this->actor);
+    s32 type = SHOTSUN_GET_TYPE(&this->actor);
 
     if (play->msgCtx.ocarinaMode == 3) {
         switch (play->msgCtx.lastPlayedSong) {
             case OCARINA_SONG_STORMS:
-                if (params == SHOTSUN_FAIRY_SPAWNER_STORMS) {
+                if (type == SHOTSUN_FAIRY_SPAWNER_STORMS) {
                     this->actionFunc = ShotSun_TriggerFairy;
                     play->msgCtx.ocarinaMode = 4;
                 }
                 break;
             case OCARINA_SONG_SUNS:
-                if (params == SHOTSUN_FAIRY_SPAWNER_SUNS) {
+                if (type == SHOTSUN_FAIRY_SPAWNER_SUNS) {
                     this->actionFunc = ShotSun_TriggerFairy;
                     play->msgCtx.ocarinaMode = 4;
                 }
diff --git a/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.h b/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.h
index 3ba7f35d9a..ad94fda730 100644
--- a/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.h
+++ b/src/overlays/actors/ovl_Shot_Sun/z_shot_sun.h
@@ -3,7 +3,7 @@
 
 #include "global.h"
 
-#define SHOTSUN_GET_FF(thisx) ((thisx)->params & 0xFF)
+#define SHOTSUN_GET_TYPE(thisx) ((thisx)->params & 0xFF)
 #define SHOTSUN_FAIRY_SPAWNER_SUNS 0x40
 #define SHOTSUN_FAIRY_SPAWNER_STORMS 0x41
 
@@ -17,7 +17,14 @@ typedef struct ShotSun {
     /* 0x190 */ ShotSunActionFunc actionFunc;
     /* 0x194 */ Vec3s hitboxPos;
     /* 0x19A */ s16 timer;
-    /* 0x19C */ s8 unk_19C; // leftover from OOT secret ocarina occurrence function.
+    /* 0x19C */ s8 fairySpawnerState; // leftover from OOT secret ocarina occurrence function.
 } ShotSun; // size = 0x1A0
 
+// Left over from OOT, unused in MM
+typedef enum {
+    /* 0 */ SPAWNER_OUT_OF_RANGE,
+    /* 1 */ SPAWNER_OCARINA_START,
+    /* 2 */ SPAWNER_OCARINA_PLAYING
+} FairySpawnerState;
+
 #endif // Z_SHOT_SUN_H