From f6f5434dda9b23113d3705e3a4df797d2b4d31d9 Mon Sep 17 00:00:00 2001
From: Blockyyy <88585273+Blockyyy@users.noreply.github.com>
Date: Fri, 20 Feb 2026 01:34:25 +0100
Subject: [PATCH] set_sound_bank_override (#1046)

---
 autogen/convert_functions.py          |  2 ++
 autogen/lua_definitions/functions.lua |  6 ++++++
 docs/lua/functions-4.md               | 29 +++++++++++++++++++++++++++
 docs/lua/functions.md                 |  5 +++++
 src/audio/load.c                      | 11 ++++++++++
 src/audio/load.h                      |  4 ++++
 src/pc/lua/smlua_functions_autogen.c  | 25 +++++++++++++++++++++++
 src/pc/lua/utils/smlua_audio_utils.c  |  3 +++
 src/pc/network/network.c              |  2 ++
 9 files changed, 87 insertions(+)

diff --git a/autogen/convert_functions.py b/autogen/convert_functions.py
index 5f2cb8aea..8846db56f 100644
--- a/autogen/convert_functions.py
+++ b/autogen/convert_functions.py
@@ -80,6 +80,7 @@ in_files = [
     "src/audio/seqplayer.h",
     "src/engine/lighting_engine.h",
     "src/pc/network/sync_object.h",
+    "src/audio/load.h",
 ]
 
 override_allowed_functions = {
@@ -99,6 +100,7 @@ override_allowed_functions = {
     "src/game/ingame_menu.h":               [ "set_min_dialog_width", "set_dialog_override_pos", "reset_dialog_override_pos", "set_dialog_override_color", "reset_dialog_override_color", "set_menu_mode", "create_dialog_box", "create_dialog_box_with_var", "create_dialog_inverted_box", "create_dialog_box_with_response", "reset_dialog_render_state", "set_dialog_box_state", "handle_special_dialog_text" ],
     "src/audio/seqplayer.h":                [ "sequence_player_set_tempo", "sequence_player_set_tempo_acc", "sequence_player_set_transposition", "sequence_player_get_tempo", "sequence_player_get_tempo_acc", "sequence_player_get_transposition", "sequence_player_get_volume", "sequence_player_get_fade_volume", "sequence_player_get_mute_volume_scale" ],
     "src/pc/network/sync_object.h":         [ "sync_object_is_initialized", "sync_object_is_owned_locally", "sync_object_get_object" ],
+    "src/audio/load.h":                     [ "set_sound_bank_override" ],
 }
 
 override_disallowed_functions = {
diff --git a/autogen/lua_definitions/functions.lua b/autogen/lua_definitions/functions.lua
index 29ab49c53..f7b0aa63d 100644
--- a/autogen/lua_definitions/functions.lua
+++ b/autogen/lua_definitions/functions.lua
@@ -5240,6 +5240,12 @@ function le_set_light_use_surface_normals(id, useSurfaceNormals)
     -- ...
 end
 
+--- @param bank integer
+--- Overrides the soundbank, set to -1 to reset
+function set_sound_bank_override(bank)
+    -- ...
+end
+
 --- @param m MarioState
 --- @return integer
 --- Checks if Mario's current animation has reached its final frame (i.e., the last valid frame in the animation). Useful for deciding when to transition out of an animation-driven action
diff --git a/docs/lua/functions-4.md b/docs/lua/functions-4.md
index 18fa49891..6c8cb8c8b 100644
--- a/docs/lua/functions-4.md
+++ b/docs/lua/functions-4.md
@@ -583,6 +583,35 @@ Sets whether a lighting engine point light will use a surface's normals to deter
 
 <br />
 
+---
+# functions from load.h
+
+<br />
+
+
+## [set_sound_bank_override](#set_sound_bank_override)
+
+### Description
+Overrides the soundbank, set to -1 to reset
+
+### Lua Example
+`set_sound_bank_override(bank)`
+
+### Parameters
+| Field | Type |
+| ----- | ---- |
+| bank | `integer` |
+
+### Returns
+- None
+
+### C Prototype
+`void set_sound_bank_override(s32 bank);`
+
+[:arrow_up_small:](#)
+
+<br />
+
 ---
 # functions from mario.h
 
diff --git a/docs/lua/functions.md b/docs/lua/functions.md
index 6407c26ed..e2f94b46b 100644
--- a/docs/lua/functions.md
+++ b/docs/lua/functions.md
@@ -997,6 +997,11 @@
 
 <br />
 
+- load.h
+   - [set_sound_bank_override](functions-4.md#set_sound_bank_override)
+
+<br />
+
 - mario.h
    - [is_anim_at_end](functions-4.md#is_anim_at_end)
    - [is_anim_past_end](functions-4.md#is_anim_past_end)
diff --git a/src/audio/load.c b/src/audio/load.c
index 14498b196..9ad0a479b 100644
--- a/src/audio/load.c
+++ b/src/audio/load.c
@@ -1481,6 +1481,13 @@ u8 get_missing_bank(u32 seqId, s32 *nonNullCount, s32 *nullCount) {
 #endif
 
 #ifndef VERSION_SH
+
+s32 gOverrideBank = -1;
+
+void set_sound_bank_override(s32 bank) {
+    gOverrideBank = bank;
+}
+
 struct AudioBank *load_banks_immediate(s32 seqId, u8 *arg1) {
     void *ret = NULL;
     u32 bankId = 0;
@@ -1498,6 +1505,10 @@ struct AudioBank *load_banks_immediate(s32 seqId, u8 *arg1) {
         bankId = gAlBankSets[offset - 1];
 #endif
 
+        if (gOverrideBank > 0) {
+            bankId = gOverrideBank;
+        }
+
         if (IS_BANK_LOAD_COMPLETE(bankId) == TRUE) {
 #ifdef VERSION_EU
             ret = get_bank_or_seq(&gBankLoadedPool, 2, bankId);
diff --git a/src/audio/load.h b/src/audio/load.h
index 36ad4ecf4..df8bb55aa 100644
--- a/src/audio/load.h
+++ b/src/audio/load.h
@@ -53,6 +53,7 @@ extern s32 gMinAiBufferLength;
 extern s16 gTempoInternalToExternal;
 extern s8 gAudioUpdatesPerFrame; // = 4
 extern s8 gSoundMode;
+extern s32 gOverrideBank;
 
 #ifdef VERSION_SH
 extern OSMesgQueue gUnkQueue1;
@@ -95,6 +96,9 @@ void preload_sequence(u32 seqId, u8 preloadMask);
 #endif
 void load_sequence(u32 player, u32 seqId, s32 loadAsync);
 
+/* |description|Overrides the soundbank, set to -1 to reset|descriptionEnd| */
+void set_sound_bank_override(s32 bank);
+
 #ifdef VERSION_SH
 void func_sh_802f3158(s32 index, s32 arg1, s32 arg2, OSMesgQueue *retQueue);
 u8 *func_sh_802f3220(u32 index, u32 *a1);
diff --git a/src/pc/lua/smlua_functions_autogen.c b/src/pc/lua/smlua_functions_autogen.c
index 559c81c63..c4b6b4f0e 100644
--- a/src/pc/lua/smlua_functions_autogen.c
+++ b/src/pc/lua/smlua_functions_autogen.c
@@ -54,6 +54,7 @@
 #include "src/audio/seqplayer.h"
 #include "src/engine/lighting_engine.h"
 #include "src/pc/network/sync_object.h"
+#include "src/audio/load.h"
 
 
   ///////////////
@@ -15889,6 +15890,27 @@ int smlua_func_le_set_light_use_surface_normals(lua_State* L) {
     return 1;
 }
 
+  ////////////
+ // load.h //
+////////////
+
+int smlua_func_set_sound_bank_override(lua_State* L) {
+    if (L == NULL) { return 0; }
+
+    int top = lua_gettop(L);
+    if (top != 1) {
+        LOG_LUA_LINE("Improper param count for '%s': Expected %u, Received %u", "set_sound_bank_override", 1, top);
+        return 0;
+    }
+
+    s32 bank = smlua_to_integer(L, 1);
+    if (!gSmLuaConvertSuccess) { LOG_LUA("Failed to convert parameter %u for function '%s'", 1, "set_sound_bank_override"); return 0; }
+
+    set_sound_bank_override(bank);
+
+    return 1;
+}
+
   /////////////
  // mario.h //
 /////////////
@@ -37575,6 +37597,9 @@ void smlua_bind_functions_autogen(void) {
     smlua_bind_function(L, "le_get_light_use_surface_normals", smlua_func_le_get_light_use_surface_normals);
     smlua_bind_function(L, "le_set_light_use_surface_normals", smlua_func_le_set_light_use_surface_normals);
 
+    // load.h
+    smlua_bind_function(L, "set_sound_bank_override", smlua_func_set_sound_bank_override);
+
     // mario.h
     smlua_bind_function(L, "is_anim_at_end", smlua_func_is_anim_at_end);
     smlua_bind_function(L, "is_anim_past_end", smlua_func_is_anim_past_end);
diff --git a/src/pc/lua/utils/smlua_audio_utils.c b/src/pc/lua/utils/smlua_audio_utils.c
index e692476f4..80aeca7fc 100644
--- a/src/pc/lua/utils/smlua_audio_utils.c
+++ b/src/pc/lua/utils/smlua_audio_utils.c
@@ -18,6 +18,7 @@
 #include "pc/debuglog.h"
 #include "pc/pc_main.h"
 #include "pc/fs/fmem.h"
+#include "audio/load.h"
 
 struct AudioOverride {
     bool enabled;
@@ -73,6 +74,8 @@ bool smlua_audio_utils_override(u8 sequenceId, s32* bankId, void** seqData) {
     struct AudioOverride* override = &sAudioOverrides[sequenceId];
     if (!override->enabled) { return false; }
 
+    if (gOverrideBank > -1) { override->bank = gOverrideBank; }
+
     if (override->loaded) {
         *seqData = override->buffer;
         *bankId = override->bank;
diff --git a/src/pc/network/network.c b/src/pc/network/network.c
index d267d7cb8..6bd1d4882 100644
--- a/src/pc/network/network.c
+++ b/src/pc/network/network.c
@@ -36,6 +36,7 @@
 #include "game/mario.h"
 #include "engine/math_util.h"
 #include "engine/lighting_engine.h"
+#include "src/audio/load.h"
 
 #ifdef DISCORD_SDK
 #include "pc/discord/discord.h"
@@ -711,6 +712,7 @@ void network_shutdown(bool sendLeaving, bool exiting, bool popup, bool reconnect
     gOverrideFar = 0;
     gOverrideFOV = 0;
     gRoomOverride = -1;
+    gOverrideBank = -1;
     gCurrActStarNum = 0;
     gCurrActNum = 0;
     gCurrCreditsEntry = NULL;