From Valve Developer Community
Revision as of 15:09, 9 February 2006 by Charron (talk | contribs) (Using the env_soundscape Entity: ask your questions in the talk page.)
Jump to: navigation, search

Soundscapes are definitions of sounds to be played within the Source engine. These soundscapes include settings for various DSP effects as well as commands for controlling sound playback (randomizing, looping etc). The sound system will play one soundscape at a time and crossfade between soundscapes as they are changed. There is some flexibility here that will be explained later in the document. The entity env_soundscape can be used to set a player's soundscape if he moves within its radius and it has line of sight to the player. Only one env_soundscape can be active per player at any one time. The env_soundscape refers to individual soundscapes that are defined in the soundscapes.txt script file, or in a custom, map-specific file.

<Half-Life 2> List of HL2 Soundscapes

<Counter-Strike: Source> List of CSS Soundscapes

Using the env_soundscape Entity

To control soundscapes in a game map, we use the env_soundscape entity. Each entity has a radius and soundscape field. The soundscape field is the name of a soundscape to play when activated, as defined in soundscapes.txt. The radius describes a sphere around the entity that a player must be within to be considered for activating the soundscape. The player must also be visible to the soundscape entity (not occluded by walls or other obstructions). Once a player has triggered a soundscape, that soundscape will remain active until a new one is activated by the player. This means that even if a player leaves a soundscape’s radius after having activated it, the soundscape will continue to play. Only one soundscape may play at any one time. If a new soundscape is activated, the currently playing soundscape will fade out while the new one fades in.

The entity also has eight entity references slots available for use. These correspond to the position values declared in the soundscape. These may point to any valid entity, and will use that entity’s position as a reference point for sound spatialization. Creating and Editing soundscapes.txt Entries

Soundscapes.txt is a simple key/value pair file with the same format as .VMT or .VMF:

   "key1" "value1" 
   "key2" "value2" 
          "key3" "value3" 
   "key4" "value4" 

// Comment text, not parsed 
"example2"        // This is a comment as well 

Each root-level section (a section that is not within another section) is considered to be a definition of a soundscape. The name given to this soundscape is referenced by the env_soundscape entity.



Sets the DSP effect to a particular room number. In general this should be set to 1, which is the “automatic” DSP. With this DSP the sound engine will attempt to discover the proper parameters based on the surrounding geometry. Setting the DSP to 0 will result in effectively turning DSP effects off. Using other pre-sets are only recommended for special cases. These pre-sets are declared in the ../hl2/scripts/dsp_preset.txt file.


    // This soundscape disables DSP and plays no sounds 
               "dsp"   "0" 


Plays a looping sound until a new soundscape is triggered.


  • The name of the wave file.


  • Sets the wave's volume (0-1).


  • Sets the pitch for the wave (100 is normal).


  • Sets the attenuation of the wave (only used if a "position" command follows).
    • Note.png Note: These can be random intervals - the random value will be chosen once each time the soundscape is triggered.


  • References a position by index (0-7) that the level designer has pointed to in the env_soundscape entity.


    // This plays a single looping sound, with a generic reverb (room type 1)
         "dsp"   "1" 
                "volume"       "1" 
                "pitch"        "100" 
                "wave"         "ambient/areas/air_exchange/indoor2.wav" 


Plays random sound events until a new soundscape is triggered.


  • Time interval of the random event.


  • Random volume interval (0-1).


  • Random pitch interval (50-250).


  • Random attenuation of sound.


  • A list of random wave files to choose from.


  • Position to use, if spatialized (0-7).


        "dsp"   "1" 
            // Play every 0.1 to 1.5 seconds 
            "time" "0.1, 1.5" 
            // At a volume of 0.5 to 1 
            "volume" "0.5,1" 
            // At a pitch of 50% to 120% 
            "pitch" "50,120" 
            // With an attenuation of 0.7 
            "attenuation" "0.7" 
            // At entity specified at position 1 
            "position"  "1" 
            // Play one of these .wav files randomly each time 
                "wave" "temp/soundscape_test/music_snippet1.wav" 
                "wave" "temp/soundscape_test/music_snippet2.wav" 
                "wave" "temp/soundscape_test/music_snippet3.wav" 


Plays another soundscape and all of its sub-commands.

NOTE: DSP effects cannot be altered by sub-soundscapes.


  • Sub-soundscape to play.


  • All volumes in the sub-soundscape are scaled by this value (0-1).


  • An offset added to each position index of the sub-soundscape (0-7).


  • Forces all sub-soundscape positional sounds to occur at a single position originating from the entity at this index (0-7).


  • Forces all sub-soundscape ambient sounds to be spatialized at a particular position originating from the entity at this index. Useful to make ambient sounds come “from a direction" (0-7).

        "dsp"   "1" 
            // Sub-soundscape to play 
            "name" "GenericIndoor"
            // All sub-soundscape volumes reduced by 50% 
            "volume" "0.5"
            // All sub-soundscape position sounds will come from this point 
            "positionoverride" "0"
            // All sub-soundscape ambient sounds will come from this point 
            "ambientpositionoverride" "1" 

See also


Sound Mixers are used to provide custom volume control over various sound categories, called mix groups. Sound Mixers are referenced in Soundscapes via "SOUNDMIXER" "name".

Example soundscape with soundmixer.

	"dsp"	"1"
	"dsp_volume" "1.0"
	"SOUNDMIXER" "Default_Mix"

ALWAYS use Default_Mix as a template.

//	group name			mix value
//	----------			---------
	"Explosions"			"0.90"
	"Player_Weapons_Loud"		"1.0"
	"Player_Suit"			"0.56"
	"Weapons"			"0.79"
	"AHELI_WEAPON"			"0.85"
	"bullethit"			"0.67"
	"Music"				"0.81"
	"All"				"0.72"


  • scripts/soundmixers.txt from create a mod, source sdk
  • scripts/soundscapes.txt from create a mod, source sdk