Document code_8006BA00 (Audio Sound Sources) (#997)

* Document SoundSources

* PR Suggestions

* Duration timers to dec

* `PlaySfxByPosAndId` -> `PlaySoundByPosition`

* Improve names

* `PlaySfxAtStationaryPosition` -> `PlaySfxAtFixedWorldPos` and `originWorldPos` -> `worldPos`

* format

3 files changed, 14 insertions, 12 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 7f77064c6..a46fdb52f 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -2986,7 +2986,7 @@ Actor* Actor_Find(ActorContext* actorCtx, s32 actorId, s32 actorCategory) {
  */
 void Enemy_StartFinishingBlow(GlobalContext* globalCtx, Actor* actor) {
     globalCtx->actorCtx.freezeFlashTimer = 5;
-    Audio_PlaySoundAtPosition(globalCtx, &actor->world.pos, 20, NA_SE_EN_LAST_DAMAGE);
+    SoundSource_PlaySfxAtFixedWorldPos(globalCtx, &actor->world.pos, 20, NA_SE_EN_LAST_DAMAGE);
 }
 
 s16 func_80032CB4(s16* arg0, s16 arg1, s16 arg2, s16 arg3) {
diff --git a/src/code/z_play.c b/src/code/z_play.c
index 787bbb186..672eb0b14 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -228,7 +228,7 @@ void Gameplay_Init(GameState* thisx) {
     func_80112098(globalCtx);
     Message_Init(globalCtx);
     GameOver_Init(globalCtx);
-    func_8006BA00(globalCtx);
+    SoundSource_InitAll(globalCtx);
     Effect_InitContext(globalCtx);
     EffectSs_InitInfo(globalCtx, 0x55);
     CollisionCheck_InitContext(globalCtx, &globalCtx->colChkCtx);
@@ -975,7 +975,7 @@ void Gameplay_Update(GlobalContext* globalCtx) {
                 LOG_NUM("1", 1, "../z_play.c", 3771);
             }
 
-            func_8006BA30(globalCtx);
+            SoundSource_UpdateAll(globalCtx);
 
             if (1 && HREG(63)) {
                 LOG_NUM("1", 1, "../z_play.c", 3777);
diff --git a/src/code/code_8006BA00.c b/src/code/z_sound_source.c
index 9cc18bfa5..ce54ee393 100644
--- a/src/code/code_8006BA00.c
+++ b/src/code/z_sound_source.c
@@ -1,6 +1,6 @@
 #include "global.h"
 
-void func_8006BA00(GlobalContext* globalCtx) {
+void SoundSource_InitAll(GlobalContext* globalCtx) {
     SoundSource* sources = &globalCtx->soundSources[0];
     s32 i;
 
@@ -9,16 +9,16 @@ void func_8006BA00(GlobalContext* globalCtx) {
     // clang-format on
 }
 
-void func_8006BA30(GlobalContext* globalCtx) {
+void SoundSource_UpdateAll(GlobalContext* globalCtx) {
     SoundSource* source = &globalCtx->soundSources[0];
     s32 i;
 
     for (i = 0; i < ARRAY_COUNT(globalCtx->soundSources); i++) {
         if (source->countdown != 0) {
             if (DECR(source->countdown) == 0) {
-                Audio_StopSfxByPos(&source->relativePos);
+                Audio_StopSfxByPos(&source->projectedPos);
             } else {
-                SkinMatrix_Vec3fMtxFMultXYZ(&globalCtx->viewProjectionMtxF, &source->originPos, &source->relativePos);
+                SkinMatrix_Vec3fMtxFMultXYZ(&globalCtx->viewProjectionMtxF, &source->worldPos, &source->projectedPos);
             }
         }
 
@@ -26,7 +26,7 @@ void func_8006BA30(GlobalContext* globalCtx) {
     }
 }
 
-void Audio_PlaySoundAtPosition(GlobalContext* globalCtx, Vec3f* pos, s32 duration, u16 sfxId) {
+void SoundSource_PlaySfxAtFixedWorldPos(GlobalContext* globalCtx, Vec3f* worldPos, s32 duration, u16 sfxId) {
     s32 countdown;
     SoundSource* source;
     s32 smallestCountdown = 0xFFFF;
@@ -39,6 +39,7 @@ void Audio_PlaySoundAtPosition(GlobalContext* globalCtx, Vec3f* pos, s32 duratio
             break;
         }
 
+        // Store the sound source with the smallest remaining countdown
         countdown = source->countdown;
         if (countdown < smallestCountdown) {
             smallestCountdown = countdown;
@@ -47,14 +48,15 @@ void Audio_PlaySoundAtPosition(GlobalContext* globalCtx, Vec3f* pos, s32 duratio
         source++;
     }
 
+    // If no sound source is available, replace the sound source with the smallest remaining countdown
     if (i >= ARRAY_COUNT(globalCtx->soundSources)) {
         source = backupSource;
-        Audio_StopSfxByPos(&source->relativePos);
+        Audio_StopSfxByPos(&source->projectedPos);
     }
 
-    source->originPos = *pos;
+    source->worldPos = *worldPos;
     source->countdown = duration;
 
-    SkinMatrix_Vec3fMtxFMultXYZ(&globalCtx->viewProjectionMtxF, &source->originPos, &source->relativePos);
-    Audio_PlaySoundGeneral(sfxId, &source->relativePos, 4, &D_801333E0, &D_801333E0, &D_801333E8);
+    SkinMatrix_Vec3fMtxFMultXYZ(&globalCtx->viewProjectionMtxF, &source->worldPos, &source->projectedPos);
+    Audio_PlaySoundGeneral(sfxId, &source->projectedPos, 4, &D_801333E0, &D_801333E0, &D_801333E8);
 }