Dynamic Sounds for Guns - RedDeadlyCreeper/ArmoredCombatExtended GitHub Wiki

What's this?

Since git 460, ACE features dynamic sounds, which allows to play different sound variations from one gun, achieving a more realistic (and natural) gun fire during combat, depending on the used gun and what distance is being heard.

Although this looks hard, it's not. Here i will explain you how you can create one.

Requirements before you start (Mandatory)

basic lua knowledge (know how to edit tables)
The sounds you are going to use. You require as minimun:

At least 2 sounds for close distance
At least 2 sounds for medium distance
At least 2 sounds for far distance

Also make sure they are compatible with the supported formats

Recommended tools (optional)

A code editor (IDE), like Sublime text or Visual Studio Code
A sound editor, like Audacity

Not using a code editor, you rely on using notepad which is not really suitable for this

Step 1: Folder Structure - LUA

First, we are going to create a folder inside of our addons folder, put a name of your liking. In my case i will call it MyCoolSoundAddon for this guide. Then get in there
Once inside, create another folder inside, called lua
Inside of lua folder, create several folders in a way that at the end you have this: addons/MyCoolSoundAddon/lua/acf/shared/sounds/ where addons is the folder where we created our addon.
Create an empty text file and put a name of your liking. Make sure that its name is NOT gunfire since thats what ACE already use and change the format to .lua. Ignore any extension warning and continue.

If you use the gunfire name, you will be overriding the main ace sounds, which could lead to errors if not done correctly. Simply avoid it.

Step 2: Folder Structure - Sound files

Go back to your addon folder and create another folder called sound. It must be at the same location as lua folder
Now inside of sound folder, the structure is up to you, however, for the sake of organization and because no one likes to find between multiple folders, you can follow this simple concept:

Create a folder inside of sound folder with a name of your liking.
Inside of that folder, create 1 folder called content.
Inside of content folder, you will create a folder for all sound variations that one gun possess (i.e 100 which means for something with caliber 100mm). If you have alot of variations, create close, medium and far folders inside to orgarnize it better.
When populating the sound folder, leave one close sound outside of content folder of each variation, change its name to GUN_NAME_multi where GUN_NAME is the name of your gun sound. I will explain why later.

For this tutorial. I will use the following sounds and the proper structure explained above. [Needs sample extructure linked here.]

Step 3: LUA file template

Once you have structured your sounds, go to your lua file which you created for your sounds and get into it.
Inside of said file, paste the following code there:

ACE_DefineGunFireSound( "sound path as id", 
    {
        main = {
            Volume 	= 1, --the volume of the closest sounds
            Pitch 	= 100, --closest sound pitch
            Package = {
                --here will be the mp3 to play close sounds
            }
        },
        mid = { -- the same as above, but for medium sounds 
            Volume 	= 1,
            Pitch 	= 100,
            Package = {
            }
        },
        far = { -- the same as above, but for far sounds 
            Volume 	= 1,
            Pitch 	= 100,
            Package = {
            }
        }
    }
 )

This function consists in the following parameters:

The first parameter will be the unique identifier for our sound, in this area we will use our GUN_NAME_multi, that we have created previously. This sound is merely an id and will not played during the execution.
The second parameter is a table that contains 3 sub-tables: main, mid, and far. Each sub-table has 3 key-value pairs representing Volume, Pitch and Package. Where:
main table represents the closest sound, mid represents the mid sound and far represents the farthest sound from the listener.
Volume is a number between 0-1, representing the volume of the sound. You can use a higher number but wont increase its dbs.
Pitch is a number between 0-255, representing the pitch of the sound.
Package is a table that contains a list of sounds to be played. Note that sounds in this table are played in a sequential order, from the first sound until the last one.

So, if we apply our data here. The function would look like:

ACE_DefineGunFireSound( "MyCoolSounds/SuperSound_Multi.mp3", 
    {
        main = {
            Volume 	= 1, --the volume of the closest sounds
            Pitch 	= 110, --closest sound pitch
            Package = {
                "MyCoolSounds/content/Mycoolsoundpackage/close/close1.mp3",
                "MyCoolSounds/content/Mycoolsoundpackage/close/close2.mp3",
            }
        },
        mid = { -- the same as above, but for medium sounds 
            Volume 	= 2, --i want this sound doesnt lose volume over distance easily.
            Pitch 	= 100,
            Package = {
                "MyCoolSounds/content/Mycoolsoundpackage/mid/mid1.mp3",
                "MyCoolSounds/content/Mycoolsoundpackage/mid/mid2.mp3",
            }
        },
        far = { -- the same as above, but for far sounds 
            Volume 	= 1,
            Pitch 	= 90,
            Package = {
                "MyCoolSounds/content/Mycoolsoundpackage/far/far1.mp3",
                "MyCoolSounds/content/Mycoolsoundpackage/far/far2.mp3",
            }
        }
    }
 )

Be advised to always use a sound editor to amplify the sound, as the Volume parameter will NOT help you on that.