3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _sdktools_sound_included
36 #define _sdktools_sound_included
39 * Sound should be from the target client.
41 #define SOUND_FROM_PLAYER -2
44 * Sound should be from the listen server player.
46 #define SOUND_FROM_LOCAL_PLAYER -1
49 * Sound is from the world.
51 #define SOUND_FROM_WORLD 0
58 SNDCHAN_REPLACE = -1, /**< Unknown */
59 SNDCHAN_AUTO = 0, /**< Auto */
60 SNDCHAN_WEAPON = 1, /**< Weapons */
61 SNDCHAN_VOICE = 2, /**< Voices */
62 SNDCHAN_ITEM = 3, /**< Items */
63 SNDCHAN_BODY = 4, /**< Player? */
64 SNDCHAN_STREAM = 5, /**< "Stream channel from the static or dynamic area" */
65 SNDCHAN_STATIC = 6, /**< "Stream channel from the static area" */
66 SNDCHAN_VOICE_BASE = 7, /**< "Channel for network voice data" */
67 SNDCHAN_USER_BASE = 135 /**< Anything >= this is allocated to game code */
71 * Sound flags for the sound emitter system.
75 SND_NOFLAGS= 0, /**< Nothing */
76 SND_CHANGEVOL = 1, /**< Change sound volume */
77 SND_CHANGEPITCH = 2, /**< Change sound pitch */
78 SND_STOP = 3, /**< Stop the sound */
79 SND_SPAWNING = 4, /**< Used in some cases for ambients */
80 SND_DELAY = 5, /**< Sound has an initial delay */
81 SND_STOPLOOPING = 6, /**< Stop looping all sounds on the entity */
82 SND_SPEAKER = 7, /**< Being played by a mic through a speaker */
83 SND_SHOULDPAUSE = 8, /**< Pause if game is paused */
87 * Various predefined sound levels in dB.
91 SNDLEVEL_NONE = 0, /**< None */
92 SNDLEVEL_RUSTLE = 20, /**< Rustling leaves */
93 SNDLEVEL_WHISPER = 25, /**< Whispering */
94 SNDLEVEL_LIBRARY = 30, /**< In a library */
95 SNDLEVEL_FRIDGE = 45, /**< Refridgerator */
96 SNDLEVEL_HOME = 50, /**< Average home (3.9 attn) */
97 SNDLEVEL_CONVO = 60, /**< Normal conversation (2.0 attn) */
98 SNDLEVEL_DRYER = 60, /**< Clothes dryer */
99 SNDLEVEL_DISHWASHER = 65, /**< Dishwasher/washing machine (1.5 attn) */
100 SNDLEVEL_CAR = 70, /**< Car or vacuum cleaner (1.0 attn) */
101 SNDLEVEL_NORMAL = 75, /**< Normal sound level */
102 SNDLEVEL_TRAFFIC = 75, /**< Busy traffic (0.8 attn) */
103 SNDLEVEL_MINIBIKE = 80, /**< Mini-bike, alarm clock (0.7 attn) */
104 SNDLEVEL_SCREAMING = 90, /**< Screaming child (0.5 attn) */
105 SNDLEVEL_TRAIN = 100, /**< Subway train, pneumatic drill (0.4 attn) */
106 SNDLEVEL_HELICOPTER = 105, /**< Helicopter */
107 SNDLEVEL_SNOWMOBILE = 110, /**< Snow mobile */
108 SNDLEVEL_AIRCRAFT = 120, /**< Auto horn, aircraft */
109 SNDLEVEL_RAIDSIREN = 130, /**< Air raid siren */
110 SNDLEVEL_GUNFIRE = 140, /**< Gunshot, jet engine (0.27 attn) */
111 SNDLEVEL_ROCKET = 180, /**< Rocket launching (0.2 attn) */
114 #define SNDVOL_NORMAL 1.0 /**< Normal volume */
115 #define SNDPITCH_NORMAL 100 /**< Normal pitch */
116 #define SNDPITCH_LOW 95 /**< A low pitch */
117 #define SNDPITCH_HIGH 120 /**< A high pitch */
118 #define SNDATTN_NONE 0.0 /**< No attenuation */
119 #define SNDATTN_NORMAL 0.8 /**< Normal attenuation */
120 #define SNDATTN_STATIC 1.25 /**< Static attenuation? */
121 #define SNDATTN_RICOCHET 1.5 /**< Ricochet effect */
122 #define SNDATTN_IDLE 2.0 /**< Idle attenuation? */
125 * Prefetches a sound.
127 * @param name Sound file name relative to the "sounds" folder.
130 native PrefetchSound(const String:nane[]);
133 * This function is not known to work, and may crash. You should
134 * not use it. It is provided for backwards compatibility only.
136 * @param name Sound file name relative to the "sounds" folder.
137 * @return Duration in seconds.
139 #pragma deprecated Does not work, may crash.
140 native Float:GetSoundDuration(const String:name[]);
143 * Emits an ambient sound.
145 * @param name Sound file name relative to the "sounds" folder.
146 * @param pos Origin of sound.
147 * @param entity Entity index to associate sound with.
148 * @param level Sound level (from 0 to 255).
149 * @param flags Sound flags.
150 * @param vol Volume (from 0.0 to 1.0).
151 * @param pitch Pitch (from 0 to 255).
152 * @param delay Play delay.
155 native EmitAmbientSound(const String:name[],
157 entity = SOUND_FROM_WORLD,
158 level = SNDLEVEL_NORMAL,
160 Float:vol = SNDVOL_NORMAL,
161 pitch = SNDPITCH_NORMAL,
165 * Fades a client's volume level toward silence or a given percentage.
167 * @param client Client index.
168 * @param percent Fade percentage.
169 * @param outtime Fade out time, in seconds.
170 * @param holdtime Hold time, in seconds.
171 * @param intime Fade in time, in seconds.
173 * @error Invalid client index or client not in game.
175 native FadeClientVolume(client, Float:percent, Float:outtime, Float:holdtime, Float:intime);
180 * @param entity Entity index.
181 * @param channel Channel number.
182 * @param name Sound file name relative to the "sounds" folder.
185 native StopSound(entity, channel, const String:name[]);
188 * Emits a sound to a list of clients.
190 * @param clients Array of client indexes.
191 * @param numClients Number of clients in the array.
192 * @param sample Sound file name relative to the "sounds" folder.
193 * @param entity Entity to emit from.
194 * @param channel Channel to emit with.
195 * @param level Sound level.
196 * @param flags Sound flags.
197 * @param volume Sound volume.
198 * @param pitch Sound pitch.
199 * @param speakerentity Unknown.
200 * @param origin Sound origin.
201 * @param dir Sound direction.
202 * @param updatePos Unknown (updates positions?)
203 * @param soundtime Alternate time to play sound for.
204 * @param ... Optional list of Float[3] arrays to specify additional origins.
206 * @error Invalid client index.
208 native EmitSound(const clients[],
210 const String:sample[],
211 entity = SOUND_FROM_PLAYER,
212 channel = SNDCHAN_AUTO,
213 level = SNDLEVEL_NORMAL,
215 Float:volume = SNDVOL_NORMAL,
216 pitch = SNDPITCH_NORMAL,
218 const Float:origin[3] = NULL_VECTOR,
219 const Float:dir[3] = NULL_VECTOR,
220 bool:updatePos = true,
221 Float:soundtime = 0.0,
225 * Emits a sentence to a list of clients.
227 * @param clients Array of client indexes.
228 * @param numClients Number of clients in the array.
229 * @param sentence Sentence index (from PrecacheSenteFile).
230 * @param entity Entity to emit from.
231 * @param channel Channel to emit with.
232 * @param level Sound level.
233 * @param flags Sound flags.
234 * @param volume Sound volume.
235 * @param pitch Sound pitch.
236 * @param speakerentity Unknown.
237 * @param origin Sound origin.
238 * @param dir Sound direction.
239 * @param updatePos Unknown (updates positions?)
240 * @param soundtime Alternate time to play sound for.
241 * @param ... Optional list of Float[3] arrays to specify additional origins.
243 * @error Invalid client index.
245 native EmitSentence(const clients[],
249 channel = SNDCHAN_AUTO,
250 level = SNDLEVEL_NORMAL,
252 Float:volume = SNDVOL_NORMAL,
253 pitch = SNDPITCH_NORMAL,
255 const Float:origin[3] = NULL_VECTOR,
256 const Float:dir[3] = NULL_VECTOR,
257 bool:updatePos = true,
258 Float:soundtime = 0.0,
262 * Called when an ambient sound is about to be emitted to one or more clients.
264 * NOTICE: all parameters can be overwritten to modify the default behavior.
266 * @param sample Sound file name relative to the "sounds" folder.
267 * @param entity Entity index associated to the sound.
268 * @param volume Volume (from 0.0 to 1.0).
269 * @param level Sound level (from 0 to 255).
270 * @param pitch Pitch (from 0 to 255).
271 * @param pos Origin of sound.
272 * @param flags Sound flags.
273 * @param delay Play delay.
274 * @return Plugin_Continue to allow the sound to be played, Plugin_Stop to block it,
275 * Plugin_Changed when any parameter has been modified.
277 functag public Action:AmbientSHook(String:sample[PLATFORM_MAX_PATH], &entity, &Float:volume, &level, &pitch, Float:pos[3], &flags, &Float:delay);
280 * Called when a sound is going to be emitted to one or more clients.
281 * NOTICE: all params can be overwritten to modify the default behaviour.
283 * @param clients Array of client indexes.
284 * @param numClients Number of clients in the array (modify this value if you add/remove elements from the client array).
285 * @param sample Sound file name relative to the "sounds" folder.
286 * @param entity Entity emitting the sound.
287 * @param channel Channel emitting the sound.
288 * @param volume Sound volume.
289 * @param level Sound level.
290 * @param pitch Sound pitch.
291 * @param flags Sound flags.
292 * @return Plugin_Continue to allow the sound to be played, Plugin_Stop to block it,
293 * Plugin_Changed when any parameter has been modified.
295 functag public Action:NormalSHook(clients[64], &numClients, String:sample[PLATFORM_MAX_PATH], &entity, &channel, &Float:volume, &level, &pitch, &flags);
298 * Hooks all played ambient sounds.
300 * @param hook Function to use as a hook.
302 * @error Invalid function hook.
304 native AddAmbientSoundHook(AmbientSHook:hook);
307 * Hooks all played normal sounds.
309 * @param hook Function to use as a hook.
311 * @error Invalid function hook.
313 native AddNormalSoundHook(NormalSHook:hook);
316 * Unhooks all played ambient sounds.
318 * @param hook Function used for the hook.
320 * @error Invalid function hook.
322 native RemoveAmbientSoundHook(AmbientSHook:hook);
325 * Unhooks all played normal sounds.
327 * @param hook Function used for the hook.
329 * @error Invalid function hook.
331 native RemoveNormalSoundHook(NormalSHook:hook);
334 * Wrapper to emit sound to one client.
336 * @param client Client index.
337 * @param sample Sound file name relative to the "sounds" folder.
338 * @param entity Entity to emit from.
339 * @param channel Channel to emit with.
340 * @param level Sound level.
341 * @param flags Sound flags.
342 * @param volume Sound volume.
343 * @param pitch Sound pitch.
344 * @param speakerentity Unknown.
345 * @param origin Sound origin.
346 * @param dir Sound direction.
347 * @param updatePos Unknown (updates positions?)
348 * @param soundtime Alternate time to play sound for.
350 * @error Invalid client index.
352 stock EmitSoundToClient(client,
353 const String:sample[],
354 entity = SOUND_FROM_PLAYER,
355 channel = SNDCHAN_AUTO,
356 level = SNDLEVEL_NORMAL,
358 Float:volume = SNDVOL_NORMAL,
359 pitch = SNDPITCH_NORMAL,
361 const Float:origin[3] = NULL_VECTOR,
362 const Float:dir[3] = NULL_VECTOR,
363 bool:updatePos = true,
364 Float:soundtime = 0.0)
368 /* Save some work for SDKTools and remove SOUND_FROM_PLAYER references */
369 entity = (entity == SOUND_FROM_PLAYER) ? client : entity;
370 EmitSound(clients, 1, sample, entity, channel,
371 level, flags, volume, pitch, speakerentity,
372 origin, dir, updatePos, soundtime);
376 * Wrapper to emit sound to all clients.
378 * @param sample Sound file name relative to the "sounds" folder.
379 * @param entity Entity to emit from.
380 * @param channel Channel to emit with.
381 * @param level Sound level.
382 * @param flags Sound flags.
383 * @param volume Sound volume.
384 * @param pitch Sound pitch.
385 * @param speakerentity Unknown.
386 * @param origin Sound origin.
387 * @param dir Sound direction.
388 * @param updatePos Unknown (updates positions?)
389 * @param soundtime Alternate time to play sound for.
391 * @error Invalid client index.
393 stock EmitSoundToAll(const String:sample[],
394 entity = SOUND_FROM_PLAYER,
395 channel = SNDCHAN_AUTO,
396 level = SNDLEVEL_NORMAL,
398 Float:volume = SNDVOL_NORMAL,
399 pitch = SNDPITCH_NORMAL,
401 const Float:origin[3] = NULL_VECTOR,
402 const Float:dir[3] = NULL_VECTOR,
403 bool:updatePos = true,
404 Float:soundtime = 0.0)
406 new maxClients = GetMaxClients();
407 new clients[maxClients];
410 for (new i=1; i<=maxClients; i++)
412 if (IsClientInGame(i))
414 clients[total++] = i;
423 EmitSound(clients, total, sample, entity, channel,
424 level, flags, volume, pitch, speakerentity,
425 origin, dir, updatePos, soundtime);
429 * Converts an attenuation value to a sound level.
430 * This function is from the HL2SDK.
432 * @param attn Attenuation value.
433 * @return Integer sound level.
435 stock ATTN_TO_SNDLEVEL(Float:attn)
439 return RoundFloat(50.0 + (20.0 / attn));
