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 ";" Usage: admin_sound_add ";<"speak words">" Usage: admin_sound_add ";" 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 ";[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 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. --------------------- 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 %s Defines the command to run on the server when a person should get punished for playing too many sounds. The %s will be replaced with the name of the person to be punished. ex. SND_PUNISH; admin_slap %s 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 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