Soundscape

A soundscape is a type of audio script used to add ambience to maps. It can be used in any number of maps, requires only a single entity to implement, and does not generate any network traffic. Soundscapes use a mixture of looped and randomly played sounds, all of which have the option to be emitted from one of eight assignable target locations; DSP and Soundmixer profiles can also be enforced.

Only one soundscape can be active at any given time, and the individual sounds used within it cannot be controlled via inputs. When another soundscape is activated, the game will cross fade from one to the other.

Tip:Cross fade time is defined by the convar soundscape_fadetime.

Soundscapes are often stored across multiple text files, making it difficult to locate and test them. To make things easier, try browsing the soundscape lists or using the in-game console command PlaySoundscape to test all the available soundscapes in the current game--they will be listed by the auto-complete feature in the console. If you still want to browse through the files themselves, you can usually find them all listed in the <game>/scripts/soundscapes_manifest.txt file.

Configuring Soundscapes

Soundscapes can only be configured through these entities:

• env_soundscape
• env_soundscape_triggerable

There are other entities which can activate the soundscape, but these are the only entities which actually define soundscape properties. The other entities will point to these and use them as masters to remotely trigger the soundscape.

Whenever these entities activate a soundscape, any positional audio will originate from the targets defined under their properties.

Tip: Many soundscapes define positions for sounds to emanate from, so it is always a good idea to peek into the soundscape entry and get a feel for what you can do. Most entries are found in the text files listed in the <game>/scripts/soundscapes_manifest.txt file. To better understand soundscape entries, see below.

Activating Soundscapes

Any soundscape entity that is enabled and becomes triggered by the player, activates its--or its master's--specified soundscape. Soundscapes remain active until a map change occurs, or another soundscape is activated--even if the entity that originally activated it becomes disabled.

Tip:The soundscape_flush console command will cancel an active soundscape.

Soundscapes can be activated by any of the following entities...

Point-based soundscape entities

• env_soundscape
• env_soundscape_triggerable
• env_soundscape_proxy
  Note:Must point to an env_soundscape or env_soundscape_triggerable

Point-based soundscape entities are triggered when the player enters the specified radius of, and has a line of sight to the entity.

Brush-based soundscape entities

• trigger_soundscape
  Note:Must point to an env_soundscape_triggerable

Brush-based soundscape entities (trigger_soundscape) are triggered only when the player:

• first enters into the volume.
• is within the volume when it becomes enabled.
• remains inside the volume while exiting another.
• remains inside the volume while another becomes disabled

Note:Precedence is always given to the closest point-based soundscape that the player is still triggering. In all other cases, the active soundscape will always be that of the last successfully triggered soundscape entity.

Tip:Use the convar soundscape_debug to examine which entity is active and why.

Soundscape Placement

At first, a good rule is to place only as many soundscapes as you absolutely need. Try to choose from a similar set of soundscapes to be played, and then pick one that will be your primary soundscape. After that, place your secondary soundscapes at every contrasting location (e.g. house, generator room). Make sure that every location with localized sound effects has its own master soundscape that is tied to the proper targets.

Once you've gotten a general idea of where your soundscapes will be located, you'll then be able to start adding/configuring the entities that will trigger your soundscapes and create a kind of blueprint for how soundscapes will flow from one to another. In many cases, you'll be placing entities that block off all exits from your contrasting locations with triggers to your primary soundscapes. Basically, the goal is to anticipate the player's movement throughout the map, and to block off each area in such a way that it will always have the proper soundscape activated.

After your flow is organized, you'll be able to specialize your soundscapes/triggers to behave in complex ways (e.g responding to game events).

Creating Soundscapes

Soundscape scripts are very similar to soundscripts, but still remain entirely different things. Soundscapes require a few of their own rules, and are placed in plain text files that are separate from normal soundscript files. A typical soundscape file might be named soundscape_mall.txt and may contain anywhere from 5-30 different soundscapes that take on the following format...

<name>
{
	<rule>
	{
		<keyvalue>
		...
	}

	...
}

Common keyvalues

wave <string>

The path and filename of the sound to play, relative to game\sound\.

volume <normal>

1 is full power, 0 is silent.

pitch <integer>

Percentage value. +/-30 is the useful range.

position <0-7>

One of eight locations in the world (defined by the mapper) from which a sound can be emitted.

position random

As above, but the sound emits from a completely random location near the player.

attenuation <float>

How quickly the sound's volume drops as the camera moves away from it. Only relevant with a position specified.

Todo: What are the rules?

soundlevel <string>

Can be used instead of attenuation. Accepts one of the engine's pre-set values.

Warning:Remember to enclose any values with space characters in "quote marks".

Randomized values

Some rules accept 'upper' and 'lower' parameter values. For example:

"pitch"	"80,120"

Whenever the rule is executed the value will be randomly selected within the given range.

Rules

playlooping

Plays a sound constantly. Does not allow random values.

Note:Sound files will not properly loop unless they have a cue point. See Looping a Sound.

"playlooping"
{
	"volume"	"0.98"
	"pitch"		"110"
	"soundlevel"	"SNDLVL_85dB"

	"position"	"0"

	"wave"	"ambient/swamps/water_Lap_loop_st.wav"
}

playrandom

Plays a sound after given number of seconds. Allows random values.

Playrandom requires all wave KVs to be inside rndwave (even if there is only one). A random selection will be made every time the rule is executed.

"playrandom"
{
	"time"		"1,4"
	"volume"	"0.4,1"
	"pitch"		"90,105"
	"soundlevel"	"SNDLVL_85dB"

	"position"	"0"

	"rndwave"
	{
		"wave"	"ambient/wind/wind_med1.wav"
		"wave"	"ambient/wind/wind_hit1.wav"
	}
}

playsoundscape

Plays a complete soundscape. DSP presets in the 'sub-scape' are ignored.

name

Name of the soundscape to play.

position <int>

Offsets each position index of the sub-scape.

Todo: What does that mean?

positionoverride <int>

Forces all positioned sounds in the sub-scape to emit from one location.

ambientpositionoverride <int>

Forces all unpositioned (i.e. ambient) sounds in the sub-scape to emit from one location.

"SubScape"
{ 
	"playsoundscape"
	{ 
		"name"	"GenericIndoor"

		// Overall sub-scape volume to 50% 
		"volume"	"0.5"

		// Emit all positioned sounds from position 0
		"positionoverride"	"0"

		// Emit all ambient sounds from position 1
		"ambientpositionoverride"	"1"
	} 
}

dsp

Overrides the current DSP preset (which would otherwise be derived from the $surfaceprop of nearby materials).

For a list of values, open scripts\dsp_presets.txt. You may need to extract this from the relevant engine GCF with GCFScape. To preview a DSP preset, submit room_type <int> to the console.

Note:Be careful when setting presets in soundscapes that could be used in many different locations.

// Disable DSP and play no ambient sounds 
"Empty"
{ 
	"dsp"	"0"
}

Todo: What is dsp_volume? Does it actually exist?

soundmixer

Selects a custom soundmixer. Soundmixers manage the priority and volume of groups of sounds; create new ones in scripts\soundmixers.txt (ALWAYS use Default_Mix as a template).

"quiet"
{
	"soundmixer"	"Citadel_Dialog_Only"

	...
}

Example

"swamp.water.slow"
{
	"dsp" "1"

	"playlooping"
	{
		"volume"	"0.98"
		"pitch"		"110"
		"soundlevel"	"SNDLVL_85dB"

		"position"	"0"

		"wave"	"ambient/swamps/water_Lap_loop_st.wav"
	}

	"playrandom"
	{
		"time"		"1,4"
		"volume"	"0.4,1"
		"pitch"		"90,105"
		"soundlevel"	"SNDLVL_85dB"

		"position"	"1"

		"rndwave"
		{
			"wave"	"ambient/wind/wind_med1.wav"
			"wave"	"ambient/wind/wind_hit1.wav"
		}
	}
}

Using custom soundscapes

Soundscapes can be stored in two ways:

• In the game specific text files listed in <game>\scripts\soundscapes_manifest.txt.

• In map specific text files. The soundscape name and location should be as following:

    <game>\scripts\soundscapes_<yourmapname>.txt

For example, with a Counter-Strike: Source map called de_kilo2.bsp:

    <game>\scripts\soundscapes_de_kilo2.txt

With proper naming of your soundscape script the game will load it when the map loads.

Note:All soundscape names must be globally unique within a game.

See also

• env_soundscape
• env_soundscape_proxy
• env_soundscape_triggerable
• trigger_soundscape
• Notepad++ VDF languages