Overview

When adding custom music to an area, you will likely want to mute any vanilla music that might be playing. These methods are by no means exhaustive, but do list a few different ways to mute vanilla music. Each method will have slightly different benefits and drawbacks.

Stopping the main_backgroundtrack to mute vanilla music

The easiest method to mute vanilla music is to stop the main_backgroundtrack from playing with game_manager.music.main_backgroundtrack.playing = false. This completely mutes all music and ambience which may be undesirable for certain scenarios. Additionally the game may randomly restart the music, though the vanilla sound callback should catch most instances. By hooking the creation of the BGM_master sound using set_vanilla_sound_callback, you won't need to create any POST_UPDATE callbacks.

set_vanilla_sound_callback(VANILLA_SOUND.BGM_BGM_MASTER, VANILLA_SOUND_CALLBACK_TYPE.STARTED, function()
	game_manager.music.main_backgroundtrack.playing = false
end)

Note that you may want a nil check before setting game_manager.music.main_backgroundtrack.playing, since it will be nil if no music is currently playing.

This method will COMPLETELY mute all music and ambience. This includes normal music, dark level music, front and back layer ambience, ghost ambience, shop music, and anger music. Additionally, you can't use VANILLA_SOUND_CALLBACK_TYPE.STOPPED to automatically stop music, since setting game_manager.music.main_backgroundtrack.playing to false stops the music.

Abusing event polyphony and voice stealing to mute vanilla music

FMOD allows sound designers to specify a limit on the maximum number of instances of an event that can play at any given time. Spelunky 2's BGM_master event has voice stealing on. This means that once the number of instances playing exceeds the max instances property defined in FMOD Studio, older event instances will be forced to go virtual (i.e. mute and stops mixing) once a new instance is started.

-- Get the event description for event:/BGM/BGM_master using its FMOD GUID
event_desc = get_event_by_id("{c8e06fe2-f2df-4f57-87a8-1fb71733c925}")
-- Create a second instance of the BGM_master
inst = event_desc:createInstance()
--[[
Starting the instance will exceed the FMOD Studio max instances property of the BGM_master,
effectively muting it since the event has voice stealing enabled.
]]
inst:start()
--[[
We need to do a little bit more to completely mute the new instance.
Shop music is on a separate parameter sheet and will still play,
since the default value of current_shop_type is 0 which is valid.
]]
inst:setParameterByName("current_shop_type", 11)

Unmuting vanilla music is fairly simple and can be done by stopping the new BGM_master event instance, and optionally releasing it (if you no longer need to mute vanilla music).

-- Unmuting the original BGM_master can be done by stopping and releasing our event instance
inst:release()
inst:stop()
inst = nil

The same event instance can simply be started again to mute any older instances. One benefit of muting vanilla music this way is that once the new event instance is stopped, the older instance will not start playing from the beginning and instead unmute.