1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/sdktools_sound.inc Sun Jul 06 04:49:55 2008 +0000
1.3 @@ -0,0 +1,442 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 + * =============================================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK.
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify it under
1.13 + * the terms of the GNU General Public License, version 3.0, as published by the
1.14 + * Free Software Foundation.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 + * details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License along with
1.22 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 + *
1.24 + * As a special exception, AlliedModders LLC gives you permission to link the
1.25 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 + * by the Valve Corporation. You must obey the GNU General Public License in
1.28 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 + * this exception to all derivative works. AlliedModders LLC defines further
1.30 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 + * or <http://www.sourcemod.net/license.php>.
1.32 + *
1.33 + * Version: $Id$
1.34 + */
1.35 +
1.36 +#if defined _sdktools_sound_included
1.37 + #endinput
1.38 +#endif
1.39 +#define _sdktools_sound_included
1.40 +
1.41 +/**
1.42 + * Sound should be from the target client.
1.43 + */
1.44 +#define SOUND_FROM_PLAYER -2
1.45 +
1.46 +/**
1.47 + * Sound should be from the listen server player.
1.48 + */
1.49 +#define SOUND_FROM_LOCAL_PLAYER -1
1.50 +
1.51 +/**
1.52 + * Sound is from the world.
1.53 + */
1.54 +#define SOUND_FROM_WORLD 0
1.55 +
1.56 +/**
1.57 + * Sound channels.
1.58 + */
1.59 +enum
1.60 +{
1.61 + SNDCHAN_REPLACE = -1, /**< Unknown */
1.62 + SNDCHAN_AUTO = 0, /**< Auto */
1.63 + SNDCHAN_WEAPON = 1, /**< Weapons */
1.64 + SNDCHAN_VOICE = 2, /**< Voices */
1.65 + SNDCHAN_ITEM = 3, /**< Items */
1.66 + SNDCHAN_BODY = 4, /**< Player? */
1.67 + SNDCHAN_STREAM = 5, /**< "Stream channel from the static or dynamic area" */
1.68 + SNDCHAN_STATIC = 6, /**< "Stream channel from the static area" */
1.69 + SNDCHAN_VOICE_BASE = 7, /**< "Channel for network voice data" */
1.70 + SNDCHAN_USER_BASE = 135 /**< Anything >= this is allocated to game code */
1.71 +};
1.72 +
1.73 +/**
1.74 + * Sound flags for the sound emitter system.
1.75 + */
1.76 +enum
1.77 +{
1.78 + SND_NOFLAGS= 0, /**< Nothing */
1.79 + SND_CHANGEVOL = 1, /**< Change sound volume */
1.80 + SND_CHANGEPITCH = 2, /**< Change sound pitch */
1.81 + SND_STOP = 3, /**< Stop the sound */
1.82 + SND_SPAWNING = 4, /**< Used in some cases for ambients */
1.83 + SND_DELAY = 5, /**< Sound has an initial delay */
1.84 + SND_STOPLOOPING = 6, /**< Stop looping all sounds on the entity */
1.85 + SND_SPEAKER = 7, /**< Being played by a mic through a speaker */
1.86 + SND_SHOULDPAUSE = 8, /**< Pause if game is paused */
1.87 +};
1.88 +
1.89 +/**
1.90 + * Various predefined sound levels in dB.
1.91 + */
1.92 +enum
1.93 +{
1.94 + SNDLEVEL_NONE = 0, /**< None */
1.95 + SNDLEVEL_RUSTLE = 20, /**< Rustling leaves */
1.96 + SNDLEVEL_WHISPER = 25, /**< Whispering */
1.97 + SNDLEVEL_LIBRARY = 30, /**< In a library */
1.98 + SNDLEVEL_FRIDGE = 45, /**< Refridgerator */
1.99 + SNDLEVEL_HOME = 50, /**< Average home (3.9 attn) */
1.100 + SNDLEVEL_CONVO = 60, /**< Normal conversation (2.0 attn) */
1.101 + SNDLEVEL_DRYER = 60, /**< Clothes dryer */
1.102 + SNDLEVEL_DISHWASHER = 65, /**< Dishwasher/washing machine (1.5 attn) */
1.103 + SNDLEVEL_CAR = 70, /**< Car or vacuum cleaner (1.0 attn) */
1.104 + SNDLEVEL_NORMAL = 75, /**< Normal sound level */
1.105 + SNDLEVEL_TRAFFIC = 75, /**< Busy traffic (0.8 attn) */
1.106 + SNDLEVEL_MINIBIKE = 80, /**< Mini-bike, alarm clock (0.7 attn) */
1.107 + SNDLEVEL_SCREAMING = 90, /**< Screaming child (0.5 attn) */
1.108 + SNDLEVEL_TRAIN = 100, /**< Subway train, pneumatic drill (0.4 attn) */
1.109 + SNDLEVEL_HELICOPTER = 105, /**< Helicopter */
1.110 + SNDLEVEL_SNOWMOBILE = 110, /**< Snow mobile */
1.111 + SNDLEVEL_AIRCRAFT = 120, /**< Auto horn, aircraft */
1.112 + SNDLEVEL_RAIDSIREN = 130, /**< Air raid siren */
1.113 + SNDLEVEL_GUNFIRE = 140, /**< Gunshot, jet engine (0.27 attn) */
1.114 + SNDLEVEL_ROCKET = 180, /**< Rocket launching (0.2 attn) */
1.115 +};
1.116 +
1.117 +#define SNDVOL_NORMAL 1.0 /**< Normal volume */
1.118 +#define SNDPITCH_NORMAL 100 /**< Normal pitch */
1.119 +#define SNDPITCH_LOW 95 /**< A low pitch */
1.120 +#define SNDPITCH_HIGH 120 /**< A high pitch */
1.121 +#define SNDATTN_NONE 0.0 /**< No attenuation */
1.122 +#define SNDATTN_NORMAL 0.8 /**< Normal attenuation */
1.123 +#define SNDATTN_STATIC 1.25 /**< Static attenuation? */
1.124 +#define SNDATTN_RICOCHET 1.5 /**< Ricochet effect */
1.125 +#define SNDATTN_IDLE 2.0 /**< Idle attenuation? */
1.126 +
1.127 +/**
1.128 + * Prefetches a sound.
1.129 + *
1.130 + * @param name Sound file name relative to the "sounds" folder.
1.131 + * @noreturn
1.132 + */
1.133 +native PrefetchSound(const String:nane[]);
1.134 +
1.135 +/**
1.136 + * This function is not known to work, and may crash. You should
1.137 + * not use it. It is provided for backwards compatibility only.
1.138 + *
1.139 + * @param name Sound file name relative to the "sounds" folder.
1.140 + * @return Duration in seconds.
1.141 + */
1.142 +#pragma deprecated Does not work, may crash.
1.143 +native Float:GetSoundDuration(const String:name[]);
1.144 +
1.145 +/**
1.146 + * Emits an ambient sound.
1.147 + *
1.148 + * @param name Sound file name relative to the "sounds" folder.
1.149 + * @param pos Origin of sound.
1.150 + * @param entity Entity index to associate sound with.
1.151 + * @param level Sound level (from 0 to 255).
1.152 + * @param flags Sound flags.
1.153 + * @param vol Volume (from 0.0 to 1.0).
1.154 + * @param pitch Pitch (from 0 to 255).
1.155 + * @param delay Play delay.
1.156 + * @noreturn
1.157 + */
1.158 +native EmitAmbientSound(const String:name[],
1.159 + const Float:pos[3],
1.160 + entity = SOUND_FROM_WORLD,
1.161 + level = SNDLEVEL_NORMAL,
1.162 + flags = SND_NOFLAGS,
1.163 + Float:vol = SNDVOL_NORMAL,
1.164 + pitch = SNDPITCH_NORMAL,
1.165 + Float:delay = 0.0);
1.166 +
1.167 +/**
1.168 + * Fades a client's volume level toward silence or a given percentage.
1.169 + *
1.170 + * @param client Client index.
1.171 + * @param percent Fade percentage.
1.172 + * @param outtime Fade out time, in seconds.
1.173 + * @param holdtime Hold time, in seconds.
1.174 + * @param intime Fade in time, in seconds.
1.175 + * @noreturn
1.176 + * @error Invalid client index or client not in game.
1.177 + */
1.178 +native FadeClientVolume(client, Float:percent, Float:outtime, Float:holdtime, Float:intime);
1.179 +
1.180 +/**
1.181 + * Stops a sound.
1.182 + *
1.183 + * @param entity Entity index.
1.184 + * @param channel Channel number.
1.185 + * @param name Sound file name relative to the "sounds" folder.
1.186 + * @noreturn
1.187 + */
1.188 +native StopSound(entity, channel, const String:name[]);
1.189 +
1.190 +/**
1.191 + * Emits a sound to a list of clients.
1.192 + *
1.193 + * @param clients Array of client indexes.
1.194 + * @param numClients Number of clients in the array.
1.195 + * @param sample Sound file name relative to the "sounds" folder.
1.196 + * @param entity Entity to emit from.
1.197 + * @param channel Channel to emit with.
1.198 + * @param level Sound level.
1.199 + * @param flags Sound flags.
1.200 + * @param volume Sound volume.
1.201 + * @param pitch Sound pitch.
1.202 + * @param speakerentity Unknown.
1.203 + * @param origin Sound origin.
1.204 + * @param dir Sound direction.
1.205 + * @param updatePos Unknown (updates positions?)
1.206 + * @param soundtime Alternate time to play sound for.
1.207 + * @param ... Optional list of Float[3] arrays to specify additional origins.
1.208 + * @noreturn
1.209 + * @error Invalid client index.
1.210 + */
1.211 +native EmitSound(const clients[],
1.212 + numClients,
1.213 + const String:sample[],
1.214 + entity = SOUND_FROM_PLAYER,
1.215 + channel = SNDCHAN_AUTO,
1.216 + level = SNDLEVEL_NORMAL,
1.217 + flags = SND_NOFLAGS,
1.218 + Float:volume = SNDVOL_NORMAL,
1.219 + pitch = SNDPITCH_NORMAL,
1.220 + speakerentity = -1,
1.221 + const Float:origin[3] = NULL_VECTOR,
1.222 + const Float:dir[3] = NULL_VECTOR,
1.223 + bool:updatePos = true,
1.224 + Float:soundtime = 0.0,
1.225 + any:...);
1.226 +
1.227 +/**
1.228 + * Emits a sentence to a list of clients.
1.229 + *
1.230 + * @param clients Array of client indexes.
1.231 + * @param numClients Number of clients in the array.
1.232 + * @param sentence Sentence index (from PrecacheSenteFile).
1.233 + * @param entity Entity to emit from.
1.234 + * @param channel Channel to emit with.
1.235 + * @param level Sound level.
1.236 + * @param flags Sound flags.
1.237 + * @param volume Sound volume.
1.238 + * @param pitch Sound pitch.
1.239 + * @param speakerentity Unknown.
1.240 + * @param origin Sound origin.
1.241 + * @param dir Sound direction.
1.242 + * @param updatePos Unknown (updates positions?)
1.243 + * @param soundtime Alternate time to play sound for.
1.244 + * @param ... Optional list of Float[3] arrays to specify additional origins.
1.245 + * @noreturn
1.246 + * @error Invalid client index.
1.247 + */
1.248 +native EmitSentence(const clients[],
1.249 + numClients,
1.250 + sentence,
1.251 + entity,
1.252 + channel = SNDCHAN_AUTO,
1.253 + level = SNDLEVEL_NORMAL,
1.254 + flags = SND_NOFLAGS,
1.255 + Float:volume = SNDVOL_NORMAL,
1.256 + pitch = SNDPITCH_NORMAL,
1.257 + speakerentity = -1,
1.258 + const Float:origin[3] = NULL_VECTOR,
1.259 + const Float:dir[3] = NULL_VECTOR,
1.260 + bool:updatePos = true,
1.261 + Float:soundtime = 0.0,
1.262 + any:...);
1.263 +
1.264 +/**
1.265 + * Called when an ambient sound is about to be emitted to one or more clients.
1.266 + *
1.267 + * NOTICE: all parameters can be overwritten to modify the default behavior.
1.268 + *
1.269 + * @param sample Sound file name relative to the "sounds" folder.
1.270 + * @param entity Entity index associated to the sound.
1.271 + * @param volume Volume (from 0.0 to 1.0).
1.272 + * @param level Sound level (from 0 to 255).
1.273 + * @param pitch Pitch (from 0 to 255).
1.274 + * @param pos Origin of sound.
1.275 + * @param flags Sound flags.
1.276 + * @param delay Play delay.
1.277 + * @return Plugin_Continue to allow the sound to be played, Plugin_Stop to block it,
1.278 + * Plugin_Changed when any parameter has been modified.
1.279 + */
1.280 +functag AmbientSHook Action:public(String:sample[PLATFORM_MAX_PATH], &entity, &Float:volume, &level, &pitch, Float:pos[3], &flags, &Float:delay);
1.281 +
1.282 +/**
1.283 + * Called when a sound is going to be emitted to one or more clients.
1.284 + * NOTICE: all params can be overwritten to modify the default behaviour.
1.285 + *
1.286 + * @param clients Array of client indexes.
1.287 + * @param numClients Number of clients in the array (modify this value if you add/remove elements from the client array).
1.288 + * @param sample Sound file name relative to the "sounds" folder.
1.289 + * @param entity Entity emitting the sound.
1.290 + * @param channel Channel emitting the sound.
1.291 + * @param volume Sound volume.
1.292 + * @param level Sound level.
1.293 + * @param pitch Sound pitch.
1.294 + * @param flags Sound flags.
1.295 + * @return Plugin_Continue to allow the sound to be played, Plugin_Stop to block it,
1.296 + * Plugin_Changed when any parameter has been modified.
1.297 + */
1.298 +functag NormalSHook Action:public(clients[64], &numClients, String:sample[PLATFORM_MAX_PATH], &entity, &channel, &Float:volume, &level, &pitch, &flags);
1.299 +
1.300 +/**
1.301 + * Hooks all played ambient sounds.
1.302 + *
1.303 + * @param hook Function to use as a hook.
1.304 + * @noreturn
1.305 + * @error Invalid function hook.
1.306 + */
1.307 +native AddAmbientSoundHook(AmbientSHook:hook);
1.308 +
1.309 +/**
1.310 + * Hooks all played normal sounds.
1.311 + *
1.312 + * @param hook Function to use as a hook.
1.313 + * @noreturn
1.314 + * @error Invalid function hook.
1.315 + */
1.316 +native AddNormalSoundHook(NormalSHook:hook);
1.317 +
1.318 +/**
1.319 + * Unhooks all played ambient sounds.
1.320 + *
1.321 + * @param hook Function used for the hook.
1.322 + * @noreturn
1.323 + * @error Invalid function hook.
1.324 + */
1.325 +native RemoveAmbientSoundHook(AmbientSHook:hook);
1.326 +
1.327 +/**
1.328 + * Unhooks all played normal sounds.
1.329 + *
1.330 + * @param hook Function used for the hook.
1.331 + * @noreturn
1.332 + * @error Invalid function hook.
1.333 + */
1.334 +native RemoveNormalSoundHook(NormalSHook:hook);
1.335 +
1.336 +/**
1.337 + * Wrapper to emit sound to one client.
1.338 + *
1.339 + * @param client Client index.
1.340 + * @param sample Sound file name relative to the "sounds" folder.
1.341 + * @param entity Entity to emit from.
1.342 + * @param channel Channel to emit with.
1.343 + * @param level Sound level.
1.344 + * @param flags Sound flags.
1.345 + * @param volume Sound volume.
1.346 + * @param pitch Sound pitch.
1.347 + * @param speakerentity Unknown.
1.348 + * @param origin Sound origin.
1.349 + * @param dir Sound direction.
1.350 + * @param updatePos Unknown (updates positions?)
1.351 + * @param soundtime Alternate time to play sound for.
1.352 + * @noreturn
1.353 + * @error Invalid client index.
1.354 + */
1.355 +stock EmitSoundToClient(client,
1.356 + const String:sample[],
1.357 + entity = SOUND_FROM_PLAYER,
1.358 + channel = SNDCHAN_AUTO,
1.359 + level = SNDLEVEL_NORMAL,
1.360 + flags = SND_NOFLAGS,
1.361 + Float:volume = SNDVOL_NORMAL,
1.362 + pitch = SNDPITCH_NORMAL,
1.363 + speakerentity = -1,
1.364 + const Float:origin[3] = NULL_VECTOR,
1.365 + const Float:dir[3] = NULL_VECTOR,
1.366 + bool:updatePos = true,
1.367 + Float:soundtime = 0.0)
1.368 +{
1.369 + new clients[1];
1.370 + clients[0] = client;
1.371 + /* Save some work for SDKTools and remove SOUND_FROM_PLAYER references */
1.372 + entity = (entity == SOUND_FROM_PLAYER) ? client : entity;
1.373 + EmitSound(clients, 1, sample, entity, channel,
1.374 + level, flags, volume, pitch, speakerentity,
1.375 + origin, dir, updatePos, soundtime);
1.376 +}
1.377 +
1.378 +/**
1.379 + * Wrapper to emit sound to all clients.
1.380 + *
1.381 + * @param sample Sound file name relative to the "sounds" folder.
1.382 + * @param entity Entity to emit from.
1.383 + * @param channel Channel to emit with.
1.384 + * @param level Sound level.
1.385 + * @param flags Sound flags.
1.386 + * @param volume Sound volume.
1.387 + * @param pitch Sound pitch.
1.388 + * @param speakerentity Unknown.
1.389 + * @param origin Sound origin.
1.390 + * @param dir Sound direction.
1.391 + * @param updatePos Unknown (updates positions?)
1.392 + * @param soundtime Alternate time to play sound for.
1.393 + * @noreturn
1.394 + * @error Invalid client index.
1.395 + */
1.396 +stock EmitSoundToAll(const String:sample[],
1.397 + entity = SOUND_FROM_PLAYER,
1.398 + channel = SNDCHAN_AUTO,
1.399 + level = SNDLEVEL_NORMAL,
1.400 + flags = SND_NOFLAGS,
1.401 + Float:volume = SNDVOL_NORMAL,
1.402 + pitch = SNDPITCH_NORMAL,
1.403 + speakerentity = -1,
1.404 + const Float:origin[3] = NULL_VECTOR,
1.405 + const Float:dir[3] = NULL_VECTOR,
1.406 + bool:updatePos = true,
1.407 + Float:soundtime = 0.0)
1.408 +{
1.409 + new maxClients = GetMaxClients();
1.410 + new clients[maxClients];
1.411 + new total = 0;
1.412 +
1.413 + for (new i=1; i<=maxClients; i++)
1.414 + {
1.415 + if (IsClientInGame(i))
1.416 + {
1.417 + clients[total++] = i;
1.418 + }
1.419 + }
1.420 +
1.421 + if (!total)
1.422 + {
1.423 + return;
1.424 + }
1.425 +
1.426 + EmitSound(clients, total, sample, entity, channel,
1.427 + level, flags, volume, pitch, speakerentity,
1.428 + origin, dir, updatePos, soundtime);
1.429 +}
1.430 +
1.431 +/**
1.432 + * Converts an attenuation value to a sound level.
1.433 + * This function is from the HL2SDK.
1.434 + *
1.435 + * @param attn Attenuation value.
1.436 + * @return Integer sound level.
1.437 + */
1.438 +stock ATTN_TO_SNDLEVEL(Float:attn)
1.439 +{
1.440 + if (attn > 0.0)
1.441 + {
1.442 + return RoundFloat(50.0 + (20.0 / attn));
1.443 + }
1.444 + return 0;
1.445 +}
