
               -----------------------------------------------------
                 -------------------------------------------------  
                    Instructions for plugin_cavey_menu.sma 1.3    
                 -------------------------------------------------  
               -----------------------------------------------------
                          Last revised 14:23 17/11/2002

	1) How do I install this?
	2) What extra functions does this add to my server?
	3) How do I use the new functions?
	4) A) How can I configure this plugin then??
	   B) What is that "menu.ini" file?
	   C) Got any sample "menu.ini" files?
	   D) Is there a nice GUI driven program to help me create "menu.ini" files?
	5) It isn't working, what is wrong with it?
	6) Any questions??

--------------------------------------------------------------------------------
///////   1) How do I install this?  ///////////////////////////////////////////
--------------------------------------------------------------------------------

-----Win32------

1) Place the uncompiled .sma in ../halflife/admin/scripting/myscripts.
   Place cavey.inc in ../halflife/admin/scripting/include directory.

2) For those with BIG menu.ini files (and I mean BIG), find the lines
   #define MAX_TOP_LAYER_MENUS 14

   #define MAX_LAYER2_MENUS 40	

   #define MAX_LAYER3_MENUS 80	
   #define MAX_LAYER4_MENUS 120	

   #define MAX_LAYER5_MENUS 90	

   Changing these values increases the total number of menus you can have
   per layer. The bigger you make them, the bigger the amx becomes and the 
   more memory it can munch.  I dont recommend adjusting any of these settings
   unless you have a VERY big menu.ini which fails to load.

3) Doubleclick the compile_all.bat 

4) Find the ../halflife/admin/scripting/mybinaries directory and copy the 
   .amx files. 

5) Paste the .amx files into the ../halflife/{moddir}/addons/adminmod/scripts
   directory. 

6) Add the names of the plugins to the plguin.ini in the {moddir}, ie for 
   plugin_cavey_menu.amx add "dlls/plugin_cavey_menu.amx" to the BOTTOM of
   the file. 

7) Set file_access_read 1 and amv_enable_beta "menu1" in your server.cfg
   If you dont, this will NOT work!!!!  If you want to use the debug function, 
   you need "file_access_write" set to 1 aswell.
   (NB For some of the beta dlls I had to use amv_enable_beta "menu 1" to enable 
    the menus.  If one does not work, try the other)

8) The plugin comes complete with a "menu" directory (you need to unzip it with
   directories being include, known as "Use Folder Names" in winzip).  This should 
   be dropped into the "cavey" directory.  Once this is done, put your menu.ini
   file itno the directory.  Some sample menu files are included for you to use
   or modify.

   NOTE - The cavey directory is defined in the vault.ini by the CAVEY_PATH 
   variable.  If you decide to move the directory to other areas you need to modify
   this variable.

9) Further customisations are discussed below.

-----Linux------

As Win32, but use compile_all.sh instead of compile_all.bat

OR

Use the Win32 to Linux converter from www.adminmod.org/index.php?go=downloads

-----------------------------------------------------------------------------------
///////   2) What extra functions does this add to my server?  ////////////////////
-----------------------------------------------------------------------------------

The extra functionalities it has are as follows.

 * This is a server side menu system for HalfLife.  It shows to the user in
   the same style as the radio menu and has multiple levels and each level can
   have multiple pages.

 * It is totally customisable via a text file, so NO SOURCE EDITING REQUIRED!!!

 * There is a CLIENT SIDE setinfo line which you can set to change the way the
   menus work.  If you use 

	setinfo "am_menugoback" "1"

   the menus dont quit when you press 0, they go back up a layer.  Also, when you 
   select an action the menus stay put to allow you to quickly select a new action.
   
-----------------------------------------------------------------------------------
///////   3) How do I use the new functions?  /////////////////////////////////////
-----------------------------------------------------------------------------------

The plugin itself is designed to be install and forget. Once installed it will 
set itself up using the standard settings (see section 4) that I defined while  
I was writing it.  These settings are designed to leave the plugin running with 
the maximum security, usability and stability.  It is recommended that you add a
line to your config.cfg of

bind "m" "admin_menu"

-----------------------------------------------------------------------------------
///////   4) A) How can I configure this plugin then??  ///////////////////////////
-----------------------------------------------------------------------------------

In your vault file you should find that you have the variables listed of

		CAVEY_MENU_DEBUG
		MENU_ACCESS_TOGGLE
		MENU_ACCESS_EXECUTE
		MENU_ACCESS_MENU
		MENU_ACCESS_CONTROL
		MENU_HIDE_OPTIONS
		MENU_DEFAULT_TEXT

But what does each of these define and how can I edit them?

		CAVEY_MENU_DEBUG
This defines whether DEBUG mode is enabled.  Debug mode will enable the command 
"admin_cavey_debug" which will dump the memory to a file.  When asking for help I 
will ask for a debug.log of the plugin which this value creates when set to 2. Please
see section 5 about "Getting more help".
  Level 0 (Default) should be used for general use.
  Level 1 enables the "admin_cavey_debug" command and will return actions through 
    messageex.  This is useful for debugging menu.ini files and can be left enabled
    if you really want to.
  Level 2 enables logging to file "debug.log".  This logs every action the plugin
    receives and dumps its memory to the file on a map change. This is meant only
    for generating a debug.log.
  Level 3 enables some serious returning of actions.  This is more for my benefit
    but if you want to see how the plugin works you can enable it for a short period.
Note that each subsequent level includes the additions of the level before.
  

		MENU_ACCESS_TOGGLE
This defines who can use the togglable CVARs.  Default is ACCESS_KICK (128) and this 
means that anyone with this access will be able to toggle the cvars you set in the 
menu.ini.  The setting can be altered to anything you like via the vault or to
safe settings via the "admin_menu_admin" command.

		MENU_ACCESS_EXECUTE
This defines you can use the menu parts which exec something in the console.  As this
could result in it running commands akin to rcon, the default access level is 
ACCESS_RCON (65536) though you can change it to any value you like in the vault or via
"admin_menu_admin"

		MENU_ACCESS_MENU
This defines you can use the "admin_menu" command itself.  Default is ACCESS_ALL (0)
though you can change it to any value you like in the vault or via "admin_menu_admin"
to make it only available to registered users, admins or whoever.

		MENU_ACCESS_CONTROL
This defines you can use the "admin_menu_admin parts" command.  As this allows you to
reconfigure the entire plugin it is set to ACCESS_RCON by default and you CAN NOT change
it via the "admin_menu_admin" command for security reasons.

		MENU_HIDE_OPTIONS
Since "Series 1.2" the plugin has "hidden" commands you do not have access to. If
you use CS it greys them out as with the text-based buy menus (no other mod supports
coloured menus in case you were wondering).  For other mods, this function takes effect
such that if this is set to 1 (default) it will hide the command.  This can look odd
(with empty lines) so you can set it to 0 and it will replace the text with whatever
MENU_DEFAULT_TEXT is.

		MENU_DEFAULT_TEXT
In non-cs mods or if CS is not recognised, the value of this will appear whenever
a player does not have access to a menu entry.  If MENU_HIDE_OPTIONS is 1,
this setting has no relevance.  

There is also a system that provides the menus in a text file format.  This is the 
"menu.ini" and it runs as follows.

--------------------------------------------------------------------------------------
///////   4) B) What is that "menu.ini" file?  ///////////////////////////////////////
--------------------------------------------------------------------------------------

  Each line is a new entry. Each entry has two core components which are its type and the 
  level (where it is in the structure). The rest of them change depending on the type.

add_menu - This adds a menu and has the following format.

	add_menu 1 "Description" 

  The layer to which it has been added (here 1) means that the next values should be on 
  layer 2. If they are on layer 3 I dont actually know what would happen, they might just 
  get ignored or it might all go a bit off, I just dont recommend it. If the next item is 
  on layer 1, the sub-menu will be "finished" and the result is that a new menu will be 
  added in the original layer. Subsequent additions to layer 2 would be lost, so you need 
  the "add_menu" to go down to a new layer, but to only alter the layer number to go back 
  up. 

menu_amcmd - This adds an adminmod command to the menu (anything that can be run through
  plugin_exec) 

	menu_amcmd 2 "Description" "command data" 

  This adds a menu item with a Description that, when selected, will be executed through 
  plugin_exec.  You may now use a ";" to seperate commands for any given menu entry.
  Examples
	
	menu_amcmd 2 "Funmode On" "admin_csay Blue Fun mode has been enabled!!;admin_fun 1"
	menu_amcmd 2 "FriendlyFire" "admin_csay Red NOTICE^n^nFriendly fire is ENABLED"
	
  NOTES * If a player does not have access to the FIRST command, the entry will be hidden.
	* If they have access to the first command but not the second, they will get REJECT 
	  messages for each command they do not have access to.
	* You CANNOT mix AdminCommands with Console commands, it wont work.

menu_selfexec - This actually executes the command on the client.

	menu_selfexec 2 "Description" "Command" 

  This adds a menu item of Description that, when selected, executes the Command on the
  client using execclient.  This is useful for running commands in other metamod plugins
  or setting client side cvars.  Examples

	menu_selfexec 2 "Set Menus to ^"Go Back^"" "setinfo am_menugoback 1"
	menu_selfexec 2 "Set Menus to ^"Cancel^"" "setinfo am_menugoback 0"
	menu_selfexec 2 "Show plbot menu" "plb_menu"
	menu_selfexec 2 "Show statsme menu" "statsme_menu"

  NOTES * If allow_client_exec is disabled (0) these commands will be automatically hidden
          or greyed out (depending on the mod and your choices).

menu_player - This adds an option to do an action to the player

	menu_player 2 "Description" "Command" 

  This adds a menu item of Description that, when selected, displays a list of players 
  under the heading of Description. When a player is then selected, they will be targeted 
  with the Command. Ergo, putting Command as "admin_slap" and choosing player "Ade" will 
  result in "admin_slap Ade". You may now use a ";" to seperate commands for any given menu 
  entry.  I have also added in that "%PLAYER%" will be replaced by the targets name.  If
  "%PLAYER%" is not found in the string, the users name will automatically be passed as the
  first argument. Examples

	menu_player 2 "Slap" "admin_slap"
	menu_player 2 "Slap" "admin_slap %PLAYER%"
	menu_player 2 "Slap n say" "admin_slap %PLAYER%;admin_tsay Red I am watching you %PLAYER%, be careful!"

  NOTES * If a player does not have access to the FIRST command, the entry will be hidden.
	* If they have access to the first command but not the second, they will get REJECT 
	  messages for each command they do not have access to.
	* You CANNOT mix AdminCommands with Console commands, it wont work.
	* The MAXIMUM length of an argument is defined in the .sma as MAX_MENU_DATA.

menu_console - Runs a console command (anything run by exec)

	menu_console 2 "Description" "Command" 

  This adds a menu item with a Description that, when selected, will be executed through exec. 
  You may now use a ";" to seperate commands for any given menu entry.  Example 

	menu_console 2 "Shut down server" "say Restarting round;sv_restartround 10"

  NOTES * You CANNOT mix AdminCommands with Console commands, it wont work.

menu_toggle - Toggles the value of a given CVar

	menu_toggle 2 "Description" "cvar" "Lower" "Increment" "Upper" 

  This adds a menu item with a Description that, when selected, causes the value of the cvar 
  to be altered. It will be altered from its current state by adding Increment to it up to a 
  maximum of Upper when it will be reset to Lower. Very useful for toggleing things like 
  friendly fire. You can NOT use a ";" in this type of entry.  Examples:-

	menu_toggle 2 "Start money" "mp_startmoney" "800" "800" "16000"
	menu_toggle 2 "Friendly Fire" "mp_friendlyfire" "0" "1" "1"

  NOTES * This ONLY works with Server CVars, NOT adminmod commands!

add_file - Includes a file into the menu.

	add_file 1 "filename"

  This acts just like you took the filename, copied its contents and pasted them into the 
  main menu.  The paths are relative to the {moddir}. Note that this ignores the line 
  number and simply loads the file.  The files contents should be written to fit into
  the main menu.ini.

--------------------------------------------------------------------------------------
///////   4) C) Got any sample "menu.ini" files?  ////////////////////////////////////
--------------------------------------------------------------------------------------

Some sample menus have been included with the plugin.  One was written by me and others
were provided by the following:-

Filename			Provided by		A URL
------------------------------|-----------------------|--------------------------------
Goku Menu.ini 			AD[NsG]SR71Goku		http://www.scriptordie.com
KTrain Menu.ini			KTrain			
Cavey Menu.ini			Caveman			http://www.scriptordie.com
PapaSmurf Menu.ini		Papa Smurf 
D-Fence Menu (German).ini	D-Fence			http://www.damn-clan.net
Roost2 Menu.zip			Roost2			http://www.rubberroost.net

--------------------------------------------------------------------------------------
///////   4) D) Is there a nice GUI driven program to help me create "menu.ini" files?
--------------------------------------------------------------------------------------

Wraith has written a small program (Win32) to help people get to grips with the
menu.ini file.  It is available from here:-

	http://www.scriptordie.com/cavey/menuparser.zip

NOTE -  While I am confidant that file is clean, virus checking and proper use remains 
	the responsibility of the user.  This program is FREE and comes with NO 
	WARRANTY what-so-ever.  So no, you cant bitch at anyone if it screws up.
	If you do not like this, dont use it.
     -  Also, it is designed for version 1.2 of the menu plugin.  Some features are
	not supported (like %PLAYER% and menu_selfexec)

--------------------------------------------------------------------------------------
///////   5) A)  It isn't working, what is wrong with it?  ///////////////////////////
--------------------------------------------------------------------------------------

Okay, a list of symptoms and problems in the order that you ought to check them, PLEASE
read through these carefully.....

Symptom		- Whenever someone uses admin_menu the server exits.
Possible Causes	- You have not updated AdminMod correctly.  Please make sure that
		  you are using a POST b2.50.42 dll.  Anything earlier causes horrible
		  crashes and the server to quit.

Symptom		- It is not compiling when I click the compile_all file and the amx
		  is 0 bytes in size.
Possible Causes	- You have not updated AdminMod correctly.  Please make sure that
		  you are using a POST 2.50.42 release
		- Okay, for this you need to check for a new version of the plugin from
		  http://www.scriptordie.com/ . If the version available there still
		  has the problem I will want you to e-mail me the plugin_cavey_menu_error.txt
		  file created by the compiler or ICQ me about the problem.  It is 
		  probably a known problem

Symptom		- I use "admin_menu" and the server says "[ADMIN] Beta Feature 'menu' 
		  not enabled", why is it not working?
Possible Causes	- You have not set ' amv_enable_beta "menu 1" ' in your server.cfg.
		  If you do, this message should go away.......

Symptom		- I dont see the menu when I use admin_menu.
Possible Causes	- You have not set the amv_enable_beta with the correct setting.  
		  Please see section 1 step 7 for details.
		- You have set the menu to only respond to people with an access level
		  that you do not have yourself.  Check the settings and try again.
		- Is it installed correctly?  Do an "admin_version" as a client or
		  "admin_command admin_version" in the HLDS/RCON console and look
		  for the menu plugin.  Does it exist?  Does it say (Disabled) ?

Symptom		- I get a menu but it only contains a "Main Menu" and "0) Cancel"
Possible Causes - The menu.ini file is not in the correct place and the plugin could 
		  not find it.  Make sure it is not named "menu.ini.txt" by mistake 
		  and that a menu.ini actually exists.  Also note that in Linux the
		  filename IS case sensitive.
		- The menu.ini file is blank.  It needs to contain some stuff to 
		  actually work
		
Symptom		- The plugin has (Disabled) itself.
Possible Causes - Either file_access_read and/or amv_enable_beta are set to 0
		- You do not have the correct version of the adminmod.  This requires 
		  AM Beta 2.50.42 or newer.

Symptom		- I cannot see the plugin in admin_version.
Possible Causes - It is not installed correctly.  Please try re-installing the plugin.
		- Check the beginning of the logs and see if it failed to load. Due to
		  the size and complexity of the plugin it can fail to compile so you 
		  should try to compile it again.  If this fails I need the compiled
		  amx, the uncompiled .sma and what OS you are running your server on.
		  REMEMBER - Linux and Win32 .amx files are NOT the same!!!!!

Symptom		- I am running CS and I dont see the coloured menus.
Possible Causes - This detects the mod through the liblist.gam, so you need file_access_read
		  set to 1.  Assuming you have that enabled, look in the vault for a
		  setting that says
			MOD Counter-Strike
		  This is how CS identifies it self in the liblist.gam.  If it does not
		  read as above it will not be identified and therefore no colours

Symptom		- I am running Firearms and I select things from the menu and it is
		  disappears without a trace.
Possible Causes - This detects the mod through the liblist.gam, so you need file_access_read
		  set to 1.  Assuming you have that enabled, look in the vault for a
		  setting that says
			MOD Firearms
		  This is how FA identifies it self in the liblist.gam.  If it does not
		  read as above it will not be identified and therefore the menu
		  plugin will not adjust itself to cope.

I have not found any other problems, if you find one, please tell me......

--------------------------------------------------------------------------------------
///////   5) B)  HELP!!!!!  //////////////////////////////////////////////////////////
--------------------------------------------------------------------------------------

If you think it is broken on your server, I will require the following files 
(preferably zipped) and information.  Failure to provide any file will result in me 
ignoring the request and/or swearing at you.

  -=    Files    =-
A debug.log of the error occuring. (For this you need to turn Debug mode on, see 
  section 4)A) )
A set of server logs where the error occurs.
A copy of the compiled .amx file
A copy of the uncompiled .sma file you created the amx file from.
A copy of the plugin.ini.
A copy of the menu.ini(s).

  -= Information =-
What adminmod version are you running? (2.50.26a, 2.50.42 etc....)
What version of what modification are you running? (CS 1.5, DoD 3.1 etc...)
What operating system are you running the server on? (Linux of Win32)
Is your server a dedicated server or a listenserver?

IMPORTANT -
* If you do not provide ANY ONE of these I will not give you any help.  
* I will NOT help with installing this plugin and will tell you to re-read this readme.
  If you send me questions regarding this I will add the question to the FAQ.
* Please note that my support is a privilidge and not a right.

--------------------------------------------------------------------------------------
///////   6) Any questions??  ////////////////////////////////////////////////////////
--------------------------------------------------------------------------------------

Author     - Joe "Caveman" Noyes

A/S/L      - 21/Male/Exeter and Droitwich Spa, England.

ICQ#       - 70710878
Home Page  - http://www.scriptordie.com/
E-mail/MSN - caveman@scriptordie.com
