Setting Up Speakers

This article shows how a mapper can drop a speaker entity in the map and set it up correctly in DarkRadiant. The focus is on shoundshader keywords and how to override them.

Create A Speaker Entity

To create a speaker you can simply click in DarkRadiant and select "Create speaker...". This will:

create a speaker entity
open a window that lets you choose a sound

After choosing a sound you can alter the sound's properties in the entity inspector.

To do that it is handy to know how sounds in our game basically work. Via sound shaders, that is:

Sound Shaders And Spawnargs

A sound shader is a text file that resides in darkmod/sounds and comes with the .sndshd extension. These shaders tell the engine where the .waves or .oggs can be found along with some common parameters.

As an example we look at the shader for "footsteps on stone materials while walking" (you would not put these in game via a speaker normally, but you could do it since all sounds work technically the same):

 tdm_footstep_stone_walk
 { 
 	description "Made by GoldChocobo"
 	no_dups
 	minDistance 1
 	maxDistance 30
 	volume -12
 
 	sound/sfx/movement/footsteps/player/stone_walk01.ogg
 	sound/sfx/movement/footsteps/player/stone_walk02.ogg
 	sound/sfx/movement/footsteps/player/stone_walk03.ogg
 	sound/sfx/movement/footsteps/player/stone_walk04.ogg
 }

It starts with the shader name "tdm_footstep_stone_walk". This will show up in DarkRadiant's "Choose sound" dialog. Then we have some keywords followed by the actual sound files and their relative path.

There are four sounds (not only one) to allow variety. They get played in a random order, one each time the sound is triggered. (In most cases, see Problem Hearing Varied Sounds.)

Picking the volume keyword you can see it is followed by a negative value. These are meant to be decibel (dB), so we can expect 0 to be the maximum while a reduction by 10 approximately is half the volume.

If you created your speaker and wanted to change it's volume in DarkRadiant you would go to the entity inspector (default shortcut: n) and add the spawnarg s_volume. Whatever number you enter here is meant to override the shader setting.

This is what it looks like:

The icons left to the keyword indicate Radiant knows them -- you will get a tooltip on mouseover. If you mistype anything you will see nothing there, which is a good indicator.

So what we have is a system where our shaders provide the default values. We can override these values in the map file using the appropriate spawnargs. Note that not defining anything in the shader as well as in your map file won't crash the game -- there are still fallback values (propably hardcoded in the engine).

In the following list the keywords are presented as a pair, where possible. The soundshader keyword is followed by the corresponding counterpart you would use in DR.

volume/ s_volume

The volume is set in dB. Usually this means there is a maximum of 0 dB. The minimum is -60 dB which results in absoulute silence.

Edit (demagogue): I found a handy decibel calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "3" is 1.25 the volume.  "10" would be double (probably too loud).

Up to a certain point the game allows the use of positive values as well, but be aware, as this is sensitive:

To prevent clipping the engine has a mechanism that does not allow the volume to overdrive your sound hardware. For testing, it can be disabled via the s_clipVolumes cvar, but if it is active it will clip the volume for every output sound channel after all the other calculations are done -- this includes stereo panning, so once the volume setting is too high all the speakers (in your headphones, on your stereo) will play the sound at the same maximum volume. It gets virtually monofied, the player no longer is able to locate the sound.

In general it is best to avoid setting the volume on an individual speaker unless strictly necessary, because it prevents future updates to the volume specified in the sound shader from taking effect in your map. It is preferable to set the volume correctly on the sound shader declaration itself (or request that the Dark Mod team do so, if it is a core asset supplied with the mod).

unclamped/ s_unclamped

Possible values are 0 and 1. This overrides the global volume clipping and will make your sound bypass the s_clipVolumes setting.

Should be used with extra care, can trigger hardware clipping. This will not damage your hardware, but sound real crappy -- keep in mind this is a game and not your favourite tube amp.

minDistance/ s_mindistance

This works together with maxDistance like this:

Around the speaker there is a spherical volume, defined by minDistance. Inside that, the sound plays at the specified full volume. The (hopefully) larger maxDistance defines a bigger sphere. Outside of it the volume will be 0, inside of it there is a falloff from max. to min.

Note: Do not set s_mindistance to 0!

While a real sound does not have a "mindistance" it will not work to set s_mindistance to 0. A quick test revealed the following behavior:

This shows we can overide the shader values with our spawnarg in DR, but when we set it to 0 it counts not as a number but as a toggle that simply disables our intended input. This is as good as deleting the property.

The value will fall back to the shader default (lucky case is purple, bad cases are red). In the right column (red and yellow field) you can see what happens when no values are provided by the shader nor the spawnarg: doom simply sets the minDistance to 1.

As a resort mappers can always use s_mindistance 1, that's close enaugh for rock'n'roll.

maxDistance/ s_maxdistance

See above. The outlines of maxDistance can be drag-resized in DarkRadiant. This does not show you the real dispersion of the sound in most cases (due to occlusion, see below).

Not setting the maxDistance or at the same time setting s_maxdistance to 0 (which is insane anyway) will cause doom to use 10 instead.

looping/ s_looping

Turns on and off looping. The sound will repeat endlessly in a forward loop.

omnidirectional/ s_omni

The sound will have the same volume on all speakers, so it sounds like not having a specific origin. Normally used for ambience music (when not using the preferred method via Location Settings). Works with falloff as provided by minDistance and maxDistance.

global/ s_global

Plays the sound at full volume everywhere in the map.

no_occlusion/ s_occlusion

The shader keyword turns occlusion off, s_occlusion must be set to 1 for the same effect (this is counterintuitive).

What is occlusion? -- To resemble a realistic falloff for sounds, the game traces the route to the speaker from the player position through vis_portals instead of line of sight. Even closed doors or windows are taken into account for that calculation.

If you want your specific sound to be not affected by this, you can turn it off this way.

Note: it is highly recommended to turn occlusion off for ambient music, or it will fade when you close a door etc.

shakes/ s_shakes

A special effect, that shakes the screen when the sound plays. Possible values are fractions between 0 and 1. This is multiplied with the volume to determine the intensity of the effect.

Note: s_shakes 0 will disable itself and fall back to the shakes value in the shader.

Note2: Iddevnet says it should not be used with .ogg files.

n. a./ s_waitfortrigger

If set to 1 the speaker will wait for a trigger to activate it.

n. a./ s_shader

Points to the sound shader the speaker uses. Can as well be used to reference audio files directly, when not present in any shader.

leadin/ n. a.

Specifies a file that is played as a lead-in to a looped part of the sound.

leadinVolume/ n. a.

Volume of the lead-in part in a looped sound.

no_dups/ n. a.

This prevents the same audio file out of the multiple ones in a shader to be played twice in a row when randomly playing them.

Not of any use when your shader references only one file.

private/ n. a.

The sound is only present to the player.

description/ n. a.

A short discription in the shader. In DarkMod it usually names the creator of the sound.