README.TXT
plugin_sank_sounds
November 15, 2002
FOr AdminMod version 2.50.50 or newer.
http://www.adminmod.org


Table of Contents:
===============================================================================
1. Files Included
2. Plugin Description
3. Plugin Commands
4. Installation Instructions
5. Advanced Instructions
6. snd-list.cfg Help Guide
7. Troubleshooting
8. Revision History


1. 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.


2. 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.

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 or
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!


3. 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 "<keyword>;<"speak words">"
 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.  Server girl will
 announce "Deactivated".
 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.  Server girl will
 announce "Activated".
 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)


4. 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 addons\adminmod\scripts directory, as described in the
Admin Mod installation guide, and modify your addons\adminmod\config\plugin.ini
file to include the line, "addons\adminmod\scripts\plugin_sank_sounds.amx"
(plugin_sank_sounds_l.amx if you run linux) also as described in the Admin Mod
installation guide.  The antiflood plugin should be the very first entry in the
plugin.ini file for maximum effectiveness.

3.) Put the snd-list.cfg file in your Admin Mod's config directory, for
example, "..\half-life\cstrike\addons\adminmod\config\snd-list.cfg" or
"..\hlserver\%MOD%\addons\adminmod\config\snd-list.cfg"

4.) There are two CVARS that affect this plugin: file_access_read and
file_access_write.  file_access_read is required to be set at 1, and
file_access_write is required to be 1 if you use the SND_PUNISH parameter, or
the admin_sound_write command.

5.) If u don't want to set file_access_write to 1 but you will use SND_PUNISH
command, copy sounds_punish.cfg to addons\adminmod\config

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

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 (5.) 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 Admin Mod website:
http://www.adminmod.org/

To have players automatically download custom sounds:

5.) 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!


5. 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 punished.

The included snd-list.cfg file should be all you need, but if you still have
questions, here is the how-to guide.


6. 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.  Following is a list of each parameter, its type, its default
value, a brief description, and an example of usage.  Also see included
snd-list.cfg file for examples.

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_MAX will disable the warnings.
 ex. SND_WARN; 17

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

SND_JOIN
 Type: filename
 Default: none
 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: none
 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_PUNISH
 Type: command
 Default: admin_kick
 Defines the command to run on the server when a person should get punished for
 playing too many sounds.
 ex. SND_PUNISH; admin_slap

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 will 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: none
 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.
 If there are quotes around the wav files, the words will be interpreted as
 speak commands and not wav files.  A list of valid words can be found in the
 Admin Mod help: http://www.adminmod.org/help/online
 ex. hello;  misc\hello.wav; misc\welcome.wav; misc\hi.wav; misc\shutup.wav
 ex. target; "target destroyed"


7. Troubleshooting:
===============================================================================

If your server is not responding, plug it in and press the power button.

If you log an error message "[plugin_sank_sounds] 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 "[plugin_sank_sounds] 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.

If the plugin just doesn't seem to work at all, it could be one of the
following reasons:
1.) You forgot to add plugin_sank_sounds.amx to your plugin.ini file
2.) You forgot to copy the AMX file to the proper directory on the server

If the plugin seems to work, but you don't hear any sounds, it could be one of
the following reasons:
1.) You forgot to copy the WAV files to the proper directory on the server
2.) You forgot to create the proper RES files so clients can download the WAVs
3.) The WAV does not play becaues it is not in PCM format.  Windows users can
    use Windows' Sound Recorder to both view which format, and convert formats.
4.) The wav file passes all steps 1-3, but still just won't play.  I don't know
    what is wrong.  I've seen two WAV files that fall under this category.


8. Revision History
===============================================================================
 * March 21, 2001 - Original hard-coded version released.
 * July 2, 2001 - Rewrote to be text file configurable
 * November 18, 2001 - Added admin_sound_play command, new variables SND_DELAY,
 *  SND_SPLIT and EXACT_MATCH, as well as the ability to have admin-only
 *  sounds, like the original version had.
 * March 30, 2002 - Fixed zero-length-speech bug.
 * May 30, 2002 - Updated for use with new playerinfo function (beta only)
 * November 12, 2002 - Moved snd-list.cfg file to new location, and made it all
 *  lower-case.  Sorry, linux guys, if it confuses you.  Fixed admin_sound_add
 *  bug when trying to change SND_* parameters. Added some ideas from Bill 
 *  Bateman:
 *  1.) added SND_PUNISH and changed SND_KICK to SND_MAX
 *  2.) ability to either speak or play sounds
 * August 26, 2005 by Sir D.: 
 * - punish command should work now
 * - max keywords set to 200


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