From 7ec6c77e1c6d91cfa11cb646073e1db20d9f7594 Mon Sep 17 00:00:00 2001
From: ThePlayerRolo <thesolis78243@gmail.com>
Date: Thu, 19 Mar 2026 18:14:24 -0400
Subject: [PATCH] Implement smlua_audio_utils_allocate_sequence() (#891)

---
 autogen/lua_definitions/functions.lua |  6 ++++++
 docs/lua/functions-6.md               | 21 +++++++++++++++++++++
 docs/lua/functions.md                 |  1 +
 src/pc/lua/smlua_functions_autogen.c  | 16 ++++++++++++++++
 src/pc/lua/utils/smlua_audio_utils.c  | 10 ++++++++++
 src/pc/lua/utils/smlua_audio_utils.h  |  2 ++
 6 files changed, 56 insertions(+)

diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index c716033b3..08b0b1587 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -10208,6 +10208,12 @@ function smlua_audio_utils_replace_sequence(sequenceId, bankId, defaultVolume, m
     -- ...
 end
 
+--- @return integer
+--- Allocates a new sequence ID
+function smlua_audio_utils_allocate_sequence()
+    -- ...
+end
+
 --- @param filename string
 --- @return ModAudio
 --- Loads an `audio` stream by `filename` (with extension)
diff --git a/docs/lua/functions-6.md b/docs/lua/functions-6.md
index 41b220737..a639b7db9 100644
--- a/docs/lua/functions-6.md
+++ b/docs/lua/functions-6.md
@@ -5616,6 +5616,27 @@ Replaces the sequence corresponding to `sequenceId` with one called `m64Name`.m6
 
 <br />
 
+## [smlua_audio_utils_allocate_sequence](#smlua_audio_utils_allocate_sequence)
+
+### Description
+Allocates a new sequence ID
+
+### Lua Example
+`local integerValue = smlua_audio_utils_allocate_sequence()`
+
+### Parameters
+- None
+
+### Returns
+- `integer`
+
+### C Prototype
+`u8 smlua_audio_utils_allocate_sequence(void);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ## [audio_stream_load](#audio_stream_load)
 
 ### Description
diff --git a/docs/lua/functions.md b/docs/lua/functions.md
index ecce742d3..b463ac63e 100644
--- a/docs/lua/functions.md
+++ b/docs/lua/functions.md
@@ -1828,6 +1828,7 @@
 - smlua_audio_utils.h
    - [smlua_audio_utils_reset_all](functions-6.md#smlua_audio_utils_reset_all)
    - [smlua_audio_utils_replace_sequence](functions-6.md#smlua_audio_utils_replace_sequence)
+   - [smlua_audio_utils_allocate_sequence](functions-6.md#smlua_audio_utils_allocate_sequence)
    - [audio_stream_load](functions-6.md#audio_stream_load)
    - [audio_stream_destroy](functions-6.md#audio_stream_destroy)
    - [audio_stream_play](functions-6.md#audio_stream_play)
diff --git a/src/pc/lua/smlua_functions_autogen.c b/src/pc/lua/smlua_functions_autogen.c
index 70d040309..54bb0672b 100644
--- a/src/pc/lua/smlua_functions_autogen.c
+++ b/src/pc/lua/smlua_functions_autogen.c
@@ -30424,6 +30424,21 @@ int smlua_func_smlua_audio_utils_replace_sequence(lua_State* L) {
     return 1;
 }
 
+int smlua_func_smlua_audio_utils_allocate_sequence(UNUSED lua_State* L) {
+    if (L == NULL) { return 0; }
+
+    int top = lua_gettop(L);
+    if (top != 0) {
+        LOG_LUA_LINE("Improper param count for '%s': Expected %u, Received %u", "smlua_audio_utils_allocate_sequence", 0, top);
+        return 0;
+    }
+
+
+    lua_pushinteger(L, smlua_audio_utils_allocate_sequence());
+
+    return 1;
+}
+
 int smlua_func_audio_stream_load(lua_State* L) {
     if (L == NULL) { return 0; }
 
@@ -38470,6 +38485,7 @@ void smlua_bind_functions_autogen(void) {
     // smlua_audio_utils.h
     smlua_bind_function(L, "smlua_audio_utils_reset_all", smlua_func_smlua_audio_utils_reset_all);
     smlua_bind_function(L, "smlua_audio_utils_replace_sequence", smlua_func_smlua_audio_utils_replace_sequence);
+    smlua_bind_function(L, "smlua_audio_utils_allocate_sequence", smlua_func_smlua_audio_utils_allocate_sequence);
     smlua_bind_function(L, "audio_stream_load", smlua_func_audio_stream_load);
     smlua_bind_function(L, "audio_stream_destroy", smlua_func_audio_stream_destroy);
     smlua_bind_function(L, "audio_stream_play", smlua_func_audio_stream_play);
diff --git a/src/pc/lua/utils/smlua_audio_utils.c b/src/pc/lua/utils/smlua_audio_utils.c
index 80aeca7fc..9b02de52e 100644
--- a/src/pc/lua/utils/smlua_audio_utils.c
+++ b/src/pc/lua/utils/smlua_audio_utils.c
@@ -173,6 +173,16 @@ void smlua_audio_utils_replace_sequence(u8 sequenceId, u8 bankId, u8 defaultVolu
     LOG_LUA_LINE("Could not find m64 at path: %s", m64path);
 }
 
+u8 smlua_audio_utils_allocate_sequence(void) {
+    for (u8 seqId = SEQ_COUNT + 1; seqId < MAX_AUDIO_OVERRIDE; seqId++) {
+        if (!sAudioOverrides[seqId].enabled) {
+            return seqId;
+        }
+    }
+    LOG_ERROR("Cannot allocate more custom sequences.");
+    return MAX_AUDIO_OVERRIDE;
+}
+
   ///////////////
  // mod audio //
 ///////////////
diff --git a/src/pc/lua/utils/smlua_audio_utils.h b/src/pc/lua/utils/smlua_audio_utils.h
index deca8b0d0..93696c80d 100644
--- a/src/pc/lua/utils/smlua_audio_utils.h
+++ b/src/pc/lua/utils/smlua_audio_utils.h
@@ -8,6 +8,8 @@ void smlua_audio_utils_reset_all(void);
 bool smlua_audio_utils_override(u8 sequenceId, s32* bankId, void** seqData);
 /* |description|Replaces the sequence corresponding to `sequenceId` with one called `m64Name`.m64 with `bankId` and `defaultVolume`|descriptionEnd| */
 void smlua_audio_utils_replace_sequence(u8 sequenceId, u8 bankId, u8 defaultVolume, const char* m64Name);
+/* |description|Allocates a new sequence ID|descriptionEnd| */
+u8 smlua_audio_utils_allocate_sequence(void);
 
   ////////////////
  // mod sounds //