Customising Gun Sounds

[ this is slightly irrelevant as the gun package is outdated - but this will still apply, just some logic will conflict ]

Without any modifications, modded guns will play a default shoot and reload sound (or whatever your example gun has as its example sounds). Luckily, changing what sounds they play is quite simple.

Gun sounds are handled by what are known as gun switch groups, which determine what sounds play upon certain actions (shooting, reloading, charging, etc.). This is accessed via a field in your gun object, usually via gun.gunSwitchGroup.

Setting to a Basegame Gun's Sounds

If you wish for your gun to play the same sounds as a different one, or more accurately, think that a certain basegame gun's sounds work well enough for your gun design, you can easily set the switch group from one to your mod. In your gun's Add(), or equivalent method, after the first few lines, write:

gun.gunSwitchGroup = (PickupObjectDatabase.GetById([ID]) as Gun).gunSwitchGroup;

What does this code actually mean?

PickupObjectDatabase is a class in the base Gungeon's code that stores all of the game's items and guns.

.GetById() is a method that PickupObjectDatabase has, which retrieves a certain item based on its ID, stored in the game, this returns an object of type PickupObject, which is not a gun, and thus does not contain the gun switch group that we need.

asGun is a way to cast the PickupObject so that it tells the compiler to treat PickupObject as if it is a Gun, allowing us to access it's gunSwitchGroup, which is what the final part does.

Replace [ID] with the ID of the gun you wish to acquire the sounds of. A list of gun IDs can be found on this page in the gitbook.

So for example,

gun.gunSwitchGroup = (PickupObjectDatabase.GetById(91) as Gun).gunSwitchGroup

Will set the gun's switch group to that of the H4mmer, meaning that all shoot and reload sounds will be the same as the H4mmer's.

Mixing and Matching Basegame Gun Sounds

Now, let's say that for your custom weapon, the M1's shoot sound works very well, but for the reload sound you would prefer if it played the crossbows. Unfortunately, this means that setting the gunSwitchGroup to an existing one will no longer work as you will only be able to take all of the M1's sounds or all of the crossbow's sounds.

What you used to have to do was to manually play the shoot or reload sound that you wanted, but we have an easier and better solution now:

Introducing SoundAPI

SoundAPI is a custom API that was developed to create custom gun switch groups, allowing for easy mixing and matching as well as convenient custom sound support.

SoundAPI should be automatically built into the latest version of Alexandria - ensure it is up to date, and then put using Alexandria.SoundAPI; at the top of your gun's code, where all of the other usings are.

Then, set your gun's gunSwitchGroup to a string of your choice. This will be the name of your custom switch group. The convention is to use the format "[prefix]_[gunIdentifier]" so that cross-mod incompatibility doesn't happen. For example, a mod with a prefix exp and gun called example_rifle might use the string "exp_exmplerifle".

Then on the next few lines, add code in this format:

SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Shot_01", 
                                [name of the shoot sound you want]);
SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Reload_01", 
                                [name of the reload sound(s) you want]);

The line containing "Play_WPN_Gun_Shot_01" will add your desired shoot sound to your gun, and the line containing "Play_WPN_Gun_Reload_01" will add your desired reload sound to your gun.

You can find a list of basegame sounds on this page. Don't worry - it will seem daunting at first, and not all the guns have a sound with their name in it, so play around, search using Ctrl + F, and if worst comes to worst, just use a different sound until you can find it. Note that all valid weapon sounds should begin with Play_WPN_.

So, going back to the initial example, if I wanted my gun to play the M1's shoot sound but the Crossbows reload, I would type this:

gun.gunSwitchGroup = "exp_exmplerifle";
SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Shot_01", "Play_WPN_m1rifle_shot_01");
SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Reload_01", "Play_WPN_crossbow_reload_01");

Note that you can play multiple sounds per event - just add a comma before the bracket and enter the string of a different sound! For example, if I wanted my gun to have the crossbow's reload sound and a spin sound on reload, I would write:

SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Reload_01", "Play_WPN_crossbow_reload_01", "Play_WPN_SAA_spin_01");

Using Custom Sounds

The hardest part about making your guns use custom sounds is making and getting them into your mod. To learn how to add custom sounds to your mod, click here.

Make sure you know what name your custom sound event uses - it's most likely just going to be its file name or a variant of it (with Play_ in front of it, for example). Once you've got that, you just use SoundManager and add it to your custom switch group.

Say, if I had a "Play_Custom_Shoot_Sound_001" and a "exmplereloadsound" for my two custom sounds, I would do:

un.gunSwitchGroup = "exp_examplegun";
SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Shot_01", "Play_Custom_Shoot_Sound_001");
SoundManager.AddCustomSwitchData("WPN_Guns", gun.gunSwitchGroup, "Play_WPN_Gun_Reload_01", "exmplereloadsound");

And the gun will now use custom sounds!