View source

{{toc-right}}

'''Soundscapes''' are audio scripts that create background ambience in maps. Sound clips can be looped or played randomly, and can be emitted evenly or from specific locations. A soundscape can also enforce [[DSP]] and [[Soundmixer]] profiles.

A soundscape can be used in any number of maps, requires only a single entity to implement, and does not generate any network traffic. However, the sounds it plays cannot be precisely controlled and only one soundscape can be active at any given time.

Soundscapes will crossfade between each other over a default of three seconds. Configure this from the console with <code>soundscape_fadetime</code>.

== Implementing ==

=== env_soundscape ===

Soundscapes are generally implemented with [[env_soundscape]]. Its keyvalues, inputs etc. should be self-explanatory.

The active env_soundscape is the one that the player:

# Has direct line of sight to
# Is in range of
# Is closest to (in case of a tie)

When an env_soundscape ceases to be active, the soundscape it began persists until another one is begun or the map changes.

{{tip|Use the [[convar]] <code>soundscape_debug</code> examine which entity is active and why.}}

=== trigger_soundscape ===

The other method is [[trigger_soundscape]]. The associated [[env_soundscape_triggerable]] will be played when the player is inside the trigger volume.

{{note|Unlike env_soundscape, trigger_soundscape's soundscapes do not persist once the player leaves its influence.}}

=== Finding a soundscape ===

Hammer doesn't list available soundscapes. The best way of finding one is loading up a map and using the [[concommand]] <code>playsoundscape</code> (which does know what's available and will autocomplete while you type) to start one up.

== Creating ==

=== Example ===

Soundscapes work like this:

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

=== Saving ===

Soundscapes can be stored in two ways:
*In the game specific text files listed by <code>game\scripts\soundscapes_manifest.txt</code>.
*In map specific text files listed by <code>scripts\soundscapes_<map name, no extension>.txt</code>. See [[Creating custom soundscapes]] for more information.
In either way, all soundscape names must be globally unique within a game.

=== Common keyvalues ===

; <code>wave <[[string]]></code>
: The path and filename of the sound to play, relative to <code>game\sound\</code>.
; <code>volume <[[normal]]></code>
: 1 is full power, 0 is silent.
; <code>pitch <[[integer]]></code>
: Percentage value. +/-30 is the useful range.
; <code>position <0-7></code>
: One of eight locations in the world (defined by the mapper) from which a sound can be emitted.
; <code>position random</code>
: As above, but the sound emits from a completely random location near the player.
; <code>attenuation <[[float]]></code>
: How quickly the sound's volume drops as the camera moves away from it. Only relevant with a <code>position</code> specified. {{todo|What are the rules?}}
; <code>soundlevel <string></code>
: Can be used instead of <code>attenuation</code>. Accepts [[Soundscripts#SoundLevel|one of the engine's pre-set values]].

{{warning|Remember to enclose any values with space characters in "quote marks".}}

=== Randomised 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]].}}

==== playrandom ====

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

Playrandom requires all <code>wave</code> KVs to be inside <code>rndwave</code> (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
 
 	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.

; <code>name</code>
: Name of the soundscape to play.
; <code>position <int></code>
: Offsets each position index of the sub-scape. {{todo|What does that mean?}}
; <code>positionoverride <int></code>
: Forces all positioned sounds in the sub-scape to emit from one location.
; <code>ambientpositionoverride <int></code>
: 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 [[material]]s).

For a list of values, open <code>scripts\dsp_presets.txt</code>. You may need to extract this from the relevant engine GCF with [[GCFScape]]. To preview a DSP preset, submit <code>room_type <[[int]]></code> 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 <code>scripts\soundmixers.txt</code> (ALWAYS use Default_Mix as a template).

 quiet
 {
 	soundmixer	Citadel_Dialog_Only
 
 	...
 }

== See also ==

* [[env_soundscape]]
* [[env_soundscape_proxy]]
* [[env_soundscape_triggerable]]
* [[trigger_soundscape]]
* [[Notepad++ VDF languages]]

* [[List of HL2 Soundscapes]]
* [[List of EP2 Soundscapes]]
* [[List of CS:S Soundscapes]]
* [[List of DoD:S Soundscapes]]
* [[List of TF2 Soundscapes]]
* [[List of Portal soundscapes]]
* [[List of L4D Soundscapes]]

[[Category:Sound System]]
[[Category:Level Design]]