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

From Nexus Mods Wiki
Revision as of 15:25, 10 June 2020 by Pickysaurus (talk | contribs)
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