Audio Sfx Functions Decompiled and Documented (code_8019AF00.c) (#1242)

* sfx decomp and docs

* function headers

* namefixer

* oops

* better sfx name

* PR review

* namefixer

* PR review

* float

* namefixer

* namefixer

* namefixer

* PR Suggestions

1 files changed, 72 insertions, 45 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index e7bc92a26..ac014e5ca 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -32,6 +32,20 @@ extern s16 D_801ED8DC;                // 2 funcs
 extern Mtx D_801ED8E0;                // 1 func
 extern Actor* D_801ED920;             // 2 funcs. 1 out of z_actor
 
+#define ACTOR_AUDIO_FLAG_SFX_ACTOR_POS (1 << 0)
+#define ACTOR_AUDIO_FLAG_SFX_CENTERED_1 (1 << 1)
+#define ACTOR_AUDIO_FLAG_SFX_CENTERED_2 (1 << 2)
+#define ACTOR_AUDIO_FLAG_SFX_CENTERED_3 (1 << 3)
+#define ACTOR_AUDIO_FLAG_SFX_TIMER (1 << 4)
+#define ACTOR_AUDIO_FLAG_SEQ_KAMARO_DANCE (1 << 5)
+#define ACTOR_AUDIO_FLAG_SEQ_MUSIC_BOX_HOUSE (1 << 6)
+
+#define ACTOR_AUDIO_FLAG_SFX_ALL                                                                      \
+    (ACTOR_AUDIO_FLAG_SFX_TIMER | ACTOR_AUDIO_FLAG_SFX_CENTERED_3 | ACTOR_AUDIO_FLAG_SFX_CENTERED_2 | \
+     ACTOR_AUDIO_FLAG_SFX_CENTERED_1 | ACTOR_AUDIO_FLAG_SFX_ACTOR_POS)
+#define ACTOR_AUDIO_FLAG_SEQ_ALL (ACTOR_AUDIO_FLAG_SEQ_MUSIC_BOX_HOUSE | ACTOR_AUDIO_FLAG_SEQ_KAMARO_DANCE)
+#define ACTOR_AUDIO_FLAG_ALL (ACTOR_AUDIO_FLAG_SFX_ALL | ACTOR_AUDIO_FLAG_SEQ_ALL)
+
 // Internal forward declarations
 void Actor_KillAllOnHalfDayChange(PlayState* play, ActorContext* actorCtx);
 Actor* Actor_SpawnEntry(ActorContext* actorCtx, ActorEntry* actorEntry, PlayState* play);
@@ -663,7 +677,7 @@ void func_800B5814(TargetContext* targetCtx, Player* player, Actor* actor, GameS
 
             sfxId =
                 CHECK_FLAG_ALL(actor->flags, ACTOR_FLAG_4 | ACTOR_FLAG_1) ? NA_SE_SY_LOCK_ON : NA_SE_SY_LOCK_ON_HUMAN;
-            play_sound(sfxId);
+            Audio_PlaySfx(sfxId);
         }
 
         targetCtx->targetCenterPos.x = actor->world.pos.x;
@@ -2164,7 +2178,7 @@ void func_800B8E1C(PlayState* play, Actor* actor, f32 arg2, s16 arg3, f32 arg4)
  */
 void Player_PlaySfx(Player* player, u16 sfxId) {
     if (player->currentMask == PLAYER_MASK_GIANT) {
-        func_8019F170(&player->actor.projectedPos, sfxId);
+        Audio_PlaySfx_AtPosWithPresetLowFreqAndHighReverb(&player->actor.projectedPos, sfxId);
     } else {
         AudioSfx_PlaySfx(sfxId, &player->actor.projectedPos, 4, &gSfxDefaultFreqAndVolScale,
                          &gSfxDefaultFreqAndVolScale, &gSfxDefaultReverb);
@@ -2175,10 +2189,10 @@ void Player_PlaySfx(Player* player, u16 sfxId) {
  * Play a sound effect at the actor's position
  */
 void Actor_PlaySfx(Actor* actor, u16 sfxId) {
-    Audio_PlaySfxAtPos(&actor->projectedPos, sfxId);
+    Audio_PlaySfx_AtPos(&actor->projectedPos, sfxId);
 }
 
-void func_800B8EF4(PlayState* play, Actor* actor) {
+void Actor_PlaySfx_SurfaceBomb(PlayState* play, Actor* actor) {
     SurfaceSfxOffset surfaceSfxOffset;
 
     if (actor->bgCheckFlags & BGCHECKFLAG_WATER) {
@@ -2191,41 +2205,53 @@ void func_800B8EF4(PlayState* play, Actor* actor) {
         surfaceSfxOffset = SurfaceType_GetSfxOffset(&play->colCtx, actor->floorPoly, actor->floorBgId);
     }
 
-    Audio_PlaySfxAtPos(&actor->projectedPos, NA_SE_EV_BOMB_BOUND);
-    Audio_PlaySfxAtPos(&actor->projectedPos, NA_SE_PL_WALK_GROUND + surfaceSfxOffset);
+    Audio_PlaySfx_AtPos(&actor->projectedPos, NA_SE_EV_BOMB_BOUND);
+    Audio_PlaySfx_AtPos(&actor->projectedPos, NA_SE_PL_WALK_GROUND + surfaceSfxOffset);
 }
 
-void func_800B8F98(Actor* actor, u16 sfxId) {
+/**
+ * Play a sfx at the center of the screen using the shared audioFlag system
+ */
+void Actor_PlaySfx_FlaggedCentered1(Actor* actor, u16 sfxId) {
     actor->sfxId = sfxId;
-    actor->audioFlags &= ~(0x10 | 0x08 | 0x04 | 0x02 | 0x01);
-    actor->audioFlags |= 0x02;
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_SFX_ALL;
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SFX_CENTERED_1;
 }
 
-void func_800B8FC0(Actor* actor, u16 sfxId) {
+/**
+ * Play a sfx at the center of the screen using the shared audioFlag system
+ */
+void Actor_PlaySfx_FlaggedCentered2(Actor* actor, u16 sfxId) {
     actor->sfxId = sfxId;
-    actor->audioFlags &= ~(0x10 | 0x08 | 0x04 | 0x02 | 0x01);
-    actor->audioFlags |= 4;
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_SFX_ALL;
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SFX_CENTERED_2;
 }
 
-void func_800B8FE8(Actor* actor, u16 sfxId) {
+/**
+ * Play a sfx at the center of the screen using the shared audioFlag system
+ */
+void Actor_PlaySfx_FlaggedCentered3(Actor* actor, u16 sfxId) {
     actor->sfxId = sfxId;
-    actor->audioFlags &= ~(0x10 | 0x08 | 0x04 | 0x02 | 0x01);
-    actor->audioFlags |= 0x08;
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_SFX_ALL;
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SFX_CENTERED_3;
 }
 
-void func_800B9010(Actor* actor, u16 sfxId) {
+/**
+ * Play a sfx at the actor's position using the shared audioFlag system
+ */
+void Actor_PlaySfx_Flagged(Actor* actor, u16 sfxId) {
     actor->sfxId = sfxId;
-    actor->audioFlags &= ~(0x10 | 0x08 | 0x04 | 0x02 | 0x01);
-    actor->audioFlags |= 0x01;
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_SFX_ALL;
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SFX_ACTOR_POS;
 }
 
-void func_800B9038(Actor* actor, s32 timer) {
-    actor->audioFlags &= ~(0x10 | 0x08 | 0x04 | 0x02 | 0x01);
-    actor->audioFlags |= 0x10;
+void Actor_PlaySfx_FlaggedTimer(Actor* actor, s32 timer) {
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_SFX_ALL;
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SFX_TIMER;
 
     // The sfxId here are not actually sound effects, but instead this is data that gets sent into
-    // the io ports of the music macro language (func_801A0810 / Audio_PlaySfxAtPosWithSoundScriptIO is
-    // the function that it's used for)
+    // the io ports of the music macro language (Audio_PlaySfx_AtPosWithChannelIO / Audio_PlaySfxAtPosWithSoundScriptIO
+    // is the function that it's used for)
     if (timer < 40) {
         actor->sfxId = 3;
     } else if (timer < 100) {
@@ -2235,12 +2261,12 @@ void func_800B9038(Actor* actor, s32 timer) {
     }
 }
 
-void func_800B9084(Actor* actor) {
-    actor->audioFlags |= 0x20;
+void Actor_PlaySeq_FlaggedKamaroDance(Actor* actor) {
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SEQ_KAMARO_DANCE;
 }
 
-void func_800B9098(Actor* actor) {
-    actor->audioFlags |= 0x40;
+void Actor_PlaySeq_FlaggedMusicBoxHouse(Actor* actor) {
+    actor->audioFlags |= ACTOR_AUDIO_FLAG_SEQ_MUSIC_BOX_HOUSE;
 }
 
 s32 func_800B90AC(PlayState* play, Actor* actor, CollisionPoly* polygon, s32 bgId, Vec3f* arg4) {
@@ -2368,7 +2394,7 @@ Actor* Actor_UpdateActor(UpdateActor_Params* params) {
     }
 
     actor->sfxId = 0;
-    actor->audioFlags &= ~0x7F;
+    actor->audioFlags &= ~ACTOR_AUDIO_FLAG_ALL;
 
     if (actor->init != NULL) {
         if (Object_IsLoaded(&play->objectCtx, actor->objBankIndex)) {
@@ -2545,7 +2571,7 @@ void Actor_UpdateAll(PlayState* play, ActorContext* actorCtx) {
         actor = NULL;
         if (actorCtx->targetContext.unk4B != 0) {
             actorCtx->targetContext.unk4B = 0;
-            play_sound(NA_SE_SY_LOCK_OFF);
+            Audio_PlaySfx(NA_SE_SY_LOCK_OFF);
         }
     }
 
@@ -2630,31 +2656,32 @@ void Actor_Draw(PlayState* play, Actor* actor) {
     CLOSE_DISPS(play->state.gfxCtx);
 }
 
-void func_800B9D1C(Actor* actor) {
+void Actor_UpdateFlaggedAudio(Actor* actor) {
     s32 sfxId = actor->sfxId;
 
-    if (sfxId != 0) {
-        if (actor->audioFlags & 2) {
+    if (sfxId != NA_SE_NONE) {
+        if (actor->audioFlags & ACTOR_AUDIO_FLAG_SFX_CENTERED_1) {
             AudioSfx_PlaySfx(sfxId, &actor->projectedPos, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale,
                              &gSfxDefaultReverb);
-        } else if (actor->audioFlags & 4) {
-            play_sound(sfxId);
-        } else if (actor->audioFlags & 8) {
-            func_8019F128(sfxId);
-        } else if (actor->audioFlags & 0x10) {
-            func_801A0810(&gSfxDefaultPos, NA_SE_SY_TIMER - SFX_FLAG, (sfxId - 1));
-        } else if (actor->audioFlags & 1) {
-            Audio_PlaySfxAtPos(&actor->projectedPos, sfxId);
+        } else if (actor->audioFlags & ACTOR_AUDIO_FLAG_SFX_CENTERED_2) {
+            Audio_PlaySfx(sfxId);
+        } else if (actor->audioFlags & ACTOR_AUDIO_FLAG_SFX_CENTERED_3) {
+            Audio_PlaySfx_2(sfxId);
+        } else if (actor->audioFlags & ACTOR_AUDIO_FLAG_SFX_TIMER) {
+            Audio_PlaySfx_AtPosWithChannelIO(&gSfxDefaultPos, NA_SE_SY_TIMER - SFX_FLAG, (sfxId - 1));
+        } else if (actor->audioFlags & ACTOR_AUDIO_FLAG_SFX_ACTOR_POS) {
+            Audio_PlaySfx_AtPos(&actor->projectedPos, sfxId);
         }
     }
 
-    if (sfxId) {}
+    //! FAKE:
+    if (sfxId != NA_SE_NONE) {}
 
-    if (actor->audioFlags & 0x40) {
+    if (actor->audioFlags & ACTOR_AUDIO_FLAG_SEQ_MUSIC_BOX_HOUSE) {
         func_801A1FB4(SEQ_PLAYER_BGM_SUB, &actor->projectedPos, NA_BGM_MUSIC_BOX_HOUSE, 1500.0f);
     }
 
-    if (actor->audioFlags & 0x20) {
+    if (actor->audioFlags & ACTOR_AUDIO_FLAG_SEQ_KAMARO_DANCE) {
         func_801A1FB4(SEQ_PLAYER_BGM_MAIN, &actor->projectedPos, NA_BGM_KAMARO_DANCE, 900.0f);
     }
 }
@@ -2866,8 +2893,8 @@ void Actor_DrawAll(PlayState* play, ActorContext* actorCtx) {
             SkinMatrix_Vec3fMtxFMultXYZW(&play->viewProjectionMtxF, &actor->world.pos, &actor->projectedPos,
                                          &actor->projectedW);
 
-            if (actor->audioFlags & 0x7F) {
-                func_800B9D1C(actor);
+            if (actor->audioFlags & ACTOR_AUDIO_FLAG_ALL) {
+                Actor_UpdateFlaggedAudio(actor);
             }
 
             if (func_800BA2D8(play, actor)) {