Callbacks: What to use and when to use it

There are 3 main callback types (not including legacy)

• OnTrack
• OnMusic
• OnPlay

All callbacks take a track name and a music ID. If you ever have trouble figuring out what tracks to look out for, type

lua MusicAPI.ShowDebugInfo = true

in the console, and the text under MusicAPI Queue will show you what tracks are playing.

---

OnTrack

OnTrack callbacks are called when adding a track to the queue. They are useful if you have a new situation (like a new room type or boss) and want to tell the API we are in that situation. For example, let's say you add a new special room type that has a chance of replacing a shop (let's call it a golden shop). You would add a new track for your room, and then add a callback that looks for the track "ROOM_SHOP" and replaces it with the one you added. (You can call the track whatever you want, it may even be a good idea to put your username or your mod's name in it.)

Below are some examples using this callback. Returning nil in these callbacks means you do not want to change the track, and MusicAPI will continue to other callbacks.

MusicAPI.AddTrack("ROOM_GOLDEN_SHOP", {
        Music = Isaac.GetMusicIdByName("custom golden shop theme"),
        Flags = {"ROOM", "MY_CUSTOM_FLAG"}
})

MusicAPI.AddOnTrackCallback(function(track, state)
        if track == "ROOM_SHOP" and RoomIsGoldenShop() then --RoomIsGoldenShop defined somewhere else in the mod
                return "ROOM_GOLDEN_SHOP"
        end
end)

By default, if you return a new track then further callbacks will stop. You can allow further callbacks to run by returning true after the track, like so:

return "ROOM_GOLDEN_SHOP", true

Here's another example, but I add a jingle if the player visits a golden shop for the first time. Multiple tracks have to be encased in a table.

MusicAPI.AddTrack("ROOM_GOLDEN_SHOP", {
        Music = Isaac.GetMusicIdByName("custom golden shop theme"),
        Flags = {"ROOM", "MY_CUSTOM_FLAG"}
})

MusicAPI.AddTrack("JINGLE_GOLDEN_SHOP", {
        Music = Isaac.GetMusicIdByName("custom golden shop jingle"),
        Flags = {"JINGLE", "MY_CUSTOM_FLAG"}
})

MusicAPI.AddOnTrackCallback(function(track, state)
        if track == "ROOM_SHOP" and RoomIsGoldenShop() then --RoomIsGoldenShop defined somewhere else in the mod
                if Game():GetRoom():IsFirstVisit() then
                        return {"JINGLE_GOLDEN_SHOP", "ROOM_GOLDEN_SHOP"}
                else
                        return "ROOM_GOLDEN_SHOP"
                end
        end
end)

OnMusic

OnMusic callbacks are run when the API needs to get the actual music ID for a track to play it. If you want to simply use a different music ID than the one assigned to a track, use this. New music IDs returned in this callback will play in the same way the original would, for example some jingles play instantly rather than fading.

Here I add a callback to play a unique treasure room jingle if my modded item has spawned. With this callback type you can check the track or the music ID.

MusicAPI.AddOnMusicCallback(function(track, musicID)
        if track == "JINGLE_TREASURE_ROOM" then
                if #Isaac.FindByType(5, 350, myCollectibleId) > 0 then
                        return Isaac.GetMusicIdByName("jingle for finding my modded item")
                end
        end
end)

OnPlay

OnPlay callbacks are run when a music ID is played. Use these if you want to know what's playing, and when it happens. Returning values here does nothing.

MusicAPI.AddOnPlayCallback(function(track, musicID)
        Isaac.ConsoleOutput("Now playing:\n Track: "..track.."\n ID: "..musicID.."\n")
end)