Hpl2:HPL2/Tutorials/CustomSounds

Adding custom sounds

Preparing the sounds

First you'll need a sound-editting program; Audacity is a common choice - it is free and will suit most needs.

The sounds need to be in .ogg format. If your sound files are formatted as .MP3, .WAV or anything else, you need to use one your audio editing software of choice to convert your sound file to an .ogg file format. In Audacity, you just need to drag the file into the program and then export as .ogg.

Tip: It is recommended to use mono files. Stereo should only be used for music and ambient tracks, because it will play directly at the player rather than play in 3D.

If you only want to play this sound as music, you can skip the next few steps and jump right to the custom music section.

Managing sound files

In your mod's (FC or CS, doesn't matter) folder, create a folder for sounds. It can be called however you want, but sounds would probably be the best.

Tip: If your mod has a lot of custom sounds, make sure to organise them into subfolders!

Place the tutorial.ogg file in the created (sub)folder.

Creating the sound entity file

The behaviour of the sound in the game is determined by a "sound entity" file. These files have a .snt extension.

For the fastest workflow, copy an existing sound file that works similarly to how you want and change its name. Then alter the contents of that file rather than writing them from scratch.

Tip: If using Notepad++, right-click a .snt file and pick Notepad++ to edit the file.

Alternatively, you can do the following:

Create a .txt file and name it what you want (same as the .ogg file is common), open it with any text editor you use. Notepad++ is recommended. When you finish editing the file, change the extension to the correct one. I named my file tutorial.snt.

Tip: Other extensions might work, but it is recommended to give sound files the .snt extension used by the main game. This will allow your sound to be placed in a level without scripting.

In the file, you can edit quite a few things, and among them is..Adding your sound-file into the script! And since my sound file is door.ogg, It shall go to the MAIN section. Random soundfiles will be covered later on.

<SOUNDENTITY>
 <SOUNDS>
   <Main>
      <Sound File="door.ogg" />
   	</Main>
   </SOUNDS>
   <PROPERTIES Volume="5" MinDistance="1" MaxDistance="50" Random="0" Interval="0" FadeEnd="False" FadeStart="False" Stream="False" Loop="False" Use3D="false" Blockable="False" BlockVolumeMul="0.7" Priority="5" />
</SOUNDENTITY>

Format explanation:

<SOUNDENTITY> is the start marker of the sound file

<SOUNDS> indicates the sound list

<Main> is the list of sounds the file will play.

<Sound File="YourFileName.ogg" /> is the way to add a file to the sound. Adding multiple files will play them randomly.

<PROPERTIES> Are all the options you may use to decide how the sound will behave in-game.

Properties

The basics

• Volume is how loud the sound should play. Volume=1 would make the sound play at the normal volume of the sound file. Volume=0.5 would half as loud. Volume=2 would amplify the sound to twice its normal volume.

• MinDistance and MaxDistance are used for attenuation, which means how the sound fades out over distance. Within the MinDistance the sound will be at the full Volume level. As the player moves from MinDistance to MaxDistance away from the sound, the volume will fade towards silence. Outside of MaxDistance it does not play at all.

• Loop should be set to "true" if the sound should loop.

• Use3D should be set to "true" if the sound should originate from a point in the game world. Otherwise it will be all around the player and will not fade with distance.

Well thats it! You now created your very own sound! Place it in the map with the Level Editor or use it with PlaySoundAtEntity(); in your level script (check Engine scripts for details).

More advanced .snt properties

• Loop, Random and Interval are all used together to define whether and how the sound should loop. Loop=true will make the sound repeat. If Interval is 0 then the sound will loop continuously, but if Interval is set to a value > 0, then that becomes a delay inserted between the repeitions. If Random is set to a value > 0 and < 1, then it defines the random chance of the sound playing on that interval. If Random is <=0 or >=1, then the sound will always play every interval.

For example, an ambient background track that should play continuously with no gaps should have:

Random="1" Interval="0" Loop="true"

A sound that should repeat periodically, with a 25% chance of playing again every 15 seconds would be defined like this:

Random="0.25" Interval="15" Loop="true"

• Random does not affect the random variant sounds listed in the .snt file. Those each have an equal chance of playing, although the engine will try to stop them from playing twice in a row if possible.

• Use3D causes the sound to originate from a point in space, and move between the left and right stereo channels, but it is also required for attenuation. If Use3D is false, then the sound will have no stereo separation but it will also not fade over distance. Only mono sounds can be used as 3D. Stereo sounds retain the the left/right channel in the sound file and always behave as Use3d="false".

• Stream defines whether the sound can be preloaded. Stream="false" is the normal behaviour for short sounds that are loaded into memory and played when needed. Stream="true" makes the sound play from the disk. This is slower but saves memory, so should be used for large sound files that are played rarely.

• FadeEnd and FadeStart, if true, will cause looping sounds to fade in or out on their first or last repetition.

• Blockable, BlockVolumeMul, and Priority do not seem to be implemented in the engine. (Blockable and BlockVolumeMul may have been intended to define how the sounds are muffled by world geometry, and Priority may have been intended to be used when culling sounds. Although all three properties are read from the .snt file, they do not seem to be referenced in any other code.) ^[Confirm]

• <SOUNDS> categories: as well as <Main> the engine will also read lists of sounds from <Start> and <Stop> nodes. These may provide alternate sounds for the beginning and end of a loop. ^[Confirm]

Adding custom music

Custom music only needs to be a file in the .ogg format. It won't need an .snt file to be played with PlayMusic(); or at the credits, but you won't be able to use PlaySoundAtEntity(); with this file.

Just like with sounds, it is good to create a folder for music in the mod's main folder, e.g. music. Put the .ogg file there.

See Engine scripts to learn how to use PlayMusic();.

Keep in mind that only one music file can play at a time. For ambient sound, it is better to create a sound file (like described earlier). That way you can layer ambient sound with actual music when needed.