Difference between revisions of "Soundscripts"

From Valve Developer Community
Jump to: navigation, search
Line 4: Line 4:
;{{Note|>The sound file MUST be in a folder within the <code>sounds</code> folder. So (sounds/)folder/sound.wav will work, while (sounds/)sound.wav will not.}}
;{{Note|The sound file MUST be in a folder within the <code>sounds</code> folder. So (sounds/)folder/sound.wav will work, while (sounds/)sound.wav will not.}}

Revision as of 22:46, 24 August 2011

Soundscripts contain "sound entries" that are used to wrap Source-specific playback instructions around WAV or MP3 files.

Note.png Note: The sound file MUST be in a folder within the sounds folder. So (sounds/)folder/sound.wav will work, while (sounds/)sound.wav will not.

A sound entry can define the meaning of a sound to NPCs, its pitch and volume, how far away it can be heard from (attenuation), and can be used to randomise which precise sound file is played. Template:P2-add can be used to define even more complex behaviours.

Soundscripts are loaded on the server only from:

  • scripts/game_sounds_manifest.txt
  • maps/<mapname>_level_sounds.txt

All filepaths within a soundscript are relative to the sound folder.

Example entry

	channel		CHAN_AUTO
	volume		VOL_NORM
	pitch		PITCH_NORM
	soundlevel	SNDLVL_NORM
	wave		common/null.wav

If a value has a space or tab character within it, wrap it in "quote marks".

Tip.png Tip: To have a random numeric value chosen every time the sound plays, type a lower bound and a higher bound, separated by a comma. Example: volume 0.45,0.65.


Wave / rndwave

Filename of the sound to play.

wave	common/blah1.wav

You can also have the engine pick from a list of random files. A given sound won't repeat until all of the others have played. Note that the random choice is decided by the server, not the client.

	wave	common/blah1.wav
	wave	common/blah2.wav
	wave	common/blah3.wav


A number between 0 and 1, where 1 is the sound's original volume. VOL_NORM will insert your mod's default volume, which will probably be 1.


Any number between 0 and 255, where 100 is the sound's original pitch and 255 is high.

  • PITCH_LOW = 95
  • PITCH_HIGH = 120


Channels are used to categorise sounds in a way that NPCs, and game logic in general, can understand.

Default, generic channel.
Player and NPC weaponsfire.
Voiceover dialogue.
Generic physics impact sounds, health/suit chargers, 'use' sounds.
Clothing, ragdoll impacts, footsteps, knocking/pounding/punching etc.
Sounds that can be delayed by an async load, i.e. aren't responses to particular events.
Confirm:This won't make the sound actually stream; use the * prefix for that.
Used when playing sounds through console commands.
A constant/background sound that doesn't require any reaction.
Network voice data (online voice communications)
Custom channels can be defined here.


The sound's attenuation; how fast it drops away. The engine starts running into trouble below 60dB.

Code Value Description
SNDLVL_NONE 0 Everywhere
SNDLVL_20dB Rustling leaves
SNDLVL_25dB Whispering
SNDLVL_30dB Library
SNDLVL_45dB Refrigerator
SNDLVL_50dB 3.9 Average home
SNDLVL_55dB 3.0
SNDLVL_IDLE 2.0 Normal conversation, clothes dryer
SNDLVL_65dB 1.5 Washing machine, dishwasher
SNDLVL_70dB 1.0 Car, vacuum cleaner, mixer, electric sewing machine
SNDLVL_NORM 0.8 Busy traffic
SNDLVL_80dB 0.7 Mini-bike, alarm clock, noisy restaurant, office tabulator, outboard motor, passing snowmobile
SNDLVL_TALKING 0.7 Valve's chosen dialogue attenuation
SNDLVL_85dB 0.6 Average factory, electric shaver
SNDLVL_90dB 0.5 Screaming child, passing motorcycle, convertible ride on freeway
SNDLVL_100dB 0.4 Subway train, diesel truck, woodworking shop, pneumatic drill, boiler shop, jackhammer
SNDLVL_105dB Helicopter, power mower
SNDLVL_110dB Snowmobile (drivers seat), inboard motorboat, sandblasting
SNDLVL_120dB Car horn, propeller aircraft
SNDLVL_130dB Air raid siren
SNDLVL_GUNFIRE 0.27 Threshold of pain, gunshot, jet engine
SNDLVL_140dB 0.2
SNDLVL_150dB 0.2
SNDLVL_180dB Rocket launching

Operator stacks

Portal 2 introduced operator stacks, which are used to add complex behaviour to sounds. To enable them, you must set soundentry_version to 2.

There are three types of stack, each triggered at different times:

  • start_stack
  • update_stack
  • stop_stack

In each case you can either start from scratch or use the import_stack command to extend a template defined in scripts/sound_operator_stacks.txt.


	channel		CHAN_AUTO
	soundlevel	SNDLVL_105db
	volume		1.0
		wave		"vfx/light_flicker/light_flicker_end_01.wav"
		wave		"vfx/light_flicker/light_flicker_end_02.wav"
		wave		"vfx/light_flicker/light_flicker_end_03.wav"
		wave		"vfx/light_flicker/light_flicker_end_04.wav"

	soundentry_version 2

		start_stack // applied when the sound begins
			import_stack 	"P2_exclusion_time_blocker_start" // defined in scripts/sound_operator_stacks.txt

			// We are now extending/configuring P2_exclusion_time_blocker_start

			block_entries // prevents another sound from playing
				input_duration 0.25 // seconds to block for
				match_entry "World.LightFlickerEnd" // the sound entry to block
				match_entity false // only on the same entity that this sound is playing from?


There are 28 operators used in Portal 2, but they are re-configured and combined in hundreds of different ways. Most of the resulting "stacks" are very specific, and this page will only deal with the more general ones.

To do: Work out a sane way of documenting all this!


Limits the maximum number of sounds that can be played at once, either by sound name or entity. A sound will not stop itself from playing.

import_stack	"P2_poly_limiting_start"

	match_entry "VFX.OGSignFlicker"
	input_max_entries 3.000000


Smoothly transitions a sound from one location to up to eight others as the player moves through a map. An unreleased tool can auto-generate these. Position 1 is where the sound was emitted from.

import_stack "p2_update_dialog_spatial_cave"

	input_entry_count 3
	// position 2
	input_position_1[0]	2129
	input_position_1[1]	-850
	input_position_1[2]	-1267
	// position 3
	input_position_2[0]	1473
	input_position_2[1]	-1200
	input_position_2[2]	-1343


Plays another sound entry.

import_stack "stop_and_play"

	entry_name VFX.FizzlerDestroy

Sound Characters

The first two characters of a WAV's name are scanned for the following:

Streams from the disc, get flushed soon after. Use for one-off dialogue files or music.
Bypasses DSP and affected by the user's music volume setting.
Non-directional; audible everywhere. "Default mono or stereo", whatever that means.
Doppler encoded stereo: left for heading towards the listenr and right for heading away.
Stereo with direction: left channel for front facing, right channel for rear facing. Mixed based on listener's direction.
Distance-variant stereo. Left channel is close, right channel is far. Transition distance is hard-coded; see below.
Spatializes both channels, allowing them to be placed at specific locations within the world; see below.
Note.png Note: Sometimes "(" must be used instead; see below.
Forces low quality, non-interpolated pitch shift.
Memory resident; cache locked.
An NPC sentence.
Voice chat data. You shouldn't ever need to use this.

For example:


Spatial Stereo

Adding ")" in front of a stereo sound name in the soundscript such as ")weapons/m4a1/m4_shoot.wav" tells the sound engine that it is a spatialized sound; this allows the sound to emit from a specific location within the world. When not used, stereo sounds play in a fixed 2-channel orientation and cannot be panned to simulate a location. Single-channel files do not require ")" before the filename and will be spatialized automatically.


Soundscapes have special needs. Stereo wave files used in PlayRandom require that ( is placed before the filename. PlayLooping still uses ) but ( will spatialize the two channels separately for an alternate effect; ( sounds more environmental, but the exact nature of this behavior is unknown. Generic soundscripts can sometimes use ( to gain the same stereo spatialization that occurs in PlayLooping.

For example:

wave ")ambient/stereo_alarm.wav" // Typical usage in a standard soundscript

But in soundscapes:

	time		33,68
	volume		.6,1
	pitch		90,105
	position	0
		wave "ambient/mono_siren.wav" // Mono files are always spatialized properly
		wave ")ambient/stereo_alarm.wav" // WRONG; sound will not be spatialized
		wave "(ambient/stereo_siren.wav" // Correct; sound will be spatialized normally
	volume		.6
	pitch		100
	position	0
	wave		")ambient/stereo_siren.wav" // standard spatialization; both channels originate at same location
	//wave		"(ambient/stereo_siren.wav" // stereo spatialization; one of the channels is spatialized alternatively

Distance variance in Source

Adding ^ in front of a sound name, such as "^weapons/explode3.wav" tells the sound engine that it is a distance based sound. The left channel of the .wav is the 'near' sound that will play when the sound originates close to you, and the right channel is the 'far' sound that will play when the sound originates far from you. If the ^ mark is not used in the soundscript the sound is treated as stereo with no directionality or distance. This is a different feature than the sndlvl entry to control attenuation. This distant variant feature allows you to play two different sounds (but using only one file) and cross-fading between the two depending on how far away the sound originates.

Currently the fade distances are hardcoded to begin at 20 feet (240 world units) and end at 110 feet (1320 world units) and cannot be changed in a mod.

See also


  • src/public/soundflags.h
  • src/public/soundchars.h
  • scripts/game_sounds_header.txt
  • scripts/game_sounds.txt
  • scripts/game_sounds_manifest.txt