Soundscape (Source 2)

Source Engine

Source 2

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.

Individual "Sounds" within a soundscape are called Sound Events. A soundscape script includes a listing of all Sound Events within the soundscape, and parameters on how the audio can be heard, played back, or otherwise manipulated. Beyond that, individual sound events can have their own parameters defined, which will function as written unless the parameters of the soundscape override those specific functions. The parameters that can be specified in a soundscape or sound event are theoretically option, as without defining them, they will revert to an engine "default".

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

Tip:

• Cross fade time is defined by the cvar soundscape_fadetime, or fadetime in newer branches.
• Use the cvar soundscape_debug to examine which soundscape is active and why.
• Soundscapes and sound events can be configured to either load into memory upon being called (i.e. a player entering a soundscape radius), or they can be pre-loaded upon launch of the addon in-game. This is preferable for sound events that need to be as timely as possible (such as gunshots), but is unnecessary for sounds such as music or atmosphere. The delay to load into memory is minimal, but perceptible in some instances.

Note:

• Sound files will not properly loop unless they have a cue point. See Looping a Sound. In Source 2, both .WAV & .MP3 files can be looped.
• At least one soundscape radius or trigger box should cover the info_player_start or whatever game specific player spawn entities you have, else the players will spawn without loading any soundscape until they trigger a Soundscape.

Soundscapes

Browsing Soundscapes

Soundscapes are typically located in the scripts\ folder of a game, stored across multiple text files prefixed with soundscapes_. Each file is loaded via scripts\soundscapes_manifest.txt, which lists all soundscape scripts that should be mounted by the game. Soundscapes mounted through the manifest can be used anywhere in the game, even if they're only intended for a specific area.

Some Source 2 titles have done away with having many of the game files accessible as editable text files, and instead have many such functions packed into .vpk files. For others, these files can beaccessed through an addon's Sounds & Sound Events folders, and the soundevents_addon.vsndevts file.

At the bottom of this article you will find links to lists of soundscapes for individual games, along with attempts at describing them.

You can browse through all the available soundscapes in a current game first hand, using the in-game console command PlaySoundscape. After typing in the first letter as the commands parameter, the auto-complete feature will list them as suggestions. You can then scroll through this list using the arrow keys.

Configuring Soundscapes

Soundscapes can only be configured through the entity env_soundscape.

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. (Such as point_soundevent).

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 <addon>/Sound Events/soundevents_addon.vsndevts 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.

Soundscape entities

env_soundscape entities are themselves point-based, but trigger when the player enters their specified radius and the entity has a line of sight to them. This radius has no bearing on where and how the audio plays, only when it is triggered. A soundscape will not stop playing just because a player exits its radius or it loses line of sight to them.

As only one soundscape can be active at any one time, if one or more soundscape entities are triggered simultaneously, the closest one is given precedence.

Tip:Use the cvar 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).

Custom Soundscapes

Creation

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.

Bug:If a soundscape's name is too long, soundscape entities will not be able to trigger it, although it will still be triggerable through console. Character limit unknown.  [todo tested in ?]

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

	...
}

Common keyvalues For Sound Events

type <string>

This references specific pre-defined classifications for audio files, and how they are treated in individual Source games. Generally required to properly define an initial sound event, essentially telling the engine "You're allowed to use this for this game". type does not inherently define any parameters. (i.e. type "csgo_mega"

vsnd_files_track_01 <string>

The path and filename of the sound to play, relative to addon\sound\. vsnd_files_track_01 can be modified for each sequential sound file being referenced (i.e. vsnd_files_track_01 = "sound/soundfile_01.vsnd", vsnd_files_track_02 = "sound/soundfile_02.vsnd". This must reference the compiled (.vsnd) version of the audio file, located under the game directory, rather than the original .WAV or .MP3 file located in the addon directory. Multiple files can be referenced as one "track", at which point the file played will be randomly selected when the sound event is called on by the soundscape.

soundevent_01 <string>

References another pre-existing sound event. soundevent_01 can be modified for each sequential sound file being referenced (i.e. soundevent_01 = "Sound_Event.01", vsnd_files_track_02 = Sound_Event.02.

base <string>

Copies a pre-existing copy, from which sounds and parameters will be pulled from, but can be overridden. (i.e. base = "Sound_Event.01"

volume <float>

1 is full power, 0 is silent.

volume_random_max <float>

Defines upper end of a range. 1 is full power, 0 is silent.

volume_random_min <float>

Defines lower end of a range. 1 is full power, 0 is silent.

use_distance_volume_mapping_curve <string>

Enables or disables position-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

distance_volume_mapping_curve <normal>

Defines a distance-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_distance_volume_mapping_curve. This function is useful for creating sound entities that "radiate" sound, and are immersive.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ distance, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 1 at the entity origin, and 0 500 units away:

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 500.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Distance is defined in Hammer Units from the entity origin. Volume is a range, where 1 is full power and 0 is silent.

use_time_volume_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables time-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

time_volume_mapping_curve <normal>

Similar to distance_volume_mapping_curve, defines a time-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_time_volume_mapping_curve. This function is useful for creating fade-ins.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ time, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 0 at the beginning of the sound event being triggered, and fades-in with a linear curve to 1 after 5 seconds.

[ 0.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

[ 5.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

Time is defined in seconds. Volume is a range, where 1 is full power and 0 is silent.

use_fadetime_volume_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables further time-based volume mapping, which can then be defined by another keyvalue. Possible values include true & false.

fadetime_volume_mapping_curve <normal>

Similar to distance_volume_mapping_curve, defines a time-to-volume ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_fadetime_volume_mapping_curve. This function is useful for creating fade-outs.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ time, volume, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where volume is 1 at the beginning of the sound event being triggered, and fades-out with a linear curve to 0 after 5 seconds.

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 5.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Time is defined in seconds. Volume is a range, where 1 is full power and 0 is silent.

pitch <integer>

Integer value for audio pitch. 1 is the original pitch of the file, and every whole integer increases or decreases the pitch by an octave (12 semitones, 1200 cents). Non-whole integers are valid, for smaller scale changes in pitch. Importantly, pitch also defines playback speed. Thus, pitch = 1 will result in a file playing back at original pitch and original speed, pitch = 2 will result in a file playing back at one octave above it's original pitch and twice it's original speed, and pitch = 0.5 will result in a file playing back at one octave below it's original pitch and half it's original speed.

pitch_random_max <float>

Defines upper end of a range. Positive number required.

pitch_random_min <float>

Defines lower end of a range. Negative number required.

occlusion <string>

Similar to use_distance_volume_mapping_curve, enables or disables occlusion, which can then be defined by another keyvalue. Possible values include true & false.

occlusion_intensity <integer>

Determines how occluded sounds are when played back. Will not function unless enabled by occlusion. Occlusion results in a sound being "muffled" when the player has a solid object between their line of sight of the sound origin, with occlusion_intensity acting as a percentage value ranging from 0 to 100.

use_distance_unfiltered_stereo_mapping_curve <string>

Similar to use_distance_volume_mapping_curve, enables or disables distance-based stereo mapping, which can then be defined by another keyvalue. Possible values include true & false.

distance_unfiltered_stereo_mapping_curvee <normal>

Similar to distance_volume_mapping_curve, defines a distance-to-stero width ratio curve by mapping points on a graph with up to three data points via integer strings. Will not function unless enabled by use_distance_unfiltered_stereo_mapping_curve. This function is useful for immersion, as immersive sounds are often wider in the stero field when closer to the player, and more narrow when further away.

A data point is defined as six integers with one decimal place: [ X.X, X.X, X.X, X.X, X.X, X.X, ]

Each value is related to an attribute of the data point: [ distance, stereo width, curve point #1, curve point #2, curve point #3, curve point #4, ]

Example of a straight line curve, where stereo width is 1 when the player is at the same location as the sound origin, and 0 when the player is 500 units away from the sound origin.

[ 0.0, 1.0, 0.0, 0.0, 2.0, 3.0, ]

[ 500.0, 0.0, 0.0, 0.0, 2.0, 3.0, ]

Distance is defined in Hammer Units from the entity origin. Stereo Width is a range, where 1 is the original stereo imaging of the audio file and 0 is fully mono playback.

Rules

Confirm:Which rules maintain common syntax with Source 1 soundscripts, and all new possible rules available in Source 2.

Storing and using custom soundscapes

Source 2 does away with the sound scripts model, and replaces those files with soundevents_addon.vsndevts. This is also an editable text file, and is where new user-created soundscapes and sound events can be entered. This file contains example soundscapes and sound events that can be copied or modified. The same key values and functions detailed earlier for scripts work within this file as well. The This file details potential uses for the preset base soundevents and soundscapes, and more information on implementing new content.

An example of a base Soundscape:

"ambient_example.outdoors" = 
{
	base = "amb.soundscapeParent.base"
	enable_child_events = true
	soundevent_01 = 
	[
		"ambient_example.outdoors.birds",
		"ambient_example.outdoors.airplanes",
		"ambient_example.outdoors.wind",
	]
}

An example of a base sound event:

"amb.base" = 
{
	type = "csgo_mega"
	mixgroup = "Amb_Common"
	occlusion_intensity = 0.0
	distance_effect_mix = 0.0
	restrict_source_reverb = true
	use_distance_unfiltered_stereo_mapping_curve = true
	use_time_volume_mapping_curve = true
	distance_volume_mapping_curve = 
	[
		[
			0.0, 1.0, -0.00394, -0.00394,
			2.0, 3.0,
		],
		[
			300.0, 0.0, -0.002991, -0.002991,
			2.0, 3.0,
		],
	]
	fadetime_volume_mapping_curve = 
	[
		[
			0.0, 1.0, -1.223776, -1.223776,
			2.0, 3.0,
		],
		[
			0.208571, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
	distance_unfiltered_stereo_mapping_curve = 
	[
		[
			0.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
		[
			300.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
	time_volume_mapping_curve = 
	[
		[
			0.0, 0.0, 0.0, 0.0,
			2.0, 3.0,
		],
		[
			0.297143, 1.0, 0.0, 0.0,
			2.0, 3.0,
		],
	]
}

While soundevents_addon.vsndevts is a text file, it has to be compiled by either Hammer, or the Game Engine before it will function correctly. If you have completed entered in all the parameters for your soundscapes and sound events in the text file, and they are not appearing in Hammer or playing in game, soundevents_addon.vsndevts can be recompiled either be re-openeing a build of the map in-game, or by selecting the file in the "Asset Browser", right clicking, and selecting Recompile > Full>.

To add Soundscape and sound event entries to soundevents_addon.vsndevts, they should be added directly after the soundscape templates in the file, just before the ///BASE SOUNDEVENT TEMPLATES header. An example Source 2 Soundscape:

"soundscape_name" 
{
	base = "amb.looping.stereo.base"
	volume = 0.2 
	pitch = 1.0
	mixgroup = "Ambient"
	use_distance_volume_mapping_curve = false	
	vsnd_files_track_01 = "sounds/soundevent_audio_file.vsnd"
	distance_unfiltered_stereo_mapping_curve = 
	[
		[
			0.0, 1.0, 0.0, 0.0, 2.0, 3.0,
		],
		[
			1000, 1.0, 0.0, 0.0, 2.0, 3.0,
		],
	]
}

This example uses a template soundevent base for many of its parameters when playing back the audio file, and then overrides a few of those parameters, such as the specified stereo mapping curve.

Storing Audio Files

In Source 2, Audio files that you would like to become sound events, triggerable as part of a soundscape, must be stored in the sounds folder, under the content directory of your addon. After you have placed files there, launch Hammer, and open your addon. This should cause the audio files to be auto-compiled into .vsnd files. Check the asset browser, or the sounds folder, under the game directory, to ensure they have been compiled. The soundevents_addon.vsndevts file can only read, and call on .vsnd files, rather than the raw .wav or .mp3 files.

See also

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