alliedmodders/sourcemod — pull request #65 by powerlord (2014-07-03 15:10:19+00:00)
Title: New functions for SDKTools to get information from game_sound files

This is an updated version of the code from [bug 5942](https://bugs.alliedmods.net/show_bug.cgi?id=5942)

Basically, it consists of two natives: `PrecacheScriptSound` and `GetGameSoundParams`.

`native bool:PrecacheScriptSound(const String:soundname[]);`
`PrecacheScriptSound` caches all sounds associated with a game sound that aren't already cached.

```
native bool:GetGameSoundParams(const String:gameSound[],
&channel,
&soundLevel,
&Float:volume,
&pitch,
String:sample[],
maxlength,
entity=SOUND_FROM_PLAYER);
```
`GetGameSoundParams` takes a game sound name and fetches the fields from game_sounds.txt (and a game's other game_sound files) into the channel, soundLevel, volume, pitch, and sample fields. entity is used to determine the gender of the sound if a particular sound has genders. It will return false if the sound wasn't found. Note that sample will be random on game_sounds that have a rndwave section.

In addition, there are several new natives that serve as wrappers for `GetGameSoundParams`:
`EmitGameSound`, `EmitGameSoundToAll`, `EmitGameSoundToClient`, and `EmitAmbientGameSound`. These are all based on the EmitSound wrappers of the same name and take roughly the same arguments, but with the game sound name instead of the sample.

These wrap `GetGameSoundParams` and` EmitSound`/`EmitAmbientSound` as appropriate. All of them return false if GetGameSoundParams returns false.

Standard expected usage is something like this:

```
public OnMapStart()
{
PrecacheScriptSound(""Announcer.MVM_Bonus");
}

// Later on
EmitGameSoundToClient(client, "Announcer.MVM_Bonus");
```

Note: Most game sounds are precached by the game itself on map start, but this isn't guaranteed. For instance, TF2 doesn't cache the above sound on non-MvM maps. Therefore, it's recommended to use PrecacheScriptSound, which checks if a sound is precached before precaching it.