plugin_pager (v6.11)

/*****************************************\
* Bill Bateman aka "HunteR"               *
* http://thepit.shacknet.nu/cs            *
* http://thepit.shacknet.nu/bill/plugins/ *
* huntercc@hotmail.com                    *
\*****************************************/

////////////////////////////////////////////////////////////////////////////

This plugin will read from a text file Player/Message combinations and
  when someone with a matching Name, IP Address, or AuthID connects to the
  server, the specified message will be sent to only that person.  This
  allows admins to leave a custom message to be sent to other admins/players
  after they connect so they don't have to wait for the target player to
  join the game.  Full names or partial names (such as clan tags) can be
  used; this allows for Clan-only messages.

Much of the code for the file parsing and the playsoundall function was
  borrowed from plugin_sank_sounds, by Luke Sankey <sank@spu.edu>

Functions included in this plugin:
  admin_pager_add "<search_type>;<target>;<message>"
  admin_pager_delete [index]
  admin_pager_list
  admin_pager_mode
  admin_pager_msg
  admin_pager_off
  admin_pager_on
  admin_pager_reload
  admin_pager_resend [target]
  admin_pager_sound


Be sure to read the important notes and the sample config at the
bottom of this file!!


//////////////////////////
Installation instructions:
//////////////////////////

1) Compile the plugin_pager.sma file

2) Put the resulting plugin_pager.amx file in your scripts folder,
   for example:  <MOD>\addons\adminmod\scripts\plugin_pager.amx
   where <MOD> is the name of your mod; "cstrike" for Counter-Strike,
   "tfc" for Team Fortress Classic, etc

3) Put any custom sound files in your <MOD>\sound\misc folder
      *** If you do not wish to use a custom sound with the messages, you
      *** may skip this step!

4) Create a .res file for each map in your mapcycle, for example de_dust.res
   and open it in a simple text editor such as Notepad.  Now add a line for
   each of your custom sounds, like this:  sound/misc/run.wav
   Each sound file should be on its own line.  Then make a copy of this res
   file for each map in your cycle.
      *** If you do not wish to use a custom sound with the messages, you
      *** may skip this step!
   
5) Next, open your plugin.ini file and at the bottom add the following line:
   addons/adminmod/scripts/plugin_pager.amx

6) Place the PAGER.cfg file in your <MOD>\addons\adminmod\config folder

7) Next time the map changes the plugin will load and send messages to anyone
   in the config file that connects.

///////////////////////////////
"PAGER.CFG" Config File Format:
///////////////////////////////

 PAGER_MODE;<1 or 2>
 PAGER_MESSAGE;<text>
 PAGER_SOUND;<sound_file>
 <search_type>;<user>;<message>

 PAGER_MODE :  [default: 1]
     Specifies whether to display the PAGER_MESSAGE or not when sending
     a message to a player.  By default this is set to 1:
	     MODE 1 => Display PAGER_MESSAGE
	     MODE 2 => Don't

 PAGER_MESSAGE :  [default: "You have a message!!"]
     This is the test message sent to a player just before he/she receives
     any messages they have waiting.  By setting this to "default" (without
     the quotation marks), this becomes "You have a message!!".

 PAGER_SOUND :  [default: one of 6 random sounds]
     This can be either an external wav file, such as the pg_*.wav files
     included with this plugin, or a built-in wav file such as those
     used by the speak command or the speech plugin.

     If you want to specify a sound file, type in the location of the
     file starting from the sound directory - but always use a forward
     slash, "/", instead of a backslash, for both internal and external
     sound files (new in v6.02).

     For an internal sound file, do NOT include the .wav at the end.
     You must also NOT include the command "speak" -- this plugin does
     that automatically.  See the examples below.

     For a list of available internal sounds, you will need to get
     a pak-file extractor such as PakExplorer, which can be found at
     http://quakestuff.telefragged.com

     The most commonly used internal sounds are in the half-life\valve
     directory in the file pak0.pak
     
     (See the note below the sample config files for more details)

 <search_type> :
     1=Exact Name
     2=Partial Name
     3=IP Address
     4=AuthID

 <user> :
     Exact Name, Partial Name, IP Address, or AuthID
     (see description of <search_type> for more info).
     Names are not case sensitive.

 <message> :
     Type in a message to be sent to a connecting player.


#######################################
# Any line starting with # is a comment
# and is ignored by the plugin.
#
# Sample Config File #1
#
# Mode 1 = display PAGER_MESSAGE
PAGER_MODE;1
#
# All players with messages waiting for them will see
# "You have a message!!" before they are delivered
PAGER_MESSAGE;You have a message!!
#
# This plays the wav file located in your mod's sound\misc folder
# by the name of "pg_subspsig.wav"
PAGER_SOUND;misc/pg_subspsig.wav
#
# 1=Exact Name, 2=Partial Name, 3=IP Address, 4=AuthID
1;HunteR;This message will be sent only to people whose name is exactly HunteR, Hunter, etc
2;Hunt;This message will be sent to anyone with "Hunt" in their name
3;192.168.1.1;This message will go to anyone with an IP address of 192.168.1.1
4;12345;This message will go to anyone with a AuthID of 12345
1;HunteR;You can also leave multiple messages for each user
#
#######################################
#
# Sample Config File #2
#
# Mode 2 = don't display PAGER_MESSAGE
PAGER_MODE;2
#
# "default" sets PAGER_MESSAGE to "You have a message!!"
PAGER_MESSAGE;default
#
# Players will hear a male voice speak the following:
# "You have a message from The Pit"
# because the (e17) after the word "plant" tells Half-Life
# to only play the first 17% of the "plant" wav file
PAGER_SOUND;you have a message from the plant(e17) it
#
# 1=Exact Name, 2=Partial Name, 3=IP Address, 4=AuthID
1;HunteR;This message will be sent only to people whose name is exactly HunteR, Hunter, etc
2;Hunt;This message will be sent to anyone with "Hunt" in their name
3;192.168.1.1;This message will go to anyone with an IP address of 192.168.1.1
4;12345;This message will go to anyone with a AuthID of 12345
1;HunteR;You can also leave multiple messages for each user


//////////////////////////////////
A note about internal sound files:
//////////////////////////////////

  There are many sound files that are "built-in" to the Half-Life game, and they
  can be accessed by using the "speak" command followed by the location of the sound
  file in the Half-Life\valve\pak0.pak file, relative to the "sound" folder.  For
  example, the sound "safe_day.wav" is located at "sound/fvox/safe_day.wav" and it
  can be used by typing the following into the PAGER_SOUND field: "fvox/safe_day"
  (the quotation marks should be LEFT OUT)

    Note: you do not need to add "speak" to the beginning... as long as the file location
    does NOT end in ".wav", the plugin will automatically attempt to "speak" it.
  
  To view the contents of this file, you need a pak file extractor, such as PakExplorer
  which can be downloaded from http://quakestuff.telefragged.com
  
  There are several parameters that can be added to modify the sound when played, but
  the only one I use is "e".  This is used as follows, but WITHOUT the quotation marks:

    "fvox/safe_day(e25)"

  The above line will play only the first 25% of the wav file.
  
  To learn how to use the other parameters, you'll have to do a search on the internet.


////////////////
Important Notes:
////////////////

Several major changes are noted below, by version:

v6.11 Note:
 Minor tweaks, better compatibility for AdminMod 2.50.58 and later

v6.10 Note:
 Updated for Steam & AdminMod 2.50.58

v6.02 Note:
 ALL sounds are now "spoken", which means all sounds (both internal and external) must be
 defined in the config file with a forward slash "/" instead of a backslash "\"

v6 Note:
 Support for AdminMod v2.50.50 and Steam now added, meaning AuthID replaces WonID.
 Also, the default location of the PAGER.CFG file is now "<MOD>\addons\adminmod\config"

v5 Note:
 "Spoken" sound messages no longer require the additional "speak" command or the quotation
 marks; see the example in Setup or see Sample Config file.

v3 Note:
 This version features some documentation corrections, as well as bug fixes.  The most
 important documentation correction is in regards to the search_type.  The original version
 incorrectly said a search_type of 3 is for WonID and 4 is for IP Address... it should be
 the other way around.  This means some of you may have to make some changes to your config
 files if you have not already done so.

v2 Note:
 Thanks to Surfdevil for posting on the AdminMod forums about a typo of mine!


I hope I haven't left anything out!
