mirror of
https://github.com/alliedmodders/amxmodx.git
synced 2024-10-16 23:37:04 +03:00
amxmisc: Documentation updates and additions
This commit is contained in:
Valentin Grünbacher
parent
77762b9c2c
commit
5f278eee7b
@ -16,12 +16,35 @@
|
||||
#include <amxmodx>
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Returns if the client has any admin flags set
|
||||
*
|
||||
* @param id Client index
|
||||
*
|
||||
* @return 1 if client has any admin flags, 0 otherwise
|
||||
*/
|
||||
stock is_user_admin(id)
|
||||
{
|
||||
new __flags = get_user_flags(id);
|
||||
return (__flags > 0 && !(__flags & ADMIN_USER));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns if the user can execute the current command by checking the necessary
|
||||
* admin flags and parameter count. Displays a denied access message to the user
|
||||
* if missing privileges or a usage example if too few parameters are provided.
|
||||
*
|
||||
* @note This should be used inside of a command forward as it uses read_argc()
|
||||
* to check the parameter count.
|
||||
*
|
||||
* @param id Client index
|
||||
* @param level Required admin flags
|
||||
* @param cid Command id
|
||||
* @param num Required number of parameters
|
||||
* @param acesssilent If true no denied access message will be printed
|
||||
*
|
||||
* @return 1 if access granted and parameters provided, 0 otherwise
|
||||
*/
|
||||
stock cmd_access(id, level, cid, num, bool:accesssilent = false)
|
||||
{
|
||||
new has_access = 0;
|
||||
@ -64,6 +87,14 @@ stock cmd_access(id, level, cid, num, bool:accesssilent = false)
|
||||
return 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns if the client has the specified admin flags.
|
||||
*
|
||||
* @param id Client index
|
||||
* @param level Required admin flags
|
||||
*
|
||||
* @return 1 if client has the admin flags, 0 otherwise
|
||||
*/
|
||||
stock access(id, level)
|
||||
{
|
||||
if (level == ADMIN_ADMIN)
|
||||
@ -78,18 +109,36 @@ stock access(id, level)
|
||||
return (get_user_flags(id) & level);
|
||||
}
|
||||
|
||||
/**
|
||||
* Flags related to cmd_target:
|
||||
* 1 - obey immunity
|
||||
* 2 - allow yourself
|
||||
* 4 - must be alive
|
||||
* 8 - can't be bot
|
||||
/**
|
||||
* cmd_target flags
|
||||
*/
|
||||
#define CMDTARGET_OBEY_IMMUNITY (1<<0)
|
||||
#define CMDTARGET_ALLOW_SELF (1<<1)
|
||||
#define CMDTARGET_ONLY_ALIVE (1<<2)
|
||||
#define CMDTARGET_NO_BOTS (1<<3)
|
||||
#define CMDTARGET_OBEY_IMMUNITY (1<<0) // Obey immunity
|
||||
#define CMDTARGET_ALLOW_SELF (1<<1) // Allow self targeting
|
||||
#define CMDTARGET_ONLY_ALIVE (1<<2) // Target must be alive
|
||||
#define CMDTARGET_NO_BOTS (1<<3) // Target can't be a bot
|
||||
|
||||
/**
|
||||
* Processes a generic target pattern and tries to match it to a client based
|
||||
* on filtering flags. If no unique target is found an appropriate message is
|
||||
* displayed to the admin.
|
||||
*
|
||||
* @note The pattern is first matched case insensitively against client names.
|
||||
* If no match is found it is matched against client authids. If still no
|
||||
* match is found and the pattern starts with '#' it is finally matched
|
||||
* against client userids.
|
||||
* @note Since client names are matched by substring the pattern can potentially
|
||||
* match multiple targets. In that case the function will return 0 and ask
|
||||
* the admin to provide a unique pattern.
|
||||
* @note The filtering flags are applied after the pattern matching has
|
||||
* finished. That means the pattern has to be unique against all clients
|
||||
* on the server even if some of them are not eligible.
|
||||
*
|
||||
* @param id Client index of admin performing an action
|
||||
* @param arg Target pattern
|
||||
* @param flags Filtering flags, see CMDTARGET_* constants above
|
||||
*
|
||||
* @return Client index, or 0 if no or multiple clients matched
|
||||
*/
|
||||
stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY)
|
||||
{
|
||||
new player = find_player("bl", arg);
|
||||
@ -145,12 +194,13 @@ stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY)
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard method to show activity to clients connected to the server.
|
||||
* This depends on the amx_show_activity cvar. See documentation for more details.
|
||||
* Standard method to show admin activity to clients connected to the server.
|
||||
* This depends on the amx_show_activity cvar. See documentation for more details.
|
||||
*
|
||||
* @param id The user id of the person doing the action.
|
||||
* @param name The name of the person doing the action.
|
||||
* @param fmt The format string to display. Do not put the "ADMIN:" prefix in this.
|
||||
* @param id Client index performing the action
|
||||
* @param name Name of client performing the action
|
||||
* @param fmt Formatting rules
|
||||
* @param ... Variable number of formatting parameters
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
@ -237,14 +287,14 @@ stock show_activity(id, const name[], const fmt[], any:...)
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard method to show activity to one single client.
|
||||
* This is useful for messages that get pieced together by many language keys.
|
||||
* This depends on the amx_show_activity cvar. See documentation for more details.
|
||||
* Standard method to show admin activity to a single client.
|
||||
* This depends on the amx_show_activity cvar. See documentation for more details.
|
||||
*
|
||||
* @param idtarget The user id of the person to display to. 0 is invalid.
|
||||
* @param idadmin The user id of the person doing the action.
|
||||
* @param name The name of the person doing the action.
|
||||
* @param fmt The format string to display. Do not put the "ADMIN:" prefix in this.
|
||||
* @param idtarget Client index to display message to
|
||||
* @param id Client index performing the action
|
||||
* @param name Name of client performing the action
|
||||
* @param fmt Formatting rules
|
||||
* @param ... Variable number of formatting parameters
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
@ -254,7 +304,7 @@ stock show_activity_id(idtarget, idadmin, const name[], const fmt[], any:...)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
static __amx_show_activity;
|
||||
if (__amx_show_activity == 0)
|
||||
{
|
||||
@ -437,6 +487,18 @@ stock show_activity_key(const KeyWithoutName[], const KeyWithName[], const ___Ad
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns if the mod running on the server supports colored menus.
|
||||
*
|
||||
* @note The full list of mods supporting colored menus:
|
||||
* Counter-Strike, Counter-Strike: Condition Zero, Deathmatch Classic,
|
||||
* Day of Defeat, Team Fortress Classic and Half-Life: Deathmatch.
|
||||
* @note Since this is a stock and compiled into the plugin, the list of
|
||||
* supported mods will not update and require recompilation of the plugin
|
||||
* if the list ever changed.
|
||||
*
|
||||
* @return 1 if colored menus are supported, 0 otherwise
|
||||
*/
|
||||
stock colored_menus()
|
||||
{
|
||||
static ColoredMenus = -1;
|
||||
@ -465,6 +527,11 @@ stock colored_menus()
|
||||
return ColoredMenus;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns if the mod running on the server is a version of Counter-Strike.
|
||||
*
|
||||
* @return 1 if mod is Counter-Strike, 0 otherwise
|
||||
*/
|
||||
stock cstrike_running()
|
||||
{
|
||||
new mod_name[32];
|
||||
@ -473,6 +540,13 @@ stock cstrike_running()
|
||||
return (equal(mod_name, "cstrike") || equal(mod_name, "czero") || equal(mod_name, "csv15") || equal(mod_name, "cs13"));
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns if the server is running a specific mod.
|
||||
*
|
||||
* @param mod Mod name to check for
|
||||
*
|
||||
* @return 1 if mod name matches, 0 otherwise
|
||||
*/
|
||||
stock is_running(const mod[])
|
||||
{
|
||||
new mod_name[32];
|
||||
@ -481,42 +555,92 @@ stock is_running(const mod[])
|
||||
return equal(mod_name, mod);
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the path to the AMXX base directory.
|
||||
*
|
||||
* @param name Buffer to copy path to
|
||||
* @param len Maximum buffer size
|
||||
*
|
||||
* @return Number of cells written to buffer
|
||||
*/
|
||||
stock get_basedir(name[], len)
|
||||
{
|
||||
return get_localinfo("amxx_basedir", name, len);
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the path to the AMXX configs directory.
|
||||
*
|
||||
* @param name Buffer to copy path to
|
||||
* @param len Maximum buffer size
|
||||
*
|
||||
* @return Number of cells written to buffer
|
||||
*/
|
||||
stock get_configsdir(name[], len)
|
||||
{
|
||||
return get_localinfo("amxx_configsdir", name, len);
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the path to the AMXX data directory.
|
||||
*
|
||||
* @param name Buffer to copy path to
|
||||
* @param len Maximum buffer size
|
||||
*
|
||||
* @return Number of cells written to buffer
|
||||
*/
|
||||
stock get_datadir(name[], len)
|
||||
{
|
||||
return get_localinfo("amxx_datadir", name, len);
|
||||
}
|
||||
|
||||
/**
|
||||
* Provides a shorthand to register a working menu.
|
||||
*
|
||||
* @note Combines the necessary calls to register_menuid() and
|
||||
* register_menucmd() into a single function.
|
||||
*
|
||||
* @param title Menu name
|
||||
* @param keys Key flags
|
||||
* @param function Callback function
|
||||
* @param outside Catch menus outside the calling plugin
|
||||
*
|
||||
* @noreturn
|
||||
* @error If an invalid callback function is specified, an error will
|
||||
* be thrown.
|
||||
*/
|
||||
stock register_menu(const title[], keys, const function[], outside = 0)
|
||||
{
|
||||
register_menucmd(register_menuid(title, outside), keys, function);
|
||||
}
|
||||
|
||||
/**
|
||||
* Backwards Compatibility
|
||||
* don't use it!
|
||||
* Alias to get_configsdir provided for backwards compatibility. Originally
|
||||
* intended to retrieve the AMXX custom directory.
|
||||
*
|
||||
* @deprecated Should not be used as the concept of a custom directory does no
|
||||
* longer exists in AMXX.
|
||||
*
|
||||
* @param name Buffer to copy path to
|
||||
* @param len Maximum buffer size
|
||||
*
|
||||
* @return Number of cells written to buffer
|
||||
*/
|
||||
#pragma deprecated The concept of a custom directory no longer exists in AMXX. Do not use.
|
||||
stock get_customdir(name[], len)
|
||||
{
|
||||
return get_localinfo("amxx_configsdir", name, len);
|
||||
return get_configsdir(name, len);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a menu item to Menus Front-End plugin ("amxmodmenu").
|
||||
* Adds a menu item/command to the admin menu (amxmodmenu) handled by the
|
||||
* "Menus Front-End" plugin, if it is loaded.
|
||||
*
|
||||
* @param MENU_TEXT Text that will be shown for this item in menu.
|
||||
* @param MENU_CMD Command that should be executed to start menu.
|
||||
* @param MENU_ACCESS Access required for menu.
|
||||
* @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command.
|
||||
* @param MENU_TEXT Item text that will be displayed in the menu
|
||||
* @param MENU_CMD Command that will be executed on the client
|
||||
* @param MENU_ACCESS Admin access required for menu command
|
||||
* @param MENU_PLUGIN Case-insensitive name or filename of plugin providing
|
||||
* the menu command
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
@ -526,12 +650,15 @@ stock AddMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const
|
||||
}
|
||||
|
||||
/**
|
||||
* Add a menu item to "amx_menu", that should also be accessible by non-admins.
|
||||
* Adds a menu item/command to the client menu (amx_menu) handled by the
|
||||
* "Menus Front-End" plugin, if it is loaded. Items should be accessible by
|
||||
* non-admins.
|
||||
*
|
||||
* @param MENU_TEXT Text that will be shown for this item in menu.
|
||||
* @param MENU_CMD Command that should be executed to start menu.
|
||||
* @param MENU_ACCESS Access required for menu.
|
||||
* @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command.
|
||||
* @param MENU_TEXT Item text that will be displayed in the menu
|
||||
* @param MENU_CMD Command that will be executed on the client
|
||||
* @param MENU_ACCESS Admin access required for menu command
|
||||
* @param MENU_PLUGIN Case-insensitive name or filename of plugin providing
|
||||
* the menu command
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
@ -541,7 +668,17 @@ stock AddClientMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS,
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal function used by above stocks.
|
||||
* Helper function used by AddMenuItem() and AddClientMenuItem()
|
||||
*
|
||||
* @param MENU_TEXT Item text that will be displayed in the menu
|
||||
* @param MENU_CMD Command that will be executed on the client
|
||||
* @param MENU_ACCESS Admin access required for menu command
|
||||
* @param MENU_PLUGIN Case-insensitive name or filename of plugin
|
||||
* providing the menu command
|
||||
* @param ADD_TO_CLIENT_MENU If true adds command to client menu, false adds
|
||||
* to admin menu
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const MENU_PLUGIN[], const bool:ADD_TO_CLIENT_MENU)
|
||||
{
|
||||
@ -557,7 +694,7 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c
|
||||
|
||||
new status = callfunc_begin(ADD_TO_CLIENT_MENU ? "AddClientMenu" : "AddMenu", filename);
|
||||
new bool:failed = true;
|
||||
switch (status)
|
||||
switch (status)
|
||||
{
|
||||
case 1:
|
||||
{
|
||||
@ -592,11 +729,28 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c
|
||||
callfunc_end();
|
||||
}
|
||||
|
||||
/**
|
||||
* Computes an offset from a given value while constraining it between the
|
||||
* specified bounds, rolling over if necessary.
|
||||
*
|
||||
* @note Example: The range is 1-5 and the base value (seed) is 3, the offset
|
||||
* that the value should be moved by is also 3. Offsetting the value by 3
|
||||
* would result in 6, but it is to be constrained between 1 and 5. With
|
||||
* clamp() this would result in 5, but this function rolls the value over
|
||||
* and returns 1 instead.
|
||||
*
|
||||
* @param low Lower bound
|
||||
* @param high Higher bound
|
||||
* @param seed Base value
|
||||
* @param offset Offset to move
|
||||
*
|
||||
* @return Computed offset value between specified bounds
|
||||
*/
|
||||
stock constraint_offset(low, high, seed, offset)
|
||||
{
|
||||
new numElements = high - low + 1;
|
||||
offset += seed - low;
|
||||
|
||||
|
||||
if (offset >= 0)
|
||||
{
|
||||
return low + (offset % numElements);
|
||||
@ -610,25 +764,25 @@ stock constraint_offset(low, high, seed, offset)
|
||||
}
|
||||
|
||||
/**
|
||||
* Tells if the user has ANY of the provided flags.
|
||||
* Returns if the client has any of the specified admin flags.
|
||||
*
|
||||
* @param id Client index
|
||||
* @param flags Flag string
|
||||
*
|
||||
* @return 1 if the user has ANY of the provided flags, 0 otherwise
|
||||
* @return 1 if the user has any of the specified flags, 0 otherwise
|
||||
*/
|
||||
stock has_flag(id, const flags[])
|
||||
{
|
||||
return (get_user_flags(id) & read_flags(flags));
|
||||
}
|
||||
|
||||
/**
|
||||
* Tells if the user has ALL of the provided flags.
|
||||
/**
|
||||
* Returns if the client has all of the specified admin flags.
|
||||
*
|
||||
* @param id Client index
|
||||
* @param flags Flag string
|
||||
*
|
||||
* @return 1 if the user has ALL of the provided flags, 0 otherwise
|
||||
* @return 1 if the user has all of the specified flags, 0 otherwise
|
||||
*/
|
||||
stock has_all_flags(id, const flags[])
|
||||
{
|
||||
@ -637,11 +791,11 @@ stock has_all_flags(id, const flags[])
|
||||
}
|
||||
|
||||
/**
|
||||
* Resets a client's menu.
|
||||
* Resets the client's menu.
|
||||
*
|
||||
* @note This is just a wrapper around show_menu for the sake of readability.
|
||||
* @note This is a wrapper around show_menu() for the sake of readability.
|
||||
*
|
||||
* @param index Client to reset menu to, use 0 to reset to all clients
|
||||
* @param index Client to reset menu of, 0 to reset all clients
|
||||
*
|
||||
* @noreturn
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user