From 349da0484bd00835de6c6198c1da31d42ebca966 Mon Sep 17 00:00:00 2001
From: Josh <32826900+ShinyDragonHunter@users.noreply.github.com>
Date: Sat, 27 Dec 2025 01:11:40 +0000
Subject: [PATCH] Document m4a xcmd_0C

---
 constants/m4a_constants.inc |  2 +-
 include/gba/m4a_internal.h  |  8 ++++----
 src/m4a.c                   | 18 +++++++++---------
 src/m4a_tables.c            |  7 ++++---
 4 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/constants/m4a_constants.inc b/constants/m4a_constants.inc
index 2599b6c4aa..73f98f31f7 100644
--- a/constants/m4a_constants.inc
+++ b/constants/m4a_constants.inc
@@ -181,7 +181,7 @@
 	struct_field o_MusicPlayerTrack_ToneData_sustain, 1
 	struct_field o_MusicPlayerTrack_ToneData_release, 1
 	struct_field o_MusicPlayerTrack_gap, 10
-	struct_field o_MusicPlayerTrack_unk_3A, 2
+	struct_field o_MusicPlayerTrack_timer, 2
 	struct_field o_MusicPlayerTrack_unk_3C, 4
 	struct_field o_MusicPlayerTrack_cmdPtr, 4
 	struct_field o_MusicPlayerTrack_patternStack, 12
diff --git a/include/gba/m4a_internal.h b/include/gba/m4a_internal.h
index 5c3a0872ce..90e5e421a8 100644
--- a/include/gba/m4a_internal.h
+++ b/include/gba/m4a_internal.h
@@ -257,8 +257,8 @@ struct PokemonCrySong
     u8 tieCmd; // 0x29
     u8 tieKeyValue; // 0x2A
     u8 tieVelocityValue; // 0x2B
-    u8 unkCmd0C[2]; // 0x2C
-    u16 unkCmd0CParam; // 0x2E
+    u8 xwaitCmd[2]; // 0x2C
+    u16 length; // 0x2E
     u8 end[2]; // 0x30
 };
 
@@ -306,7 +306,7 @@ struct MusicPlayerTrack
     struct SoundChannel *chan;
     struct ToneData tone;
     u8 gap[10];
-    u16 unk_3A;
+    u16 timer;
     u32 unk_3C;
     u8 *cmdPtr;
     u8 *patternStack[3];
@@ -495,7 +495,7 @@ void ply_xiecv(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
 void ply_xiecl(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
 void ply_xleng(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
 void ply_xswee(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
-void ply_xcmd_0C(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
+void ply_xwait(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
 void ply_xcmd_0D(struct MusicPlayerInfo *, struct MusicPlayerTrack *);
 
 #endif // GUARD_GBA_M4A_INTERNAL_H
diff --git a/src/m4a.c b/src/m4a.c
index 33f20455f3..1a2d541887 100644
--- a/src/m4a.c
+++ b/src/m4a.c
@@ -1612,26 +1612,26 @@ void ply_xswee(struct MusicPlayerInfo *mplayInfo, struct MusicPlayerTrack *track
     track->cmdPtr++;
 }
 
-void ply_xcmd_0C(struct MusicPlayerInfo *mplayInfo, struct MusicPlayerTrack *track)
+void ply_xwait(struct MusicPlayerInfo *mplayInfo, struct MusicPlayerTrack *track)
 {
-    u32 unk;
+    u32 len;
 
 #ifdef UBFIX
-    unk = 0;
+    len = 0;
 #endif
 
-    READ_XCMD_BYTE(unk, 0) // UB: uninitialized variable
-    READ_XCMD_BYTE(unk, 1)
+    READ_XCMD_BYTE(len, 0) // UB: uninitialized variable
+    READ_XCMD_BYTE(len, 1)
 
-    if (track->unk_3A < (u16)unk)
+    if (track->timer < (u16)len)
     {
-        track->unk_3A++;
+        track->timer++;
         track->cmdPtr -= 2;
         track->wait = 1;
     }
     else
     {
-        track->unk_3A = 0;
+        track->timer = 0;
         track->cmdPtr += 2;
     }
 }
@@ -1719,7 +1719,7 @@ void SetPokemonCryPitch(s16 val)
 
 void SetPokemonCryLength(u16 val)
 {
-    gPokemonCrySong.unkCmd0CParam = val;
+    gPokemonCrySong.length = val;
 }
 
 void SetPokemonCryRelease(u8 val)
diff --git a/src/m4a_tables.c b/src/m4a_tables.c
index 5bc1075494..1f339b060f 100644
--- a/src/m4a_tables.c
+++ b/src/m4a_tables.c
@@ -251,6 +251,7 @@ const u8 gClockTable[] =
 #define xRELE  0x07
 #define xIECV  0x08
 #define xIECL  0x09
+#define xWAIT  0x0c
 
 #define EOT    0xce
 #define TIE    0xcf
@@ -282,8 +283,8 @@ const struct PokemonCrySong gPokemonCrySongTemplate =
     .tieCmd = TIE,
     .tieKeyValue = 60, // default is Cn3
     .tieVelocityValue = 127,
-    .unkCmd0C = {XCMD, 0x0C},
-    .unkCmd0CParam = 60,
+    .xwaitCmd = {XCMD, xWAIT},
+    .length = 60, // frames to wait
     .end = {EOT, FINE}
 };
 
@@ -301,6 +302,6 @@ const XcmdFunc gXcmdTable[] =
     ply_xiecl,
     ply_xleng,
     ply_xswee,
-    ply_xcmd_0C,
+    ply_xwait,
     ply_xcmd_0D,
 };