Mod Loader/Reference/Soundtrack API

These methods change the rotating playlist used by MusicController.PlayNext. They do not affect quest character themes, special music, or the ending theme.

Wait for the music controller

The controller may not exist when your plugin starts. Use WhenReady before reading or changing the playlist. Call the API on Unity's main thread.

using System;
using System.IO;
using BepInEx;
using DressmakerMods;
using UnityEngine;

[BepInPlugin("example.music", "Example Music", "1.0.0")]
[BepInDependency("yuu.dressmaker.mods")]
public sealed class ExampleMusic : BaseUnityPlugin
{
    private IDisposable ready;
    private IDisposable addedTrack;
    private IDisposable hiddenTrack;
    private AssetBundle bundle;

    private void Start()
    {
        bundle = AssetBundle.LoadFromFile(
            Path.Combine(Paths.PluginPath, "ExampleMusic", "music"));
        AudioClip clip = bundle?.LoadAsset<AudioClip>("MainTheme");
        ready = SoundtrackModApi.WhenReady(() =>
        {
            AudioClip[] originals = SoundtrackModApi.GetOriginalTracks();
            if (originals.Length > 0)
                hiddenTrack = SoundtrackModApi.SuppressTrack(originals[0]);

            if (clip != null)
                addedTrack = SoundtrackModApi.RegisterTrack("example.music.theme", clip);
        });
    }

    private void OnDestroy()
    {
        ready?.Dispose();
        hiddenTrack?.Dispose();
        addedTrack?.Dispose();
        bundle?.Unload(false);
    }
}

Methods and properties

bool IsReady: True after the music controller has been created.
IDisposable WhenReady(Action callback): Runs the callback when the controller is ready, or immediately if it already is. Dispose the returned handle to cancel a callback that has not run.
AudioClip[] GetOriginalTracks(): Returns a copy of the game's original rotating tracks. Returns an empty array before the controller is ready.
AudioClip[] GetTracks(): Returns a copy of the current playlist. Returns an empty array before the controller is ready.
IDisposable RegisterTrack(string id, AudioClip clip): Adds a clip to the playlist. IDs must be unique across loaded plugins. Dispose the handle to remove the track.
bool RemoveTrack(string id): Removes a track added through this API. Returns false if the ID is unknown. Disposing its registration after removal is safe.
IDisposable SuppressTrack(AudioClip clip): Hides that clip from the rotating playlist until the handle is disposed. If several plugins suppress the same clip, all handles must be disposed before it returns.

Playlist edits apply on the next track selection; the current track finishes normally. Keep each registered clip and its AssetBundle loaded while the clip is in use.

Back to the Mod Loader guide