From 844785f850a3af7dc0a09da1134d81a3f2b514ea Mon Sep 17 00:00:00 2001
From: Squeetz <alenyla@hotmail.com>
Date: Sun, 22 Mar 2026 14:31:21 +0100
Subject: [PATCH] Document m4a xcmd 12 (#699)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Waits n frames. Used by Pokémon cries.
---
 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 1a744dc7f..3add62175 100644
--- a/constants/m4a_constants.inc
+++ b/constants/m4a_constants.inc
@@ -178,7 +178,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 fa509e511..609259b03 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 00d66f8fc..ebd3afe29 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 55eae171f..286e938ba 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
@@ -283,8 +284,8 @@ const struct PokemonCrySong gPokemonCrySongTemplate =
     TIE,
     60, // TIE key (default is Cn3)
     127, // TIE velocity
-    {XCMD, 0x0C},
-    60, // unk value
+    {XCMD, xWAIT},
+    60, // frames to wait
     {EOT, FINE} // end
 };
 
@@ -302,6 +303,6 @@ const XcmdFunc gXcmdTable[] =
     ply_xiecl,
     ply_xleng,
     ply_xswee,
-    ply_xcmd_0C,
+    ply_xwait,
     ply_xcmd_0D,
 };