Flummi/amxmodx
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #208 from Nextra/inc-doc2

Browse Source 
Update include documentation #2
This commit is contained in:
Vincent Herbet 2015-03-09 19:45:47 +01:00
commit 22c3d62dec
13 changed files with 2699 additions and 1179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
plugins/include/amxconst.inc
View File

@ -8,7 +8,7 @@
// https://alliedmods.net/amxmodx-license // https://alliedmods.net/amxmodx-license
#if defined _amxconst_included #if defined _amxconst_included
#endinput #endinput
#endif #endif
#define _amxconst_included #define _amxconst_included

250
plugins/include/amxmisc.inc
View File

@ -8,7 +8,7 @@
// https://alliedmods.net/amxmodx-license // https://alliedmods.net/amxmodx-license
#if defined _amxmisc_included #if defined _amxmisc_included
#endinput #endinput
#endif #endif
#define _amxmisc_included #define _amxmisc_included
@ -16,12 +16,35 @@
#include <amxmodx> #include <amxmodx>
#endif #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) stock is_user_admin(id)
{ {
new __flags = get_user_flags(id); new __flags = get_user_flags(id);
return (__flags > 0 && !(__flags & ADMIN_USER)); 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) stock cmd_access(id, level, cid, num, bool:accesssilent = false)
{ {
new has_access = 0; new has_access = 0;
@ -64,6 +87,14 @@ stock cmd_access(id, level, cid, num, bool:accesssilent = false)
return 1; 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) stock access(id, level)
{ {
if (level == ADMIN_ADMIN) if (level == ADMIN_ADMIN)
@ -78,18 +109,36 @@ stock access(id, level)
return (get_user_flags(id) & level); return (get_user_flags(id) & level);
} }
/** /**
* Flags related to cmd_target: * cmd_target flags
* 1 - obey immunity
* 2 - allow yourself
* 4 - must be alive
* 8 - can't be bot
*/ */
#define CMDTARGET_OBEY_IMMUNITY (1<<0) #define CMDTARGET_OBEY_IMMUNITY (1<<0) // Obey immunity
#define CMDTARGET_ALLOW_SELF (1<<1) #define CMDTARGET_ALLOW_SELF (1<<1) // Allow self targeting
#define CMDTARGET_ONLY_ALIVE (1<<2) #define CMDTARGET_ONLY_ALIVE (1<<2) // Target must be alive
#define CMDTARGET_NO_BOTS (1<<3) #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) stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY)
{ {
new player = find_player("bl", arg); 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. * 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. * 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 id Client index performing the action
* @param name The name of the person doing the action. * @param name Name of client performing the action
* @param fmt The format string to display. Do not put the "ADMIN:" prefix in this. * @param fmt Formatting rules
* @param ... Variable number of formatting parameters
* *
* @noreturn * @noreturn
*/ */
@ -237,14 +287,14 @@ stock show_activity(id, const name[], const fmt[], any:...)
} }
/** /**
* Standard method to show activity to one single client. * Standard method to show admin activity to a 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.
* 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 idtarget Client index to display message to
* @param idadmin The user id of the person doing the action. * @param id Client index performing the action
* @param name The name of the person doing the action. * @param name Name of client performing the action
* @param fmt The format string to display. Do not put the "ADMIN:" prefix in this. * @param fmt Formatting rules
* @param ... Variable number of formatting parameters
* *
* @noreturn * @noreturn
*/ */
@ -254,7 +304,7 @@ stock show_activity_id(idtarget, idadmin, const name[], const fmt[], any:...)
{ {
return; return;
} }
static __amx_show_activity; static __amx_show_activity;
if (__amx_show_activity == 0) 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() stock colored_menus()
{ {
static ColoredMenus = -1; static ColoredMenus = -1;
@ -465,6 +527,11 @@ stock colored_menus()
return ColoredMenus; 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() stock cstrike_running()
{ {
new mod_name[32]; 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")); 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[]) stock is_running(const mod[])
{ {
new mod_name[32]; new mod_name[32];
@ -481,42 +555,92 @@ stock is_running(const mod[])
return equal(mod_name, 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) stock get_basedir(name[], len)
{ {
return get_localinfo("amxx_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) stock get_configsdir(name[], len)
{ {
return get_localinfo("amxx_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) stock get_datadir(name[], len)
{ {
return get_localinfo("amxx_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) stock register_menu(const title[], keys, const function[], outside = 0)
{ {
register_menucmd(register_menuid(title, outside), keys, function); register_menucmd(register_menuid(title, outside), keys, function);
} }
/** /**
* Backwards Compatibility * Alias to get_configsdir provided for backwards compatibility. Originally
* don't use it! * 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) 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_TEXT Item text that will be displayed in the menu
* @param MENU_CMD Command that should be executed to start menu. * @param MENU_CMD Command that will be executed on the client
* @param MENU_ACCESS Access required for menu. * @param MENU_ACCESS Admin access required for menu command
* @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command. * @param MENU_PLUGIN Case-insensitive name or filename of plugin providing
* the menu command
* *
* @noreturn * @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_TEXT Item text that will be displayed in the menu
* @param MENU_CMD Command that should be executed to start menu. * @param MENU_CMD Command that will be executed on the client
* @param MENU_ACCESS Access required for menu. * @param MENU_ACCESS Admin access required for menu command
* @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command. * @param MENU_PLUGIN Case-insensitive name or filename of plugin providing
* the menu command
* *
* @noreturn * @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) 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 status = callfunc_begin(ADD_TO_CLIENT_MENU ? "AddClientMenu" : "AddMenu", filename);
new bool:failed = true; new bool:failed = true;
switch (status) switch (status)
{ {
case 1: case 1:
{ {
@ -592,11 +729,28 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c
callfunc_end(); 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) stock constraint_offset(low, high, seed, offset)
{ {
new numElements = high - low + 1; new numElements = high - low + 1;
offset += seed - low; offset += seed - low;
if (offset >= 0) if (offset >= 0)
{ {
return low + (offset % numElements); 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 id Client index
* @param flags Flag string * @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[]) stock has_flag(id, const flags[])
{ {
return (get_user_flags(id) & read_flags(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 id Client index
* @param flags Flag string * @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[]) 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 * @noreturn
*/ */

726
plugins/include/amxmodx.inc
View File

File diff suppressed because it is too large Load Diff

2
plugins/include/amxmodx_version.inc
View File

@ -8,7 +8,7 @@
// https://alliedmods.net/amxmodx-license // https://alliedmods.net/amxmodx-license
#if defined _amxmodx_version_included #if defined _amxmodx_version_included
#endinput #endinput
#endif #endif
#define _amxmodx_version_included #define _amxmodx_version_included

30
plugins/include/cellarray.inc
View File

@ -63,7 +63,9 @@ stock ByteCountToCells(size)
* number of items. The items are not valid to read or set * number of items. The items are not valid to read or set
* until they have actually been pushed into the array. * until they have actually been pushed into the array.
* *
* @return Handle to the array. * @return New array handle, which must be freed via ArrayDestroy()
* @error If an invalid cellsize is provided an error will be
* thrown.
*/ */
native Array:ArrayCreate(cellsize = 1, reserved = 32); native Array:ArrayCreate(cellsize = 1, reserved = 32);
@ -431,7 +433,7 @@ native DoNotUse:ArrayGetStringHandle(Array:which, item);
* *
* @param which Array to destroy * @param which Array to destroy
* *
* @return 1 if the array was destroyed, 0 if nothing had to be * @return 1 if the Array was destroyed, 0 if nothing had to be
* destroyed (invalid handle) * destroyed (invalid handle)
*/ */
native ArrayDestroy(&Array:which); native ArrayDestroy(&Array:which);
@ -444,10 +446,10 @@ native ArrayDestroy(&Array:which);
* *
* public MySortFunc(Array:array, item1, item2, const data[], data_size) * public MySortFunc(Array:array, item1, item2, const data[], data_size)
* *
* array - Array handle in its current un-sorted state * array - Array handle in its current un-sorted state
* item1, item2 - Current item pair being compared * item1, item2 - Current item pair being compared
* data[] - Extra data array passed to the sort func * data[] - Extra data array passed to the sort func
* data_size - Size of extra data * data_size - Size of extra data
* *
* @note The comparison function should return: * @note The comparison function should return:
* -1 if item1 should go before item2 * -1 if item1 should go before item2
@ -485,20 +487,20 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0);
* *
* public MySortFunc(Array:array, elem1, elem2, const data[], data_size) * public MySortFunc(Array:array, elem1, elem2, const data[], data_size)
* *
* array - Array handle in its current un-sorted state * array - Array handle in its current un-sorted state
* elem1, elem2 - Current element pair being compared * elem1, elem2 - Current element pair being compared
* data[] - Extra data array passed to the sort func * data[] - Extra data array passed to the sort func
* data_size - Size of extra data * data_size - Size of extra data
* *
* @note For Arrays with a cellsize larger than 1 (used for storing arrays and * @note For Arrays with a cellsize larger than 1 (used for storing arrays and
* strings), the function is called in the following manner: * strings), the function is called in the following manner:
* *
* public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size)
* *
* array - Array handle in its current un-sorted state * array - Array handle in its current un-sorted state
* elem1[], elem2[] - Current element pair being compared * elem1[], elem2[] - Current element pair being compared
* data[] - Extra data array passed to the sort func * data[] - Extra data array passed to the sort func
* data_size - Size of extra data * data_size - Size of extra data
* *
* *
* @note The comparison function should return: * @note The comparison function should return:

138
plugins/include/cellstack.inc
View File

@ -12,131 +12,139 @@
#endif #endif
#define _cellstack_included #define _cellstack_included
/**
* Stack tag declaration
*
* @note Plugins are responsible for freeing all Stack handles they acquire.
* Failing to free handles will result in the plugin and AMXX leaking
* memory.
*/
enum Stack enum Stack
{ {
Invalid_Stack = 0 Invalid_Stack = 0
}; };
/** /**
* Creates a stack structure. A stack is a LIFO (last in, first out) * Creates a stack structure. A stack is a LIFO (last in, first out) vector of
* vector (array) of items. It has O(1) insertion and O(1) removal. * of items. It has O(1) insertion and O(1) removal.
* *
* Stacks have two operations: Push (adding an item) and Pop (removes * @note Stacks provide only two operations: Push (adding an item to the top)
* items in reverse-push order). * and Pop (remove an item from the top, in reverse-push order).
* @note The contents of the stack are uniform; i.e. storing a string and then
* retrieving it as an integer is NOT the same as str_to_num()!
* @note The "blocksize" determines how many cells each stack slot has, it can
* not be changed after creation.
* *
* The contents of the stack are uniform; i.e. storing a string and then * @param blocksize The number of cells each entry in the stack can hold
* retrieving it as an integer is NOT the same as StringToInt()!
* *
* The "blocksize" determines how many cells each slot has; it cannot * @return New stack Handle, which must be freed via DestroyStack()
* be changed after creation. * @error If an invalid blocksize is provided an error will be
* * thrown.
* @param blocksize The number of cells each entry in the stack can
* hold. For example, 32 cells is equivalent to:
* new Array[X][32]
*
* @return New stack Handle.
* @error Invalid block size.
*/ */
native Stack:CreateStack(blocksize = 1); native Stack:CreateStack(blocksize = 1);
/** /**
* Pushes a value onto the end of the stack, adding a new index. * Pushes a value onto the end of the stack, adding a new index.
* *
* This may safely be used even if the stack has a blocksize * @note This may safely be used even if the stack has a blocksize greater than
* greater than 1. * 1.
* *
* @param handle Stack handle. * @param handle Stack handle
* @param value Value to push. * @param value Value to push
* *
* @noreturn * @noreturn
* @error Invalid handle or out of memory. * @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/ */
native PushStackCell(Stack:handle, any:value); native PushStackCell(Stack:handle, any:value);
/** /**
* Pushes a string onto the end of a stack, truncating it if it is * Pushes a string onto the end of a stack, truncating it if it is too long.
* too big.
* *
* @param handle Stack handle. * @param handle Stack handle
* @param value String to push. * @param value String to push
* *
* @noreturn * @noreturn
* @error Invalid handle or out of memory. * @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/ */
native PushStackString(Stack:handle, const value[]); native PushStackString(Stack:handle, const value[]);
/** /**
* Pushes an array of cells onto the end of a stack. The cells * Pushes an array of cells onto the end of a stack. The cells are pushed as a
* are pushed as a block (i.e. the entire array takes up one stack slot), * block (i.e. the entire array takes up one stack slot), rather than pushing
* rather than pushing each cell individually. * each cell individually.
*
* @param handle Stack handle
* @param values Block of values to copy
* @param size If not set, the number of elements copied from the array
* will be equal to the blocksize, if set higher than the
* blocksize, the operation will be truncated,
* *
* @param handle Stack handle.
* @param values Block of values to copy.
* @param size If not set, the number of elements copied from the array
* will be equal to the blocksize. If set higher than the
* blocksize, the operation will be truncated.
* @noreturn * @noreturn
* @error Invalid handle or out of memory. * @error If an invalid handle is provided or the resizing
* operation runs out of memory, an error will be thrown.
*/ */
native PushStackArray(Stack:handle, const any:values[], size= -1); native PushStackArray(Stack:handle, const any:values[], size= -1);
/** /**
* Pops a cell value from a stack. * Pops a cell value from a stack.
* *
* @param handle Stack handle. * @param handle Stack handle
* @param value Variable to store the value. * @param value Variable to store the value in
* @param block Optionally specify which block to read from * @param block Optionally specify which block to read from (useful if the
* (useful if the blocksize > 0). * blocksize is > 0)
* @param asChar Optionally read as a byte instead of a cell. * @param asChar Optionally read as a byte instead of a cell
* *
* @return True on success, false if the stack is empty. * @return True on success, false if the stack is empty.
* @error Invalid handle, Invalid block or Invalid byte. * @error If an invalid handle, invalid block or invalid byte is
* provided, an error will be thrown.
*/ */
native bool:PopStackCell(Stack:handle, &any:value, block = 0, bool:asChar = false); native bool:PopStackCell(Stack:handle, &any:value, block = 0, bool:asChar = false);
/** /**
* Pops a string value from a stack. * Pops a string value from a stack.
* *
* @param handle Stack handle. * @param handle Stack handle
* @param buffer Buffer to store string. * @param buffer Buffer to copy string to
* @param maxlength Maximum size of the buffer. * @param maxlength Maximum size of the buffer
* @param written Number of characters copied. * @param written Variable to store number of characters copied to
* *
* @return True on success, false if the stack is empty. * @return True on success, false if the stack is empty
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown.
*/ */
native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0); native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0);
/** /**
* Pops an array of cells from a stack. * Pops an array of cells from a stack.
* *
* @param handle Stack handle. * @param handle Stack handle
* @param buffer Buffer to store the array in. * @param buffer Array to copy value to
* @param size If not set, assumes the buffer size is equal to the * @param size Size of buffer, if not set (-1) assumes the size is equal to
* blocksize. Otherwise, the size passed is used. * the stack blocksize
* *
* @return True on success, false if the stack is empty. * @return True on success, false if the stack is empty
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown.
*/ */
native bool:PopStackArray(Stack:handle, any:buffer[], size = -1); native bool:PopStackArray(Stack:handle, any:buffer[], size = -1);
/** /**
* Checks if a stack is empty. * Returns if a stack is empty.
* *
* @param handle Stack handle. * @param handle Stack handle
* *
* @return True if empty, false if not empty. * @return True if empty, false if not empty
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown.
*/ */
native bool:IsStackEmpty(Stack:handle); native bool:IsStackEmpty(Stack:handle);
/** /**
* Pops a value off a stack, ignoring it completely. * Pops a value off a stack, ignoring it completely.
* *
* @param handle Stack handle. * @param handle Stack handle
* *
* @return True if something was popped, false otherwise. * @return True if a value was popped, false if stack is empty
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown.
*/ */
stock PopStack(Stack:handle) stock PopStack(Stack:handle)
{ {
@ -145,10 +153,14 @@ stock PopStack(Stack:handle)
} }
/** /**
* Destroys the stack, and resets the handle to 0 to prevent accidental usage after it is destroyed. * Destroys a stack and frees its memory.
* *
* @param which The stack to destroy. * @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
* *
* @noreturn * @param handle Stack to destroy
*
* @return 1 if the Stack was destroyed, 0 if nothing had to be
* destroyed (invalid handle)
*/ */
native DestroyStack(&Stack:handle); native DestroyStack(&Stack:handle);

242
plugins/include/celltrie.inc
View File

@ -12,176 +12,209 @@
#endif #endif
#define _celltrie_included #define _celltrie_included
/**
* Hash map tag declaration
*
* @note The word "Trie" in this API is historical. As of AMX Mod X 1.8.3,
* tries have been internally replaced with hash tables, which have O(1)
* insertion time instead of O(n).
* @note Plugins are responsible for freeing all Trie handles they acquire.
* Failing to free handles will result in the plugin and AMXX leaking
* memory.
*/
enum Trie enum Trie
{ {
Invalid_Trie = 0 Invalid_Trie = 0
}; };
/**
* Hash map snapshot tag declaration
*
* @note Plugins are responsible for freeing all Snapshot handles they acquire.
* Failing to free handles will result in the plugin and AMXX leaking
* memory.
*/
enum Snapshot enum Snapshot
{ {
Invalid_Snapshot = 0 Invalid_Snapshot = 0
}; };
/** /**
* Creates a hash map. A hash map is a container that can map strings (called * Creates a hash map. A hash map is a container that maps strings (called keys)
* "keys") to arbitrary values (cells, arrays, or strings). Keys in a hash map * to arbitrary values (cells, arrays or strings).
* are unique. That is, there is at most one entry in the map for a given key.
* *
* Insertion, deletion, and lookup in a hash map are all considered to be fast * @note Keys in a hash map are unique so there is no more than one entry in the
* operations, amortized to O(1), or constant time. * map for any given key.
* @note Insertion, deletion, and lookup in a hash map are all considered to be
* fast operations, amortized to O(1), or constant time.
* *
* The word "Trie" in this API is historical. As of AMX Mod X 1.8.3, tries have * @return New Map handle, which must be freed via TrieDestroy()
* been internally replaced with hash tables, which have O(1) insertion time
* instead of O(n).
*
* @return New Map handle, which must be freed via TrieDestroy().
*/ */
native Trie:TrieCreate(); native Trie:TrieCreate();
/** /**
* Clears all entries from a Map. * Clears all entries from a Map.
* *
* @param handle Map handle. * @param handle Map handle
* *
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
* @noreturn
*/ */
native TrieClear(Trie:handle); native TrieClear(Trie:handle);
/** /**
* Sets a value in a hash map, either inserting a new entry or replacing an old one. * Sets a cell value in a hash map, either inserting a new entry or replacing
* an old one.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param value Value to store at this key. * @param value Value to store
* @param replace If false, operation will fail if the key is already set. * @param replace If false the operation will fail if the key is already set
* *
* @return True on success, false on failure. * @return 1 on success, 0 otherwise
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native TrieSetCell(Trie:handle, const key[], any:value, bool:replace = true); native TrieSetCell(Trie:handle, const key[], any:value, bool:replace = true);
/** /**
* Sets a string value in a Map, either inserting a new entry or replacing an old one. * Sets a string value in a hash map, either inserting a new entry or replacing
* an old one.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param value String to store. * @param value String to store
* @param replace If false, operation will fail if the key is already set. * @param replace If false the operation will fail if the key is already set
* *
* @return True on success, false on failure. * @return 1 on success, 0 otherwise
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native TrieSetString(Trie:handle, const key[], const value[], bool:replace = true); native TrieSetString(Trie:handle, const key[], const value[], bool:replace = true);
/** /**
* Sets an array value in a Map, either inserting a new entry or replacing an old one. * Sets an array value in a hash map, either inserting a new entry or replacing
* an old one.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param buffer Array to store. * @param buffer Array to store
* @param size Number of items in the array. * @param size Array size
* @param replace If false, operation will fail if the key is already set. * @param replace If false the operation will fail if the key is already set
* *
* @return True on success, false on failure. * @return 1 on success, 0 otherwise
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* Invalid array size. * thrown. or invalid array size
*/ */
native TrieSetArray(Trie:handle, const key[], const any:buffer[], size, bool:replace = true); native TrieSetArray(Trie:handle, const key[], const any:buffer[], size, bool:replace = true);
/** /**
* Retrieves a value in a Map. * Retrieves a cell value from a hash map.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param value Variable to store value. * @param value Variable to store value to
* @return True on success. False if the key is not set, or the key is set *
* as an array or string (not a value). * @return True on success, false if either the key is not set or the
* @error Invalid handle. * value type does not match (value is string or array)
* @error If an invalid handle is provided an error will be
* thrown.
*/ */
native bool:TrieGetCell(Trie:handle, const key[], &any:value); native bool:TrieGetCell(Trie:handle, const key[], &any:value);
/** /**
* Retrieves a string in a Map. * Retrieves a string from a hash map.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param output Buffer to store value. * @param output Buffer to copy the value to
* @param outputsize Maximum size of string buffer. * @param outputsize Maximum size of buffer
* @param size Optional parameter to store the number of bytes written to the buffer. * @param size Optional variable to store the number of cells written
* to the buffer in
* *
* @return True on success. False if the key is not set, or the key is set * @return True on success, false if either the key is not set or
* as a value or array (not a string). * the value type does not match (value is cell or array)
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* Invalid buffer size. * thrown.
*/ */
native bool:TrieGetString(Trie:handle, const key[], output[], outputsize, &size = 0); native bool:TrieGetString(Trie:handle, const key[], output[], outputsize, &size = 0);
/** /**
* Retrieves an array in a Map. * Retrieves a string from a hash map.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* @param output Buffer to store array. * @param output Array to copy the value to
* @param outputsize Maximum size of array buffer. * @param outputsize Maximum size of array
* @param size Optional parameter to store the number of elements written to the buffer. * @param size Optional variable to store the number of cells written
* to the array in
* *
* @return True on success. False if the key is not set, or the key is set * @return True on success, false if either the key is not set or
* as a value or string (not an array). * the value type does not match (value is cell or string)
* @error Invalid handle. * @error If an invalid handle or array size is provided an error
* Invalid array size. * will be thrown.
*/ */
native bool:TrieGetArray(Trie:handle, const key[], any:output[], outputsize, &size = 0); native bool:TrieGetArray(Trie:handle, const key[], any:output[], outputsize, &size = 0);
/** /**
* Removes a key entry from a Map. * Removes an entry from a hash map.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* *
* @return True on success, false if the value was never set. * @return True on success, false if the key was never set
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native bool:TrieDeleteKey(Trie:handle, const key[]); native bool:TrieDeleteKey(Trie:handle, const key[]);
/** /**
* Checks a key entry existence from a Map. * Checks a hash map for the existence of an entry.
* *
* @param handle Map handle. * @param handle Map handle
* @param key Key string. * @param key Key string
* *
* @return True on success, false if the value was never set. * @return True if the key is set, false otherwise
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native bool:TrieKeyExists(Trie:handle, const key[]); native bool:TrieKeyExists(Trie:handle, const key[]);
/** /**
* Destroys a Map. * Destroys a hash map and frees its memory.
* *
* @param handle Map handle. * @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
* *
* @return True on success, false if the value was never set. * @param handle Map handle
* @error Invalid handle. *
* @return 1 on success, 0 if an invalid handle was passed in
*/ */
native TrieDestroy(&Trie:handle); native TrieDestroy(&Trie:handle);
/** /**
* Retrieves the number of elements in a map. * Returns the number of entries in a hash map.
* *
* @param handle Map handle. * @param handle Map handle
* *
* @return Number of elements in the trie. * @return Number of elements in the hash map
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native TrieGetSize(Trie:handle); native TrieGetSize(Trie:handle);
/** /**
* Creates a snapshot of all keys in the map. If the map is changed after this * Creates a snapshot of all keys in a hash map. If the map is changed
* call, the changes are not reflected in the snapshot. Keys are not sorted. * afterwards, the changes are not reflected in the snapshot.
* Keys are not sorted.
* *
* @param handle Map handle. * @param handle Map handle
* *
* @return New map snapshot handle, which must be freed via TrieSnapshotDestroy(). * @return New map snapshot handle, which must be freed via
* @error Invalid handle. * TrieSnapshotDestroy()
* @error If an invalid handle is provided an error will be
* thrown.
*/ */
native Snapshot:TrieSnapshotCreate(Trie:handle); native Snapshot:TrieSnapshotCreate(Trie:handle);
@ -190,10 +223,11 @@ native Snapshot:TrieSnapshotCreate(Trie:handle);
* different from the size of the map, since the map can change after the * different from the size of the map, since the map can change after the
* snapshot of its keys was taken. * snapshot of its keys was taken.
* *
* @param handle Map snapshot. * @param handle Map snapshot handle
* *
* @return Number of keys. * @return Number of keys
* @error Invalid handle. * @error If an invalid handle is provided an error will be
* thrown.
*/ */
native TrieSnapshotLength(Snapshot:handle); native TrieSnapshotLength(Snapshot:handle);
@ -201,33 +235,37 @@ native TrieSnapshotLength(Snapshot:handle);
* Returns the buffer size required to store a given key. That is, it returns * Returns the buffer size required to store a given key. That is, it returns
* the length of the key plus one. * the length of the key plus one.
* *
* @param handle Map snapshot. * @param handle Map snapshot handle
* @param index Key index (starting from 0). * @param index Key index (starting from 0)
* *
* @return Buffer size required to store the key string. * @return Buffer size required to store the key string
* @error Invalid handle or index out of range. * @error If an invalid handle is provided an error will be
* thrown. or index out of range
*/ */
native TrieSnapshotKeyBufferSize(Snapshot:handle, index); native TrieSnapshotKeyBufferSize(Snapshot:handle, index);
/** /**
* Retrieves the key string of a given key in a map snapshot. * Retrieves the key string of a given key in a map snapshot.
* *
* @param handle Map snapshot. * @param handle Map snapshot handle
* @param index Key index (starting from 0). * @param index Key index (starting from 0)
* @param buffer String buffer. * @param buffer String buffer
* @param maxlength Maximum buffer length. * @param maxlength Maximum buffer length
* *
* @return Number of bytes written to the buffer. * @return Number of bytes written to the buffer
* @error Invalid handle or index out of range. * @error If an invalid handle is provided an error will be
* thrown. or index out of range
*/ */
native TrieSnapshotGetKey(Snapshot:handle, index, buffer[], maxlength); native TrieSnapshotGetKey(Snapshot:handle, index, buffer[], maxlength);
/** /**
* Destroys a Map snapshot * Destroys a map snapshot and frees its memory.
* *
* @param handle Map snapshot. * @note The function automatically sets the variable passed to it to 0 to aid
* in preventing accidental usage after destroy.
* *
* @return True on success, false if the value was never set. * @param handle Map snapshot handle
* @error Invalid handle. *
* @return 1 on success, 0 if an invalid handle was passed in
*/ */
native TrieSnapshotDestroy(&Snapshot:handle); native TrieSnapshotDestroy(&Snapshot:handle);

176
plugins/include/core.inc
View File

@ -6,36 +6,196 @@
*/ */
#if defined _core_included #if defined _core_included
#endinput #endinput
#endif #endif
#define _core_included #define _core_included
/**
* Returns the free memory space available to the plugin.
*
* @note This is a debugging function that is not intended for general plugin
* use.
*
* @return Free memory space in bytes
*/
native heapspace(); native heapspace();
/**
* Returns the function index of a public function declared in the plugin.
*
* @param name Function name
*
* @return Function index > 0 on success, -1 if function was not found
* @error If the function name is too long (longer than 63 characters)
* an error will be thrown.
*/
native funcidx(const name[]); native funcidx(const name[]);
/**
* Returns the number of arguments passed into the currently executed function.
*
* @return Number of arguments passed
*/
native numargs(); native numargs();
native getarg(arg, index=0);
native setarg(arg, index=0, value);
/**
* Retrieves an argument value passed into the currently executed function.
*
* @param arg Argument index
* @param index Index to retrieve from the argument (for arrays and strings)
*
* @return Argument value at given index
*/
native getarg(arg, index = 0);
/**
* Sets the value of an argument passed into the currently executed function.
*
* @note This is not equal to assigning a new value to a by-reference argument.
*
* @param arg Argument index
* @param index Index to set in the argument (for arrays and strings)
*/
native setarg(arg, index = 0, value);
/**
* Converts a character to lowercase.
*
* @note This is not UTF8 or locale-safe.
*
* @param c Character to convert
*
* @return Converted character
*/
native tolower(c); native tolower(c);
/**
* Converts a character to uppercase.
*
* @note This is not UTF8 or locale-safe.
*
* @param c Character to convert
*
* @return Converted character
*/
native toupper(c); native toupper(c);
/**
* Swaps the bytes of a value (the lowest byte becomes the highest byte).
*
* @param c Value to swap
*
* @return Byte-swapped value
*/
native swapchars(c); native swapchars(c);
/**
* Returns a random number between 0 and a specified upper bound.
*
* @param max Exclusive upper bound
*
* @return Random value
*/
native random(max); native random(max);
/**
* Returns the smaller of two provided values.
*
* @param value1 Value one
* @param value2 Value two
*
* @return Smaller of the two values
*/
native min(value1, value2); native min(value1, value2);
native max(value1, value2);
native clamp(value, min=cellmin, max=cellmax);
/**
* Returns the bigger of two provided values.
*
* @param value1 Value one
* @param value2 Value two
*
* @return Bigger of the two values
*/
native max(value1, value2);
/**
* Limits a provided value between two specified bounds.
*
* @param value Value to clamp
* @param min Lower bound
* @param max Upper bound
*
* @return The value if it is between the lower and upper bound, min if
* value is below, max if it is above the specified bounds.
*/
native clamp(value, min = cellmin, max = cellmax);
/**
* Returns a value raised to a specified exponent.
*
* @param value Value
* @param exponent Exponent to raise value to
*
* @return Value to the power of exponent
*/
native power(value, exponent); native power(value, exponent);
/**
* Returns the approximated square root of a value.
*
* @note This uses a simple successice approximation algorithm (continuously
* dividing the value) and only deals with integers, this makes it very
* imprecise.
*
* @param value Value
*
* @return Square root of the value
*/
native sqroot(value); native sqroot(value);
native time(&hour=0,&minute=0,&second=0); /**
native date(&year=0,&month=0,&day=0); * Retrieves the current time in hours, minutes and seconds.
*
* @param hour Variable to store hours in
* @param minute Variable to store minutes in
* @param second Variable to store seconds in
*
* @return Unix timestamp
*/
native time(&hour = 0, &minute = 0, &second = 0);
native tickcount(&granularity=0); /**
* Retrieves the current date in year, month and day.
*
* @param hour Variable to store year in
* @param minute Variable to store month in
* @param second Variable to store day in
*
* @noreturn
*/
native date(&year = 0, &month = 0, &day = 0);
/**
* Returns the elapsed CPU seconds.
*
* @note This is a debugging function that is not intended for general plugin
* use.
* @note This uses the C clock() function internally and comes with all its
* drawbacks attached.
*
* @param granularity Unused
*
* @return Number of CPU seconds elapsed
*/
native tickcount(&granularity = 0);
/**
* Returns the absolute value of a number.
*
* @param x Integral value
*
* @return Absolute value of x (x if it is greater than 0, -x otherwise)
*/
stock abs(x) stock abs(x)
{ {
return x > 0 ? x : -x; return x > 0 ? x : -x;

299
plugins/include/csstats.inc
View File

@ -8,62 +8,271 @@
// https://alliedmods.net/amxmodx-license // https://alliedmods.net/amxmodx-license
#if defined _csstats_included #if defined _csstats_included
#endinput #endinput
#endif #endif
#define _csstats_included #define _csstats_included
/* Gets stats from given weapon index. If wpnindex is 0 /**
* then the stats are from all weapons. If weapon has not been used function * Retrieves the client's current weapon statistics.
* returns 0 in other case 1. Fields in stats are: *
* 0 - kills * @note For a list of default CS weapon ids see the CSW_* constants in
* 1 - deaths * amxconst.inc, this function also works on custom weapons.
* 2 - headshots * @note For a list of possible body hitplaces see the HIT_* constants in
* 3 - teamkilling * amxconst.inc
* 4 - shots * @note The fields in the statistics are:
* 5 - hits * 0 - Kills
* 6 - damage * 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
*
* @param index Client index
* @param wpnindex Weapon id, or 0 to retrieve total statistics across all
* weapons
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
*
* @return 1 on success, 0 if no statistics are available for the weapon
* id
* @error If an invalid client index or weapon id is provided, an
* error will be thrown.
*/
native get_user_wstats(index, wpnindex, stats[8], bodyhits[8]);
* For body hits fields see amxconst.inc. */ /**
native get_user_wstats(index,wpnindex,stats[8],bodyhits[8]); * Retrieves the client's weapon statistics from the current round.
*
* @note For a list of default CS weapon ids see the CSW_* constants in
* amxconst.inc, this function also works on custom weapons.
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
*
* @param index Client index
* @param wpnindex Weapon id, or 0 to retrieve total statistics across all
* weapons
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
*
* @return 1 on success, 0 if no statistics are available for the
* weapon id
* @error If an invalid client index or weapon id is provided, an
* error will be thrown.
*/
native get_user_wrstats(index, wpnindex, stats[8], bodyhits[8]);
/* Gets round stats from given weapon index.*/ /**
native get_user_wrstats(index,wpnindex,stats[8],bodyhits[8]); * Retrieves the client's weapon statistics from the permanent storage on the
* server.
*
* @note The permanent storage is updated on every respawn or client disconnect.
* @note Player rank is determined by the customizable "get_score" function in
* "data/csstats.amxx". By default it uses the difference of kills to
* deaths/teamkills.
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
* 7 - Rank
*
* @param index Client index
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
*
* @return Players rank > 0 on success, or 0 if player is not ranked
* and no statistics are available
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native get_user_stats(index, stats[8], bodyhits[8]);
/* Gets overall stats which are stored in file on server /**
* and updated on every respawn or user disconnect. * Retrieves the client's statistics from the current round.
* Function returns the position in stats by diff. kills to deaths. */ *
native get_user_stats(index,stats[8],bodyhits[8]); * @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
*
* @param index Client index
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
*
* @return 1 on success, 0 if no statistics are available
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native get_user_rstats(index, stats[8], bodyhits[8]);
/* Gets round stats of player. */ /**
native get_user_rstats(index,stats[8],bodyhits[8]); * Retrieves the client's statistics inflicted upon another client from the
* current round.
*
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
*
* @param index Client index
* @param victim Victim client index, or 0 to retrieve the statistics against
* all victims
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
* @param wpnname Optional buffer to copy last used weapon name to
* @param len Maximum buffer size
*
* @return 1 on success, 0 if no statistics are available against the
* specified victim
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native get_user_vstats(index, victim, stats[8], bodyhits[8], wpnname[] = "", len = 0);
/* Gets stats with which user have killed/hurt his victim. If victim is 0 /**
* then stats are from all victims. If victim has not been hurt, function * Retrieves the client's statistics received from another client from the
* returns 0 in other case 1. User stats are reset on his respawn. */ * current round.
native get_user_vstats(index,victim,stats[8],bodyhits[8],wpnname[]="",len=0); *
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
*
* @param index Client index
* @param wpnindex Attacker client index, or 0 to retrieve the statistics from
* all attackers
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
* @param wpnname Optional buffer to copy last used weapon name to
* @param len Maximum buffer size
*
* @return 1 on success, 0 if no statistics are available against the
* specified attacker
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native get_user_astats(index, wpnindex, stats[8], bodyhits[8], wpnname[] = "", len = 0);
/* Gets stats with which user have been killed/hurt. If killer is 0 /**
* then stats are from all attacks. If killer has not hurt user, function * Resets the current round weapon, attacker and victim statistics.
* returns 0 in other case 1. User stats are reset on his respawn. */ *
native get_user_astats(index,wpnindex,stats[8],bodyhits[8],wpnname[]="",len=0); * @param index Client index
*
/* Resets life, weapon, victims and attackers user stats. */ * @noreturn
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native reset_user_wstats(index); native reset_user_wstats(index);
/* Gets overall stats which stored in stats.dat file in amx folder /**
* and updated on every mapchange or user disconnect. * Retrieves statistics from the permanent storage on the server via iterative,
* Function returns next index of stats entry or 0 if no more exists. */ * incremental access.
native get_stats(index,stats[8],bodyhits[8],name[],len,authid[] = "",authidlen = 0); *
* @note The permanent storage is updated on every respawn or client disconnect.
* @note Player rank is determined by the customizable "get_score" function in
* "data/csstats.amxx". By default it uses the difference of kills to
* deaths/teamkills.
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
* @note The fields in the statistics are:
* 0 - Kills
* 1 - Deaths
* 2 - Headshots
* 3 - Teamkills
* 4 - Shots
* 5 - Hits
* 6 - Damage
* 7 - Rank
*
* @param index Rank index
* @param stats Buffer to copy statistics to
* @param bodyhits Buffer to copy body hits to
* @param name Buffer to copy client name to
* @param len Maximum name buffer size
* @param authid Buffer to copy client auth id to
* @param authidlen Maximum authid buffer size
*
* @return Next rank index (> 0 and > index), or 0 if no more
* statistics exist
*/
native get_stats(index, stats[8], bodyhits[8], name[], len, authid[] = "", authidlen = 0);
/* Returns number of all entries in stats. */ /**
* Returns the number of all entries in the permanent statistics storage.
*
* @return Number of entries in statistics storage
*/
native get_statsnum(); native get_statsnum();
/* /**
* new stats: * Retrieves the client's objective statistics from the permanent storage.
* 0 - total defusions *
* 1 - bomb defused * @note The permanent storage is updated on every respawn or client disconnect.
* 2 - bomb plants * @note The fields in the statistics are:
* 3 - bomb explosions * 0 - total defusions
*/ * 1 - bomb defused
native get_user_stats2(index,stats[4]); * 2 - bomb plants
native get_stats2(index,stats[4],authid[] = "",authidlen = 0); * 3 - bomb explosions
*
* @param index Client index
* @param stats Buffer to copy statistics to
*
* @return Players rank > 0 on success, or 0 if player is not ranked
* and no statistics are available
* @error If an invalid client index is provided, an error will be
* thrown.
*/
native get_user_stats2(index, stats[4]);
/**
* Retrieves objective statistics from the permanent storage on the server via
* iterative, incremental access.
*
* @note The permanent storage is updated on every respawn or client disconnect.
* @note The fields in the statistics are:
* 0 - total defusions
* 1 - bomb defused
* 2 - bomb plants
* 3 - bomb explosions
*
* @param index Client index
* @param stats Buffer to copy statistics to
* @param authid Buffer to copy client auth id to
* @param authidlen Maximum authid buffer size
*
* @return Next rank index (> 0 and > index), or 0 if no more
* statistics exist
*/
native get_stats2(index, stats[4], authid[] = "", authidlen = 0);

1321
plugins/include/cstrike.inc
View File

File diff suppressed because it is too large Load Diff

276
plugins/include/csx.inc
View File

@ -12,7 +12,7 @@
// //
#if defined _csx_included #if defined _csx_included
#endinput #endinput
#endif #endif
#define _csx_included #define _csx_included
@ -27,65 +27,237 @@
#pragma library csx #pragma library csx
#endif #endif
/* /**
* Forwards * Map objective flags returned by get_map_objectives().
*/ */
/* Function is called after player to player attacks ,
* if players were damaged by teammate TA is set to 1 */
forward client_damage(attacker,victim,damage,wpnindex,hitplace,TA);
/* Function is called after player death ,
* if player was killed by teammate TK is set to 1 */
forward client_death(killer,victim,wpnindex,hitplace,TK);
forward grenade_throw( index,greindex,wId );
forward bomb_planting(planter);
forward bomb_planted(planter);
forward bomb_explode(planter,defuser);
forward bomb_defusing(defuser);
forward bomb_defused(defuser);
/************* Shared Natives Start ********************************/
/* Custom Weapon Support */
/* function will return index of new weapon */
native custom_weapon_add( const wpnname[],melee = 0,const logname[]="" );
/* Function will pass damage done by this custom weapon to stats module and other plugins */
native custom_weapon_dmg( weapon, att, vic, damage, hitplace=0 );
/* Function will pass info about custom weapon shot to stats module */
native custom_weapon_shot( weapon,index ); // weapon id , player id
/* function will return 1 if true */
native xmod_is_melee_wpn(wpnindex);
/* Returns weapon name. */
native xmod_get_wpnname(wpnindex,name[],len);
/* Returns weapon logname. */
native xmod_get_wpnlogname(wpnindex,name[],len);
/* Returns weapons array size */
native xmod_get_maxweapons();
/* Returns stats array size */
native xmod_get_stats_size();
/************* Shared Natives End ********************************/
enum MapObjective enum MapObjective
{ {
MapObjective_Bomb = (1<<0), MapObjective_Bomb = (1<<0),
MapObjective_Hostage = (1<<1), MapObjective_Hostage = (1<<1),
MapObjective_Vip = (1<<2), MapObjective_Vip = (1<<2),
MapObjective_Escape = (1<<3), MapObjective_Escape = (1<<3),
}; };
/** /**
* Gets current map objectives. * Called after a client attacks another client.
* *
* @return Returns a bits sum if objectives are found, otherwise 0. * @note For a list of possible weapon ids see the CSW_* constants in
* See MapObjective_* constants. * amxconst.inc
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
*
* @param attacker Attacker client index
* @param victim Victim client index
* @param damage Damage dealt to victim
* @param wpnindex Weapon id
* @param hitplace Body hitplace
* @param ta If nonzero the attack was a team attack
*
* @noreturn
*/
forward client_damage(attacker, victim, damage, wpnindex, hitplace, TA);
/**
* Called after a client death.
*
* @note For a list of possible weapon ids see the CSW_* constants in
* amxconst.inc
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
*
* @param attacker Attacker client index
* @param victim Victim client index
* @param wpnindex Weapon id
* @param hitplace Body hitplace
* @param tk If nonzero the death was a teamkill
*
* @noreturn
*/
forward client_death(killer, victim, wpnindex, hitplace, TK);
/**
* Called after a grenade was thrown.
*
* @note Weapon id is one of CSW_HEGRENADE, CSW_SMOKEGRENADE or CSW_FLASHBANG.
*
* @param index Client index
* @param greindex Grenade entity index
* @param wId Weapon id
*
* @noreturn
*/
forward grenade_throw(index, greindex, wId);
/**
* Called after a bomb plant attempt has started.
*
* @param planter Planter client index
*
* @noreturn
*/
forward bomb_planting(planter);
/**
* Called after a bomb plant has finished.
*
* @param planter Planter client index
*
* @noreturn
*/
forward bomb_planted(planter);
/**
* Called when the bomb exploded.
*
* @param planter Planter client index
* @param defuser Defuser client index, if applicable
*
* @noreturn
*/
forward bomb_explode(planter, defuser);
/**
* Called after a bomb defuse attempt has started.
*
* @param defuser Defuser client index
*
* @noreturn
*/
forward bomb_defusing(defuser);
/**
* Called after a bomb defuse has finished.
*
* @param defuser Defuser client index
*
* @noreturn
*/
forward bomb_defused(defuser);
/**
* @section Shared natives
*/
/**
* Adds a custom weapon to the stats system.
*
* @note The weapon name should be the full display name of the gun such as
* "Desert Eagle" while the logname should be "weapon_deagle".
*
* @param wpnname Full weapon name
* @param melee If nonzero the weapon will be considered a melee weapon
* @param logname Weapon short name
*
* @return Cusom weapon id (>0) on success, 0 if no more custom weapons
* can be added
*/
native custom_weapon_add(const wpnname[], melee = 0, const logname[] = "");
/**
* Triggers a damage event on a custom weapon, adding it to the internal stats.
*
* @note This will also call the client_damage() and client_kill() forwards if
* applicable.
* @note For a list of possible body hitplaces see the HIT_* constants in
* amxconst.inc
*
* @param weapon Custom weapon id
* @param att Attacker client index
* @param vic Victim client index
* @param damage Damage dealt
* @param hitplace Optional body hitplace
*
* @noreturn
* @error If the weapon id is not a custom weapon, an invalid client
* index, damage value or hitplace is provided, an error will
* be thrown.
*/
native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0);
/**
* Adds a shot event on a custom weapon to the internal stats.
*
* @param weapon Custom weapon id
* @param index Client index
*
* @noreturn
* @error If the weapon id is not a custom weapon or an invalid client
* index is provided, an error will be thrown.
*/
native custom_weapon_shot(weapon, index);
/**
* Returns if the weapon is considered a melee weapon.
*
* @note For a list of default CS weapon ids see the CSW_* constants in
* amxconst.inc, this function also works on custom weapons.
* @note For the default CS weapons this obviously returns true only for
* CSW_KNIFE.
*
* @param wpnindex Weapon id
*
* @return 1 if weapon is a melee weapon, 0
* @error If an invalid weapon id is provided an error will be thrown.
*/
native xmod_is_melee_wpn(wpnindex);
/**
* Retrieves the full weapon name of a weapon id.
*
* @note For a list of default CS weapon ids see the CSW_* constants in
* amxconst.inc, this function also works on custom weapons.
* @note For the default CS weapons this obviously returns true only for
* CSW_KNIFE.
*
* @param wpnindex Weapon id
* @param name Buffer to copy weapon name to
* @param len Maximmum buffer size
*
* @return Number of cells written to buffer
* @error If an invalid weapon id is provided an error will be thrown.
*/
native xmod_get_wpnname(wpnindex, name[], len);
/**
* Retrieves the weapon log name of a weapon id.
*
* @note For a list of default CS weapon ids see the CSW_* constants in
* amxconst.inc, this function also works on custom weapons.
* @note For the default CS weapons this obviously returns true only for
* CSW_KNIFE.
*
* @param wpnindex Weapon id
* @param name Buffer to copy weapon log name to
* @param len Maximmum buffer size
*
* @return Number of cells written to buffer
* @error If an invalid weapon id is provided an error will be thrown.
*/
native xmod_get_wpnlogname(wpnindex, name[], len);
/**
* Returns the maximum amount of weapons that the stats system supports.
*
* @return Maximum number of weapons supported
*/
native xmod_get_maxweapons();
/**
* Returns the number of stats tracked by the stats system.
*
* @return Number of stats tracked
*/
native xmod_get_stats_size();
/**
* @endsection Shared natives
*/
/**
* Returns the current map's objectives as a bitflag value.
*
* @note For a list of possible map objective flags see the MapObjective enum.
*
* @return Bitflag value of map objectives
*/ */
native MapObjective:get_map_objectives(); native MapObjective:get_map_objectives();

281
plugins/include/cvars.inc
View File

@ -8,44 +8,61 @@
// https://alliedmods.net/amxmodx-license // https://alliedmods.net/amxmodx-license
#if defined _cvars_included #if defined _cvars_included
#endinput #endinput
#endif #endif
#define _cvars_included #define _cvars_included
/** /**
* CVAR flags for create_cvar() * CVAR flags for create_cvar() and register_cvar().
*/ */
#define FCVAR_NONE 0 /* No flags */ #define FCVAR_NONE 0 // No special behavior
#define FCVAR_ARCHIVE 1 /* Set to cause it to be saved to vars.rc */ #define FCVAR_ARCHIVE 1 // Cvar will be saved to vars.rc Set to cause it to be saved to vars.rc
#define FCVAR_USERINFO 2 /* Changes the client's info string */ #define FCVAR_USERINFO 2 // Cvar changes the client's info string
#define FCVAR_SERVER 4 /* Notifies players when changed */ #define FCVAR_SERVER 4 // Clients get notified when cvar value is changed
#define FCVAR_EXTDLL 8 /* Defined by external DLL */ #define FCVAR_EXTDLL 8 // Defined by an external DLL
#define FCVAR_CLIENTDLL 16 /* Defined by the client dll */ #define FCVAR_CLIENTDLL 16 // Defined by the client DLL
#define FCVAR_PROTECTED 32 /* It's a server cvar, but we don't send the data since it's a password, etc. Sends 1 if it's not bland/zero, 0 otherwise as value */ #define FCVAR_PROTECTED 32 // Cvar value is masked from outside access, should be used for sensitive cvars like passwords
#define FCVAR_SPONLY 64 /* This cvar cannot be changed by clients connected to a multiplayer server. */ #define FCVAR_SPONLY 64 // Cvar can't be changed by clients connected to a multiplayer server
#define FCVAR_PRINTABLEONLY 128 /* This cvar's string cannot contain unprintable characters ( e.g., used for player name etc ). */ #define FCVAR_PRINTABLEONLY 128 // The cvar string value can not contain unprintable characters
#define FCVAR_UNLOGGED 256 /* If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */ #define FCVAR_UNLOGGED 256 // If the cvar is FCVAR_SERVER, don't log changes to a file/the console
#define FCVAR_NOEXTRAWHITEPACE 512 /* Strip trailing/leading white space from this cvar */ #define FCVAR_NOEXTRAWHITEPACE 512 // Automatically strips trailing/leading white space from the string value
/**
* Cvar bound constants used with [get|set]_pcvar_bounds().
*/
enum CvarBounds
{
CvarBound_Upper = 0,
CvarBound_Lower
};
/** /**
* Creates a new cvar for the engine. * Creates a new cvar for the engine.
* *
* @note This has the same effect as register_cvar but provides more options. * @note This has the same effect as register_cvar() but provides more options.
* @note For a list of possible cvar flags see FCVAR_* constants above. * @note For a list of possible cvar flags see FCVAR_* constants above.
* @note If an already existing cvar is registered it will not be duplicated. * @note If an already existing cvar is registered it will not be duplicated.
* The default value is only set when the cvar is registered for the very
* first time since the server was started. Cvar bounds are overwritten
* by the create_cvar() call just as if they were re-set using
* set_pcvar_bounds().
* @note The returned cvar pointer should be used with the get_pcvar_* and * @note The returned cvar pointer should be used with the get_pcvar_* and
* set_pcvar_* set of functions. * set_pcvar_* set of functions.
* *
* @param name Cvar name * @param name Cvar name
* @param string Default cvar value * @param string Default cvar value
* @param flags Optional bitsum of flags specifying cvar behavior * @param flags Optional bitsum of flags specifying cvar behavior
* @param description Optional description of the cvar * @param description Optional description of the cvar
* @param has_min Optional boolean that specifies if the cvar has a minimum value * @param has_min Optional boolean that specifies if the cvar has a
* @param min_val Minimum floating point value * minimum value
* @param has_max Optional boolean that specifies if the cvar has a maximum value * @param min_val Minimum floating point value
* @param max_val Maximum floating point value * @param has_max Optional boolean that specifies if the cvar has a
* maximum value
* @param max_val Maximum floating point value
* *
* @return Unique cvar pointer * @return Unique cvar pointer
* @error If invalid bounds are provided (min_val > max_val or
* vice versa), an error will be thrown.
*/ */
native create_cvar(const name[], const string[], flags = FCVAR_NONE, const description[] = "", bool:has_min = false, Float:min_val = 0.0, bool:has_max = false, Float:max_val = 0.0); native create_cvar(const name[], const string[], flags = FCVAR_NONE, const description[] = "", bool:has_min = false, Float:min_val = 0.0, bool:has_max = false, Float:max_val = 0.0);
@ -55,6 +72,8 @@ native create_cvar(const name[], const string[], flags = FCVAR_NONE, const descr
* @note Deprecated. Consider to use create_cvar for more options. * @note Deprecated. Consider to use create_cvar for more options.
* @note For a list of possible cvar flags see FCVAR_* constants in amxconst.inc * @note For a list of possible cvar flags see FCVAR_* constants in amxconst.inc
* @note If an already existing cvar is registered it will not be duplicated. * @note If an already existing cvar is registered it will not be duplicated.
* The default value is only set when the cvar is registered for the very
* first time since the server was started.
* @note The returned cvar pointer should be used with the get_pcvar_* and * @note The returned cvar pointer should be used with the get_pcvar_* and
* set_pcvar_* set of functions. * set_pcvar_* set of functions.
* *
@ -65,7 +84,7 @@ native create_cvar(const name[], const string[], flags = FCVAR_NONE, const descr
* *
* @return Unique cvar pointer * @return Unique cvar pointer
*/ */
native register_cvar(const name[], const string[], flags = FCVAR_NONE, Float:fvalue=0.0); native register_cvar(const name[], const string[], flags = FCVAR_NONE, Float:fvalue = 0.0);
/** /**
* Returns if a cvar is registered on the server. * Returns if a cvar is registered on the server.
@ -79,8 +98,9 @@ native cvar_exists(const cvar[]);
/** /**
* Returns the cvar pointer of the specified cvar. * Returns the cvar pointer of the specified cvar.
* *
* @note A pointer is also returned by register_cvar(). Plugins can (and should) * @note A pointer is also returned by register_cvar() and create_cvar().
* retrieve and use pointers for already existing mod cvars. * Plugins can (and should) retrieve and use pointers for already existing
* mod cvars.
* *
* @param cvar Cvar name to find * @param cvar Cvar name to find
* *
@ -93,41 +113,45 @@ native get_cvar_pointer(const cvar[]);
* *
* @note Changing the cvar value from within this forward can lead to infinite * @note Changing the cvar value from within this forward can lead to infinite
* recursion and should be avoided. * recursion and should be avoided.
* @note Callback will be called in the following manner: * @note The callback will be called in the following manner:
* *
* public cvar_change_callback(pcvar, const old_value[], const new_value[]) * public cvar_change_callback(pcvar, const old_value[], const new_value[])
* *
* pcvar - Pointer to cvar that was changed * pcvar - Pointer to cvar that was changed
* old_value - String containing the value of the cvar before it was changed * old_value - Buffer containing the previous value of the cvar
* new_value - String containing the new value of the cvar * new_value - Buffer containing the new value of the cvar
* *
* The return value is ignored * The return value is ignored
* *
* @param pcvar Pointer to cvar * @param pcvar Pointer to cvar
* @param callback Name of callback function * @param callback Name of callback function
* *
* @return Callback handle that can be used with [disable|enable]_cvar_hook * @return Callback handle that can be used with
* @error Invalid cvar pointer or invalid callback function * [disable|enable]_cvar_hook
* @error If an invalid cvar pointer or callback function is provided,
* an error will be thrown.
*/ */
native cvarhook:hook_cvar_change(pcvar, const callback[]); native cvarhook:hook_cvar_change(pcvar, const callback[]);
/** /**
* Stops a cvar hook forward from triggering. * Disables a cvar hook, stopping it from being called.
* *
* @note Use the handle returned by hook_cvar_change as the parameter here. * @note Use the handle returned by hook_cvar_change as the parameter here.
* *
* @param handle Forward to stop * @param handle Forward to disable
* @error Invalid hook handle * @error If an invalid hook handle is provided, an error will be
* thrown.
*/ */
native disable_cvar_hook(cvarhook:handle); native disable_cvar_hook(cvarhook:handle);
/** /**
* Starts a cvar hook forward back up. * Enables a cvar hook, restoring it to being called.
* *
* @note Use the handle returned by hook_cvar_change as the parameter here. * @note Use the handle returned by hook_cvar_change as the parameter here.
* *
* @param handle Forward to back up * @param handle Forward to enable
* @error Invalid hook handle * @error If an invalid hook handle is provided, an error will be
* thrown.
*/ */
native enable_cvar_hook(cvarhook:handle); native enable_cvar_hook(cvarhook:handle);
@ -135,14 +159,13 @@ native enable_cvar_hook(cvarhook:handle);
* Returns flags of a cvar. The cvar is accessed by name. * Returns flags of a cvar. The cvar is accessed by name.
* *
* @note For a list of possible flags see the FCVAR_* constants in amxconst.inc * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent get_pcvar_flags() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the get_pcvar_flags function.
* *
* @param cvar Cvar name to retrieve flags from * @param cvar Cvar name to retrieve flags from
* *
* @return 1 on success, 0 if cvar does not exist or is not permitted * @return Flag value
*/ */
native get_cvar_flags(const cvar[]); native get_cvar_flags(const cvar[]);
@ -154,10 +177,9 @@ native get_cvar_flags(const cvar[]);
* @note For a list of possible flags see the FCVAR_* constants in amxconst.inc * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
* @note This function just adds the flags using a bitwise-or operation. After * @note This function just adds the flags using a bitwise-or operation. After
* it has run the flags may not exactly equal the specified bitflag sum. * it has run the flags may not exactly equal the specified bitflag sum.
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent set_pcvar_flags() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the set_pcvar_flags function.
* *
* @param cvar Cvar name to remove flags from * @param cvar Cvar name to remove flags from
* @param flags Bitflag sum of flags to set * @param flags Bitflag sum of flags to set
@ -173,11 +195,8 @@ native set_cvar_flags(const cvar[], flags);
* and "sv_cheats" cvars. * and "sv_cheats" cvars.
* @note For a list of possible flags see the FCVAR_* constants in amxconst.inc * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc
* @note This function removes the flags using a bitwise-and operation. * @note This function removes the flags using a bitwise-and operation.
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the set_pcvar_flags() function should be used instead.
* of processing time, especially if many cvars have been registered. For
* a vastly superior alternative look at the set_pcvar_flags function.
*
* *
* @param cvar Cvar name to remove flags from * @param cvar Cvar name to remove flags from
* @param flags Bitflag sum of flags to remove * @param flags Bitflag sum of flags to remove
@ -189,10 +208,9 @@ native remove_cvar_flags(const cvar[], flags=-1);
/** /**
* Gets a string value from a cvar. The cvar is accessed by name. * Gets a string value from a cvar. The cvar is accessed by name.
* *
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent get_pcvar_string() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the get_pcvar_string function.
* *
* @param cvar Cvar name to retrieve value from * @param cvar Cvar name to retrieve value from
* @param output Buffer to copy cvar value to * @param output Buffer to copy cvar value to
@ -205,10 +223,9 @@ native get_cvar_string(const cvarname[], output[], iLen);
/** /**
* Sets a cvar to a given string value. The cvar is accessed by name. * Sets a cvar to a given string value. The cvar is accessed by name.
* *
* @note Accessing a cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent set_pcvar_string() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the set_pcvar_string function.
* *
* @param cvar Cvar name to set value of * @param cvar Cvar name to set value of
* @param value Value to set cvar to * @param value Value to set cvar to
@ -220,10 +237,9 @@ native set_cvar_string(const cvar[], const value[]);
/** /**
* Returns a floating value from a cvar. The cvar is accessed by name. * Returns a floating value from a cvar. The cvar is accessed by name.
* *
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent get_pcvar_float() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the get_pcvar_float function.
* *
* @param cvarname Cvar name to retrieve value from * @param cvarname Cvar name to retrieve value from
* *
@ -234,10 +250,9 @@ native Float:get_cvar_float(const cvarname[]);
/** /**
* Sets a cvar to a given float value. The cvar is accessed by name. * Sets a cvar to a given float value. The cvar is accessed by name.
* *
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent set_pcvar_float() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the set_pcvar_float function.
* *
* @param cvar Cvar name to set value of * @param cvar Cvar name to set value of
* @param value Value to set cvar to * @param value Value to set cvar to
@ -249,10 +264,9 @@ native set_cvar_float(const cvar[], Float:value);
/** /**
* Returns an integer value from a cvar. The cvar is accessed by name. * Returns an integer value from a cvar. The cvar is accessed by name.
* *
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent get_pcvar_num() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the get_pcvar_num function.
* *
* @param cvarname Cvar name to retrieve value from * @param cvarname Cvar name to retrieve value from
* *
@ -263,10 +277,9 @@ native get_cvar_num(const cvarname[]);
/** /**
* Sets a cvar to a given integer value. The cvar is accessed by name. * Sets a cvar to a given integer value. The cvar is accessed by name.
* *
* @note Accessing a Cvar by name requires this function to walk through the * @note Accessing a Cvar by name is slower than direct pointer access, which is
* engine's cvar list every time, which can result in a considerable waste * why the otherwise equivalent set_pcvar_num() function should be used
* of processing time, especially if many cvars have been registered. For * instead.
* a vastly superior alternative look at the set_pcvar_num function.
* *
* @param cvar Cvar name to set value of * @param cvar Cvar name to set value of
* @param value Value to set cvar to * @param value Value to set cvar to
@ -283,7 +296,8 @@ native set_cvar_num(const cvarname[], value);
* @param pcvar Pointer to cvar to retrieve flags from * @param pcvar Pointer to cvar to retrieve flags from
* *
* @return 1 on success, 0 if cvar pointer is invalid * @return 1 on success, 0 if cvar pointer is invalid
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native get_pcvar_flags(pcvar); native get_pcvar_flags(pcvar);
@ -298,7 +312,8 @@ native get_pcvar_flags(pcvar);
* @param flags Bitflag sum of flags to set * @param flags Bitflag sum of flags to set
* *
* @return 1 on success, 0 if cvar does not exist or is not permitted * @return 1 on success, 0 if cvar does not exist or is not permitted
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native set_pcvar_flags(pcvar, flags); native set_pcvar_flags(pcvar, flags);
@ -308,7 +323,8 @@ native set_pcvar_flags(pcvar, flags);
* @param pcvar Pointer to cvar to retrieve value from * @param pcvar Pointer to cvar to retrieve value from
* *
* @return Cvar value, converted to int * @return Cvar value, converted to int
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native get_pcvar_num(pcvar); native get_pcvar_num(pcvar);
@ -318,7 +334,8 @@ native get_pcvar_num(pcvar);
* @param pcvar Pointer to cvar to retrieve value from * @param pcvar Pointer to cvar to retrieve value from
* *
* @return Cvar value, converted to bool * @return Cvar value, converted to bool
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native bool:get_pcvar_bool(pcvar); native bool:get_pcvar_bool(pcvar);
@ -329,7 +346,8 @@ native bool:get_pcvar_bool(pcvar);
* @param num Value to set cvar to * @param num Value to set cvar to
* *
* @noreturn * @noreturn
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native set_pcvar_num(pcvar, num); native set_pcvar_num(pcvar, num);
@ -340,7 +358,8 @@ native set_pcvar_num(pcvar, num);
* @param num Value to set cvar to * @param num Value to set cvar to
* *
* @noreturn * @noreturn
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native set_pcvar_bool(pcvar, bool:num); native set_pcvar_bool(pcvar, bool:num);
@ -350,7 +369,8 @@ native set_pcvar_bool(pcvar, bool:num);
* @param pcvar Pointer to cvar to retrieve value from * @param pcvar Pointer to cvar to retrieve value from
* *
* @return Cvar value, converted to float * @return Cvar value, converted to float
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native Float:get_pcvar_float(pcvar); native Float:get_pcvar_float(pcvar);
@ -361,7 +381,8 @@ native Float:get_pcvar_float(pcvar);
* @param num Value to set cvar to * @param num Value to set cvar to
* *
* @noreturn * @noreturn
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native set_pcvar_float(pcvar, Float:num); native set_pcvar_float(pcvar, Float:num);
@ -373,7 +394,8 @@ native set_pcvar_float(pcvar, Float:num);
* @param maxlen Maximum size of the buffer * @param maxlen Maximum size of the buffer
* *
* @return Number of cells written to buffer. * @return Number of cells written to buffer.
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native get_pcvar_string(pcvar, string[], maxlen); native get_pcvar_string(pcvar, string[], maxlen);
@ -384,40 +406,36 @@ native get_pcvar_string(pcvar, string[], maxlen);
* @param string Value to set cvar to * @param string Value to set cvar to
* *
* @noreturn * @noreturn
* @error If an invalid cvar pointer is specified, an error is thrown. * @error If an invalid cvar pointer is provided, an error will be
* thrown.
*/ */
native set_pcvar_string(pcvar, const string[]); native set_pcvar_string(pcvar, const string[]);
/** /**
* Cvar bound values used with get/set_pcvar_bounds() * Retrieves the specified value boundary of a cvar.
*/
enum CvarBounds
{
CvarBound_Upper = 0,
CvarBound_Lower
};
/**
* Retrieves the specified value bounds of a cvar.
* *
* @param pcvar Pointer to cvar * @param pcvar Pointer to cvar
* @param type Type of bound to retrieve, CvarBound_Lower or CvarBound_Upper * @param type Type of boundary to retrieve
* @param value Variable to store the specified bound to * @param value Variable to store the specified boundary to
* *
* @return True if the cvar has the specified bound set, false otherwise. * @return True if the cvar has a boundary set, false otherwise
* @error If an invalid cvar pointer or CvarBounds value, an error is thrown. * @error If an invalid cvar pointer or boundary type is provided,
* an error will be thrown.
*/ */
native bool:get_pcvar_bounds(pcvar, CvarBounds:type, &Float:value); native bool:get_pcvar_bounds(pcvar, CvarBounds:type, &Float:value);
/** /**
* Sets the specified bounds of a cvar. * Sets the specified boundary of a cvar.
* *
* @param pcvar Pointer to cvar * @param pcvar Pointer to cvar
* @param type Type of bound to set, CvarBound_Lower or CvarBound_Upper * @param type Type of boundary to set
* @param set If set to true, cvar will use specified bound. If false, bound will be removed * @param set If true the cvar boundary will be set, otherwise it will be
* @param value Floating point value to use as the specified bound * removed (value is ignored)
* @param value Floating point value to use as the boundary
* *
* @error If an invalid cvar pointer or CvarBounds value, an error is thrown. * @noreturn
* @error If an invalid cvar pointer or boundary type is provided, an
* error will be thrown.
*/ */
native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0); native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0);
@ -432,7 +450,9 @@ native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0);
* @param pcvar Pointer to cvar * @param pcvar Pointer to cvar
* @param var Global variable to keep updated * @param var Global variable to keep updated
* *
* @error Invalid cvar pointer, invalid provided variable or cvar/variable already binded. * @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/ */
native bind_pcvar_num(pcvar, &any:var); native bind_pcvar_num(pcvar, &any:var);
@ -447,7 +467,9 @@ native bind_pcvar_num(pcvar, &any:var);
* @param pcvar Pointer to cvar * @param pcvar Pointer to cvar
* @param var Global variable to keep updated * @param var Global variable to keep updated
* *
* @error Invalid cvar pointer, invalid provided variable or cvar/variable already binded. * @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/ */
native bind_pcvar_float(pcvar, &Float:var); native bind_pcvar_float(pcvar, &Float:var);
@ -463,7 +485,9 @@ native bind_pcvar_float(pcvar, &Float:var);
* @param var Global array to keep updated * @param var Global array to keep updated
* @param varlen Maximum length of string array * @param varlen Maximum length of string array
* *
* @error Invalid cvar pointer, invalid provided variable or cvar/variable already binded. * @noreturn
* @error If an invalid cvar pointer or variable is provided, an error
* will be thrown.
*/ */
native bind_pcvar_string(pcvar, any:var[], varlen); native bind_pcvar_string(pcvar, any:var[], varlen);
@ -475,13 +499,14 @@ native bind_pcvar_string(pcvar, any:var[], varlen);
native get_plugins_cvarsnum(); native get_plugins_cvarsnum();
/** /**
* Retrieves information about a plugin-registered cvar. * Retrieves information about a plugin-registered cvar via iterative access.
* *
* @note The returned cvar pointer should be used with the get_pcvar_* and * @note The returned cvar pointer should be used with the get_pcvar_* and
* set_pcvar_* set of functions. * set_pcvar_* set of functions.
* @note The cvar index does not equal the cvar pointer. It is the internal
* AMXX id of a cvar, incremented for each registered cvar.
* *
* @param num Cvar index, this does not equal the cvar pointer, it is * @param num Index to retrieve
* the internal index, incremented for each registered cvar
* @param name Buffer to copy cvar name to * @param name Buffer to copy cvar name to
* @param namelen Maximum buffer size * @param namelen Maximum buffer size
* @param flags Variable to store cvar flags to * @param flags Variable to store cvar flags to
@ -492,7 +517,7 @@ native get_plugins_cvarsnum();
* *
* @return 1 on success, 0 if index is invalid * @return 1 on success, 0 if index is invalid
*/ */
native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_handle=0, description[]="", desc_len=0); native get_plugins_cvar(num, name[], namelen, &flags = 0, &plugin_id = 0, &pcvar_handle = 0, description[] = "", desc_len = 0);
/** /**
* Dispatches a client cvar query, allowing the plugin to query for its value on * Dispatches a client cvar query, allowing the plugin to query for its value on
@ -502,10 +527,10 @@ native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_han
* *
* public cvar_query_callback(id, const cvar[], const value[], const param[]) * public cvar_query_callback(id, const cvar[], const value[], const param[])
* *
* id - Client index * id - Client index
* cvar - Cvar queried * cvar - Cvar queried
* value - Cvar value on the client * value - Cvar value on the client
* param - Extra data [optional] * param - Optional extra data
* *
* @param id Client index * @param id Client index
* @param cvar Cvar to query * @param cvar Cvar to query
@ -515,10 +540,8 @@ native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_han
* *
* @noreturn * @noreturn
* @error If the client index is not within the range of 1 to * @error If the client index is not within the range of 1 to
* MaxClients or the client is not connected, an error * MaxClients, the client is not connected, the callback
* will be thrown. * function is invalid or the querying process encounters
* If the callback function is invalid, cvar querying is * a problem, an error will be thrown.
* unavailable or the querying process runs out of memory,
* an error will be thrown.
*/ */
native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[]=""); native query_client_cvar(id, const cvar[], const resultFunc[], paramlen = 0, const params[] = "");

135
plugins/include/datapack.inc
View File

@ -10,129 +10,142 @@
#if defined _datapack_included #if defined _datapack_included
#endinput #endinput
#endif #endif
#define _datapack_included #define _datapack_included
/** /**
* DataPacks are a way to store and move around various types of data in AMX Mod X Scripting. * Datapack tag declaration
* Since some things are not possible in AMX Mod X, such as a function consuming a String, *
* DataPacks help us get these Strings and other items where they need to go. * @note Datapacks provide a way to store and move around arbitrary amounts (and
* types) of data in AMX Mox X. Data is packed into a single cell value -
* the DataPack handle. This handle can be passed around more easily, can
* be returned by functions and can simulate advanced concepts like string
* consummation.
* @note Plugins are responsible for freeing all datapack handles they acquire.
* Failing to free handles will result in the plugin and AMXX leaking
* memory.
*/ */
enum DataPack enum DataPack
{ {
Invalid_DataPack = 0 Invalid_DataPack = 0
}; };
/** /**
* Creates a new data pack. * Creates a new datapack.
* *
* @return A Handle to the data pack. * @return New datapack handle, which must be freed via DestroyDataPack().
*/ */
native DataPack:CreateDataPack(); native DataPack:CreateDataPack();
/** /**
* Packs a normal cell into a data pack. * Packs a cell value into a datapack.
*
* @param pack Datapack handle
* @param cell Cell value to pack
* *
* @param pack Handle to the data pack.
* @param cell Cell to add.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackCell(DataPack:pack, any:cell); native WritePackCell(DataPack:pack, any:cell);
/** /**
* Packs a float into a data pack. * Packs a float value into a datapack.
*
* @param pack Datapack handle
* @param val Float value to pack
* *
* @param pack Handle to the data pack.
* @param val Float to add.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackFloat(DataPack:pack, Float:val); native WritePackFloat(DataPack:pack, Float:val);
/** /**
* Packs a string into a data pack. * Packs a string into a datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param str String to add. * @param str String to pack
* @return Length of copied string. *
* @error Invalid handle. * @return Length of copied string
* @error If an invalid handle is provided, an error will be thrown.
*/ */
native WritePackString(DataPack:pack, const str[]); native WritePackString(DataPack:pack, const str[]);
/** /**
* Reads a cell from a data pack. * Reads a cell from a Datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Cell value. *
* @error Invalid handle, or bounds error. * @return Cell value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/ */
native any:ReadPackCell(DataPack:pack); native any:ReadPackCell(DataPack:pack);
/** /**
* Reads a float from a data pack. * Reads a float from a datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Float value. *
* @error Invalid handle, or bounds error. * @return Float value
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/ */
native Float:ReadPackFloat(DataPack:pack); native Float:ReadPackFloat(datapack:pack);
/** /**
* Reads a string from a data pack. * Reads a string from a Datapack.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param buffer Destination string buffer. * @param buffer Buffer to copy string to
* @param maxlen Maximum length of output string buffer. * @param maxlen Maximum size of buffer
* @return Length of output string. *
* @error Invalid handle, or bounds error. * @return Number of cells written to buffer
* @error If an invalid handle is provided, or not enough data is left
* in the datapack, an error will be thrown.
*/ */
native ReadPackString(DataPack:pack, buffer[], maxlen); native ReadPackString(DataPack:pack, buffer[], maxlen);
/** /**
* Resets the position in a data pack. * Resets the datapack read/write position to the start.
*
* @param pack Datapack handle
* @param clear If true, clears the contained data
* *
* @param pack Handle to the data pack.
* @param clear If true, clears the contained data.
* @noreturn * @noreturn
* @error Invalid handle. * @error If an invalid handle is provided, an error will be thrown.
*/ */
native ResetPack(DataPack:pack, bool:clear=false); native ResetPack(DataPack:pack, bool:clear = false);
/** /**
* Returns the read or write position in a data pack. * Returns the datapack read/write position.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @return Numerical position in the data pack. *
* @error Invalid handle. * @return Position in the datapack
* @error If an invalid handle is provided, an error will be thrown.
*/ */
native GetPackPosition(DataPack:pack); native GetPackPosition(DataPack:pack);
/** /**
* Sets the read/write position in a data pack. * Sets the datapack read/write position.
*
* @note This should only ever be used with (known to be valid) positions
* returned by GetPackPosition(). It is not possible for plugins to safely
* compute datapack positions.
*
* @param pack Datapack handle
* @param position New position to set
* *
* @param pack Handle to the data pack.
* @param position New position to set.
* @noreturn * @noreturn
* @error Invalid handle, or position is beyond the pack bounds. * @error If an invalid handle is provided, or the new position is
* out of datapack bounds, an error will be thrown.
*/ */
native SetPackPosition(DataPack:pack, position); native SetPackPosition(DataPack:pack, position);
/** /**
* Returns whether or not a specified number of bytes from the data pack * Destroys the datapack and frees its memory.
* position to the end can be read.
* *
* @param pack Handle to the data pack. * @param pack Datapack handle
* @param bytes Number of bytes to simulate reading.
* @return True if can be read, false otherwise.
* @error Invalid handle.
*/
native bool:IsPackReadable(DataPack:pack, bytes);
/**
* Disposes of a data pack.
* *
* @param pack Handle to the data pack. * @return True if disposed, false otherwise
* @return True if disposed, false otherwise.
*/ */
native DestroyDataPack(&DataPack:pack); native DestroyDataPack(&DataPack:pack);