How to create a voice pack using the Custom NPC Voices Framework

From Nexus Mods Wiki
Jump to: navigation, search

Original version by mpe3us

This guide will go through the different steps required for setting up a custom voice pack for the Custom NPC Voices Framework.

Before starting this tutorial, you'll need to be set up Unity and the B&S modding SDK.

If you should have any questions or improvement suggestion about this guide, feel free to DM or @mpe3us on the B&S Discord.

Creating the voice pack

First things first, you need some audio clips for your voice pack. The audio clips can be anything as long as you have them in the format of either .wav, .mp3, .ogg or .aif. I do recommend that all of your audio clips are lower than 5 seconds in length and definitely no longer than 10 seconds to avoid potential performance-related issues. Make sure that the voice clips have a decent volume level, as there is a limit for high you can set it in-game. You can use Audacity for boosting the volume of your clips.

To give you an idea of which type of voice lines would be fitting for a voice pack, here are the different “voice events” which is currently available:

  • "attackSounds": Triggers when an NPC performs a basic attack (the short attack animations).
  • "attackBigSounds": Triggers when an NPC performs an advanced attack (the longer attack animations)
  • "hitSounds": Triggers when the NPC takes damage
  • "deathSounds": Triggers when the NPC dies “normally”
  • "slowDeathSounds": Triggers when the NPC dies “slowly” (e.g. a stab kill)
  • "fallingSounds": Triggers when the NPC is falling (e.g. from a ledge)
  • "tauntSounds": Triggers randomly within a predetermined time interval
  • "friendlyDeathSounds": Triggers when a friendly NPC dies
  • "grabSounds": Triggers when you grab an NPC
  • "telegrabSounds": Triggers when you use telekinesis on an NPC using the mod “Dark Chains” (only works if Dark Chains is installed)

At this point, I recommend that you categorize your audio clips into different folders depending on which voice event you plan on having each of your voice lines associated with (see image below).

However, you are not required to have audio clips for each voice event for your voice pack to work. You can also use the same audio clips for different voice events e.g. using “deathSounds” as “slowDeathSounds”.


After you have decided which audio clips you want to use and categorized them, it’s time to import them in Unity.

Importing the audio clips in Unity

Before importing audio clips into Unity, start by creating a folder inside the Unity project which will contain your categorized audio clip folders. You can create a folder in Unity by right-clicking in the “Projects” window, followed by clicking “Create” and finally “Folder”:


Select all of your categorized folders containing the audio clips and drag them inside your newly created folder in Unity:


Depending on the size and number of audio clips, it can take a bit for Unity to load them.

Audio clip import settings

After the audio clips have been imported and loaded into Unity, it is important that you configure the audio clips to use the correct import settings. Otherwise the audio won’t work with the game’s NPC speech system.

For each audio clip, you want to set it up with the following settings:


You can select multiple audio clips at the same time, so you don’t have to go through each individual clip. Make sure that you hit Apply after changing the settings.

Audio Containers

Now we need to set up an AudioContainer for each voice category, which is what we will end up exporting to a new mod folder in the StreamingAssets folder.

To create a new AudioContainer, right-click in the “Projects” window, and then click “Create” -> “Blade & Sorcery” -> “AudioContainer”:


Using the AttackSounds first as an example, name the AudioContainer to something that makes sense, e.g. MyVoicePack_AttackSounds, as we are going to need the name of the AudioContainer later. (MyVoicePack should be the name of your voice pack).

Now select the newly created AudioContainer. First, we want to assign an AssetBundle to the AudioContainer which you do by clicking on “None” in the bottom of the Inspector window. Select “New…” and type in a unique name:


It’s important that you the name AssetBundle something unique. We are also going to use the name of AssetBundle again later on.

Now it’s time to add your audio clips to the AudioContainer. Using the AttackSounds as an example, I have 3 audio clips that I want to use. For this example, it means that we want to set the ‘Size’ of ‘Sounds’ to 3:


By doing so, we get 3 slots for audio clips which want to fill out with our 3 attack sounds. We do this by dragging each individual clip into an open slot:


And now we are done with AudioContainer for the AttackSounds!

Repeat the process of creating an AudioContainer for each voice category: (1) Give it a unique name, (2) Assign a name to the AssetBundle using the previous AssetBundle name which you created, (3) Assign the appropriate audio clips to the ‘Sounds’ list.

In the end, should have up to 10 different AudioContainers assigned to the same AssetBundle name.

Build and export the AssetBundle

Before building and exporting our AssetBundle, we first need to create a mod folder for the voice pack. This is done by going to the “Blade & Sorcery” tab in the top panel and clicking on “Mod Configuration”. By doing so, a new window should pop up as seen below. Before clicking “Create New Mod”, make sure that the directory path to your StreamingAssets folder is correct.


After hitting the “Create New Mod” button, another new window should pop-up where you need to fill in the following info about your mod:


After having filled in the information, click “Save Info”.

After doing so, a folder with your “Mod Name” should appear in your StreamingAssets folder containing a manifest file with the information that you just typed in:


Back in Unity, go to the “Blade & Sorcery” tab and click “Asset Bundle Builder”. Using the below image as a reference, here you want to (3) Tick the the name of your AssetBundle, (4) Click on drop-down button, (5) Select your mod, (6) Tick the option to “Export asset bundles to their respective mod folders” and finally (7) Click Build Asset Bundles.


After doing so, Unity will start building an AssetBundle containing all your AudioContainers. The time it takes to build the bundle depends on your combined file size in audio clips (if you get a console error when trying to build the AssetBundle, close the “B&S Asset Bundle Builder” and re-open or restart Unity if it still does not work).

After Unity is done building the AssetBundle you should see an “.assets” file in your mod folder corresponding to the name you set for it:


For the Custom NPC Voices Framework to recognize the AssetBundle, you must rename the “.assets” file extension to “.voicepacks”, such that it looks like this instead:


If you are not able to see and edit file extensions, take a look at this link: and scroll down to “Method 2”.

The AssetBundle is now built, exported and completed. Now it’s time to bind it to a VoiceCreature.

Setting up a VoicedCreature JSON

To avoid setting up a VoicedCreature JSON from scratch, I recommend that you download the NPC Voicepack Overhaul Sample here.

Inside of the mod folder “VoiceFramework_Sample”, copy the “VoicedCreature_Test.json” file to your own mod folder and rename “Test” to something unique, e.g. the name of your voice pack or AssetBundle. Make sure that the file still starts with “VoicedCreature_” otherwise the framework will not be able to recognize the file.

Now open the VoicedCreature file using your favourite text or code editor, I personally recommend Notepad++, Sublime Text or Visual Studio Code. You can also just use Notepad if you prefer, but the former will highlight any potential syntax errors you might have in your JSON file.

If you copied the VoicedCreature_Test file, you should see this inside the file:

  "id": "VoicedCreature_Test",
  "creatureIDs": [ ],
  "brainIDs": [ ],
  "containerIDs": [ ],
  "forcedSex": "",
  "maleVoiceSets": [
  	"id": "Test",
  	"attackSounds": "@voicepack_test:Test_Attack.asset",
  	"attackBigSounds": "@voicepack_test:Test_AttackBig.asset",
  	"hitSounds": "@voicepack_test:Test_Hit.asset",
  	"deathSounds": "@voicepack_test:Test_Death.asset",
  	"slowDeathSounds": "@voicepack_test:Test_SlowDeath.asset",
  	"fallingSounds": "@voicepack_test:Test_Falling.asset",
  	"grabSounds": "@voicepack_test:Test_Grab.asset",
  	"telegrabSounds": "@voicepack_test:Test_Grab.asset",
  	"friendlyDeathSounds": "@voicepack_test:Test_FriendlyDeath.asset",
  	"tauntSounds": "@voicepack_test:Test_Taunt.asset",
  	"probabilityWeight": 1.0,
  	"volume": 1.0
  "femaleVoiceSets": [   
  	"id": "Test",
  	"attackSounds": "@voicepack_test:Test_Attack.asset",
  	"attackBigSounds": "@voicepack_test:Test_AttackBig.asset",
  	"hitSounds": "@voicepack_test:Test_Hit.asset",
  	"deathSounds": "@voicepack_test:Test_Death.asset",
  	"slowDeathSounds": "@voicepack_test:Test_SlowDeath.asset",
  	"fallingSounds": "@voicepack_test:Test_Falling.asset",
  	"grabSounds": "@voicepack_test:Test_Grab.asset",
  	"telegrabSounds": "@voicepack_test:Test_Grab.asset",
  	"friendlyDeathSounds": "@voicepack_test:Test_FriendlyDeath.asset",
  	"tauntSounds": "@voicepack_test:Test_Taunt.asset",
  	"probabilityWeight": 1.0,
  	"volume": 1.0

Let’s go through each setting and configure them.

Key Details
id The unique identifier for your VoicedCreature JSON file. Rename this to e.g. the name of your JSON file. Make sure that it is unique.
creatureIDs A list containing the IDs of the creatures (NPCs) that should have their default voices replaced. For example, if you want to have your voice pack affect all default creatures your creatureIDs should look like this:

"creatureIDs": [ "Human", "HumanMage", "HumanMageMale" ] Leave the list blank if you don’t want to use this feature.

brainIDs A list containing the IDs of brains that should have their default voices replaced. This is useful for having different voices depending on wave difficulty. Take a look at the “Brains” folder inside of the “Default” folder for the different IDs. Leave the list blank if you don’t want to use this feature.
containerIDs A list containing the IDs of CreatureTables that should have their default voices replaced. This is useful for having different voices depending on the NPC “faction”, e.g. the barbarians in the Arena or the cultists in the Ruins. Take a look at the “CreatureTables” folder inside of the “Default” folder for the different IDs. Leave the list blank if you don’t want to use this feature.
forcedSex If your voice pack is only intended to a specific gender, set this line to either

“forcedSex”: “Male” or “forcedSex”: “Female”. It is possible to have multiple voice sets in the same VoicedCreature JSON, so leave this blank if you are going to another set of voices of the opposite gender to the voice pack.

maleVoiceSets and femaleVoiceSets This is where we are going to reference the individual AudioContainers from your AssetBundle. If your voice set is for a male, when you need to set up “maleVoiceSets” otherwise “femaleVoiceSets”.

Using the “attackSounds” as an example, it currently looks like this: "attackSounds": "@voicepack_test:Test_Attack.asset"

Replace voicepack_test with the name of your .voicepacks AssetBundle and replace Test_Attack with the name of your AudioContainer containing the attack sounds. Repeat this process for each voice category.

If you do not plan on adding more voice sets to your voice pack, then make sure to delete the gender counterpart of what you just edited. E.g. if only have populated “maleVoiceSets” then set “femaleVoiceSets” to: “femaleVoiceSets”: [ ] I recommend taking a look at the “VoicedCreature_Sample.json” file from the sample voice pack for the advanced setup of multiple voice sets.

probabilityWeight Multiplier for the chance of this particular voiceset to be picked for an NPC if multiple are available. Usually, you just want to leave this at 1.0.
Volume Volume for the voice set. 0.7 is the default value for the default in-game voices. Setting the value higher than 1.0 won’t have an effect.

For an alternative approach for setting up the VoicedCreature JSON, take a look at the JSON Generator For Voice Framework by Jome.

Testing the voice pack

When you are done setting up the VoicedCreature and ensured that it is formatted correctly, it is finally time to test the voice pack in-game.

Make sure that you have the Custom NPC Voices Framework installed, otherwise your voice pack will not work. So when you get around to uploading your mod on Nexus, make sure to set the Custom NPC Voices Framework as a required mod, which will notify users with an automatic pop-up when downloading your voice pack. If you absolutely insist on making your mod work standalone, you can copy the “VoiceFramework.dll” and “Level_Settings.json” inside of your mod folder. But be aware that by doing so, it can break other installed voice packs as they might depend on a newer version of the framework as I put new updates out.

If your voice pack does not seem to be working make sure to look out for any potential errors in the in-game console (press F8 on the keyboard to see it). The console should give you indications of what the problem could be. Otherwise, make sure to have all other voice packs uninstalled when testing yours such that you are guaranteed that only your voice pack have the chance of being activated.

And that’s it! See the next section for tips and tricks.

Tips and tricks

  1. If multiple voice packs are installed and referencing the same IDs, they simply get added to the pool of possible voices that the given NPC can get. So don’t worry about your voice pack conflicting with another.
  2. Remember that you don’t need a unique AudioContainer for each voice event/category. E.g. you can use one set of death sounds for both “deathSounds” and “slowDeathSounds” when setting up the VoicedCreature json.
  3. You can control the trigger chance for individual voice clips by adding the same audio clip multiple times to the “Sounds” list in the given AudioContainer.
  4. If you feel like the audio level of your voice clips is too low, even though you already have configured at the volume to the max of 1.0, you need to boost the volume of the audio clip of the audio file itself, e.g. using Audacity ( Make sure you re-import the audio clips in Unity and re-build and re-export the AssetBundle if you make changes to audio clips. Also, remember to rename AssetBundle file extension from “.assets” to “.voicepacks” each time you re-export.