Necropolis Music Modding Guide

🎵 Overview

This guide will teach you how to replace the music in Necropolis with your own custom tracks. No complex coding required - just a few lines of code and your Wwise project!

Table of Contents

1. What You Can Do
2. Prerequisites
3. Replacing Music
4. Abraxis Audio Methods
5. Music States Reference
6. Create Your BepInEx Plugin
7. Advanced Topics
8. API References
9. Tips For Success
10. Example Mod
11. Troubleshooting
12. Credits

What You Can Do

✅ Replace all game music with your own
✅ Create music for specific environments (swamp, ice cave, etc.)
✅ Have different music for exploration vs combat
✅ Run multiple music mods simultaneously
✅ Your music automatically respects the game's volume slider

Prerequisites

• Wwise 2015.1 (free from Audiokinetic's website)
• Basic C# knowledge (you'll write ~30 lines)
• BepInEx 5 installed in Necropolis
• Audio files for your music

Replacing Music (Environment-Aware)

Necropolis uses an environment-based music system. Different areas trigger different music based on AudioState_EnvironmentSet values.

Understanding Environment Music System

The game sets environment states like:

• Forest - Forest areas
• Foundry - Foundry areas
• Temple - Temple areas
• Hellscape - Hell areas
• Ice_Cave - Just the ice caves, not the ice areas
• Palace - Either an old/unused or very specific area that Im not aware of
• Swamp - Swamp areas
• Thunder - Also not sure on this one yet.
• Schism - Most of the default areas of the game.
• End_Space - I think its the area with the portal at the end?
• No_Set - UNSURE
• Report_Window - UNSURE

Music events are triggered based on combat state:

• Explore mode: Background exploration music
• Combat mode: Intense combat music

Available Music Switch Values

Each environment area has 5 available values to swap music-

From the Music_Switch:

• Title - Title screen
• Explore - Exploration mode, when you are walking around
• Combat - Combat mode, when you are fighting something
• Quiet - Quiet moments, this is normally not set to any music
• Credits - End credits

-Usually, only Explore and Combat are used between environments

Abraxis Audio Methods for Replacing Music

In Abraxis Audio, CustomWwiseAPI has helper methods to make music replacement easy-

MusicConfig

A MusicConfig is an easy way for the mod to get the name of your soundbank, then name of your events, and what environments you'd like it to play in

• When using a MusicConfig, you will need to register it, then you will be able to Enable/Disable it for playback

// This music only plays in Ice Cave
CustomWwiseAPI.RegisterMusicConfig(
   "name_of_music_config", //This is what you are going to call your Music Config, it can be anything, you will reference it later
   "custommusic",  //This is the name of your bnk, without the extension (.bnk)
   musicEvents, //This variable is your Dictionary of custom music, explained below
   new[] { "Ice_Cave", "Swamp" }  // List of what environments to play your custom music in
);

// Map music states to your events
var musicEvents = new Dictionary<AudioBankManager.MusicState, string>
{
   { AudioBankManager.MusicState.TITLE, "Custom_Music_Title" },
   { AudioBankManager.MusicState.EXPLORE, "Custom_Music_Explore" },
   { AudioBankManager.MusicState.COMBAT, "Custom_Music_Combat" }
};

And with your MusicConfig registered, all you have to do is enable it, and AbraxisAudio takes care of the rest!

//Now that its registered, you can enable it! The mod will now be checking environments and replace the music when necessary
CustomWwiseAPI.EnableMusicConfig("name_of_music_config");

Pattern 1: Replace All Music

// This is what you just did above - works everywhere!
CustomWwiseAPI.RegisterMusicConfig("my_music", "custommusic", musicEvents, null); //When environment is null, it means you want to play in all environments!
CustomWwiseAPI.EnableMusicConfig("my_music");

Pattern 2: Music for Specific Environments Only

// This music only plays in Ice Cave
CustomWwiseAPI.RegisterMusicConfig(
    "ice_music", 
    "icemusic", 
    iceEvents,
    new[] { "Ice_Cave" }  // Only this environment
);
CustomWwiseAPI.EnableMusicConfig("ice_music");

Valid environment names:

"Schism", "Forest", "Foundry", "Hellscape", "Ice_Cave", 
"Palace", "Swamp", "Temple", "Thunder", "End_Space" , "No_Set", "Report_Window"

Pattern 3: Multiple Music Mods at Once

Lets say you want to have different custom exploration and combat music for different sets of environments, well you can enable multiple music configs!

When you enable multiple music configs - the system picks the best match:

// Swamp-specific music
CustomWwiseAPI.RegisterMusicConfig("swamp_music", "swampbank", swampEvents, 
    new[] { "Swamp" });

// General fallback for everywhere else
CustomWwiseAPI.RegisterMusicConfig("general_music", "generalbank", generalEvents, 
    null);  // null = all environments

// Enable BOTH (order = priority)
CustomWwiseAPI.EnableMusicConfig("general_music");  // Lower priority
CustomWwiseAPI.EnableMusicConfig("swamp_music");    // Higher priority

// Result:
// - In Swamp → swamp_music plays
// - Everywhere else → general_music plays

Music States Reference

Map these states to your events:

You don't have to provide events for all states - unmapped states will default to the regular game music.

Create Your BepInEx Plugin

Before you can create your plugin, read the Setting up Your Sounds & Music in Wwise2015.1 guide, and make sure you know how to create a soundbank.

Create a new C# file in your mod folder:

using BepInEx;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using CustomWwiseSoundbanks;

[BepInPlugin("com.yourname.custommusic", "Custom Music", "1.0.0")]
[BepInDependency("com.necropolis.customwwisesoundbanks")]
public class CustomMusicPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        StartCoroutine(SetupMusic());
    }
    
    private IEnumerator SetupMusic()
    {
        // Wait for system to be ready
        while (!CustomWwiseAPI.IsReady)
            yield return new WaitForSeconds(0.5f);
            
        // Wait for your bank to load (it loads automatically!)
        while (!CustomWwiseAPI.IsBankLoaded("custommusic"))
            yield return new WaitForSeconds(0.5f);
        
        // Map music states to your events
        var musicEvents = new Dictionary<AudioBankManager.MusicState, string>
        {
            { AudioBankManager.MusicState.TITLE, "Custom_Music_Title" },
            { AudioBankManager.MusicState.EXPLORE, "Custom_Music_Explore" },
            { AudioBankManager.MusicState.COMBAT, "Custom_Music_Combat" }
        };
        
        // Register and enable your music!
        CustomWwiseAPI.RegisterMusicConfig("my_music", "custommusic", musicEvents, null);
        CustomWwiseAPI.EnableMusicConfig("my_music");
        
        Logger.LogInfo("Custom music activated!");
    }
}

Package Your Mod

Your mod folder should look like this:

BepInEx/
└── plugins/
    └── YourMusicMod/
        ├── YourMusicMod.dll
        └── custommusic.bnk

The system automatically finds and loads .bnk files from your plugin folder!

Advanced Topics

Playing Music for Exploration Only

var exploreOnlyEvents = new Dictionary<AudioBankManager.MusicState, string>
{
    { AudioBankManager.MusicState.EXPLORE, "Custom_Explore" }
    // No combat music - game will use its combat music
};

CustomWwiseAPI.RegisterMusicConfig("explore_only", "explorebank", exploreOnlyEvents, null);
CustomWwiseAPI.EnableMusicConfig("explore_only");

Runtime Control

Enable/disable music dynamically:

private void Update()
{
    // Press F9 to toggle music
    if (Input.GetKeyDown(KeyCode.F9))
    {
        if (CustomWwiseAPI.IsConfigEnabled("my_music"))
        {
            CustomWwiseAPI.DisableMusicConfig("my_music");
            Logger.LogInfo("Music disabled");
        }
        else
        {
            CustomWwiseAPI.EnableMusicConfig("my_music");
            Logger.LogInfo("Music enabled");
        }
    }
}

File Structure

Your mod should be organized like this:

# After building, copy to game:
Necropolis/
└── BepInEx/
    └── plugins/
        └── YourMusicMod/
            ├── YourMusicMod.dll
            └── custommusic.bnk   # Your soundbank, can be anywhere in your mod's folder

API Reference

RegisterMusicConfig

CustomWwiseAPI.RegisterMusicConfig(
    string configId,                              // Unique ID: "my_music"
    string bankName,                              // Bank name: "custommusic"
    Dictionary<MusicState, string> musicEvents,   // State → Event mapping
    string[] allowedEnvironments                  // null = everywhere, or specific environments
);

EnableMusicConfig

CustomWwiseAPI.EnableMusicConfig("my_music");

DisableMusicConfig

CustomWwiseAPI.DisableMusicConfig("my_music");

Check Status

bool enabled = CustomWwiseAPI.IsConfigEnabled("my_music");
string[] active = CustomWwiseAPI.GetActiveConfigIds();
string playing = CustomWwiseAPI.GetCurrentlyPlayingConfigId();

Tips for Success

🎵 Music Quality

• Use high-quality source audio
• Ensure smooth loop points in Wwise
• Test at different volume levels
• Consider dynamics (quiet vs loud sections)

🔧 Technical

• Always wait for bank to load before enabling
• Use descriptive config IDs
• Test in different environments
• Enable debug logging when troubleshooting

📦 Distribution

• Include clear installation instructions
• List which environments your music affects
• Mention if it replaces all music or specific areas
• Test with other music mods

🤝 Compatibility

• Use unique config IDs (include your mod name)
• Don't disable other mods' configs
• Document which environments your mod affects
• Consider making environment filters configurable

Example: Complete Music Mod

Here's a complete, copy-paste-ready example:

using BepInEx;
using BepInEx.Configuration;
using BepInEx.Logging;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using CustomWwiseSoundbanks;

namespace MyMusicMod
{
    [BepInPlugin(PLUGIN_GUID, PLUGIN_NAME, PLUGIN_VERSION)]
    [BepInDependency("com.necropolis.customwwisesoundbanks")]
    public class MyMusicPlugin : BaseUnityPlugin
    {
        public const string PLUGIN_GUID = "com.yourname.custommusic";
        public const string PLUGIN_NAME = "My Custom Music";
        public const string PLUGIN_VERSION = "1.0.0";

        internal static new ManualLogSource Logger;
        private ConfigEntry<bool> _enableCustomMusic;

        private void Awake()
        {
            Logger = base.Logger;
            
            // Make it configurable
            _enableCustomMusic = Config.Bind("General", "EnableCustomMusic", true,
                "Enable custom music replacement");

            if (_enableCustomMusic.Value)
            {
                StartCoroutine(SetupMusic());
            }
            else
            {
                Logger.LogInfo("Custom music disabled by config");
            }
        }

        private IEnumerator SetupMusic()
        {
            // Wait for system
            while (!CustomWwiseAPI.IsReady)
                yield return new WaitForSeconds(0.5f);

            // Wait for bank
            while (!CustomWwiseAPI.IsBankLoaded("mymusic"))
                yield return new WaitForSeconds(0.5f);

            Logger.LogInfo("Bank loaded successfully!");

            // Setup music
            var musicEvents = new Dictionary<AudioBankManager.MusicState, string>
            {
                { AudioBankManager.MusicState.TITLE, "My_Title_Music" },
                { AudioBankManager.MusicState.EXPLORE, "My_Explore_Music" },
                { AudioBankManager.MusicState.COMBAT, "My_Combat_Music" }
            };

            CustomWwiseAPI.RegisterMusicConfig("mymusic_config", "mymusic", musicEvents, null);
            CustomWwiseAPI.EnableMusicConfig("mymusic_config");

            Logger.LogInfo($"{PLUGIN_NAME} activated!");
        }

        private void OnDisable()
        {
            // Clean up
            if (CustomWwiseAPI.IsConfigEnabled("mymusic_config"))
            {
                CustomWwiseAPI.DisableMusicConfig("mymusic_config");
            }
        }
    }
}

Troubleshooting

Music Not Playing

Check 1: Is your bank loaded?

if (!CustomWwiseAPI.IsBankLoaded("custommusic"))
{
    Logger.LogError("Bank not loaded!");
}

Check 2: Are event names correct?

• Event names must match exactly what's in Wwise
• Check for typos

Check 3: Is the config enabled? You can use GetActiveConfigIds() to get a list of the enabled Music Configs

string[] active = CustomWwiseAPI.GetActiveConfigIds();
Logger.LogInfo($"Active configs: {string.Join(", ", active)}");

Music Plays at Full Volume Even at 0%

You didn't set up the MusicVolume RTPC in Wwise! Check the Setting up Your Sounds & Music in Wwise 2015.1 guide

Music Cuts Out When Changing Environments

If you set environment filters, music only plays in those environments:

// This only plays in Swamp
CustomWwiseAPI.RegisterMusicConfig("music", "bank", events, new[] { "Swamp" });

// To play everywhere, pass null:
CustomWwiseAPI.RegisterMusicConfig("music", "bank", events, null);

Multiple Configs But Wrong One Plays

Priority matters! Last enabled = highest priority:

// ❌ WRONG: general_music has highest priority
CustomWwiseAPI.EnableMusicConfig("swamp_music");   
CustomWwiseAPI.EnableMusicConfig("general_music"); // This overrides everything!

// ✅ CORRECT: swamp_music has highest priority
CustomWwiseAPI.EnableMusicConfig("general_music");  // Fallback
CustomWwiseAPI.EnableMusicConfig("swamp_music");    // Specific areas

Common Mistakes

❌ Using new[] { "All" } - Not a real environment! Use null instead
❌ Selecting "Game-Defined Auxiliary Sends Volume" - Use "Voice Volume"
❌ Forgetting to loop music in Wwise - Check audio source properties
❌ Bank name typos - "mybank" vs "mybank.bnk" (don't include .bnk in code)
❌ Event name typos - Names must match exactly

Getting Help

If you run into issues:

1. Enable debug logging - Set EnableDebugLogging = true in BepInEx config
2. Check the console - Look for [MUSIC] entries
3. Verify basics:
   • Bank is in correct folder
   • Config is enabled
   • Event names are correct
   • Volume RTPC is set up
4. Check documentation - See Readmes within Abraxis Audio

Credits

• Abraxis Audio - Custom Wwise Soundbanks System - Built for Necropolis modding community
• Wwise - Audiokinetic's audio middleware
• BepInEx - Unity modding framework

Ready to create your music mod? Start with Step 1! 🎵