Using Custom Sounds

Prerequisites

The current method for generating sound banks uses a Python script, so Python must be installed on your system. You can download and install the latest version by following the instructions on Python's official website.

Your project must also be set up to use the Alexandria modding library. This should be done by default if you have followed the mod setup instructions on the Creating a Mod page.

One-time Setup

In the GMStart() method of your mod's BaseUnityPlugin class, add the following line somewhere.

SoundManager.LoadSoundbanksFromAssembly();

Navigate to your project's "Resources" folder in your file explorer, then create a new subfolder named "Sounds". Then, download the latest version of the sound bank generation script and move it into your new "Sounds" folder (if it doesn't download automatically, hit Ctrl + S and save it manually).

Double-click on gen-gungeon-audio-bank.py in your file explorer to run the sound bank generation script. This should create an empty sound bank named Sounds.bnk in your "Sounds" folder. In Visual Studio, right clickSounds.bnk in the Solution Explorer, select "Properties", then change the Build Action to "Embedded Resource".

Basic Usage

Adding a new sound to your mod is super simple:

• Drag a .wav file from anywhere on your computer into your "Sounds" folder.

• Double-click gen-gungeon-audio-bank.py to regenerate your sound bank.

• Rebuild your project.

That's it! You can play your sound in game with the following code (replace "soundName" with the name of your .wav file not including the .wav extension):

AkSoundEngine.PostEvent("soundName", GameManager.Instance.gameObject);

For instructions on setting up sounds for your guns, see the Customising Gun Sounds page. The remainder of this guide covers advanced use cases and troubleshooting steps.

Advanced Usage

Tweaking Sound Parameters

In addition to your "Sounds.bnk" file, running the sound bank generation script also creates a "Sounds.csv" file if it doesn't exist. This file can be edited in any text editor or spreadsheet software to tweak the playback parameters of your sounds. Each line in this file has the following format:

name,volume,loops,channel,limit

• name is the filename (minus the .wav extension) of the sound the remaining fields will modify.

• volume controls the gain of the sound in decibels. E.g., 0 plays the sound as it is on your file system, 2 plays it slightly louder, 10 plays it twice as loud, -10 plays it half as loud, etc. This should generally be kept between -10 and 10.

• loops controls how many times the sound loops whenever it plays. 1 makes the sound play once, 3 makes it play 3 times, 0 makes it loop indefinitely until manually stopped, etc.

• channel must be either sound or music and controls whether the sound plays on Gungeon's sound or music channel (this mostly only affects whether the sound's volume is controlled using the Sound or Music slider in the game's Audio options tab).

• limit controls the maximum number of instances of a sound that can play at once, with 0 being unlimited. If the limit for a sound is reached and another instance of the sound is played, the oldest instance of the sound will immediately stop playing.

Note that sounds are included in your sound bank whether or not they have a corresponding entry in "Sounds.csv". Sounds without explicit entries are assumed to have volume of 0, loops of 1, channel of sound, and limit of 0.

"Sounds.csv" is only used by the sound bank generation script, and does not need to be embedded in your project. However, any time you modify "Sounds.csv", you must rerun the sound bank generation script and rebuild your project to apply changes, just as if you had added a new sound.

Playback Control

The playback of sounds created with the sound bank generation script can be controlled using a handful of suffixes when calling PostEvent(). Assuming your sound bank includes a sound named "mysound.wav" and you have a GameObject named myObject:

AkSoundEngine.PostEvent("mysound", myObject);

...will play "mysound.wav" on myObject. If myObject is destroyed, "mysound.wav" will automatically stop playing on myObject.

AkSoundEngine.PostEvent("mysound_stop", myObject);

...will stop all instances of "mysound.wav" playing on myObject. This can be useful for controlling the overlap of voices or other sounds that wouldn't make sense to be playing simultaneously on the same object.

AkSoundEngine.PostEvent("mysound_stop_all", myObject);

...will stop all instances of "mysound.wav" playing on all objects. This can be useful for stopping indefinitely looping sounds.

AkSoundEngine.PostEvent("mysound_pause", myObject);

...will pause all instances of "mysound.wav" playing on myObject. Useful in conjunction with:

AkSoundEngine.PostEvent("mysound_resume", myObject);

...which will resume playback of any paused instances of "mysound.wav" on myObject from the position they were paused.

Control Over Sound Bank Generation

The sound bank generation script searches its current directory for the first .csv file it finds and generates a sound bank with the same name. This means you can change the base name of "Sounds.csv" from "Sounds" to whatever you want to change your sound bank's name. If you do this, remember to update your project's embedded resources accordingly with the new bank filename.

For even finer control over sound bank generation (e.g., for integrating it into your build process), the script can also be run from the command line with various flags to control where audio files are read from, where the data spreadsheet is read from, where the sound bank is output, and what the sound bank is named. Run the script with the -h flag for a full list of options available.

Troubleshooting / FAQ

***PLEASE FOR THE LOVE OF PETE READ THIS PART FIRST***

Most issues that you're likely to encounter involve attempting to use audio files with an unsupported format.

If any issues whatsoever occur when adding or playing your sounds, the first thing you should try is opening your file in your preferred audio processing software (Audacity is recommended) and re-exporting it with the following settings:

• Format: Microsoft .wav (the script only works with .wav files)

• Encoding: Signed 16-bit PCM (24-bit and 32-bit might also work, do NOT use 8-bit or ADPCM)

• Channels: Stereo or Mono

• Sample Rate: at least 16000Hz for stereo and 22050Hz for mono

If re-exporting your audio file doesn't solve your issue, please read on.

My sounds aren't playing at all

Double check that you've done the following:

• Embedded your sound bank in your mod project

• Loaded your sound bank using SoundManager.LoadSoundbanksFromAssembly()

• Posted an event using the name of your sound (minus the .wavextension)

My sounds are playing too quietly / loudly

If your sound is slightly too quiet or too loud, you can tweak its gain (volume) via the spreadsheet described in the Tweaking Sound Parameters section.

If your sound is EXTREMELY quiet or loud, you should normalize it to -1.0dB and re-export it in Audacity. From there, you can continue to tweak the volume to your liking in Audacity, or you can make the remaining small adjustments using the spreadsheet as described above.

When I run the bank generation script, it prints "wave.Error: unknown format"

You are probably trying to embed a file that is either 1) not a WAV file at all, or 2) is encoded as an ADPCM wave. See the "Read First" section.

The game crashes whenever I try to play my sound

You are probably trying to embed an 8-bit wave file (common in audio dumps from old console games such as the Gameboy or NES). See the "Read First" section.

My sound is playing with a lower / higher pitch than it does when I play it outside the game

This usually happens when trying to play a mono .wav file with a low sample rate (16000Hz or lower). See the "Read First" section.

I want to add music to my mod, but I don't want to include a zillion megabyte .wav file! D:

If you absolutely need support for audio other than .wav files, you will need to revert to using the older, more difficult WWise method for creating sound banks. Since you've read this far into this guide, I trust you to be responsible, so feel free to use this guide and to ignore the warning at the top. :)