Soundscripts
Soundscripts contain "sound entries" that are used to wrap Source-specific playback instructions around WAV or MP3 files.
File format
Sound entry
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. Operator stacks (in all games since ) can be used to define even more complex behaviours.
Soundscripts are loaded on the server only from:
All filepaths within a soundscript are relative to the game's sound\
folder.
Example
entry.name { 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".
volume 0.45,0.65
.Commands
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.
rndwave { wave common/blah1.wav wave common/blah2.wav wave common/blah3.wav }
sound\
folder. So sound\folder\sound.wav
will work, while sound\sound.wav
will not.Volume
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
.
Pitch
Any number between 0 and 255, where 100 is the sound's original pitch and 255 is very high.
- PITCH_LOW = 95
- PITCH_HIGH = 120
Channel
Channels are used to categorize sounds in a way that NPCs, and game logic in general, can understand.
- Exceeding this will result in a channel allocation error, preventing sounds from playing.
- CHAN_AUTO
- Default, generic channel.
- CHAN_WEAPON
- Player and NPC weapons.
- CHAN_VOICE
- Voiceover dialogue. Used for regular voice lines, etc.
- Note:If sound with this channel is emit by an entity that has the "mouth" attachment, the sound comes from it.
- CHAN_VOICE2
- Additional voice channel. Used in for the announcer.
- CHAN_ITEM
- Generic physics impact sounds, health/suit chargers,
+use
sounds. - CHAN_BODY
- Clothing, ragdoll impacts, footsteps, knocking/pounding/punching etc.
- CHAN_STREAM
- 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.
- CHAN_REPLACE
- Used when playing sounds through console commands.
- CHAN_STATIC
- A constant/background sound that doesn't require any reaction.
- CHAN_VOICE_BASE
- Network voice data (online voice communications)
- CHAN_USER_BASE+<number>
- Custom channels can be defined here (Allocates a channel for the desire sound entry).
SoundLevel
The sound's attenuation; how fast it drops away. The engine starts running into trouble below 60dB.
The following list contains all default sound levels, their attenuation value, real world examples, and in-game examples. All values and real world examples were taken from src\public\soundflags.h
.
It is possible to pass a literal number value ("150" as opposed to "SNDLVL_150") and freely choose any number between 0 and 255. Games tested:
Operator stacks
Portal 2 engine branch introduced Operator Stacks, which are used to add complex behaviour to sounds. To enable them, you must set soundentry_version
to 2
.
Outside Portal 2, they are supported in Counter-Strike: Global Offensive and Dota 2 (which now uses Source 2; the operator stacks have been greatly expanded upon and many of their names have been changed), Day of Infamy, and Insurgency.
There are three types of stack, each triggered at different times:
prestart_stack
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
.
Example
VFX.LightFlickerEnd
{
channel CHAN_AUTO
soundlevel SNDLVL_105db
volume 1.0
rndwave
{
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
operator_stacks
{
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?
}
}
}
}
Templates
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.
limit_sound
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"
limit_sound
{
match_entry "VFX.OGSignFlicker"
input_max_entries 3.000000
}
position_array
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"
position_array
{
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
}
play_entry
Plays another sound entry.
import_stack "stop_and_play"
play_entry
{
entry_name VFX.FizzlerDestroy
}
Sound characters
The first two characters of a WAV's name are scanned for the following:
Symbol | Name | Purpose | Game/branch | Notes |
---|---|---|---|---|
* | CHAR_STREAM | Streams from the disc, get flushed soon after. Use for one-off dialogue files or non-looping music. | All | |
# | CHAR_DRYMIX | Bypasses DSP, becomes affected by the user's music volume setting (snd_musicvolume). The latter part also requires the sound to be non directional (soundlevel of 0). | -//- | Warning:Using this character on a sound entry utilizing an update_stack where the volume is zeroed out, whether by the update_stack or by the sound entry itself(volume 0.0), will cause an update_stack loop. Not only does this have negative performance implications, the sound will consume an audio channel until the loop is interrupted or the sound is stopped.[Confirm]
|
@ | CHAR_OMNI | Non-directional sound; plays "everywhere", similar to SNDLVL_NONE, except it fades with distance from its source based on its sound level. | -//- | |
> | CHAR_DOPPLER | Doppler encoded stereo: left for heading towards the listener and right for heading away. | -//- | |
< | CHAR_DIRECTIONAL | Stereo with direction: left channel for front facing, right channel for rear facing. Mixed based on listener's direction. | -//- | Todo: Relationship with
CHAR_DIRSTEREO in Counter-Strike: Global Offensive? |
^ | CHAR_DISTVARIANT | Distance-variant stereo. Left channel is close, right channel is far. | -//- | Transition distance is hard-coded; see below. |
) | CHAR_SPATIALSTEREO | Spatializes both channels, allowing them to be placed at specific locations within the world; see below. | -//- | Sometimes ( must be used instead; see below.
|
} | CHAR_FAST_PITCH | Forces low quality, non-interpolated pitch shift. | -//- | |
$ | CHAR_CRITICAL | Forces sound to be cached at a fixed point in memory. | Up to | Only affects Original Xbox, which streams all audio regardless of * unless marked as critical. (removed since ). |
! | CHAR_SENTENCE | An NPC sentence. | Since | |
? | CHAR_USERVOX | Voice chat data. You shouldn't ever need to use this. | All | |
& | CHAR_HRTF_FORCE | Indicates wav should use HRTF spatialization for all entities (including owners). | ||
~ | CHAR_HRTF | Indicates wav should use HRTF spatialization for non-owners. | ||
` | CHAR_HRTF_BLEND | Indicates wav should use HRTF spatialization for non-owners, blended with stereo for sounds sufficiently close. | ||
+ | CHAR_RADIO | Indicates a 'radio' sound -- should be played without spatialization. | ||
$ | CHAR_SUBTITLED | Indicates the subtitles are forced. | ||
% | CHAR_MUSIC | Indicates main menu music. | ||
( | CHAR_DIRSTEREO | Indicates directional stereo wav (like doppler). |
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
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
.
(
stereo-spatialization behavior present in all engine branches? Some preliminary testing reveals it may be absent from Garry's Mod.For example:
wave ")ambient/stereo_alarm.wav" // Typical usage in a standard soundscript
But in soundscapes:
playrandom
{
time 33,68
volume .6,1
pitch 90,105
position 0
rndwave
{
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
}
}
PlayLooping
{
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 sound file 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 crossfading between the two depending on how far away the sound originates.
The fade distances are hardcoded to begin at 240 world units and end at 1320 world units, and cannot be changed in custom maps or mods.
See also
ambient_generic
- Soundscape
- Left 4 Dead Soundscripts
- Podcast 17 Mike Morasky Interview - Discussion about audio production and insight into the evolution of the sound system. Archived from the original.