README.TXT
plugin_sank_sounds
July 9, 2001
FOr AdminMod version 2.50e or newer.
http://www.adminmod.org


Files Included:
===============================================================================
README.TXT - This file.
plugin_sank_sounds.sma - Plugin source.
plugin_sank_sounds.amx - Compiled win32 version.
plugin_sank_sounds_l.amx - Complied linux version.
snd-list.txt - sample file.
awwcrap.wav
awwcrap2.wav
awwman.wav
bud.wav
comeagain.wav
cs_siege.res
de_dust2.res
doh.wav
doh2.wav
doh3.wav
doh4.wav
doh5.wav
doh7.wav
dohnuts.wav
dohoo.wav
doomed.wav
er.wav
haha.wav
ow.wav
weis.wav
woohoo.wav
woohoo2.wav
 27 files.


Plugin Description:
===============================================================================

This plugin will read from a text file keyword/wav file combinations and when a
player says one of the keywords, it will trigger HL to play that wav file to
all players.  It allows reloading of the file without restarting the current
level, as well as adding keyword/wav combinations from the console during
gameplay.  If it finds it can't read the file, it will automagically set
file_access_read to 1 and then set it back to 0 when it's done.

My most deepest thanks goes to William Bateman (aka HunteR)
 http://thepit.shacknet.nu
 huntercc@hotmail.com
For he was the one who got me motivated once again to write this plugin since I
don't run a server anymore. And besides that, he helped write parts of it.

If, after reading this file many times over you are still confused as to how
this plugin works or how to set it up properly, then please go to the adminmod
forums at http://www.adminmod.org   If they fail you, email Bill Bateman.  As
a very last final resort, email me: sank@spu.edu

If you see an error message that says to increase MAX_RANDOM or MAX_KEYWORDS
then you'll have to recompile the plugin.  You can increase these at the top
of the file by just changing the default number to a bigger number.  The side
effect is that the amx file quickly gets very large.  If you only use 1 wav
per keyword, then you can keep MAX_RANDOM to 1 or 2.  If you don't have very
many keywords but each one can play one of 10 different sounds, then you'll
want a small MAX_KEYWORDS but a big MAX_RANDOM.  Be careful not to just set
the values to some obscenely huge number, because then the plugin will use too
much memory and could cause the server to become unstable.

Enjoy!


Plugin Commands:
===============================================================================

admin_sound_add
 Adds a Word/Wav combo to the list.  If it is a valid line in the config
 file, then it is a valid parameter here.  The only difference is you can
 only specify one .wav file at a time with this command.
 Usage: admin_sound_add "<keyword>;<dir\wav>"
 Usage: admin_sound_add "<setting>;<value>"
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_help
 Instead of using admin_help, which uses static data, admin_sound_help
 always lists the most up-to-date information because the Word/Wav list can
 change in the middle of gameplay.  admin_sound_help lists all admin_sound
 commands and keywords to the user.
 Usage: admin_sound_help
 Access required: ACCESS_ALL

admin_sound_off
 Turns off the playing of the wav files for this plugin only.
 Usage: admin_sound_off
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_on
 Turns on the playing of the wav files for this plugin only.
 Usage: admin_sound_on
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_play
 Plays any sound to all players
 Usage: admin_sound_play misc\killchicken.wav
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_reload
 Reloads the Word/Wav combos from filename.
 Usage: admin_sound_reload [filename]
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_remove
 Removes a Word/Wav combo from the list. You must specify a keyword, but it
 is not necessary to specify a wav if you want to remove all wavs associated
 with that keyword. Surrounding quotes are required.
 Usage: admin_sound_remove "<keyword>;[wav]"
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)

admin_sound_write
 Saves the current configuration of Word/Wav combos to filename for possible
 reloading at a later time. You cannot overwrite the default file.
 Usage: admin_sound_write <filename>
 Access required: ACCESS_SOUND (both ACCESS_SAY and ACCESS_CONFIG)


Installation Instructions:
===============================================================================

Linux guys be sure to specify the -a flag when unzipping the text files so that
the line ends are converted properly.

1.) Put all of the wav files in your MOD's sound\misc directory, for example,
"..\half-life\cstrike\sounds\misc" or "..\hlserver\%MOD%\sounds\misc"

2.) Put the plugin_sank_sounds.amx (plugin_sank_sounds_l.amx if you run linux)
file in your mod's dlls directory, as described in the AdminMod installation
guide, and modify your plugin.ini file to include the line,
"dlls\plugin_sank_sounds.amx" (plugin_sank_sounds_l.amx if you run linux) also
as described in the AdminMod installation guide.  If you have
plugin_sank_antiflood installed, be sure its entry in the plugin.ini file is on
a line prior to the sounds plugin, or the sounds won't have the flood
protection.  The antiflood plugin actually should be the very first entry in
the plugin.ini file for maximum effectiveness.

3.) Put the snd-list.cfg file in your mod's root directory, for example,
"..\half-life\cstrike\snd-list.cfg" or "..\hlserver\%MOD%\snd-list.cfg"

                        ---------------------

There are two common ways of using custom sounds on your server.  One is to
force everyone to download them when they connect, and the other is to give
them a message when they connect that they need to go download them from your
website.

If you choose to force people to download your custom sounds when they connect,
then read the following installation instruction (4.) otherwise be sure to tell
your players that they need to go download the sound pack.  An easy way to do
this is to use plugin_sank_consgreet.  You can get it at the AdminMod website:
http://www.adminmod.org/ascript/plugin.php

To have players automatically download custom sounds:

4.) The most important thing to know is that just because the sounds are on the
server doesn't mean that the players will hear them.  You have to tell the
clients to download the sounds, which is accomplished with *.res files.  RES
files are simple text files that list which files the client is to download
when the server starts that map.  For maximum effectiveness, each map in your
MOD\maps directory should have a corresponding RES file.  I have included two
examples to help you on your way.  I have approximately half of the wav's in
each RES file, so that the downloading of the sounds does not take forever.
You will want to duplicate these RES files for each map in your mapcycle.

5.) That's It!


Advanced Instructions:
===============================================================================

If you have plugins working already then the addition of this one should be 
fairly simple for you.  Now whenever someone says one of the words in the first
column of your SND-LIST.CFG file, then your server will play one of the sounds
in the second column to all who have the wav downloaded.

The most important part of using this plugin is its spamming and flooding
detection and filtering.  Depending on your config file, there is a maximum
number of sounds a player can use per level. If they say too many sounds, then
they will get kicked.

The included SND-LIST.CFG file should be all you need, but if you still have
questions, here is the how-to guide.


SND-LIST.CFG help guide:
===============================================================================

The script reads in one line at a time. Lines beginning with a '#' or '//' are
ignored. Tokens are always separated by semi-colons (;) and tabs and spaces are
meaningless.

SND_WARN
 Type: integer
 Default: 0
 Defines the number of things a person can say before they are warned.  Setting
 this value to a number bigger than SND_KICK will disable the warnings.
 ex. SND_WARN; 17

SND_KICK
 Type: integer
 Default: 0
 Defines the number of things a person can say before they get kicked.  Setting
 this value to zero will disable the sound quota.
 ex. SND_KICK; 20

SND_JOIN
 Type: filename
 Default: ""
 Defines the path to a wav file, relative to the sound directory, of a sound
 that gets played when a player connects.  Specifying this path to point to a
 file that doesn't exist, or specifying nothing at all will disable the
 playing of a sound when players connect.
 ex. SND_JOIN; "misc\welcome.wav"

SND_EXIT
 Type: filename
 Default: ""
 Defines the path to a wav file, relative to the sound directory, of a sound
 to get played when a player leaves the game.  Specifying this path to point
 to a file that doesn't exist, or specifying nothing at all will disable the
 playing of a sound when players disconnect.
 ex. SND_EXIT; "misc\killChicken.wav"

SND_DELAY
 Type: integer
 Default: 0
 Defines the number of seconds required between sounds being played.
 ex. SND_DELAY; 0

SND_SPLIT
 Type: boolean
 Default: 0
 Defines whether or not alive players will hear sounds from dead players and
 visa-versa. Setting to 1 will split sounds, setting to 0 to play sounds to
 everybody.
 ex. SND_SPLIT; 1

EXACT_MATCH
 Type: boolean
 Default: 1
 Setting this to 1 will make the plugin only trigger on exact matches when
 looking for keywords in chat messages.  Setting this to 0 will look for a
 keyword anywhere within a chat message
 ex. EXACT_MATCH; 1

Keyword; Wav1;Wav2;Wav3...
 Type: Word/Wav combo
 Default: ""
 Keyword defines the keyword for the plugin to pick up on.
 Wav1, Wav2, Wav3... defines the wav files for the plugin to choose
 from. It will randomly pick one from the list when someone says the keyword.
 ex. hello;  misc\hello.wav; misc\welcome.wav; misc\hi.wav; misc\shutup.wav


Troubleshooting:
===============================================================================

If you log an error message "Sound Plugin >> Increase MAX_RANDOM" then you
have specified too many choices for a single keyword.  To fix this, either
remove some of the wav files for that keyword or recompile the script after
increasing the MAX_RANDOM definition at the top.

In a similar manner, if you log an error message "Sound Plugin >> Increase
MAX_KEYWORDS" then you have specified too many keywords for the plugin to
pick up on.  To fix this, either shorten the number of keywords specified in
the SND-LIST.CFG file, or recompile the script after increasing the
MAX_KEYWORDS definition at the top.


That should give you the details to be an expert, if you have any questions or
bug reports, contact info is in the Plugin Description section.

Luke Sankey
sank@spu.edu

Installationanleitung:
----------------------
Eigentlich muss die Zip-Datei einfach nur in den cstrike-ordner ("Pfadangaben verwenden")
entpackt werden (ohne die Ordner Doc und Source) und dann noch Folgendes in der
plugin.ini im cstrike-ordner eingetragen werden: plugins/plugin_sank_sounds.amx !

! Achtung ! : Bei Linux Servern muss die Datei plugin_sank_sounds.amx im Dlls-Ordner
durch die aus dem Unterordner "Linux" ersetzt werden!

Damit steht dann eine etwas erweiterte Standardauswahl von Sounds sofort parat.
Diese können aber durchaus noch erweitert werden: sound.wav ins Verzeichnis 
cstrike\sound\misc und dann in der SND-LIST.CFG im cstrike-dir eintragen.