From 5f278eee7badecb253c5f492b93435c96c8fc748 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 17 Feb 2015 15:24:14 +0100 Subject: [PATCH 01/10] amxmisc: Documentation updates and additions --- plugins/include/amxmisc.inc | 248 +++++++++++++++++++++++++++++------- 1 file changed, 201 insertions(+), 47 deletions(-) diff --git a/plugins/include/amxmisc.inc b/plugins/include/amxmisc.inc index 289566dd..8c516f0b 100755 --- a/plugins/include/amxmisc.inc +++ b/plugins/include/amxmisc.inc @@ -16,12 +16,35 @@ #include #endif +/** + * Returns if the client has any admin flags set + * + * @param id Client index + * + * @return 1 if client has any admin flags, 0 otherwise + */ stock is_user_admin(id) { new __flags = get_user_flags(id); return (__flags > 0 && !(__flags & ADMIN_USER)); } +/** + * Returns if the user can execute the current command by checking the necessary + * admin flags and parameter count. Displays a denied access message to the user + * if missing privileges or a usage example if too few parameters are provided. + * + * @note This should be used inside of a command forward as it uses read_argc() + * to check the parameter count. + * + * @param id Client index + * @param level Required admin flags + * @param cid Command id + * @param num Required number of parameters + * @param acesssilent If true no denied access message will be printed + * + * @return 1 if access granted and parameters provided, 0 otherwise + */ stock cmd_access(id, level, cid, num, bool:accesssilent = false) { new has_access = 0; @@ -64,6 +87,14 @@ stock cmd_access(id, level, cid, num, bool:accesssilent = false) return 1; } +/** + * Returns if the client has the specified admin flags. + * + * @param id Client index + * @param level Required admin flags + * + * @return 1 if client has the admin flags, 0 otherwise + */ stock access(id, level) { if (level == ADMIN_ADMIN) @@ -78,18 +109,36 @@ stock access(id, level) return (get_user_flags(id) & level); } -/** - * Flags related to cmd_target: - * 1 - obey immunity - * 2 - allow yourself - * 4 - must be alive - * 8 - can't be bot +/** + * cmd_target flags */ -#define CMDTARGET_OBEY_IMMUNITY (1<<0) -#define CMDTARGET_ALLOW_SELF (1<<1) -#define CMDTARGET_ONLY_ALIVE (1<<2) -#define CMDTARGET_NO_BOTS (1<<3) +#define CMDTARGET_OBEY_IMMUNITY (1<<0) // Obey immunity +#define CMDTARGET_ALLOW_SELF (1<<1) // Allow self targeting +#define CMDTARGET_ONLY_ALIVE (1<<2) // Target must be alive +#define CMDTARGET_NO_BOTS (1<<3) // Target can't be a bot +/** + * Processes a generic target pattern and tries to match it to a client based + * on filtering flags. If no unique target is found an appropriate message is + * displayed to the admin. + * + * @note The pattern is first matched case insensitively against client names. + * If no match is found it is matched against client authids. If still no + * match is found and the pattern starts with '#' it is finally matched + * against client userids. + * @note Since client names are matched by substring the pattern can potentially + * match multiple targets. In that case the function will return 0 and ask + * the admin to provide a unique pattern. + * @note The filtering flags are applied after the pattern matching has + * finished. That means the pattern has to be unique against all clients + * on the server even if some of them are not eligible. + * + * @param id Client index of admin performing an action + * @param arg Target pattern + * @param flags Filtering flags, see CMDTARGET_* constants above + * + * @return Client index, or 0 if no or multiple clients matched + */ stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY) { new player = find_player("bl", arg); @@ -145,12 +194,13 @@ stock cmd_target(id, const arg[], flags = CMDTARGET_OBEY_IMMUNITY) } /** - * Standard method to show activity to clients connected to the server. - * This depends on the amx_show_activity cvar. See documentation for more details. + * Standard method to show admin activity to clients connected to the server. + * This depends on the amx_show_activity cvar. See documentation for more details. * - * @param id The user id of the person doing the action. - * @param name The name of the person doing the action. - * @param fmt The format string to display. Do not put the "ADMIN:" prefix in this. + * @param id Client index performing the action + * @param name Name of client performing the action + * @param fmt Formatting rules + * @param ... Variable number of formatting parameters * * @noreturn */ @@ -237,14 +287,14 @@ stock show_activity(id, const name[], const fmt[], any:...) } /** - * Standard method to show activity to one single client. - * This is useful for messages that get pieced together by many language keys. - * This depends on the amx_show_activity cvar. See documentation for more details. + * Standard method to show admin activity to a single client. + * This depends on the amx_show_activity cvar. See documentation for more details. * - * @param idtarget The user id of the person to display to. 0 is invalid. - * @param idadmin The user id of the person doing the action. - * @param name The name of the person doing the action. - * @param fmt The format string to display. Do not put the "ADMIN:" prefix in this. + * @param idtarget Client index to display message to + * @param id Client index performing the action + * @param name Name of client performing the action + * @param fmt Formatting rules + * @param ... Variable number of formatting parameters * * @noreturn */ @@ -254,7 +304,7 @@ stock show_activity_id(idtarget, idadmin, const name[], const fmt[], any:...) { return; } - + static __amx_show_activity; if (__amx_show_activity == 0) { @@ -437,6 +487,18 @@ stock show_activity_key(const KeyWithoutName[], const KeyWithName[], const ___Ad } } +/** + * Returns if the mod running on the server supports colored menus. + * + * @note The full list of mods supporting colored menus: + * Counter-Strike, Counter-Strike: Condition Zero, Deathmatch Classic, + * Day of Defeat, Team Fortress Classic and Half-Life: Deathmatch. + * @note Since this is a stock and compiled into the plugin, the list of + * supported mods will not update and require recompilation of the plugin + * if the list ever changed. + * + * @return 1 if colored menus are supported, 0 otherwise + */ stock colored_menus() { static ColoredMenus = -1; @@ -465,6 +527,11 @@ stock colored_menus() return ColoredMenus; } +/** + * Returns if the mod running on the server is a version of Counter-Strike. + * + * @return 1 if mod is Counter-Strike, 0 otherwise + */ stock cstrike_running() { new mod_name[32]; @@ -473,6 +540,13 @@ stock cstrike_running() return (equal(mod_name, "cstrike") || equal(mod_name, "czero") || equal(mod_name, "csv15") || equal(mod_name, "cs13")); } +/** + * Returns if the server is running a specific mod. + * + * @param mod Mod name to check for + * + * @return 1 if mod name matches, 0 otherwise + */ stock is_running(const mod[]) { new mod_name[32]; @@ -481,42 +555,92 @@ stock is_running(const mod[]) return equal(mod_name, mod); } +/** + * Retrieves the path to the AMXX base directory. + * + * @param name Buffer to copy path to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer + */ stock get_basedir(name[], len) { return get_localinfo("amxx_basedir", name, len); } +/** + * Retrieves the path to the AMXX configs directory. + * + * @param name Buffer to copy path to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer + */ stock get_configsdir(name[], len) { return get_localinfo("amxx_configsdir", name, len); } +/** + * Retrieves the path to the AMXX data directory. + * + * @param name Buffer to copy path to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer + */ stock get_datadir(name[], len) { return get_localinfo("amxx_datadir", name, len); } +/** + * Provides a shorthand to register a working menu. + * + * @note Combines the necessary calls to register_menuid() and + * register_menucmd() into a single function. + * + * @param title Menu name + * @param keys Key flags + * @param function Callback function + * @param outside Catch menus outside the calling plugin + * + * @noreturn + * @error If an invalid callback function is specified, an error will + * be thrown. + */ stock register_menu(const title[], keys, const function[], outside = 0) { register_menucmd(register_menuid(title, outside), keys, function); } /** - * Backwards Compatibility - * don't use it! + * Alias to get_configsdir provided for backwards compatibility. Originally + * intended to retrieve the AMXX custom directory. + * + * @deprecated Should not be used as the concept of a custom directory does no + * longer exists in AMXX. + * + * @param name Buffer to copy path to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer */ +#pragma deprecated The concept of a custom directory no longer exists in AMXX. Do not use. stock get_customdir(name[], len) { - return get_localinfo("amxx_configsdir", name, len); + return get_configsdir(name, len); } /** - * Add a menu item to Menus Front-End plugin ("amxmodmenu"). + * Adds a menu item/command to the admin menu (amxmodmenu) handled by the + * "Menus Front-End" plugin, if it is loaded. * - * @param MENU_TEXT Text that will be shown for this item in menu. - * @param MENU_CMD Command that should be executed to start menu. - * @param MENU_ACCESS Access required for menu. - * @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command. + * @param MENU_TEXT Item text that will be displayed in the menu + * @param MENU_CMD Command that will be executed on the client + * @param MENU_ACCESS Admin access required for menu command + * @param MENU_PLUGIN Case-insensitive name or filename of plugin providing + * the menu command * * @noreturn */ @@ -526,12 +650,15 @@ stock AddMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const } /** - * Add a menu item to "amx_menu", that should also be accessible by non-admins. + * Adds a menu item/command to the client menu (amx_menu) handled by the + * "Menus Front-End" plugin, if it is loaded. Items should be accessible by + * non-admins. * - * @param MENU_TEXT Text that will be shown for this item in menu. - * @param MENU_CMD Command that should be executed to start menu. - * @param MENU_ACCESS Access required for menu. - * @param MENU_PLUGIN The exact case-insensitive name of plugin holding the menu command. + * @param MENU_TEXT Item text that will be displayed in the menu + * @param MENU_CMD Command that will be executed on the client + * @param MENU_ACCESS Admin access required for menu command + * @param MENU_PLUGIN Case-insensitive name or filename of plugin providing + * the menu command * * @noreturn */ @@ -541,7 +668,17 @@ stock AddClientMenuItem(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, } /** - * Internal function used by above stocks. + * Helper function used by AddMenuItem() and AddClientMenuItem() + * + * @param MENU_TEXT Item text that will be displayed in the menu + * @param MENU_CMD Command that will be executed on the client + * @param MENU_ACCESS Admin access required for menu command + * @param MENU_PLUGIN Case-insensitive name or filename of plugin + * providing the menu command + * @param ADD_TO_CLIENT_MENU If true adds command to client menu, false adds + * to admin menu + * + * @noreturn */ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, const MENU_PLUGIN[], const bool:ADD_TO_CLIENT_MENU) { @@ -557,7 +694,7 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c new status = callfunc_begin(ADD_TO_CLIENT_MENU ? "AddClientMenu" : "AddMenu", filename); new bool:failed = true; - switch (status) + switch (status) { case 1: { @@ -592,11 +729,28 @@ stock AddMenuItem_call(const MENU_TEXT[], const MENU_CMD[], const MENU_ACCESS, c callfunc_end(); } +/** + * Computes an offset from a given value while constraining it between the + * specified bounds, rolling over if necessary. + * + * @note Example: The range is 1-5 and the base value (seed) is 3, the offset + * that the value should be moved by is also 3. Offsetting the value by 3 + * would result in 6, but it is to be constrained between 1 and 5. With + * clamp() this would result in 5, but this function rolls the value over + * and returns 1 instead. + * + * @param low Lower bound + * @param high Higher bound + * @param seed Base value + * @param offset Offset to move + * + * @return Computed offset value between specified bounds + */ stock constraint_offset(low, high, seed, offset) { new numElements = high - low + 1; offset += seed - low; - + if (offset >= 0) { return low + (offset % numElements); @@ -610,25 +764,25 @@ stock constraint_offset(low, high, seed, offset) } /** - * Tells if the user has ANY of the provided flags. + * Returns if the client has any of the specified admin flags. * * @param id Client index * @param flags Flag string * - * @return 1 if the user has ANY of the provided flags, 0 otherwise + * @return 1 if the user has any of the specified flags, 0 otherwise */ stock has_flag(id, const flags[]) { return (get_user_flags(id) & read_flags(flags)); } - /** - * Tells if the user has ALL of the provided flags. +/** + * Returns if the client has all of the specified admin flags. * * @param id Client index * @param flags Flag string * - * @return 1 if the user has ALL of the provided flags, 0 otherwise + * @return 1 if the user has all of the specified flags, 0 otherwise */ stock has_all_flags(id, const flags[]) { @@ -637,11 +791,11 @@ stock has_all_flags(id, const flags[]) } /** - * Resets a client's menu. + * Resets the client's menu. * - * @note This is just a wrapper around show_menu for the sake of readability. + * @note This is a wrapper around show_menu() for the sake of readability. * - * @param index Client to reset menu to, use 0 to reset to all clients + * @param index Client to reset menu of, 0 to reset all clients * * @noreturn */ From 9eb0eaf6a6a0312296c856b9b3586595bd8022a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 17 Feb 2015 17:51:56 +0100 Subject: [PATCH 02/10] core: Add documentation --- plugins/include/core.inc | 176 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 168 insertions(+), 8 deletions(-) diff --git a/plugins/include/core.inc b/plugins/include/core.inc index 039954a0..7b8ba5f9 100755 --- a/plugins/include/core.inc +++ b/plugins/include/core.inc @@ -10,33 +10,193 @@ #endif #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(); +/** + * 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[]); +/** + * Returns the number of arguments passed into the currently executed function. + * + * @return Number of arguments passed + */ 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); + +/** + * Converts a character to uppercase. + * + * @note This is not UTF8 or locale-safe. + * + * @param c Character to convert + * + * @return Converted character + */ 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); +/** + * Returns a random number between 0 and a specified upper bound. + * + * @param max Exclusive upper bound + * + * @return Random value + */ 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 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); + +/** + * 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 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) { - return x > 0 ? x : -x; + return x > 0 ? x : -x; } From ae86152282fbfd0a4060e41d7532463f351fa242 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 17 Feb 2015 15:25:53 +0100 Subject: [PATCH 03/10] cellarray/celltrie/cellstack: Documentation fixes and consistency updates --- plugins/include/cellarray.inc | 30 +++-- plugins/include/cellstack.inc | 138 ++++++++++--------- plugins/include/celltrie.inc | 244 ++++++++++++++++++++-------------- 3 files changed, 232 insertions(+), 180 deletions(-) diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc index 3c52a233..261c4707 100644 --- a/plugins/include/cellarray.inc +++ b/plugins/include/cellarray.inc @@ -63,7 +63,9 @@ stock ByteCountToCells(size) * number of items. The items are not valid to read or set * 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); @@ -431,7 +433,7 @@ native DoNotUse:ArrayGetStringHandle(Array:which, item); * * @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) */ native ArrayDestroy(&Array:which); @@ -444,10 +446,10 @@ native ArrayDestroy(&Array:which); * * public MySortFunc(Array:array, item1, item2, const data[], data_size) * - * array - Array handle in its current un-sorted state - * item1, item2 - Current item pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * item1, item2 - Current item pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * @note The comparison function should return: * -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) * - * array - Array handle in its current un-sorted state - * elem1, elem2 - Current element pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * elem1, elem2 - Current element pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * @note For Arrays with a cellsize larger than 1 (used for storing arrays and * strings), the function is called in the following manner: * * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * - * array - Array handle in its current un-sorted state - * elem1[], elem2[] - Current element pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * elem1[], elem2[] - Current element pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * * @note The comparison function should return: diff --git a/plugins/include/cellstack.inc b/plugins/include/cellstack.inc index 81043d76..15e8567f 100644 --- a/plugins/include/cellstack.inc +++ b/plugins/include/cellstack.inc @@ -12,131 +12,139 @@ #endif #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 { Invalid_Stack = 0 }; /** - * Creates a stack structure. A stack is a LIFO (last in, first out) - * vector (array) of items. It has O(1) insertion and O(1) removal. + * Creates a stack structure. A stack is a LIFO (last in, first out) vector of + * of items. It has O(1) insertion and O(1) removal. * - * Stacks have two operations: Push (adding an item) and Pop (removes - * items in reverse-push order). + * @note Stacks provide only two operations: Push (adding an item to the top) + * 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 - * retrieving it as an integer is NOT the same as StringToInt()! + * @param blocksize The number of cells each entry in the stack can hold * - * The "blocksize" determines how many cells each slot has; it cannot - * be changed after creation. - * - * @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. + * @return New stack Handle, which must be freed via DestroyStack() + * @error If an invalid blocksize is provided an error will be + * thrown. */ native Stack:CreateStack(blocksize = 1); /** * 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 - * greater than 1. + * @note This may safely be used even if the stack has a blocksize greater than + * 1. * - * @param handle Stack handle. - * @param value Value to push. + * @param handle Stack handle + * @param value Value to push * * @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); /** - * Pushes a string onto the end of a stack, truncating it if it is - * too big. + * Pushes a string onto the end of a stack, truncating it if it is too long. * - * @param handle Stack handle. - * @param value String to push. + * @param handle Stack handle + * @param value String to push * * @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[]); /** - * Pushes an array of cells onto the end of a stack. The cells - * are pushed as a block (i.e. the entire array takes up one stack slot), - * rather than pushing each cell individually. + * Pushes an array of cells onto the end of a stack. The cells are pushed as a + * block (i.e. the entire array takes up one stack slot), rather than pushing + * 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 - * @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); /** * Pops a cell value from a stack. * - * @param handle Stack handle. - * @param value Variable to store the value. - * @param block Optionally specify which block to read from - * (useful if the blocksize > 0). - * @param asChar Optionally read as a byte instead of a cell. + * @param handle Stack handle + * @param value Variable to store the value in + * @param block Optionally specify which block to read from (useful if the + * blocksize is > 0) + * @param asChar Optionally read as a byte instead of a cell * - * @return True on success, false if the stack is empty. - * @error Invalid handle, Invalid block or Invalid byte. + * @return True on success, false if the stack is empty. + * @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); /** * Pops a string value from a stack. * - * @param handle Stack handle. - * @param buffer Buffer to store string. - * @param maxlength Maximum size of the buffer. - * @param written Number of characters copied. + * @param handle Stack handle + * @param buffer Buffer to copy string to + * @param maxlength Maximum size of the buffer + * @param written Variable to store number of characters copied to * - * @return True on success, false if the stack is empty. - * @error Invalid handle. + * @return True on success, false if the stack is empty + * @error If an invalid handle is provided an error will be thrown. */ native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0); /** * Pops an array of cells from a stack. * - * @param handle Stack handle. - * @param buffer Buffer to store the array in. - * @param size If not set, assumes the buffer size is equal to the - * blocksize. Otherwise, the size passed is used. + * @param handle Stack handle + * @param buffer Array to copy value to + * @param size Size of buffer, if not set (-1) assumes the size is equal to + * the stack blocksize * - * @return True on success, false if the stack is empty. - * @error Invalid handle. + * @return True on success, false if the stack is empty + * @error If an invalid handle is provided an error will be thrown. */ 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. - * @error Invalid handle. + * @return True if empty, false if not empty + * @error If an invalid handle is provided an error will be thrown. */ native bool:IsStackEmpty(Stack:handle); /** * 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. - * @error Invalid handle. + * @return True if a value was popped, false if stack is empty + * @error If an invalid handle is provided an error will be thrown. */ 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); diff --git a/plugins/include/celltrie.inc b/plugins/include/celltrie.inc index 9a05a4b2..729be00c 100644 --- a/plugins/include/celltrie.inc +++ b/plugins/include/celltrie.inc @@ -8,180 +8,213 @@ // https://alliedmods.net/amxmodx-license #if defined _celltrie_included - #endinput + #endinput #endif #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 { 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 { Invalid_Snapshot = 0 }; /** - * Creates a hash map. A hash map is a container that can map strings (called - * "keys") to arbitrary values (cells, arrays, or strings). Keys in a hash map - * are unique. That is, there is at most one entry in the map for a given key. + * Creates a hash map. A hash map is a container that maps strings (called keys) + * to arbitrary values (cells, arrays or strings). * - * Insertion, deletion, and lookup in a hash map are all considered to be fast - * operations, amortized to O(1), or constant time. + * @note Keys in a hash map are unique so there is no more than one entry in the + * 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 - * 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(). + * @return New Map handle, which must be freed via TrieDestroy() */ native Trie:TrieCreate(); /** * 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); /** - * 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 key Key string. - * @param value Value to store at this key. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param value Value to store + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ 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 key Key string. - * @param value String to store. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param value String to store + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ 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 key Key string. - * @param buffer Array to store. - * @param size Number of items in the array. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param buffer Array to store + * @param size Array size + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. - * Invalid array size. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. or invalid array size */ 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 key Key string. - * @param value Variable to store value. - * @return True on success. False if the key is not set, or the key is set - * as an array or string (not a value). - * @error Invalid handle. + * @param handle Map handle + * @param key Key string + * @param value Variable to store value to + * + * @return True on success, false if either the key is not set or the + * 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); /** - * Retrieves a string in a Map. + * Retrieves a string from a hash map. * - * @param handle Map handle. - * @param key Key string. - * @param output Buffer to store value. - * @param outputsize Maximum size of string buffer. - * @param size Optional parameter to store the number of bytes written to the buffer. + * @param handle Map handle + * @param key Key string + * @param output Buffer to copy the value to + * @param outputsize Maximum size of 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 - * as a value or array (not a string). - * @error Invalid handle. - * Invalid buffer size. + * @return True on success, false if either the key is not set or + * the value type does not match (value is cell or array) + * @error If an invalid handle is provided an error will be + * thrown. */ 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 key Key string. - * @param output Buffer to store array. - * @param outputsize Maximum size of array buffer. - * @param size Optional parameter to store the number of elements written to the buffer. + * @param handle Map handle + * @param key Key string + * @param output Array to copy the value to + * @param outputsize Maximum size of array + * @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 - * as a value or string (not an array). - * @error Invalid handle. - * Invalid array size. + * @return True on success, false if either the key is not set or + * the value type does not match (value is cell or string) + * @error If an invalid handle or array size is provided an error + * will be thrown. */ 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 key Key string. + * @param handle Map handle + * @param key Key string * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @return True on success, false if the key was never set + * @error If an invalid handle is provided an error will be + * thrown. */ 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 key Key string. + * @param handle Map handle + * @param key Key string * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @return True if the key is set, false otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ 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. - * @error Invalid handle. + * @param handle Map handle + * + * @return 1 on success, 0 if an invalid handle was passed in */ 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. - * @error Invalid handle. + * @return Number of elements in the hash map + * @error If an invalid handle is provided an error will be + * thrown. */ native TrieGetSize(Trie:handle); /** - * Creates a snapshot of all keys in the map. If the map is changed after this - * call, the changes are not reflected in the snapshot. Keys are not sorted. + * Creates a snapshot of all keys in a hash map. If the map is changed + * 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(). - * @error Invalid handle. + * @return New map snapshot handle, which must be freed via + * TrieSnapshotDestroy() + * @error If an invalid handle is provided an error will be + * thrown. */ 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 * snapshot of its keys was taken. * - * @param handle Map snapshot. + * @param handle Map snapshot handle * - * @return Number of keys. - * @error Invalid handle. + * @return Number of keys + * @error If an invalid handle is provided an error will be + * thrown. */ 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 * the length of the key plus one. * - * @param handle Map snapshot. - * @param index Key index (starting from 0). + * @param handle Map snapshot handle + * @param index Key index (starting from 0) * - * @return Buffer size required to store the key string. - * @error Invalid handle or index out of range. + * @return Buffer size required to store the key string + * @error If an invalid handle is provided an error will be + * thrown. or index out of range */ native TrieSnapshotKeyBufferSize(Snapshot:handle, index); /** * Retrieves the key string of a given key in a map snapshot. * - * @param handle Map snapshot. - * @param index Key index (starting from 0). - * @param buffer String buffer. - * @param maxlength Maximum buffer length. + * @param handle Map snapshot handle + * @param index Key index (starting from 0) + * @param buffer String buffer + * @param maxlength Maximum buffer length * - * @return Number of bytes written to the buffer. - * @error Invalid handle or index out of range. + * @return Number of bytes written to the buffer + * @error If an invalid handle is provided an error will be + * thrown. or index out of range */ 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. - * @error Invalid handle. + * @param handle Map snapshot handle + * + * @return 1 on success, 0 if an invalid handle was passed in */ native TrieSnapshotDestroy(&Snapshot:handle); From a1c5c20d7eea972442e56b590ef84cd0386b3c7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Wed, 18 Feb 2015 03:29:26 +0100 Subject: [PATCH 04/10] amxmodx: Consistency updates, typo fixes, missing return/error added --- plugins/include/amxmodx.inc | 414 ++++++++++++++++++++---------------- 1 file changed, 230 insertions(+), 184 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index d8178038..fe8d9988 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -76,7 +76,7 @@ forward plugin_unpause(); forward server_changelevel(map[]); /** - * Called when all plugins went through plugin_init + * Called when all plugins went through plugin_init(). * * @note When this forward is called most plugins should have registered their * cvars and commands already. @@ -86,8 +86,8 @@ forward server_changelevel(map[]); forward plugin_cfg(); /** - * Called just before server deactivation and subsequent - * unloading of the plugin. + * Called just before server deactivation and subsequent unloading of the + * plugin. * * @note The plugin is required to manually free Handles it has acquired, such * as those from dynamic data structures. Failing to do that will result @@ -100,8 +100,8 @@ forward plugin_end(); /** * Called when a message is about to be logged. * - * @note Message data and information can be retrieved using the read_log* set - * of functions. + * @note Message data and information can be retrieved using the read_log set of + * functions. * * @return PLUGIN_CONTINUE to let the log message through * PLUGIN_HANDLED or higher to stop the log message @@ -123,7 +123,7 @@ forward plugin_log(); forward plugin_precache(); /** - * Called when a clients info has changed + * Called when a clients info has changed. * * @param id Client index * @@ -147,7 +147,7 @@ forward client_connect(id); * Called when the client gets a valid SteamID. * * @note This may occur before or after client_putinserver has been called. - * @note This is called for bots, and the SteamID will be "BOT" + * @note This is called for bots, and the SteamID will be "BOT". * * @param id Client index * @@ -223,7 +223,7 @@ native precache_model(const name[]); * @note Can only be used inside of the plugin_precache() forward. * @note The filepath is always relative to the "sound" folder, and the file has * to be a wav file. Precaching a file with this will add it to the engine - * sound table, making it available for usage in emit_sound for example. + * sound table, making it available for usage in emit_sound() for example. * @note Precaching other filetypes (such as mp3 music), optionally in different * locations, has to be done with precache_generic. * @@ -319,30 +319,33 @@ native get_localinfo(const info[], output[], len); * Shows text or a file in MOTD window. * * @param player Client index, use 0 to display to all clients - * @param message Message to display inside the MOTD window. If this is a - * filename the contents of this file will be displayed. - * @param header Text for the MOTD header. If this is empty the servers - * hostname will be displayed instead. + * @param message Message to display inside the MOTD window, if this is a + * filename the contents of this file will be displayed + * @param header Text for the MOTD header, if empty the servers hostname will + * be displayed instead * * @noreturn */ -native show_motd(player, const message[], const header[]=""); +native show_motd(player, const message[], const header[] = ""); /** * Sends a message to the client. * + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. + * * @param index Client index, use 0 to display to all clients * @param type Message type, see print_* destination constants in amxconst * @param message Formatting rules * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native client_print(index, type, const message[], any:...); @@ -365,6 +368,12 @@ native client_print(index, type, const message[], any:...); * client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default") * @note Including colors in ML can be done using the same escaping method: * EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default. + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. * * @param index Client index, use 0 to display to all clients * @param sender Client index used as the sender, defining the team color @@ -374,30 +383,29 @@ native client_print(index, type, const message[], any:...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native client_print_color(index, sender, const message[], any:...); /** * Sends a message to the client via the engine. * + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. + * * @param player Client index, use 0 to display to all clients * @param type Message type, see print_* destination constants in amxconst * @param message Formatting rules * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native engclient_print(player, type, const message[], any:...); @@ -410,7 +418,7 @@ native engclient_print(player, type, const message[], any:...); * * @return Number of printed characters * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native console_print(id, const message[], any:...); @@ -463,19 +471,20 @@ native console_cmd(id, const cmd[], any:...); * * @return 1 on successfully registering event * 0 on failure - * @error Invalid event name or invalid callback function + * @error If an invalid event name or callback function is provided, + * an error will be thrown. */ -native register_event(const event[], const function[], const flags[], const cond[]="", ...); +native register_event(const event[], const function[], const flags[], const cond[] = "", ...); /** * Registers a function to be called on a given log event. * * @note Examples for log conditions: - * "0=World triggered" "1=Game_Commencing" - * "1=say" - * "3=Terrorists_Win" - * "1=entered the game" - * "0=Server cvar" + * "0 = World triggered" "1 = Game_Commencing" + * "1 = say" + * "3 = Terrorists_Win" + * "1 = entered the game" + * "0 = Server cvar" * * @param function Name of callback function * @param argsnum Number of arguments of the log event @@ -489,9 +498,10 @@ native register_event(const event[], const function[], const flags[], const cond * The argument is compared to the specified string accordingly * * @return 1 on successfully registering event, 0 on failure - * @error Invalid callback function + * @error If an invalid callback function is provided, an error will + * be thrown. */ -native register_logevent(const function[], argsnum, ...); +native register_logevent(const function[], argsnum, ...); /** * Sets display parameters for hudmessages. @@ -524,24 +534,26 @@ native register_logevent(const function[], argsnum, ...); * * @noreturn */ -native set_hudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, effects=0, Float:fxtime=6.0, Float:holdtime=12.0, Float:fadeintime=0.1, Float:fadeouttime=0.2, channel=-1); +native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y = 0.35, effects = 0, Float:fxtime = 6.0, Float:holdtime = 12.0, Float:fadeintime = 0.1, Float:fadeouttime = 0.2, channel = -1); /** * Displays a message on the client HUD. * * @note Use set_hudmessage to define how the message should look on screen. + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. * * @param index Client index, use 0 to display to all clients * @param message Formatting rules * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native show_hudmessage(index, const message[], any:...); @@ -568,7 +580,7 @@ native show_hudmessage(index, const message[], any:...); * * @noreturn */ -native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, effects=0, Float:fxtime=6.0, Float:holdtime=12.0, Float:fadeintime=0.1, Float:fadeouttime=0.2); +native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y = 0.35, effects = 0, Float:fxtime = 6.0, Float:holdtime = 12.0, Float:fadeintime = 0.1, Float:fadeouttime = 0.2); /** * Displays a director message on the client HUD. @@ -580,18 +592,20 @@ native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, e * sent. There is no way to clear a specific message. * @note The message has a maximum length of 128 characters which this function * will automatically enforce. + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. * * @param index Client index, use 0 to display to all clients * @param message Formatting rules * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native show_dhudmessage(index, const message[], any:...); @@ -615,8 +629,13 @@ native show_dhudmessage(index, const message[], any:...); * @param menu Menu body * @param time Menu timeout in seconds, -1 to disable * @param title Name of the menu for internal tracking purposes + * + * @return 1 on success, 0 if menu could not be displayed (client not + * connected) + * @error If a single client is specified and the index is not + * within the range of 1 to MaxClients an error will be thrown. */ -native show_menu(index, keys, const menu[], time=-1, const title[]=""); +native show_menu(index, keys, const menu[], time = -1, const title[] = ""); /** * Retrieves values from a client message. @@ -627,22 +646,22 @@ native show_menu(index, keys, const menu[], time=-1, const title[]=""); * read_data(2, floatvalue); * written = read_data(3, buffer, buffersize); * - * * @param value Argument number to retrieve value from - * @param ... If 0 additional parameters are provided, the function - * will return the argument value directly. - * If 1 additional parameter is provided, the function will - * store a float value in that second parameter. - * If two additional parameters are provided, the function - * will copy a string to the buffer provided in the second - * parameter, using the third as the maximum buffer size. + * @param ... Changes the native's behavior depending on how many + * additional parameters are provided: + * 0 - Return the argument integer value directly + * 1 - Store the argument float value in the variable passed + * as the second parameter + * 2 - Copy the argument string value to the buffer provided + * in the second parameter, using the third as the + * maximum buffer size * - * @return If zero additional parameters are provided, the function - * will return an integer value. - * If one additional parameter is provided, the function will - * return the float value, converted (truncated) to an integer. - * If two additional parameters are provided, the function - * will return the number of cells written to the buffer. + * @return Changes depending on how many additional parameters are + * provided: + * 0 - Returns the argument integer value + * 1 - Returns the argument float value, converted + * (truncated) to an integer + * 2 - Returns the number of cells written to the buffer */ native read_data(value, any:...); @@ -724,7 +743,7 @@ native read_logargv(id, output[], len); * @error If the provided string is not valid client log data, an * error will be thrown. */ -native parse_loguser(const text[], name[], nlen, &userid=-2, authid[]="", alen=0, team[]="", tlen=0); +native parse_loguser(const text[], name[], nlen, &userid =-2, authid[] = "", alen = 0, team[] = "", tlen = 0); /** * Sends a message to the console of the server. @@ -768,7 +787,7 @@ native is_user_hltv(index); * * @note This does not throw an error if the provided index is out of the * 1 to MaxClients range. That means you can safely use this native - * without manually verifying an index to be a valid client index. + * without manually verifying that the index is a valid client index. * * @param index Client index * @@ -842,9 +861,9 @@ native get_amxx_verstring(buffer[], length); * was attacked by a non-client entity. * * @param index Client index - * @param ... Optionally a second byref parameter will be filled with the - * attacker weapon, and a third byref parameter will be filled - * with the hit place on the body. + * @param ... If provided the attacker weapon will be stored in an + * optional second parameter, and the body hit place will be + * stored in an optional third parameter * * @return Attacker client index, a non-client entity or 0 if no * attacker was found @@ -858,7 +877,7 @@ native get_user_attacker(index, ...); * Traces the client's current aim vector to see if it hits something. * * @note If the trace does not hit a client, id and body will be set to 0. - * @note If the trace hits nothing within the specified distance 0.0 is returned + * @note If the trace hits nothing within the specified distance 0 is returned. * * @param index Client index to trace aim from * @param id Variable to store hit client index (if applicable) @@ -869,7 +888,7 @@ native get_user_attacker(index, ...); * @error If the client index is not within the range of 1 to * MaxClients an error will be thrown. */ -native Float:get_user_aiming(index, &id, &body, dist=9999); +native Float:get_user_aiming(index, &id, &body, dist = 9999); /** * Returns the client's frags. @@ -949,7 +968,7 @@ native get_user_index(const name[]); * * @return Number of cells written to the buffer */ -native get_user_ip(index, ip[], len, without_port=0); +native get_user_ip(index, ip[], len, without_port = 0); /** * Returns if the client has the specified weapon in their inventory. @@ -963,7 +982,7 @@ native get_user_ip(index, ip[], len, without_port=0); * @error If the client index is not within the range of 1 to * MaxClients an error will be thrown. */ -native user_has_weapon(index, weapon, setweapon=-1); +native user_has_weapon(index, weapon, setweapon = -1); /** * Returns weapon index of the currently carried weapon. Also allows retrieval @@ -977,7 +996,7 @@ native user_has_weapon(index, weapon, setweapon=-1); * @error If the client index is not within the range of 1 to * MaxClients an error will be thrown. */ -native get_user_weapon(index, &clip=0, &ammo=0); +native get_user_weapon(index, &clip = 0, &ammo = 0); /** * Retrieves ammo in the clip and backpack of the specified weapon. @@ -1020,9 +1039,9 @@ native num_to_word(num, output[], len); * @param len Maximum size of buffer * * @return Team index on success, -1 if client index is invalid or - * the client is not connected. + * the client is not connected */ -native get_user_team(index, team[]="", len=0); +native get_user_team(index, team[] = "", len = 0); /** * Returns client's playing time in seconds. @@ -1034,7 +1053,7 @@ native get_user_team(index, team[]="", len=0); * @return Connection time in seconds, 0 if client index is invalid or * client is not connected */ -native get_user_time(index, flag=0); +native get_user_time(index, flag = 0); /** * Retrieves the ping and loss of a client. @@ -1044,7 +1063,7 @@ native get_user_time(index, flag=0); * @param loss Variable to sote loss in * * @return 1 on success, 0 if client index is invalid or the client - * is not connected. + * is not connected */ native get_user_ping(index, &ping, &loss); @@ -1064,7 +1083,7 @@ native get_user_ping(index, &ping, &loss); * @error If the client index is not within the range of 1 to * MaxClients an error will be thrown. */ -native get_user_origin(index, origin[3], mode=0); +native get_user_origin(index, origin[3], mode = 0); /** * Retrieves all weapons in the client inventory, stores them in an array and @@ -1089,6 +1108,8 @@ native get_user_weapons(index, weapons[32], &num); * @param id Weapon index * @param weapon Buffer to copy name to * @param len Maximum buffer size + * + * @return Number of cells written to buffer */ native get_weaponname(id, weapon[], len); @@ -1123,7 +1144,7 @@ native get_user_authid(index, authid[], len); * @param index Client index * * @return Client userid, 0 if the userid is not available or the - * client index is invalid. + * client index is invalid */ native get_user_userid(index); @@ -1139,9 +1160,11 @@ native get_user_userid(index); * @param index Client idex * @param power Power of the slap * @param rnddir If set to zero the player will be slapped along it's aim - * vector. If nonzero the direction will be randomized. + * vector, otherwise the direction will be randomized + * + * @return 1 if user is alive and slap succeeded, 0 otherwise */ -native user_slap(index, power, rnddir=1); +native user_slap(index, power, rnddir = 1); /** * Kills a client. @@ -1150,9 +1173,9 @@ native user_slap(index, power, rnddir=1); * @param flag If nonzero the death will not affect the client's score * * @return 1 on success, 0 if client index is invalid or the client - * is not connected. + * is not connected */ -native user_kill(index, flag=0); +native user_kill(index, flag = 0); /** * Logs a message to the current AMXX log file. @@ -1198,7 +1221,7 @@ native log_to_file(const file[], const message[], any:...); * * @return Number of clients on the server */ -native get_playersnum(flag=0); +native get_playersnum(flag = 0); /** * Stores a filtered list of client indexes to an array. @@ -1221,7 +1244,7 @@ native get_playersnum(flag=0); * * @noreturn */ -native get_players(players[MAX_PLAYERS], &num, const flags[]="", const team[]=""); +native get_players(players[MAX_PLAYERS], &num, const flags[] = "", const team[] = ""); /** * Retrieves argument of client command. @@ -1340,7 +1363,7 @@ native remove_quotes(text[]); * * @return Lenght of formatted command string * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native client_cmd(index, const command[], any:...); @@ -1355,16 +1378,16 @@ native client_cmd(index, const command[], any:...); * @note Commands emulated using this function will not trigger plugin command * hooks. For an alternative that does, see amxclient_cmd(). * - * @param index Client index, use 0 to execute from all clients. + * @param index Client index, use 0 to execute from all clients * @param command Client command to execute on * @param arg1 Optional command arguments * @param arg2 Optional command arguments * * @noreturn * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ -native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); +native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); /** * Execute a command from the client without actually sending it to the client's @@ -1377,16 +1400,16 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); * @note Commands emulated using this function will trigger other plugin's * command hooks. For an alternative that doesn't, see engclient_cmd(). * - * @param index Client index, use 0 to execute from all clients. + * @param index Client index, use 0 to execute from all clients * @param command Client command to execute on * @param arg1 Optional command arguments * @param arg2 Optional command arguments * * @noreturn * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ -native amxclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); +native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); /** * Queues a command to be executed from the server console. @@ -1484,20 +1507,20 @@ native get_time(const format[], output[], len); * @param time Unix timestamp, use -1 to use the current time * * @return Number of cells written to buffer - * @error If the conversion process fails, an error will be thrown + * @error If the conversion process fails, an error will be thrown. */ -native format_time(output[], len, const format[], time=-1); +native format_time(output[], len, const format[], time = -1); /** * Returns the system time as a unix timestamp (number of seconds since unix - * epoch) + * epoch). * * @param offset Optional offset value in seconds * * @return Unix time stamp * @error */ -native get_systime(offset=0); +native get_systime(offset = 0); /** * Converts time string to unix time stamp. @@ -1512,12 +1535,12 @@ native get_systime(offset=0); * @param input Time string to convert * @param format Formatting information for conversion * @param time If different from -1 the converted time will be added to - * this time stamp. + * this time stamp * * @return Unix time stamp - * @error If the conversion process fails, an error will be thrown + * @error If the conversion process fails, an error will be thrown. */ -native parse_time(const input[], const format[], time=-1); +native parse_time(const input[], const format[], time = -1); /** * Calls a function after a specified time has elapsed. @@ -1536,8 +1559,12 @@ native parse_time(const input[], const format[], time=-1); * map change * @param repeat If the "a" flag is set the task will be repeated this * many times + * + * @noreturn + * @error If an invalid callback function is provided, an error is + * thrown. */ -native set_task(Float:time, const function[], id=0, const any:parameter[]="", len=0, const flags[]="", repeat=0); +native set_task(Float:time, const function[], id = 0, const any:parameter[] = "", len = 0, const flags[] = "", repeat = 0); /** * Removes all tasks with the specified id. @@ -1547,7 +1574,7 @@ native set_task(Float:time, const function[], id=0, const any:parameter[]="", le * * @return Number of removed tasks */ -native remove_task(id=0, outside=0); +native remove_task(id = 0, outside = 0); /** * Modifies the time interval of all tasks with the specified id. @@ -1558,7 +1585,7 @@ native remove_task(id=0, outside=0); * * @return Number of affected tasks */ -native change_task(id=0, Float:newTime=1.0, outside=0); +native change_task(id = 0, Float:newTime = 1.0, outside = 0); /** * Returns if a task with the specified id exists. @@ -1568,7 +1595,7 @@ native change_task(id=0, Float:newTime=1.0, outside=0); * * @return 1 if a task was found, 0 otherwise */ -native task_exists(id=0, outside=0); +native task_exists(id = 0, outside = 0); /** * Sets the specified admin flags to a client. @@ -1588,7 +1615,7 @@ native task_exists(id=0, outside=0); * @error If the index is not within the range of 0 to MaxClients, an * error will be thrown. */ -native set_user_flags(index, flags=-1, id=0); +native set_user_flags(index, flags = -1, id = 0); /** * Returns the client's admin flags as a bitflag sum. @@ -1605,7 +1632,7 @@ native set_user_flags(index, flags=-1, id=0); * @error If the index is not within the range of 0 to MaxClients, an * error will be thrown. */ -native get_user_flags(index, id=0); +native get_user_flags(index, id = 0); /** * Removes the specified admin flags from a client. @@ -1624,13 +1651,13 @@ native get_user_flags(index, id=0); * @error If the index is not within the range of 0 to MaxClients, an * error will be thrown. */ -native remove_user_flags(index, flags=-1, id=0); +native remove_user_flags(index, flags = -1, id = 0); /** * Registers a callback to be called when the client executes a command from the * console. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * @note Opting in to FlagManager enables the admin privileges to be overwritten * by the end user via the cmdaccess.ini config file. @@ -1649,13 +1676,13 @@ native remove_user_flags(index, flags=-1, id=0); * @error If an invalid callback function is specified, an error * will be thrown. */ -native register_clcmd(const client_cmd[], const function[], flags=-1, const info[]="", FlagManager=-1); +native register_clcmd(const client_cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1); /** * Registers a callback to be called when the client or server executes a * command from the console. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * @note Opting in to FlagManager enables the admin privileges to be overwritten * by the end user via the cmdaccess.ini config file. @@ -1674,13 +1701,13 @@ native register_clcmd(const client_cmd[], const function[], flags=-1, const info * @error If an invalid callback function is specified, an error * will be thrown. */ -native register_concmd(const cmd[], const function[], flags=-1, const info[]="", FlagManager=-1); +native register_concmd(const cmd[], const function[], flags = -1, const info[] = "", FlagManager = -1); /** * Registers a callback to be called when the server executes a command from the * console. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param client_cmd Command to register @@ -1692,12 +1719,12 @@ native register_concmd(const cmd[], const function[], flags=-1, const info[]="", * @error If an invalid callback function is specified, an error * will be thrown. */ -native register_srvcmd(const server_cmd[], const function[], flags=-1, const info[]=""); +native register_srvcmd(const server_cmd[], const function[], flags = -1, const info[] = ""); /** * Retrieves information about a client command. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1707,7 +1734,7 @@ native register_srvcmd(const server_cmd[], const function[], flags=-1, const inf * @param info Buffer to copy command description to * @param len2 Maximum description buffer size * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * * @return 1 on succes, 0 if command was not found */ @@ -1716,11 +1743,11 @@ native get_clcmd(index, command[], len1, &flags, info[], len2, flag); /** * Returns number of registered client commands. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * * @return Number of registered client commants */ @@ -1729,7 +1756,7 @@ native get_clcmdsnum(flag); /** * Retrieves information about a server command. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1739,7 +1766,7 @@ native get_clcmdsnum(flag); * @param info Buffer to copy command description to * @param len2 Maximum description buffer size * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * * @return 1 on succes, 0 if command was not found */ @@ -1748,11 +1775,11 @@ native get_srvcmd(index, server_cmd[], len1, &flags, info[], len2, flag); /** * Returns number of registered server commands. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * * @return Number of registered server commants */ @@ -1761,7 +1788,7 @@ native get_srvcmdsnum(flag); /** * Retrieves information about a console command. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1771,19 +1798,19 @@ native get_srvcmdsnum(flag); * @param info Buffer to copy command description to * @param len2 Maximum description buffer size * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * @param id If set to 0 only server commands will be considered, * positive will only consider client commands, otherwise - * all console commands will be considered. + * all console commands will be considered * * @return 1 on succes, 0 if command was not found */ -native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id=-1); +native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id = -1); /** - * Returns the parent plugin id of a console command + * Returns the parent plugin id of a console command. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param cid Command index @@ -1792,24 +1819,26 @@ native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id=-1); * @param id_type If set to 0 only server commands will be considered, * positive will only consider client commands, otherwise * all console commands will be considered. + * + * @return Plugin id */ native get_concmd_plid(cid, flag_mask, id_type); /** * Returns number of registered console commands. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with - * the specified privilege flags. + * the specified privilege flags * @param id If set to 0 only server commands will be considered, * positive will only consider client commands, otherwise - * all console commands will be considered. + * all console commands will be considered * * @return Number of registered console commants */ -native get_concmdsnum(flag, id=-1); +native get_concmdsnum(flag, id = -1); /** * Returns unique menu id of a menu. @@ -1819,7 +1848,7 @@ native get_concmdsnum(flag, id=-1); * * @return Menu id */ -native register_menuid(const menu[], outside=0); +native register_menuid(const menu[], outside = 0); /** * Registers a callback function to a menu id and keys. @@ -1877,6 +1906,8 @@ native server_exec(); * @param att Sound attenuation * @param flags Emit flags * @param pitch Sound pitch + * + * @noreturn */ native emit_sound(index, channel, const sample[], Float:vol, Float:att, flags, pitch); @@ -1901,7 +1932,7 @@ native Float:random_float(Float:a, Float:b); native random_num(a, b); /** - * Returns unique id of a client message + * Returns unique id of a client message. * * @note Example usage: get_user_msgid("TextMsg") * @note The message id is unique as long as the server is running, but might @@ -1989,7 +2020,7 @@ native Float:get_xvar_float(id); * @noreturn * @error If an invalid xvar id is specified an error will be thrown. */ -native set_xvar_num(id, value=0); +native set_xvar_num(id, value = 0); /** * Sets the float value of a public variable. @@ -2005,7 +2036,7 @@ native set_xvar_num(id, value=0); * @noreturn * @error If an invalid xvar id is specified an error will be thrown. */ -native set_xvar_float(id, Float:value=0.0); +native set_xvar_float(id, Float:value = 0.0); /** * Returns if a module is loaded. @@ -2058,7 +2089,7 @@ native get_modulesnum(); * * @return Plugin id of the matching plugin, -1 otherwise */ -native is_plugin_loaded(const name[], bool:usefilename=false); +native is_plugin_loaded(const name[], bool:usefilename = false); /** * Retrieves info about a plugin by plugin index. @@ -2079,7 +2110,7 @@ native is_plugin_loaded(const name[], bool:usefilename=false); * @return Plugin index on success, -1 if there is no plugin with given * index */ -native get_plugin(index, filename[]="", len1=0, name[]="", len2=0, version[]="", len3=0, author[]="", len4=0, status[]="", len5=0, ...); +native get_plugin(index, filename[] = "", len1 = 0, name[] = "", len2 = 0, version[] = "", len3 = 0, author[] = "", len4 = 0, status[] = "", len5 = 0, ...); /** * Returns the number of loaded AMXX plugins. @@ -2106,7 +2137,7 @@ native get_pluginsnum(); * @error If it is attempted to use the deprecated functionality, * an error is thrown. */ -native pause(const flag[], const param1[]="", const param2[]=""); +native pause(const flag[], const param1[] = "", const param2[] = ""); /** * Unpauses a plugin so it will resume execution if it was previously paused. @@ -2127,14 +2158,14 @@ native pause(const flag[], const param1[]="", const param2[]=""); * @error If it is attempted to use the deprecated functionality, * an error is thrown. */ -native unpause(const flag[], const param1[]="", const param2[]=""); +native unpause(const flag[], const param1[] = "", const param2[] = ""); /** * Initiates a function call to this or another plugin by function name. * * @note This only sets up the function call and covers the pre-requisites. * Push parameters using the callfunc_push_* set of functions. The call - * will be executed only upon using callfunc_end() + * will be executed only upon using callfunc_end(). * * @param func Function name * @param plugin Plugin filename. If empty the calling plugin is targeted. @@ -2147,15 +2178,15 @@ native unpause(const flag[], const param1[]="", const param2[]=""); * @error If called while another callfunc has not yet been finished, * an error is thrown. */ -native callfunc_begin(const func[], const plugin[]=""); +native callfunc_begin(const func[], const plugin[] = ""); /** * Initiates a function call to this or another plugin by function id. * * @note This only sets up the function call and covers the pre-requisites. * Push parameters using the callfunc_push_* set of functions. The call - * will be executed only upon using callfunc_end() - * @note The function id can be retrieved by get_func_id() + * will be executed only upon using callfunc_end(). + * @note The function id can be retrieved by get_func_id(). * * @param func Function id * @param plugin Plugin filename. If empty the calling plugin is targeted. @@ -2167,10 +2198,10 @@ native callfunc_begin(const func[], const plugin[]=""); * @error If called while another callfunc has not yet been finished, * or the specified function is invalid, an error is thrown. */ -native callfunc_begin_i(func, plugin=-1); +native callfunc_begin_i(func, plugin = -1); /** - * Retrieves a functions id for use with callfunc_begin_i() + * Retrieves a functions id for use with callfunc_begin_i(). * * @param funcName Function name * @param pluginId Plugin id. If -1 the calling plugin is targeted. The plugin @@ -2179,7 +2210,7 @@ native callfunc_begin_i(func, plugin=-1); * @return >0 Function id on success * -1 if plugin or function was not found */ -native get_func_id(const funcName[], pluginId=-1); +native get_func_id(const funcName[], pluginId = -1); /** * Pushes an int value onto the current call. @@ -2239,13 +2270,13 @@ native callfunc_push_floatrf(&Float:value); * * @param VALUE String to push * @param copyback If true any changes made in the called function will be - * copied back to the calling plugin. + * copied back to the calling plugin * * @noreturn * @error If called without initiating a callfunc, or the maximum * amount of parameters is reached, an error is thrown. */ -native callfunc_push_str(const VALUE[], bool:copyback=true); +native callfunc_push_str(const VALUE[], bool:copyback = true); /** * Pushes an array onto the current call. @@ -2256,13 +2287,13 @@ native callfunc_push_str(const VALUE[], bool:copyback=true); * @param VALUE Array to push * @param array_size Size of the array * @param copyback If true any changes made in the called function will be - * copied back to the calling plugin. + * copied back to the calling plugin * * @noreturn * @error If called without initiating a callfunc, or the maximum * amount of parameters is reached, an error is thrown. */ -native callfunc_push_array(const VALUE[], array_size, bool:copyback=true); +native callfunc_push_array(const VALUE[], array_size, bool:copyback = true); /** * Completes the call to a function. @@ -2329,11 +2360,13 @@ native md5_file(const file[], md5buffer[34]); * @param hdr If nonzero the function will return the pcode rather than * state flags * @param plid Plugin id, -1 to target calling plugin + * + * @return Plugin flags */ -native plugin_flags(hdr=0, plid=-1); +native plugin_flags(hdr = 0, plid = -1); /** - * Allows plugins to declare module dependencies using require_module() + * Allows plugins to declare module dependencies using require_module(). * * @deprecated Module dependency has been automatically handled by the compiler * since AMXX 1.50, released in 2005. This forward is no longer @@ -2345,7 +2378,7 @@ native plugin_flags(hdr=0, plid=-1); forward plugin_modules(); /** - * Adds a module dependency + * Adds a module dependency. * * @deprecated Module dependency has been automatically handled by the compiler * since AMXX 1.50, released in 2005. This native has no effect. @@ -2358,7 +2391,7 @@ native require_module(const module[]); /** * Returns if the server is 64 bit. * - * @deprecated As a result of valve dropping support for 64bit binaries AMXX is + * @deprecated As a result of Valve dropping support for 64bit binaries AMXX is * also not shipping 64bit builds anymore. This native is basically * guaranteed to return 0. * @@ -2376,7 +2409,7 @@ native is_amd64_server(); * * @return Plugin id, -1 (INVALID_PLUGIN_ID) on failure */ -native find_plugin_byfile(const filename[], ignoreCase=1); +native find_plugin_byfile(const filename[], ignoreCase = 1); /** * Called before plugin_init(), allows the plugin to register natives. @@ -2392,8 +2425,8 @@ forward plugin_natives(); * * public native_handler(plugin_id, argc) * - * plugin_id - plugin calling the native - * argc - number of parameters + * plugin_id - plugin calling the native + * argc - number of parameters * * @note Style 1 natives are deprecated. Plugins should not use them, they might * break. @@ -2410,7 +2443,7 @@ forward plugin_natives(); * @noreturn * @error If an invalid callback is specified, an error is thrown. */ -native register_native(const name[], const handler[], style=0); +native register_native(const name[], const handler[], style = 0); /** * Registers the plugin as a library. @@ -2620,16 +2653,18 @@ native set_array_f(param, const Float:source[], size); * * public error_filter(error_code, bool:debugging, message[]) * - * error_code - AMX_ERR_* code. - * debugging - True if the plugin is in debug mode, false otherwise - * message[] - Message sent along with the error + * error_code - AMX_ERR_* code. + * debugging - True if the plugin is in debug mode, false otherwise + * message[] - Message sent along with the error * * @note The handler should return PLUGIN_CONTINUE to let the error through the * filter, or PLUGIN_HANDLED to block the error from displaying. * - * @param handler Callback function + * @param handler Function name to call * - * @error If an invalid callback is specified, an error is thrown. + * @noreturn + * @error If an invalid callback function is provided, an error + * is thrown. */ native set_error_filter(const handler[]); @@ -2691,15 +2726,22 @@ native dbg_fmt_error(buffer[], maxLength); * * public native_filter(const native[], index, trap) * - * native - Native name - * index - Native index - * trap - 0 if native couldn't be found, 1 if native use was attempted + * native - Native name + * index - Native index + * trap - 0 if native couldn't be found, 1 if native use was attempted * * @note The handler should return PLUGIN_CONTINUE to let the error through the * filter (which will throw a run-time error), or return PLUGIN_HANDLED * to continue operation. * @note Returning PLUGIN_CONTINUE if trap is 0 will result in the plugin * failing to load! + * + * @param handler Function name to call + * + * @return 1 if handler is set successfully, 0 otherwise (called + * outside of plugin_native() forward) + * @error If an invalid callback function is provided an error is + * thrown. */ native set_native_filter(const handler[]); @@ -2718,8 +2760,8 @@ native set_native_filter(const handler[]); * * public module_filter(const library[], LibType:type) * - * library - Shortname of library or class that is required - * libtrype - Type of requirement being checked (library/module or class) + * library - Shortname of library or class that is required + * libtrype - Type of requirement being checked (library/module or class) * * @note The handler should return PLUGIN_CONTINUE to let the error through the * filter (which will result in the plugin failing to load), or @@ -2750,7 +2792,7 @@ native set_module_filter(const handler[]); * @error The function is guaranteed to throw an error, using the * specified custom log message. */ -native abort(error, const fmt[]="", any:...); +native abort(error, const fmt[] = "", any:...); /** * Returns if a specific module is loaded. @@ -2812,7 +2854,7 @@ native next_hudchannel(player); * * @return HUD sync object handle */ -native CreateHudSyncObj(num=0, ...); +native CreateHudSyncObj(num = 0, ...); /** * Displays a synchronized HUD message. @@ -2823,6 +2865,12 @@ native CreateHudSyncObj(num=0, ...); * already. * @note This uses the display parameters set with set_hudmessage(), ignoring * the selected channel in favor of its own synchronization. + * @note This functions return value behaves differently depending on what is + * used as the client index: If 0 is specified, then the function will + * return 0 if nothing has been sent (no client connected). If either a + * single client is specified or there is at least one client connected, + * the number of printed characters will refer to the message that is sent + * last, to the client with the highest index. * * @param target Client index, use 0 to display to all clients * @param syncObj HUD sync object handle @@ -2830,12 +2878,8 @@ native CreateHudSyncObj(num=0, ...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * If 0 is specified as the index then 0 will be returned if - * nothing has been sent. The number of printed characters will - * otherwise refer to the message that is sent last, to the - * client with the highest index. * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); @@ -2853,7 +2897,7 @@ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); * * @noreturn * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown + * within the range of 1 to MaxClients an error will be thrown. */ native ClearSyncHud(target, syncObj); @@ -2906,6 +2950,7 @@ native get_var_addr(any:...); * * @param addr Variable address * + * @return Value at address * @error If the plugin attempts to access an address outside of the * stack or heap limits of the plugin, an error will be thrown. */ @@ -2919,6 +2964,7 @@ native get_addr_val(addr); * @param addr Variable address * @param val Value to set * + * @noreturn * @error If the plugin attempts to access an address outside of the * stack or heap limits of the plugin, an error will be thrown. */ @@ -2967,7 +3013,7 @@ native CreateOneForward(plugin_id, const name[], ...); * * @return Special handle for use in ExecuteForward() */ -native PrepareArray(const array[], size, copyback=0); +native PrepareArray(const array[], size, copyback = 0); /** * Executes a forward. @@ -3019,9 +3065,9 @@ native arrayset(array[], value, size); native get_weaponid(const name[]); /** - * Adds an admin to the dynamic admin storage for lookup at a later time + * Adds an admin to the dynamic admin storage for lookup at a later time. * - * @note For a list of possible access flags see the ADMIN_* constans in + * @note For a list of possible access flags see the ADMIN_* constants in * amxconst.inc * @note For a list of possible auth flags see the FLAG_* constants in * amxconst.inc @@ -3036,7 +3082,7 @@ native get_weaponid(const name[]); native admins_push(const AuthData[], const Password[], Access, Flags); /** - * Returns the number of admins in the dynamic admin storage + * Returns the number of admins in the dynamic admin storage. * * @return Number of admins */ @@ -3054,14 +3100,14 @@ native admins_num(); * @param BufferSize Maximum buffer size * * @return Property value if AdminProp_Access or AdminProp_Flags - * is requested. 0 otherwise. + * is requested, 0 otherwise * @error If an invalid storage index is specified, an error will * be thrown. */ -native admins_lookup(num, AdminProp:Property, Buffer[]="", BufferSize=0); +native admins_lookup(num, AdminProp:Property, Buffer[] = "", BufferSize = 0); /** - * Clears the list of dynamically stored admins + * Clears the list of dynamically stored admins. * * @noreturn */ From 50fea6be756fcb471b9b863be89db79791daf3aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Wed, 18 Feb 2015 16:24:04 +0100 Subject: [PATCH 05/10] cstrike/csx/csstats: Added documentation, consistency updates, typo fixes --- plugins/include/csstats.inc | 293 ++++++-- plugins/include/cstrike.inc | 1349 ++++++++++++++++++++++++++--------- plugins/include/csx.inc | 278 ++++++-- 3 files changed, 1500 insertions(+), 420 deletions(-) diff --git a/plugins/include/csstats.inc b/plugins/include/csstats.inc index eb8dd300..9bb7c099 100755 --- a/plugins/include/csstats.inc +++ b/plugins/include/csstats.inc @@ -12,58 +12,263 @@ #endif #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 -* returns 0 in other case 1. Fields in stats are: -* 0 - kills -* 1 - deaths -* 2 - headshots -* 3 - teamkilling -* 4 - shots -* 5 - hits -* 6 - damage +/** + * Retrieves the client's current weapon statistics. + * + * @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_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 difference of kills to deaths. + * @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. -* Function returns the position in stats by diff. kills to deaths. */ -native get_user_stats(index,stats[8],bodyhits[8]); +/** + * Retrieves the client's statistics 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 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 -* returns 0 in other case 1. User stats are reset on his respawn. */ -native get_user_vstats(index,victim,stats[8],bodyhits[8],wpnname[]="",len=0); +/** + * Retrieves the client's statistics received from 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 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 -* 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); - -/* Resets life, weapon, victims and attackers user stats. */ +/** + * Resets the current round weapon, attacker and victim statistics. + * + * @param index Client index + * + * @noreturn + * @error If an invalid client index is provided, an error will be + * thrown. + */ 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. -* Function returns next index of stats entry or 0 if no more exists. */ -native get_stats(index,stats[8],bodyhits[8],name[],len,authid[] = "",authidlen = 0); +/** + * Retrieves 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 Player rank is determined by the difference of kills to deaths. + * @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(); -/* -* new stats: -* 0 - total defusions -* 1 - bomb defused -* 2 - bomb plants -* 3 - bomb explosions -*/ -native get_user_stats2(index,stats[4]); -native get_stats2(index,stats[4],authid[] = "",authidlen = 0); +/** + * Retrieves the client's objective statistics from the permanent storage. + * + * @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 + * + * @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); diff --git a/plugins/include/cstrike.inc b/plugins/include/cstrike.inc index 6bd2846d..2ee0752d 100755 --- a/plugins/include/cstrike.inc +++ b/plugins/include/cstrike.inc @@ -12,7 +12,7 @@ // #if defined _cstrike_included - #endinput + #endinput #endif #define _cstrike_included @@ -25,329 +25,1060 @@ #pragma library cstrike #endif -/* Returns player deaths. +/** + * @section Team and team model constants, used by cs_[get|set]_user_team(). */ -native cs_get_user_deaths(index); -/* Sets player deaths. +/** + * Internal Counter-Strike model id constants. + * + * @note Model ids starting with CZ_ are only valid in Condition Zero. */ -native cs_set_user_deaths(index, newdeaths); - -/* Returns index of entity (does not have to be a player) which hostage is following. 0 is hostage doesn't follow anything. - * Note: this native does not work on Condition Zero, which has a different hostage AI than CS. - */ -native cs_get_hostage_foll(index); - -/* Set hostage to follow entity specified in followedindex. Does not have to be a player. If followedindex is 0 the hostage will stop following. - * Note: this native does not work on Condition Zero, which has a different hostage AI than CS. - */ -native cs_set_hostage_foll(index, followedindex = 0); - -/* Get unique hostage id. - */ -native cs_get_hostage_id(index); - -/* Get amount of ammo in backpack on a user for a specific weapon. - * Look in amxconst.inc for weapon types: CSW_*. - * Weapons on the same line uses the same ammo type: - * awm - * scout, ak, g3 - * para - * famas, m4a1, aug, sg550, galil, sg552 - * m3, xm - * usp, ump, mac - * fiveseven, p90 - * deagle - * p228 - * glock, mp5, tmp, elites - * flash - * he - * smoke - */ -native cs_get_user_bpammo(index, weapon); - -/* Restock/remove ammo in a user's backpack. - */ -native cs_set_user_bpammo(index, weapon, amount); - -/* Returns 1 if user has a defuse kit. - */ -native cs_get_user_defuse(index); - -/* If defusekit is 1, the user will have a defuse kit. - * You can specify a different colour for the defuse kit icon showing on hud. Default is the normal green. - * You can specify an icon. Default is "defuser". Set flash to 1 if you want the icon to flash red. - */ -native cs_set_user_defuse(index, defusekit = 1, r = 0, g = 160, b = 0, icon[] = "defuser", flash = 0); - -/* Is user in buyzone? Returns 1 when true, 0 when false. - */ -native cs_get_user_buyzone(index); - -/* Returns 1 when user has a primary weapon OR a shield in inventory, else 0. - */ -native cs_get_user_hasprim(index); - -/* Get user model. - */ -native cs_get_user_model(index, model[], len); - -/* Set user model. - */ -native cs_set_user_model(index, const model[]); - -/* Use to reset model to standard selected model. - */ -native cs_reset_user_model(index); - -/* Returns users money. - */ -native cs_get_user_money(index); - -/* Gives money to user. If flash is 1, the difference between new and old amount will flash red or green. - */ -native cs_set_user_money(index, money, flash = 1); - -/* Does user have night vision goggles? - */ -native cs_get_user_nvg(index); - -/* Set nvgoggles to 1 to give night vision goggles to index. Set it to 0 to remove them. - */ -native cs_set_user_nvg(index, nvgoggles = 1); - -/* Returns 1 if user has the "skill" to plant bomb, else 0. Normally this would only be true for a terrorist carrying a bomb. - */ -native cs_get_user_plant(index); - -/* If plant is 1, a user will be set to be able to plant bomb within the usual bomb target areas if having one. - * You should use this if you give a player a weapon_c4, or he won't be able to plant it - * without dropping it and picking it up again (only possible for terrorists). - * If showbombicon is 1, the green C4 icon will be shown on user hud (if plant "skill" was enabled). - */ -native cs_set_user_plant(index, plant = 1, showbombicon = 1); - -/* Set user team without killing player. - * If model is anything other than CS_DONTCHANGE, that will be set as player's model. - */ -enum CsInternalModel { - CS_DONTCHANGE = 0, - CS_CT_URBAN = 1, - CS_T_TERROR = 2, - CS_T_LEET = 3, - CS_T_ARCTIC = 4, - CS_CT_GSG9 = 5, - CS_CT_GIGN = 6, - CS_CT_SAS = 7, - CS_T_GUERILLA = 8, - CS_CT_VIP = 9, - CZ_T_MILITIA = 10, - CZ_CT_SPETSNAZ = 11 +enum CsInternalModel +{ + CS_DONTCHANGE = 0, + CS_CT_URBAN = 1, + CS_T_TERROR = 2, + CS_T_LEET = 3, + CS_T_ARCTIC = 4, + CS_CT_GSG9 = 5, + CS_CT_GIGN = 6, + CS_CT_SAS = 7, + CS_T_GUERILLA = 8, + CS_CT_VIP = 9, + CZ_T_MILITIA = 10, + CZ_CT_SPETSNAZ = 11, }; -native cs_set_user_team(index, {CsTeams,_}:team, {CsInternalModel,_}:model = CS_DONTCHANGE); -/* Get team directly from player's entity. - * 1 = terrorist - * 2 = counter-terrorist - * 3 = spectator +/** + * Counter-Strike team id constants. */ -enum CsTeams { - CS_TEAM_UNASSIGNED = 0, - CS_TEAM_T = 1, - CS_TEAM_CT = 2, - CS_TEAM_SPECTATOR = 3 +enum CsTeams +{ + CS_TEAM_UNASSIGNED = 0, + CS_TEAM_T = 1, + CS_TEAM_CT = 2, + CS_TEAM_SPECTATOR = 3, }; -native CsTeams:cs_get_user_team(index, &{CsInternalModel,_}:model = CS_DONTCHANGE); -/* Is user vip? Returns 1 if true, 0 if false. +/** + * @endsection */ -native cs_get_user_vip(index); -/* If vip = 1, user is set to vip. - * If model = 1, then user's model will be changed to VIP model or random CT model if vip = 0. - * If scoreboard = 1, then scoreboard will be updated to show that user is VIP. - * This shouldn't be used for players on teams other than CT. - * NOTE: this is mostly useful for unsetting vips, so they can change teams and/or buy items properly. - * It does not alter game play; the one being VIP at start of round will retain internal status as VIP; terrorists - * can terminate him and accomplish their objective, etc. +/** + * Counter-Strike armor types for use with cs_[get|set]_user_armor(). */ - native cs_set_user_vip(index, vip = 1, model = 1, scoreboard = 1); - -/* Returns 1 of specified user has tk:ed (team killed). - */ -native cs_get_user_tked(index); - -/* Returns 1 of specified user has TKed (team killed). - * tk = 1: player has TKed - * tk = 0: player hasn't TKed - * Set subtract to how many frags to subtract. Set subtract to negative value to add frags. - */ -native cs_set_user_tked(index, tk = 1, subtract = 1); - -/* Returns different values depending on if user is driving a vehicle - and if so at what speed. - * 0: no driving - * 1: driving, but standing still - * 2-4: driving, different positive speeds - * 5: driving, negative speed (backing) - * Note: these values were tested quickly, they may differ. - */ -native cs_get_user_driving(index); - -/* Returns 1 if user has a shield, else 0. - */ -native cs_get_user_shield(index); - -/* Returns 1 if user is using a stationary gun, else 0. - */ -native cs_get_user_stationary(index); - -/* Returns armor value and sets by reference the armor type in second parameter. - */ -enum CsArmorType { - CS_ARMOR_NONE = 0, // no armor - CS_ARMOR_KEVLAR = 1, // armor - CS_ARMOR_VESTHELM = 2 // armor and helmet +enum CsArmorType +{ + CS_ARMOR_NONE = 0, // no armor + CS_ARMOR_KEVLAR = 1, // body vest only + CS_ARMOR_VESTHELM = 2, // vest and helmet }; -native cs_get_user_armor(index, &CsArmorType:armortype); -/* Use this instead of fun's set_user_armor. - * Appropriate message to update client's HUD will be sent if armortype is kevlar or vesthelm. +/** + * Map zone flags returned by cs_get_user_mapzones(). */ -native cs_set_user_armor(index, armorvalue, CsArmorType:armortype); +#define CS_MAPZONE_BUY (1<<0) // Buyzone +#define CS_MAPZONE_BOMBTARGET (1<<1) // Bomb target zone +#define CS_MAPZONE_HOSTAGE_RESCUE (1<<2) // Hostage rescue zone +#define CS_MAPZONE_ESCAPE (1<<3) // Terrorist escape zone +#define CS_MAPZONE_VIP_SAFETY (1<<4) // VIP escape zone -/* Returns 1 if specified weapon is in burst mode. - */ -native cs_get_weapon_burst(index); - -/* If burstmode = 1, weapon will be changed to burst mode, 0 and non-burst mode (semiautomatic/automatic) will be activated. - * Only GLOCK and FAMAS can enter/leave burst mode. - */ -native cs_set_weapon_burst(index, burstmode = 1); - -/* Returns 1 if weapon is silenced, else 0. - */ -native cs_get_weapon_silen(index); - -/* If silence = 1, weapon will be silenced, 0 and silencer will be removed. Only USP and M4A1 can be silenced. - */ -native cs_set_weapon_silen(index, silence = 1, draw_animation = 1); - -/* Returns amount of ammo in weapon's clip. - */ -native cs_get_weapon_ammo(index); - -/* Set amount of ammo in weapon's clip. - */ -native cs_set_weapon_ammo(index, newammo); - -/* Get weapon type. Corresponds to CSW_* in amxconst.inc: 1 is CSW_P228, 2 is CSW_SCOUT and so on... - */ -native cs_get_weapon_id(index); - -/* Returns 1 if no knives mode is enabled, else 0. - */ -native cs_get_no_knives(); - -/* Enabled no knives mode by calling this with value 1. Disabled with 0. - * No knives mode means that player will not be given a knife when spawning. - * You can still give knives (ie through fun's give_item). - */ -native cs_set_no_knives(noknives = 0); - -/* Spawns a Counter-Strike player - */ -native cs_user_spawn(player); - -/* Get what weapon type (CSW_*) an armoury_entity is. - */ -native cs_get_armoury_type(index); - -/* Set an armoury_entity to be of specified type. You will have to set the appropriate model. - * The second argument, type, should be a CSW_* constant. Not all weapons are supported by Counter-strike. - * Supported weapons/items: CSW_MP5NAVY, CSW_TMP, CSW_P90, CSW_MAC10, CSW_AK47, CSW_SG552, CSW_M4A1, CSW_AUG, CSW_SCOUT - * CSW_G3SG1, CSW_AWP, CSW_M3, CSW_XM1014, CSW_M249, CSW_FLASHBANG, CSW_HEGRENADE, CSW_VEST, CSW_VESTHELM, CSW_SMOKEGRENADE - */ -native cs_set_armoury_type(index, type); - -#define CS_MAPZONE_BUY (1<<0) -#define CS_MAPZONE_BOMBTARGET (1<<1) -#define CS_MAPZONE_HOSTAGE_RESCUE (1<<2) -#define CS_MAPZONE_ESCAPE (1<<3) -#define CS_MAPZONE_VIP_SAFETY (1<<4) - -/* Returns in bitwise form if the user is in a specific map zone. - * NOTE: If user can't plant (cs_get_user_plant(index) is 0) then cs_get_user_mapzones(index) & CS_MAPZONE_BOMBTARGET will return 0 too. - */ -native cs_get_user_mapzones(index); - -/* Zoom type enum. Used for get/set_user_zoom() natives. +/** + * Constants used for cs_[get|set]_user_zoom(). */ enum { - CS_RESET_ZOOM = 0, // Reset any zoom blocking (when using this type, mode has no effect) - CS_SET_NO_ZOOM, // Disable any sort of zoom (ie: to disable zoom in all weapons use this with mode=0) - CS_SET_FIRST_ZOOM, // Set first zoom (awp style) - CS_SET_SECOND_ZOOM, // Set second zoom (awp style) - CS_SET_AUGSG552_ZOOM, // Set aug/sg552 zoom style + CS_RESET_ZOOM = 0, // Reset any zoom blocking (mode has no effect) + CS_SET_NO_ZOOM, // Disable any sort of zoom + CS_SET_FIRST_ZOOM, // Set first zoom level (AWP style) + CS_SET_SECOND_ZOOM, // Set second zoom level (AWP style) + CS_SET_AUGSG552_ZOOM, // Set AUG/SG552 zoom style }; -/* Sets a weapon zoom type on a player, any zoom type will work for all weapons, so you can even set an awp zoom to pistols :D - * The 2nd param has to be one of the above zoom types in the enum. Mode can only be 0 or 1. - * If mode=0 (blocking mode), the user will be forced to use the zoom type set by the native, and wont be able to change it (even by changing weapon) - * until the native resets the zoom with CS_RESET_ZOOM. - * If mode=1 the user will be able to restore back to a normal view by changing weapon. + +/** + * Constants used for the CS_OnBuy() and CS_OnBuyAttempt() forwards. + * + * @note While these mostly overlap with the CSW_* constants the CSI_* constants + * contain custom AMXX values that do not correspond to any real value in + * the game. The CSI_* constants should therefore be used for consistency. + */ +#define CSI_P228 CSW_P228 +#define CSI_SCOUT CSW_SCOUT +#define CSI_HEGRENADE CSW_HEGRENADE +#define CSI_XM1014 CSW_XM1014 +#define CSI_C4 CSW_C4 +#define CSI_MAC10 CSW_MAC10 +#define CSI_AUG CSW_AUG +#define CSI_SMOKEGRENADE CSW_SMOKEGRENADE +#define CSI_ELITE CSW_ELITE +#define CSI_FIVESEVEN CSW_FIVESEVEN +#define CSI_UMP45 CSW_UMP45 +#define CSI_SG550 CSW_SG550 +#define CSI_GALIL CSW_GALIL +#define CSI_FAMAS CSW_FAMAS +#define CSI_USP CSW_USP +#define CSI_GLOCK18 CSW_GLOCK18 +#define CSI_AWP CSW_AWP +#define CSI_MP5NAVY CSW_MP5NAVY +#define CSI_M249 CSW_M249 +#define CSI_M3 CSW_M3 +#define CSI_M4A1 CSW_M4A1 +#define CSI_TMP CSW_TMP +#define CSI_G3SG1 CSW_G3SG1 +#define CSI_FLASHBANG CSW_FLASHBANG +#define CSI_DEAGLE CSW_DEAGLE +#define CSI_SG552 CSW_SG552 +#define CSI_AK47 CSW_AK47 +#define CSI_P90 CSW_P90 +#define CSI_SHIELDGUN CSW_SHIELDGUN +#define CSI_VEST CSW_VEST // Custom +#define CSI_VESTHELM CSW_VESTHELM // Custom +#define CSI_DEFUSER 33 // Custom +#define CSI_NVGS 34 // Custom +#define CSI_PRIAMMO 36 // Custom +#define CSI_SECAMMO 37 // Custom + +/** + * Returns client's deaths. + * + * @param index Client index + * + * @return Client deaths + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_deaths(index); + +/** + * Sets client's deaths. + * + * @param index Client index + * @param newdeaths New value to set + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_deaths(index, newdeaths); + +/** + * Returns index of the entity that a hostage is following. + * + * @note Hostages can theoretically follow any entity in the game, so the + * returned entity index is not necessarily a client index. + * @note This native does not work on Condition Zero, which has a different + * hostage AI than other versions of Counter-Strike. + * + * @param index Hostage entity index + * + * @return Entity index if hostage is following something, 0 otherwise + * @error If the provided entity index is not a hostage, an error will + * be thrown. + */ +native cs_get_hostage_foll(index); + +/** + * Sets hostage to follow an entity. + * + * @note Hostages can theoretically follow any entity in the game, so the + * followedindex does not have to be a client index. + * @note This native does not work on Condition Zero, which has a different + * hostage AI than other versions of Counter-Strike. + * + * @param index Hostage entity index + * @param followedindex New entity to follow + * + * @noreturn + * @error If the provided entity index is not a hostage, an + * error will be thrown. + */ +native cs_set_hostage_foll(index, followedindex = 0); + +/** + * Returns unique id of a hostage. + * + * @param index Hostage entity index + * + * @return Unique hostage id + * @error If the provided entity index is not a hostage, an error will + * be thrown. + */ +native cs_get_hostage_id(index); + +/** + * Returns amount of ammo in the client's backpack for a specific weapon. + * + * @note For a list of possible weapon ids see the CSW_* constants in + * amxconst.inc + * @note Some weapons share ammo types and therefore ammo backpack pools. List + * of ammo types: + * ammo_338magnum - awp + * ammo_762nato - scout, ak47, g3sg1 + * ammo_556natobox - m249 + * ammo_556nato - famas, m4a1, aug, sg550, galil, sg552 + * ammo_buckshot - m3, xm1014 + * ammo_45acp - usp, ump45, mac10 + * ammo_57mm - fiveseven, p90 + * ammo_50ae - deagle + * ammo_357sig - p228 + * ammo_9mm - glock, mp5, tmp, elites + * / - hegrenade + * / - flashbang + * / - smokegrenade + * + * @param index Client index + * @param weapon Weapon id + * + * @return Amount of ammo in backpack + * @error If the client index is not within the range of 1 to + * MaxClients, the client is not connected, or an invalid + * weapon id is provided, an error will be thrown. + */ +native cs_get_user_bpammo(index, weapon); + +/** + * Sets amount of ammo in the client's backpack for a specific weapon. + * + * @note For a list of possible weapon ids see the CSW_* constants in + * amxconst.inc + * @note Some weapons share ammo types and therefore ammo backpack pools. List + * of ammo types: + * awp - ammo_338magnum + * scout, ak47, g3sg1 - ammo_762nato + * m249 - ammo_556natobox + * famas, m4a1, aug, sg550, galil, sg552 - ammo_556nato + * m3, xm1014 - ammo_buckshot + * usp, ump45, mac10 - ammo_45acp + * fiveseven, p90 - ammo_57mm + * deagle - ammo_50ae + * p228 - ammo_357sig + * glock, mp5, tmp, elites - ammo_9mm + * hegrenade - / + * flashbang - / + * smokegrenade - / + * + * @param index Client index + * @param weapon Weapon id + * @param amount New backpack ammo amount to set + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, the client is not connected, or an invalid + * weapon id is provided, an error will be thrown. + */ +native cs_set_user_bpammo(index, weapon, amount); + +/** + * Returns if the client has a defuse kit. + * + * @param index Client index + * + * @return 1 if the client has a defuse kit, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, the client is not connected, or an invalid + * weapon id is provided, an error will be thrown. + */ +native cs_get_user_defuse(index); + +/** + * Sets the client's defusekit status and allows to set a custom HUD icon and + * color. + * + * @param index Client index + * @param defusekit If nonzero the client will have a defusekit, otherwise + * it will be removed + * @param r Red component of icon color + * @param g Green component of icon color + * @param b Blue component of icon color + * @param icon HUD sprite to use as icon + * @param flash If nonzero the icon will flash red + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_defuse(index, defusekit = 1, r = 0, g = 160, b = 0, icon[] = "defuser", flash = 0); + +/** + * Returns if the client is inside a buyzone. + * + * @param index Client index + * + * @return 1 if the client is inside a buyzone, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_buyzone(index); + +/** + * Returns if the client has a primary weapon or a shield in the inventory. + * + * @param index Client index + * + * @return 1 if the client has a primary weapon or shield in the + * inventory, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_hasprim(index); + +/** + * Retrieves the client's player model. + * + * @param index Client index + * @param model Buffer to copy model to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_model(index, model[], len); + +/** + * Sets the client's player model. + * + * @note This is not a one-time set. The CStrike module will remember the + * selected model and try to prevent attempts at changing the player + * model, or immediately re-apply it if necessary. + * + * @param index Client index + * @param model Model name + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_set_user_model(index, const model[]); + +/** + * Resets the client's model. + * + * @note This lifts the model-lock set by a previous cs_set_user_model() call. + * + * @param index Client index + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_reset_user_model(index); + +/** + * Returns the client's amount of money. + * + * @param index Client index + * + * @return Amount of money + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_money(index); + +/** + * Sets the client's amount of money. + * + * @param index Client index + * @param money New amount to set + * @param flash If nonzero the HUD will flash the difference between new + * and old amount in red or green + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_set_user_money(index, money, flash = 1); + +/** + * Returns if the client's has night vision goggles. + * + * @param index Client index + * + * @return 1 if user has NVG, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_nvg(index); + +/** + * Sets the client's night vision goggles. + * + * @param index Client index + * @param nvgoogles If nonzero the NVG will be added to the client's + * inventory, otherwise they will be removed from it + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_nvg(index, nvgoggles = 1); + +/** + * Returns if the client has the ability to plant the bomb. + * + * @note Only with this set can the client plant the bomb within the usual bomb + * target areas. If this is not set the user can not plant the bomb, even + * when he has one in the inventory. + * + * @param index Client index + * + * @return 1 if the client is able to plant the bomb, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_plant(index); + +/** + * Sets the client's ability to plant the bomb and displays or hides the bomb + * HUD icon. + * + * @note Only with this set can the client plant the bomb within the usual bomb + * target areas. If this is not set the user can not plant the bomb, even + * when he has one in the inventory. This is only correctly set when the + * client touches a bomb and picks it up "manually" (only possible for + * Terrorists), so this should be used if the bomb is added to the + * inventory through other means. + * + * @param index Client index + * @param plant If nonzero the client will be able to plant the bomb, + * otherwise he will be unable to + * @param showbombicon If nonzero the green C4 icon will be displayed on the + * client's hud, otherwise it will be hidden + * + * @return 1 if the client is able to plant the bomb, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_plant(index, plant = 1, showbombicon = 1); + +/** + * Sets the client's team without killing the player, and sets the client model. + * + * @note For a list of valid team ids see the CsTeams enum, and for a list of + * valid internal model ids see the CsInternalModel enum. + * + * @param index Client index + * @param team Team id + * @param model Internal model id, if CS_DONTCHANGE the game will choose the + * model + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_set_user_team(index, {CsTeams,_}:team, {CsInternalModel,_}:model = CS_DONTCHANGE); + +/** + * Returns the client's team and optionally the model id. + * + * @note For a list of valid team ids see the CsTeams enum, and for a list of + * valid internal model ids see the CsInternalModel enum. + * + * @param index Client index + * @param model Optional variable to store model id in + * + * @return Team id + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native CsTeams:cs_get_user_team(index, &{CsInternalModel,_}:model = CS_DONTCHANGE); + +/** + * Returns if the client is a VIP. + * + * @param index Client index + * + * @return 1 if the client is a VIP, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_vip(index); + +/** + * Sets the client's VIP status and displayed model and scoreboard flag. + * + * @note This is mostly useful for removing VIP status so the client can change + * teams and/or buy items properly. It does not alter gameplay, the player + * that is selected as VIP at the start of a round will retain the + * internal VIP status and remain the primary objective for the game mode. + * + * @param index Client index + * @param vip If nonzero the client will be made a VIP, otherwise the + * VIP status will be removed + * @param model If nonzero the client's model will be changed to the VIP + * model, otherwise a random CT model will be selected + * @param scoreboard If nonzero the scoreboard will be updated to reflect the + * new VIP status + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_vip(index, vip = 1, model = 1, scoreboard = 1); + +/** + * Returns if the client has committed a team kill in the current round. + * + * @note If this is set to 1 the client will be punished at the start of the + * next round depending on the value of the mp_tkpunish cvar. The team + * kill status is then reset. + * + * @param index Client index + * + * @return 1 if the client has committed a team kill, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_tked(index); + +/** + * Sets the client's team kill status, indicating whether the client has + * committed a team kill in the current round. + * + * @note If this is set to 1 the client will be punished at the start of the + * next round depending on the value of the mp_tkpunish cvar. The team + * kill status is then reset. + * + * @param index Client index + * @param tk Team kill status + * @param subtract Amount of frags to subtract, negative values add frags + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_set_user_tked(index, tk = 1, subtract = 1); + +/** + * Returns if the client is currently driving a vehicle and if so, indicates + * the speed. + * + * @param index Client index + * + * @return 0 if the client is not driving, 1 if driving a vehicle but + * not moving, 2 to 4 if driving positive speeds, 5 if + * driving at a negative speed (backing) + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_driving(index); + +/** + * Returns if the client has a shield in the inventory. + * + * @param index Client index + * + * @return 1 if the client has a shield, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_shield(index); + +/** + * Returns if the client is using a stationary gun. + * + * @param index Client index + * + * @return 1 if the client uses a stationary gun, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_stationary(index); + +/** + * Returns the client's armor value and retrieves the type of armor. + * + * @note For a list of possible armor types see the CsArmorType enum. + * + * @param index Client index + * @param armortype Variable to store armor type in + * + * @return Amount of armor, 0 if client has no armor + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_get_user_armor(index, &CsArmorType:armortype); + +/** + * Sets the client's armor value the type of armor. + * + * @note For a list of possible armor types see the CsArmorType enum. + * @note Sends the appropriate message to update the client's HUD. + * + * @param index Client index + * @param armorvalue Amount of armor to set + * @param armortype CS armor type + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error + * will be thrown. + */ +native cs_set_user_armor(index, armorvalue, CsArmorType:armortype); + +/** + * Returns if the weapon is in burst mode. + * + * @note Only the Glock and Famas can return 1 as they are the only guns in the + * game that have a burst fire mode. + * @note This native does not check that the provided entity is actually a + * weapon entity. It will return incorrect values for non-weapon entities. + * + * @param index Weapon entity index + * + * @return 1 if the weapon is in burst mode, 0 otherwise + * @error If an invalid entity index or a client index is provided, + * an error will be thrown. + */ +native cs_get_weapon_burst(index); + +/** + * Sets the weapon's burst mode. + * + * @note Only the Glock and Famas can be set to burst fire mode as they are the + * only guns in the game that provide such a mode. + * @note This native does not check that the provided entity is actually a + * weapon entity. It will result in undefined behavior if used on + * non-weapon entities. + * + * @param index Weapon entity index + * @param burstmode If nonzero the weapon will be put into burstmode, + * otherwise the burst mode will be removed + * + * @return 1 if burst mode set successfully, 0 if entity is not + * an applicable weapon + * @error If an invalid entity index or a client index is + * provided, an error will be thrown. + */ +native cs_set_weapon_burst(index, burstmode = 1); + +/** + * Returns if the weapon is in silenced mode. + * + * @note Only the USP and M4A1 can return 1 as they are the only guns in the + * game that have a silenced fire mode. + * @note This native does not check that the provided entity is actually a + * weapon entity. It will return incorrect values for non-weapon entities. + * + * @param index Weapon entity index + * + * @return 1 if the weapon is in silenced mode, 0 otherwise + * @error If an invalid entity index or a client index is provided, + * an error will be thrown. + */ +native cs_get_weapon_silen(index); + +/** + * Sets the weapon's silenced mode. + * + * @note Only the USP and M4A1 can be set to silenced fire mode as they are the + * only guns in the game that provide such a mode. + * @note This native does not check that the provided entity is actually a + * weapon entity. It will result in undefined behavior if used on + * non-weapon entities. + * + * @param index Weapon entity index + * @param silence If nonzero the weapon will be put into silenced + * mode, otherwise the silenced mode will be removed + * @param draw_animation If nonzero and the weapon is currently held by a + * client, the appropriate weapon animation will be + * played + * + * @return 1 if silenced mode set successfully, 0 if entity is + * not an applicable weapon + * @error If an invalid entity index or a client index is + * provided, an error will be thrown. + */ +native cs_set_weapon_silen(index, silence = 1, draw_animation = 1); + +/** + * Returns the amount of ammo in weapon's magazine. + * + * @note This native does not check that the provided entity is actually a + * weapon entity. It will return incorrect values for non-weapon entities. + * + * @param index Weapon entity index + * + * @return Amount of ammo in magazine + * @error If an invalid entity index or a client index is provided, + * an error will be thrown. + */ +native cs_get_weapon_ammo(index); + +/** + * Sets the amount of ammo in weapon's clip. + * + * @note This native does not check that the provided entity is actually a + * weapon entity. It will result in undefined behavior if used on + * non-weapon entities. + * + * @param index Weapon entity index + * @param newammo New ammo amount + * + * @noreturn + * @error If an invalid entity index or a client index is provided, + * an error will be thrown. + */ +native cs_set_weapon_ammo(index, newammo); + +/** + * Returns the weapon id of an entity. + * + * @note For a list of possible weapon ids see the CSW_* constants in + * amxconst.inc + * @note This native does not check that the provided entity is actually a + * weapon entity. It will return incorrect values for non-weapon entities. + * + * @param index Weapon entity index + * + * @return Weapon id + * @error If an invalid entity index or a client index is provided, + * an error will be thrown. + */ +native cs_get_weapon_id(index); + +/** + * Returns if "no knives" mode is enabled. + * + * @note "No knives" mode means that the CStrike module will prevent the game + * from creating (and thus attaching) "weapon_knife" entities. This means + * that clients will spawn without knives, but knives can still be put + * into the client inventories directly. + * + * @return 1 if "no knives" mode is enabled, 0 otherwise + */ +native cs_get_no_knives(); + +/** + * Enables or disables the "no knives" mode. + * + * @note "No knives" mode means that the CStrike module will prevent the game + * from creating (and thus attaching) "weapon_knife" entities. This means + * that clients will spawn without knives, but knives can still be put + * into the client inventories directly. + * + * @param noknives If nonzero enable "no knives" mode, disable otherwise + * + * @noreturn + */ +native cs_set_no_knives(noknives = 0); + +/** + * Sets a dead client up for spawning. + * + * @note This sets the client deadflag and triggers a client think, effectively + * making the game respawn the client. Should only be used on dead + * clients. + * + * @param player Client index + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_user_spawn(player); + +/** + * Returns the armoury entity's weapon id. + * + * @note Not all weapon ids are supported by Counter-Strike, an armoury entity + * can not be a pistol, a knife or a bomb for exmaple. The full list is: + * CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG, + * CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1, + * CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG, + * CSW_SG552, CSW_AK47, CSW_P90 + * + * @param index Armoury entity index + * + * @return Weapon id + * @error If a non-armoury entity is provided, an error will be + * thrown. + */ +native cs_get_armoury_type(index); + +/** + * Sets the amoury entity type. + * + * @note Not all weapon ids are supported by Counter-Strike, an armoury entity + * can not be a pistol, a knife or a bomb for exmaple. The full list is: + * CSW_SCOUT, CSW_HEGRENADE, CSW_XM1014, CSW_MAC10, CSW_AUG, + * CSW_SMOKEGRENADE, CSW_AWP, CSW_MP5NAVY, CSW_M249, CSW_M3, CSW_M4A1, + * CSW_TMP, CSW_G3SG1, CSW_VEST, CSW_VESTHELM, CSW_FLASHBANG, + * CSW_SG552, CSW_AK47, CSW_P90 + * @note This does not update the entity model. + * + * @param index Armoury entity index + * @param type Weapon id + * + * @noreturn + * @error If a non-armoury entity is provided, an error will be + * thrown. + */ +native cs_set_armoury_type(index, type); + +/** + * Returns the map zones the client is inside of as a bitflag value. + * + * @note If the user does not have the ability to plant (cs_get_user_plant() + * returns 0) then the bitflag will not contain CS_MAPZONE_BOMBTARGET. + * @nore For a list of possible zone flags see the CS_MAPZONE_* constants. + * + * @param index Client index + * + * @return Bitflag value of map zones + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. + */ +native cs_get_user_mapzones(index); + +/** + * Sets a zoom type on the client. + * + * @note Zoom types are not tied to their intended weapons, so any zoom type can + * be combined with any weapon. + * @note For a list of possible zoom types see the zoom type enum above + * (CS_*_ZOOM constants). + * + * @param index Client index + * @param type Zoom type + * @param mode If zero (blocking) the client will be forced to use the zoom + * type set and won't be able to change it until it is reset + * with CS_RESET_ZOOM, otherwise the user can restore back to + * normal as usual + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, the client is not connected, or an invalid zoom + * type is provided, an error will be thrown. */ native cs_set_user_zoom(index, type, mode); -/* Returns how a user is zooming during the native call. Values correspond to the above enum, but will return 0 if an error occurred. +/** + * Returns if the client is zooming. + * + * @note For a list of possible zoom types see the zoom type enum above + * (CS_*_ZOOM constants). + * + * @param index Client index + * + * @return Zoom type if the user is zoomed in, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. */ native cs_get_user_zoom(index); -/* Returns the submodel setting of the player. - * If this is 1, then the user has a backpack or defuser on their model (depending on team) +/** + * Returns if a submodel is set on the client. + * + * @note In Counter-Strike the submodel setting determines whether the user has + * a bomb backpack (if a Terrorist) or a defuse kit (if a CT) on their + * model. + * + * @param index Client index + * + * @return 1 if submodel is set, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + * thrown. */ native cs_get_user_submodel(index); -/* Sets the submodel setting of the player. - * If this is 1, then the user has a backpack or defuser on their model (depending on team) - * 0 removes it. +/** + * Sets the submodel on a client. + * + * @note In Counter-Strike the submodel setting determines whether the user has + * a bomb backpack (if a Terrorist) or a defuse kit (if a CT) on their + * model. + * + * @param index Client index + * @param value If nonzero the submodel is set, otherwise it is removed + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be */ native cs_set_user_submodel(index, value); -/* Gets or sets the user's last activity time. This is the time that CS's internal afk kicker - * checks to see who has been afk too long. +/** + * Returns the client's last activity time. + * + * @note This is the time that the internal Counter-Strike afk kicker uses to + * see who has been inactive too long. + * + * @param index Client index + * + * @return Last activity time + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be */ native Float:cs_get_user_lastactivity(index); +/** + * Sets the client's last activity time. + * + * @note This is the time that the internal Counter-Strike afk kicker uses to + * see who has been inactive too long. + * + * @param index Client index + * @param value New last activity time + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + */ native cs_set_user_lastactivity(index, Float:value); -/* Gets or sets the number of hostages that a user has killed. +/** + * Returns the amount of hostages that the client has killed. + * + * @note This is the value that the internal Counter-Strike hostage punisher + * uses to determine if a client should be kicked, depending on the + * value of the mp_hostagepenalty value. + * + * @param index Client index + * + * @return Amount of hostages killed + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be */ native cs_get_user_hostagekills(index); +/** + * Sets the amount of hostages that the client has killed. + * + * @note This is the value that the internal Counter-Strike hostage punisher + * uses to determine if a client should be kicked, depending on the + * value of the mp_hostagepenalty value. The punisher only checks this + * value when a hostage is actually killed, so setting this will not cause + * a client to be kicked until they actually kill a hostage. + * + * @param index Client index + * @param value New amount of hostages killed + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients, or the client is not connected, an error will be + */ native cs_set_user_hostagekills(index, value); -/* Gets or sets the time that the hostage was last used. +/** + * Returns the last time a hostage was used. + * + * @param index Hostage entity + * + * @return Last use time + * @error If the provided entity index is not a hostage, an error will + * be thrown. */ native Float:cs_get_hostage_lastuse(index); +/** + * Sets the last time a hostage was used. + * + * @param index Hostage entity + * @param value New last use time + * + * @noreturn + * @error If the provided entity index is not a hostage, an error will + * be thrown. + */ native cs_set_hostage_lastuse(index, Float:value); -/* Gets or sets the time which the hostage can next be used. +/** + * Returns the next time a hostage can be used. + * + * @param index Hostage entity + * + * @return Next use time + * @error If the provided entity index is not a hostage, an error will + * be thrown. */ native Float:cs_get_hostage_nextuse(index); +/** + * Sets the next time a hostage can be used. + * + * @param index Hostage entity + * @param value New next use time + * + * @noreturn + * @error If the provided entity index is not a hostage, an error will + * be thrown. + */ native cs_set_hostage_nextuse(index, Float:value); -/* Gets or sets the time in which the C4 will explode. +/** + * Returns the time the bomb will explode. + * + * @param index C4 entity + * + * @return Explosion time + * @error If the provided entity index is not a bomb, an error will be + * thrown. */ native Float:cs_get_c4_explode_time(index); +/** + * Sets the time the bomb will explode. + * + * @param index C4 entity + * @param value New explosion time + * + * @noreturn + * @error If the provided entity index is not a bomb, an error will be + * thrown. + */ native cs_set_c4_explode_time(index, Float:value); -/* Gets or sets whether the C4 is being defused. +/** + * Returns if the bomb is being defused. + * + * @param index C4 entity + * + * @return 1 if the bomb is being defused, 0 otherwise + * @error If the provided entity index is not a bomb, an error will be + * thrown. */ native bool:cs_get_c4_defusing(c4index); +/** + * Sets if the bomb is being defused. + * + * @param index C4 entity + * @param defusing True if the bomb should be defused, false otherwise + * + * @noreturn + * @error If the provided entity index is not a bomb, an error will be + * thrown. + */ native cs_set_c4_defusing(c4index, bool:defusing); /** @@ -369,7 +1100,7 @@ native cs_set_c4_defusing(c4index, bool:defusing); * * @param classname Entity class name * - * @return Index of the created entity, 0 otherwise. + * @return Index of the created entity (> 0), 0 otherwise */ native cs_create_entity(const classname[]); @@ -393,74 +1124,46 @@ native cs_create_entity(const classname[]); native cs_find_ent_by_class(start_index, const classname[]); /** - * Called when CS internally fires a command to a player. It does this for a few - * functions, most notably rebuy/autobuy functionality. This is also used to pass - * commands to CZ bots internally. + * Called when CS internally fires a command to a player. * - * @param id Client index. - * @param cmd Command string. - * @return PLUGIN_HANDLED to block, PLUGIN_CONTINUE for normal operation. + * @note This is most notably used by the rebuy/autobuy functionality, + * Condition Zero also uses this to pass commands to bots internally. + * + * @param id Client index + * @param cmd Command string + * + * @return PLUGIN_CONTINUE to let the command continue + * PLUGIN_HANDLED to block the command */ forward CS_InternalCommand(id, const cmd[]); - /** - * The following constants are used with CS_OnBuy[Attempt] forwards. - */ -#define CSI_P228 CSW_P228 -#define CSI_SCOUT CSW_SCOUT -#define CSI_HEGRENADE CSW_HEGRENADE -#define CSI_XM1014 CSW_XM1014 -#define CSI_C4 CSW_C4 -#define CSI_MAC10 CSW_MAC10 -#define CSI_AUG CSW_AUG -#define CSI_SMOKEGRENADE CSW_SMOKEGRENADE -#define CSI_ELITE CSW_ELITE -#define CSI_FIVESEVEN CSW_FIVESEVEN -#define CSI_UMP45 CSW_UMP45 -#define CSI_SG550 CSW_SG550 -#define CSI_GALIL CSW_GALIL -#define CSI_FAMAS CSW_FAMAS -#define CSI_USP CSW_USP -#define CSI_GLOCK18 CSW_GLOCK18 -#define CSI_AWP CSW_AWP -#define CSI_MP5NAVY CSW_MP5NAVY -#define CSI_M249 CSW_M249 -#define CSI_M3 CSW_M3 -#define CSI_M4A1 CSW_M4A1 -#define CSI_TMP CSW_TMP -#define CSI_G3SG1 CSW_G3SG1 -#define CSI_FLASHBANG CSW_FLASHBANG -#define CSI_DEAGLE CSW_DEAGLE -#define CSI_SG552 CSW_SG552 -#define CSI_AK47 CSW_AK47 -#define CSI_P90 CSW_P90 -#define CSI_SHIELDGUN CSW_SHIELDGUN -#define CSI_VEST CSW_VEST // Custom -#define CSI_VESTHELM CSW_VESTHELM // Custom -#define CSI_DEFUSER 33 // Custom -#define CSI_NVGS 34 // Custom -#define CSI_PRIAMMO 36 // Custom -#define CSI_SECAMMO 37 // Custom - -/** - * Called when a player attempts to purchase an item. - * This is ususally called right away on buy commands issued by a player. - * - * @note Return PLUGIN_CONTINUE to allow the purchase or return a higher action to deny. + * Called when a client attempts to purchase an item. * - * @param index Player index. - * @param item Item index, see CSI_* constants. + * @note This is called immediately when the client issues a buy command. The + * game has not actually checked if the client can actually buy the + * weapon. + * @note For a list of possible item ids see the CSI_* constants. + * + * @param index Client index + * @param item Item id + * + * @return PLUGIN_CONTINUE to let the buy attempt continue + * PLUGIN_HANDLED to block the buy attempt */ forward CS_OnBuyAttempt(index, item); /** - * Called when a player purchases an item. - * This usually called right before a player gets the purchased item. + * Called when a client purchases an item. * - * @note Return PLUGIN_CONTINUE to allow the purchase or return a higher action to deny. + * @note This is called right before the user receives the item and before the + * money is deducted from their cash reserves. + * @note For a list of possible item ids see the CSI_* constants. * - * @param index Player index. - * @param item Item index, see CSI_* constants. + * @param index Client index + * @param item Item id + * + * @return PLUGIN_CONTINUE to let the buy continue + * PLUGIN_HANDLED to block the buy */ forward CS_OnBuy(index, item); diff --git a/plugins/include/csx.inc b/plugins/include/csx.inc index 3616d178..70d90883 100755 --- a/plugins/include/csx.inc +++ b/plugins/include/csx.inc @@ -27,65 +27,237 @@ #pragma library csx #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 { - MapObjective_Bomb = (1<<0), - MapObjective_Hostage = (1<<1), - MapObjective_Vip = (1<<2), - MapObjective_Escape = (1<<3), + MapObjective_Bomb = (1<<0), + MapObjective_Hostage = (1<<1), + MapObjective_Vip = (1<<2), + 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. - * See MapObjective_* constants. + * @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 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[] = ""); + +/** + * Trigger 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); + +/** + * Add 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); // weapon id , player id + +/** + * 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(); From 828d9971a4a43559cb44913c43406809f6471be1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Fri, 20 Feb 2015 15:35:06 +0100 Subject: [PATCH 06/10] cvars: Style touchups, add missing stuff, update notes about named access --- plugins/include/cvars.inc | 281 +++++++++++++++++++++----------------- 1 file changed, 152 insertions(+), 129 deletions(-) diff --git a/plugins/include/cvars.inc b/plugins/include/cvars.inc index bc256fb4..38cca88c 100644 --- a/plugins/include/cvars.inc +++ b/plugins/include/cvars.inc @@ -13,39 +13,56 @@ #define _cvars_included /** - * CVAR flags for create_cvar() + * CVAR flags for create_cvar() and register_cvar(). */ -#define FCVAR_NONE 0 /* No flags */ -#define FCVAR_ARCHIVE 1 /* Set to cause it to be saved to vars.rc */ -#define FCVAR_USERINFO 2 /* Changes the client's info string */ -#define FCVAR_SERVER 4 /* Notifies players when changed */ -#define FCVAR_EXTDLL 8 /* Defined by external 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_SPONLY 64 /* This cvar cannot 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_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_NOEXTRAWHITEPACE 512 /* Strip trailing/leading white space from this cvar */ +#define FCVAR_NONE 0 // No special behavior +#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 // Cvar changes the client's info string +#define FCVAR_SERVER 4 // Clients get notified when cvar value is changed +#define FCVAR_EXTDLL 8 // Defined by an external DLL +#define FCVAR_CLIENTDLL 16 // Defined by the client DLL +#define FCVAR_PROTECTED 32 // Cvar value is masked from outside access, should be used for sensitive cvars like passwords +#define FCVAR_SPONLY 64 // Cvar can't be changed by clients connected to a multiplayer server +#define FCVAR_PRINTABLEONLY 128 // The cvar string value can not contain unprintable characters +#define FCVAR_UNLOGGED 256 // If the cvar is FCVAR_SERVER, don't log changes to a file/the console +#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. * - * @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 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 * set_pcvar_* set of functions. * - * @param name Cvar name - * @param string Default cvar value - * @param flags Optional bitsum of flags specifying cvar behavior - * @param description Optional description of the cvar - * @param has_min Optional boolean that specifies if the cvar has a minimum value - * @param min_val Minimum floating point value - * @param has_max Optional boolean that specifies if the cvar has a maximum value - * @param max_val Maximum floating point value + * @param name Cvar name + * @param string Default cvar value + * @param flags Optional bitsum of flags specifying cvar behavior + * @param description Optional description of the cvar + * @param has_min Optional boolean that specifies if the cvar has a + * minimum value + * @param min_val Minimum 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); @@ -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 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. + * 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 * 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 */ -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. @@ -79,8 +98,9 @@ native cvar_exists(const cvar[]); /** * Returns the cvar pointer of the specified cvar. * - * @note A pointer is also returned by register_cvar(). Plugins can (and should) - * retrieve and use pointers for already existing mod cvars. + * @note A pointer is also returned by register_cvar() and create_cvar(). + * Plugins can (and should) retrieve and use pointers for already existing + * mod cvars. * * @param cvar Cvar name to find * @@ -93,56 +113,59 @@ native get_cvar_pointer(const cvar[]); * * @note Changing the cvar value from within this forward can lead to infinite * 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 - * old_value - String containing the value of the cvar before it was changed - * new_value - String containing the new value of the cvar + * pcvar - Pointer to cvar that was changed + * old_value - Buffer containing the previous 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 callback Name of callback function + * @param pcvar Pointer to cvar + * @param callback Name of callback function * - * @return Callback handle that can be used with [disable|enable]_cvar_hook - * @error Invalid cvar pointer or invalid callback function + * @return Callback handle that can be used with + * [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[]); /** - * 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 - * @error Invalid hook handle + * @param handle Forward to disable + * @error If an invalid hook handle is provided, an error will be + * thrown. */ 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 - * @error Invalid hook handle + * @param handle Forward to enable + * @error If an invalid hook handle is provided, an error will be + * thrown. */ native enable_cvar_hook(cvarhook:handle); /** - * Returns flags of a cvar. The cvar is accessed by name. + * Returns a 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 Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the get_pcvar_flags function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent get_pcvar_flags() function should be used + * instead. * - * @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[]); @@ -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 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. - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the set_pcvar_flags function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent set_pcvar_flags() function should be used + * instead. * * @param cvar Cvar name to remove flags from * @param flags Bitflag sum of flags to set @@ -173,11 +195,8 @@ native set_cvar_flags(const cvar[], flags); * and "sv_cheats" cvars. * @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 Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the set_pcvar_flags function. - * + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the set_pcvar_flags() function should be used instead. * * @param cvar Cvar name to remove flags from * @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. * - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the get_pcvar_string function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent get_pcvar_string() function should be used + * instead. * * @param cvar Cvar name to retrieve value from * @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. * - * @note Accessing a cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the set_pcvar_string function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent set_pcvar_string() function should be used + * instead. * * @param cvar Cvar name to set value of * @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. * - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the get_pcvar_float function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent get_pcvar_float() function should be used + * instead. * * @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. * - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the set_pcvar_float function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent set_pcvar_float() function should be used + * instead. * * @param cvar Cvar name to set value of * @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. * - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the get_pcvar_num function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent get_pcvar_num() function should be used + * instead. * * @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. * - * @note Accessing a Cvar by name requires this function to walk through the - * engine's cvar list every time, which can result in a considerable waste - * of processing time, especially if many cvars have been registered. For - * a vastly superior alternative look at the set_pcvar_num function. + * @note Accessing a Cvar by name is slower than direct pointer access, which is + * why the otherwise equivalent set_pcvar_num() function should be used + * instead. * * @param cvar Cvar name to set value of * @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 * * @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); @@ -298,7 +312,8 @@ native get_pcvar_flags(pcvar); * @param flags Bitflag sum of flags to set * * @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); @@ -308,7 +323,8 @@ native set_pcvar_flags(pcvar, flags); * @param pcvar Pointer to cvar to retrieve value from * * @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); @@ -318,7 +334,8 @@ native get_pcvar_num(pcvar); * @param pcvar Pointer to cvar to retrieve value from * * @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); @@ -329,7 +346,8 @@ native bool:get_pcvar_bool(pcvar); * @param num Value to set cvar to * * @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); @@ -340,7 +358,8 @@ native set_pcvar_num(pcvar, num); * @param num Value to set cvar to * * @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); @@ -350,7 +369,8 @@ native set_pcvar_bool(pcvar, bool:num); * @param pcvar Pointer to cvar to retrieve value from * * @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); @@ -361,7 +381,8 @@ native Float:get_pcvar_float(pcvar); * @param num Value to set cvar to * * @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); @@ -373,7 +394,8 @@ native set_pcvar_float(pcvar, Float:num); * @param maxlen Maximum size of the 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); @@ -384,40 +406,36 @@ native get_pcvar_string(pcvar, string[], maxlen); * @param string Value to set cvar to * * @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[]); /** - * Cvar bound values used with get/set_pcvar_bounds() - */ -enum CvarBounds -{ - CvarBound_Upper = 0, - CvarBound_Lower -}; - -/** - * Retrieves the specified value bounds of a cvar. + * Retrieves the specified value boundary of a cvar. * * @param pcvar Pointer to cvar - * @param type Type of bound to retrieve, CvarBound_Lower or CvarBound_Upper - * @param value Variable to store the specified bound to + * @param type Type of boundary to retrieve + * @param value Variable to store the specified boundary to * - * @return True if the cvar has the specified bound set, false otherwise. - * @error If an invalid cvar pointer or CvarBounds value, an error is thrown. + * @return True if the cvar has a boundary set, false otherwise + * @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); /** - * Sets the specified bounds of a cvar. + * Sets the specified boundary of a cvar. * * @param pcvar Pointer to cvar - * @param type Type of bound to set, CvarBound_Lower or CvarBound_Upper - * @param set If set to true, cvar will use specified bound. If false, bound will be removed - * @param value Floating point value to use as the specified bound + * @param type Type of boundary to set + * @param set If true the cvar boundary will be set, otherwise it will be + * 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); @@ -432,7 +450,9 @@ native set_pcvar_bounds(pcvar, CvarBounds:type, bool:set, Float:value = 0.0); * @param pcvar Pointer to cvar * @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); @@ -447,7 +467,9 @@ native bind_pcvar_num(pcvar, &any:var); * @param pcvar Pointer to cvar * @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); @@ -463,7 +485,9 @@ native bind_pcvar_float(pcvar, &Float:var); * @param var Global array to keep updated * @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); @@ -475,13 +499,14 @@ native bind_pcvar_string(pcvar, any:var[], varlen); 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 * 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 - * the internal index, incremented for each registered cvar + * @param num Index to retrieve * @param name Buffer to copy cvar name to * @param namelen Maximum buffer size * @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 */ -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 @@ -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[]) * - * id - Client index - * cvar - Cvar queried - * value - Cvar value on the client - * param - Extra data [optional] + * id - Client index + * cvar - Cvar queried + * value - Cvar value on the client + * param - Optional extra data * * @param id Client index * @param cvar Cvar to query @@ -515,10 +540,8 @@ native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_han * * @noreturn * @error If the client index is not within the range of 1 to - * MaxClients or the client is not connected, an error - * will be thrown. - * If the callback function is invalid, cvar querying is - * unavailable or the querying process runs out of memory, - * an error will be thrown. + * MaxClients, the client is not connected, the callback + * function is invalid or the querying process encounters + * a problem, 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[] = ""); From 950f3f97c1d4c72e5d5961d399df4a59f43f2303 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 24 Feb 2015 22:16:36 +0100 Subject: [PATCH 07/10] datapack: Tabs->spaces, consistency, nuke IsPackReadable --- plugins/include/datapack.inc | 138 +++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 62 deletions(-) diff --git a/plugins/include/datapack.inc b/plugins/include/datapack.inc index 80d12648..27950db5 100644 --- a/plugins/include/datapack.inc +++ b/plugins/include/datapack.inc @@ -8,131 +8,145 @@ // https://alliedmods.net/amxmodx-license #if defined _datapack_included - #endinput + #endinput #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. - * 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. + * Datapack tag declaration + * + * @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 { - 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(); /** - * 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 - * @error Invalid handle. + * @error If an invalid handle is provided, an error will be thrown. */ 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 - * @error Invalid handle. + * @error If an invalid handle is provided, an error will be thrown. */ 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 str String to add. - * @return Length of copied string. - * @error Invalid handle. + * @param pack Datapack handle + * @param str String to pack + * + * @return Length of copied string + * @error If an invalid handle is provided, an error will be thrown. */ 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. - * @return Cell value. - * @error Invalid handle, or bounds error. + * @param pack Datapack handle + * + * @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); /** - * Reads a float from a data pack. + * Reads a float from a datapack. * - * @param pack Handle to the data pack. - * @return Float value. - * @error Invalid handle, or bounds error. + * @param pack Datapack handle + * + * @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 buffer Destination string buffer. - * @param maxlen Maximum length of output string buffer. - * @return Length of output string. - * @error Invalid handle, or bounds error. + * @param pack Datapack handle + * @param buffer Buffer to copy string to + * @param maxlen Maximum size of buffer + * + * @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); /** - * 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 - * @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. - * @return Numerical position in the data pack. - * @error Invalid handle. + * @param pack Datapack handle + * + * @return Position in the datapack + * @error If an invalid handle is provided, an error will be thrown. */ 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 - * @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); /** - * Returns whether or not a specified number of bytes from the data pack - * position to the end can be read. + * Destroys the datapack and frees its memory. * - * @param pack Handle to the data pack. - * @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 Datapack handle * - * @param pack Handle to the data pack. - * @return True if disposed, false otherwise. + * @return True if disposed, false otherwise */ native DestroyDataPack(&DataPack:pack); From 902cecb0c3611ded2214db9962edf52cf209f97a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 24 Feb 2015 22:20:46 +0100 Subject: [PATCH 08/10] amxconst: Minor improvements on client_print natives --- plugins/include/amxmodx.inc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index fe8d9988..1b1b0f56 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -339,7 +339,8 @@ native show_motd(player, const message[], const header[] = ""); * last, to the client with the highest index. * * @param index Client index, use 0 to display to all clients - * @param type Message type, see print_* destination constants in amxconst + * @param type Message type, see print_* destination constants in + * amxconst.inc * @param message Formatting rules * @param ... Variable number of formatting parameters * @@ -361,8 +362,9 @@ native client_print(index, type, const message[], any:...); * ; This only works at the start of the string, * ; and precludes using other control characters * default x01 ; use default color from this point forward - * @note The team color is defined by the sender's index or a specific team - * color using the print_team_* constants in amxconst + * @note The team color is defined by the sender's index. Alternatively a + * specific team color can be enforced using the print_team_* constants in + * amxconst.inc * @note Usage examples: * client_print_color(id, print_team_red, "^4Green ^3Red ^1Default") * client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default") @@ -376,9 +378,7 @@ native client_print(index, type, const message[], any:...); * last, to the client with the highest index. * * @param index Client index, use 0 to display to all clients - * @param sender Client index used as the sender, defining the team color - * used in the message. Use print_team_* constants to force - * a specific color. + * @param sender Client index used as the message sender * @param fmt Formatting rules * @param ... Variable number of formatting parameters * @@ -399,7 +399,8 @@ native client_print_color(index, sender, const message[], any:...); * last, to the client with the highest index. * * @param player Client index, use 0 to display to all clients - * @param type Message type, see print_* destination constants in amxconst + * @param type Message type, see print_* destination constants in + * amxconst.inc * @param message Formatting rules * @param ... Variable number of formatting parameters * From bc9710e8f22da1ce68790b7362f3656f3ed890c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 24 Feb 2015 22:51:36 +0100 Subject: [PATCH 09/10] inc-doc2 nits/finishing touches --- plugins/include/amxconst.inc | 2 +- plugins/include/amxmisc.inc | 2 +- plugins/include/amxmodx.inc | 19 +++---- plugins/include/amxmodx_version.inc | 2 +- plugins/include/celltrie.inc | 2 +- plugins/include/core.inc | 4 +- plugins/include/csstats.inc | 10 ++-- plugins/include/cstrike.inc | 80 ++++++++++++++--------------- plugins/include/csx.inc | 16 +++--- plugins/include/cvars.inc | 8 +-- plugins/include/datapack.inc | 5 +- 11 files changed, 73 insertions(+), 77 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index 84d61b02..72d1fa95 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _amxconst_included - #endinput + #endinput #endif #define _amxconst_included diff --git a/plugins/include/amxmisc.inc b/plugins/include/amxmisc.inc index 8c516f0b..448293e9 100755 --- a/plugins/include/amxmisc.inc +++ b/plugins/include/amxmisc.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _amxmisc_included - #endinput + #endinput #endif #define _amxmisc_included diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 1b1b0f56..099dc984 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _amxmodx_included - #endinput + #endinput #endif #define _amxmodx_included @@ -100,8 +100,8 @@ forward plugin_end(); /** * Called when a message is about to be logged. * - * @note Message data and information can be retrieved using the read_log set of - * functions. + * @note Message data and information can be retrieved using the read_log* set + * of functions. * * @return PLUGIN_CONTINUE to let the log message through * PLUGIN_HANDLED or higher to stop the log message @@ -687,40 +687,34 @@ native read_datatype(); /** * Retrieves current log message. * - * @note Can only be used inside of the plugin_log() forward. + * @note Should only be used inside of the plugin_log() forward. * * @param output Buffer to copy log message to * @param len Maximum buffer size * * @return Number of cells written to buffer - * @error If called outside of the plugin_log() forward, an error is - * thrown. */ native read_logdata(output[], len); /** * Returns number of log message arguments. * - * @note Can only be used inside of the plugin_log() forward. + * @note Should only be used inside of the plugin_log() forward. * * @return Number of arguments in the log message - * @error If called outside of the plugin_log() forward, an error is - * thrown. */ native read_logargc(); /** * Retrieves argument of log message. * - * @note Can only be used inside of the plugin_log() forward. + * @note Should only be used inside of the plugin_log() forward. * * @param id Argument index, starting from 0 * @param output Buffer to copy log argument to * @param len Maximum buffer size * * @return Number of cells written to buffer - * @error If called outside of the plugin_log() forward, an error is - * thrown. */ native read_logargv(id, output[], len); @@ -871,7 +865,6 @@ native get_amxx_verstring(buffer[], length); * @error If the client index is not within the range of 1 to * MaxClients an error will be thrown. */ - native get_user_attacker(index, ...); /** diff --git a/plugins/include/amxmodx_version.inc b/plugins/include/amxmodx_version.inc index faba7062..7d9c502a 100644 --- a/plugins/include/amxmodx_version.inc +++ b/plugins/include/amxmodx_version.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _amxmodx_version_included - #endinput + #endinput #endif #define _amxmodx_version_included diff --git a/plugins/include/celltrie.inc b/plugins/include/celltrie.inc index 729be00c..bcf0b757 100644 --- a/plugins/include/celltrie.inc +++ b/plugins/include/celltrie.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _celltrie_included - #endinput + #endinput #endif #define _celltrie_included diff --git a/plugins/include/core.inc b/plugins/include/core.inc index 7b8ba5f9..93626ca1 100755 --- a/plugins/include/core.inc +++ b/plugins/include/core.inc @@ -6,7 +6,7 @@ */ #if defined _core_included - #endinput + #endinput #endif #define _core_included @@ -198,5 +198,5 @@ native tickcount(&granularity = 0); */ stock abs(x) { - return x > 0 ? x : -x; + return x > 0 ? x : -x; } diff --git a/plugins/include/csstats.inc b/plugins/include/csstats.inc index 9bb7c099..96e168ef 100755 --- a/plugins/include/csstats.inc +++ b/plugins/include/csstats.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _csstats_included - #endinput + #endinput #endif #define _csstats_included @@ -75,7 +75,9 @@ native get_user_wrstats(index, wpnindex, stats[8], bodyhits[8]); * server. * * @note The permanent storage is updated on every respawn or client disconnect. - * @note Player rank is determined by the difference of kills to deaths. + * @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: @@ -199,7 +201,9 @@ native reset_user_wstats(index); * incremental access. * * @note The permanent storage is updated on every respawn or client disconnect. - * @note Player rank is determined by the difference of kills to deaths. + * @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: diff --git a/plugins/include/cstrike.inc b/plugins/include/cstrike.inc index 2ee0752d..764742cd 100755 --- a/plugins/include/cstrike.inc +++ b/plugins/include/cstrike.inc @@ -12,7 +12,7 @@ // #if defined _cstrike_included - #endinput + #endinput #endif #define _cstrike_included @@ -36,18 +36,18 @@ */ enum CsInternalModel { - CS_DONTCHANGE = 0, - CS_CT_URBAN = 1, - CS_T_TERROR = 2, - CS_T_LEET = 3, - CS_T_ARCTIC = 4, - CS_CT_GSG9 = 5, - CS_CT_GIGN = 6, - CS_CT_SAS = 7, - CS_T_GUERILLA = 8, - CS_CT_VIP = 9, - CZ_T_MILITIA = 10, - CZ_CT_SPETSNAZ = 11, + CS_DONTCHANGE = 0, + CS_CT_URBAN = 1, + CS_T_TERROR = 2, + CS_T_LEET = 3, + CS_T_ARCTIC = 4, + CS_CT_GSG9 = 5, + CS_CT_GIGN = 6, + CS_CT_SAS = 7, + CS_T_GUERILLA = 8, + CS_CT_VIP = 9, + CZ_T_MILITIA = 10, + CZ_CT_SPETSNAZ = 11, }; /** @@ -55,10 +55,10 @@ enum CsInternalModel */ enum CsTeams { - CS_TEAM_UNASSIGNED = 0, - CS_TEAM_T = 1, - CS_TEAM_CT = 2, - CS_TEAM_SPECTATOR = 3, + CS_TEAM_UNASSIGNED = 0, + CS_TEAM_T = 1, + CS_TEAM_CT = 2, + CS_TEAM_SPECTATOR = 3, }; /** @@ -70,9 +70,9 @@ enum CsTeams */ enum CsArmorType { - CS_ARMOR_NONE = 0, // no armor - CS_ARMOR_KEVLAR = 1, // body vest only - CS_ARMOR_VESTHELM = 2, // vest and helmet + CS_ARMOR_NONE = 0, // no armor + CS_ARMOR_KEVLAR = 1, // body vest only + CS_ARMOR_VESTHELM = 2, // vest and helmet }; /** @@ -89,11 +89,11 @@ enum CsArmorType */ enum { - CS_RESET_ZOOM = 0, // Reset any zoom blocking (mode has no effect) - CS_SET_NO_ZOOM, // Disable any sort of zoom - CS_SET_FIRST_ZOOM, // Set first zoom level (AWP style) - CS_SET_SECOND_ZOOM, // Set second zoom level (AWP style) - CS_SET_AUGSG552_ZOOM, // Set AUG/SG552 zoom style + CS_RESET_ZOOM = 0, // Reset any zoom blocking (mode has no effect) + CS_SET_NO_ZOOM, // Disable any sort of zoom + CS_SET_FIRST_ZOOM, // Set first zoom level (AWP style) + CS_SET_SECOND_ZOOM, // Set second zoom level (AWP style) + CS_SET_AUGSG552_ZOOM, // Set AUG/SG552 zoom style }; /** @@ -246,19 +246,19 @@ native cs_get_user_bpammo(index, weapon); * amxconst.inc * @note Some weapons share ammo types and therefore ammo backpack pools. List * of ammo types: - * awp - ammo_338magnum - * scout, ak47, g3sg1 - ammo_762nato - * m249 - ammo_556natobox - * famas, m4a1, aug, sg550, galil, sg552 - ammo_556nato - * m3, xm1014 - ammo_buckshot - * usp, ump45, mac10 - ammo_45acp - * fiveseven, p90 - ammo_57mm - * deagle - ammo_50ae - * p228 - ammo_357sig - * glock, mp5, tmp, elites - ammo_9mm - * hegrenade - / - * flashbang - / - * smokegrenade - / + * ammo_338magnum - awp + * ammo_762nato - scout, ak47, g3sg1 + * ammo_556natobox - m249 + * ammo_556nato - famas, m4a1, aug, sg550, galil, sg552 + * ammo_buckshot - m3, xm1014 + * ammo_45acp - usp, ump45, mac10 + * ammo_57mm - fiveseven, p90 + * ammo_50ae - deagle + * ammo_357sig - p228 + * ammo_9mm - glock, mp5, tmp, elites + * / - hegrenade + * / - flashbang + * / - smokegrenade * * @param index Client index * @param weapon Weapon id @@ -1061,7 +1061,7 @@ native cs_set_c4_explode_time(index, Float:value); /** * Returns if the bomb is being defused. * - * @param index C4 entity + * @param c4index C4 entity * * @return 1 if the bomb is being defused, 0 otherwise * @error If the provided entity index is not a bomb, an error will be @@ -1072,7 +1072,7 @@ native bool:cs_get_c4_defusing(c4index); /** * Sets if the bomb is being defused. * - * @param index C4 entity + * @param c4index C4 entity * @param defusing True if the bomb should be defused, false otherwise * * @noreturn diff --git a/plugins/include/csx.inc b/plugins/include/csx.inc index 70d90883..c05304ea 100755 --- a/plugins/include/csx.inc +++ b/plugins/include/csx.inc @@ -12,7 +12,7 @@ // #if defined _csx_included - #endinput + #endinput #endif #define _csx_included @@ -32,10 +32,10 @@ */ enum MapObjective { - MapObjective_Bomb = (1<<0), - MapObjective_Hostage = (1<<1), - MapObjective_Vip = (1<<2), - MapObjective_Escape = (1<<3), + MapObjective_Bomb = (1<<0), + MapObjective_Hostage = (1<<1), + MapObjective_Vip = (1<<2), + MapObjective_Escape = (1<<3), }; /** @@ -154,7 +154,7 @@ forward bomb_defused(defuser); native custom_weapon_add(const wpnname[], melee = 0, const logname[] = ""); /** - * Trigger a damage event on a custom weapon, adding it to the internal stats. + * 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. @@ -175,7 +175,7 @@ native custom_weapon_add(const wpnname[], melee = 0, const logname[] = ""); native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0); /** - * Add a shot event on a custom weapon to the internal stats. + * Adds a shot event on a custom weapon to the internal stats. * * @param weapon Custom weapon id * @param index Client index @@ -184,7 +184,7 @@ native custom_weapon_dmg(weapon, att, vic, damage, hitplace = 0); * @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); // weapon id , player id +native custom_weapon_shot(weapon, index); /** * Returns if the weapon is considered a melee weapon. diff --git a/plugins/include/cvars.inc b/plugins/include/cvars.inc index 38cca88c..2e86f9ae 100644 --- a/plugins/include/cvars.inc +++ b/plugins/include/cvars.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _cvars_included - #endinput + #endinput #endif #define _cvars_included @@ -32,8 +32,8 @@ */ enum CvarBounds { - CvarBound_Upper = 0, - CvarBound_Lower + CvarBound_Upper = 0, + CvarBound_Lower }; /** @@ -156,7 +156,7 @@ native disable_cvar_hook(cvarhook:handle); native enable_cvar_hook(cvarhook:handle); /** - * Returns a 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 Accessing a Cvar by name is slower than direct pointer access, which is diff --git a/plugins/include/datapack.inc b/plugins/include/datapack.inc index 27950db5..fd2743b3 100644 --- a/plugins/include/datapack.inc +++ b/plugins/include/datapack.inc @@ -8,7 +8,7 @@ // https://alliedmods.net/amxmodx-license #if defined _datapack_included - #endinput + #endinput #endif #define _datapack_included @@ -24,10 +24,9 @@ * Failing to free handles will result in the plugin and AMXX leaking * memory. */ - enum DataPack { - Invalid_DataPack = 0 + Invalid_DataPack = 0 }; /** From a82f5216333dcb5711639f9926136a0f63af57f8 Mon Sep 17 00:00:00 2001 From: Freeman-AM Date: Sun, 1 Mar 2015 16:42:32 +0100 Subject: [PATCH 10/10] amxmodx.inc: missing commas, typo errors... --- plugins/include/amxmodx.inc | 378 ++++++++++++++++++------------------ 1 file changed, 186 insertions(+), 192 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 099dc984..ca469d4f 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -35,8 +35,8 @@ * Called just after server activation. * * @note Good place to initialize most of the plugin, such as registering - * cvars, commands or forwards, creating data structures for later use or - * generating and loading other required configuration. + * cvars, commands or forwards, creating data structures for later use, or + * generating and loading other required configurations. * * @noreturn */ @@ -49,7 +49,6 @@ forward plugin_init(); */ forward plugin_pause(); - /** * Called just after the plugin is unpaused. * @@ -61,11 +60,11 @@ forward plugin_unpause(); * Called when the mod tries to change the map. * * @note This is *only* called if the mod itself handles the map change. The - * server command "changelevel" which is used by many plugins will not - * trigger this forward. Unfortunately this means that in practice this - * forward is very unreliable, and will not be called in many situations. - * @note AMXX 1.8.3 has added the engine_changelevel() function which will utilize - * the correct engine function to change the map and therefore trigger + * server command "changelevel", which is used by many plugins, will not + * trigger this forward. Unfortunately, this means that in practice this + * forward can be unreliable and will not be called in many situations. + * @note AMXX 1.8.3 has added the engine_changelevel() function, which will utilize + * the correct engine function to change the map, and therefore trigger * this forward. * * @param map Map that the mod tries to change to @@ -76,9 +75,9 @@ forward plugin_unpause(); forward server_changelevel(map[]); /** - * Called when all plugins went through plugin_init(). + * Called when all plugins went through plugin_init() * - * @note When this forward is called most plugins should have registered their + * @note When this forward is called, most plugins should have registered their * cvars and commands already. * * @noreturn @@ -101,7 +100,7 @@ forward plugin_end(); * Called when a message is about to be logged. * * @note Message data and information can be retrieved using the read_log* set - * of functions. + * of functions. * * @return PLUGIN_CONTINUE to let the log message through * PLUGIN_HANDLED or higher to stop the log message @@ -225,8 +224,7 @@ native precache_model(const name[]); * to be a wav file. Precaching a file with this will add it to the engine * sound table, making it available for usage in emit_sound() for example. * @note Precaching other filetypes (such as mp3 music), optionally in different - * locations, has to be done with precache_generic. - * + * locations, has to be done with precache_generic() * * @param name Path to the sound file * @@ -240,7 +238,7 @@ native precache_sound(const name[]); * Precaches a generic file. * * @note Can only be used inside of the plugin_precache() forward. - * @note Precaching sounds with this will not add them to the engine sound table + * @note Precaching sounds with this will not add them to the engine sound table. * * @param szFile Path to the file * @@ -274,7 +272,7 @@ native engine_changelevel(const map[]); * * @noreturn * @error If the index is not within the range of 1 to MaxClients or - * the client is not connected an error will be thrown. + * the client is not connected, an error will be thrown. * @error If called outside of the plugin_precache() forward, an error * is thrown. */ @@ -290,7 +288,7 @@ native set_user_info(index, const info[], const value[]); * * @return Number of cells written to buffer * @error If the index is not within the range of 1 to MaxClients or - * the client is not connected an error will be thrown. + * the client is not connected, an error will be thrown. */ native get_user_info(index, const info[], output[], len); @@ -345,8 +343,8 @@ native show_motd(player, const message[], const header[] = ""); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native client_print(index, type, const message[], any:...); @@ -362,18 +360,18 @@ native client_print(index, type, const message[], any:...); * ; This only works at the start of the string, * ; and precludes using other control characters * default x01 ; use default color from this point forward - * @note The team color is defined by the sender's index. Alternatively a + * @note The team color is defined by the sender's index. Alternatively, a * specific team color can be enforced using the print_team_* constants in * amxconst.inc * @note Usage examples: * client_print_color(id, print_team_red, "^4Green ^3Red ^1Default") * client_print_color(id, id2, "^4Green ^3id2's team color, ^1Default") * @note Including colors in ML can be done using the same escaping method: - * EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default. + * EXAMPLE_ML_KEY = ^4Green ^3Team color ^1Default * @note This functions return value behaves differently depending on what is * used as the client index: If 0 is specified, then the function will * return 0 if nothing has been sent (no client connected). If either a - * single client is specified or there is at least one client connected, + * single client is specified, or there is at least one client connected, * the number of printed characters will refer to the message that is sent * last, to the client with the highest index. * @@ -383,8 +381,8 @@ native client_print(index, type, const message[], any:...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native client_print_color(index, sender, const message[], any:...); @@ -394,7 +392,7 @@ native client_print_color(index, sender, const message[], any:...); * @note This functions return value behaves differently depending on what is * used as the client index: If 0 is specified, then the function will * return 0 if nothing has been sent (no client connected). If either a - * single client is specified or there is at least one client connected, + * single client is specified, or there is at least one client connected, * the number of printed characters will refer to the message that is sent * last, to the client with the highest index. * @@ -405,8 +403,8 @@ native client_print_color(index, sender, const message[], any:...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native engclient_print(player, type, const message[], any:...); @@ -418,15 +416,15 @@ native engclient_print(player, type, const message[], any:...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native console_print(id, const message[], any:...); /** * Executes a command from the specified client or the server console. * - * @param id Client index, or 0 to print to the server console + * @param id Client index, or 0 to execute from the server console * @param cmd Formatting rules * @param ... Variable number of formatting parameters * @@ -512,8 +510,8 @@ native register_logevent(const function[], argsnum, ...); * @note There are four different HUD channels available on the client (1-4). * Sending a hudmessage to a channel will overwrite any existing messages * already displaying on that channel. - * @note If you plan to create a permanent message don't forget to specify a - * specific channel to avoid possible flickering due to auto-channeling + * @note If you plan to create a permanent message, don't forget to specify a + * specific channel to avoid possible flickering due to auto-channeling. * @note For the hudmessage coordinates x and y, -1.0 will center the message * on the respective axis. * @note These parameters stay until the next call to set_hudmessage overwrites @@ -544,7 +542,7 @@ native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y * @note This functions return value behaves differently depending on what is * used as the client index: If 0 is specified, then the function will * return 0 if nothing has been sent (no client connected). If either a - * single client is specified or there is at least one client connected, + * single client is specified, or there is at least one client connected, * the number of printed characters will refer to the message that is sent * last, to the client with the highest index. * @@ -553,8 +551,8 @@ native set_hudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native show_hudmessage(index, const message[], any:...); @@ -587,16 +585,16 @@ native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y * Displays a director message on the client HUD. * * @note Use set_dhudmessage to define how the message should look on screen. - * @note Unlike the classic HUD message which is channel-based, director + * @note Unlike the classic HUD message, which is channel-based, director * messages are stack-based. You can have up to 8 messages displaying at - * once, if more are added they will be overwritten in the order they were + * once. If more are added, they will be overwritten in the order they were * sent. There is no way to clear a specific message. * @note The message has a maximum length of 128 characters which this function * will automatically enforce. * @note This functions return value behaves differently depending on what is * used as the client index: If 0 is specified, then the function will * return 0 if nothing has been sent (no client connected). If either a - * single client is specified or there is at least one client connected, + * single client is specified, or there is at least one client connected, * the number of printed characters will refer to the message that is sent * last, to the client with the highest index. * @@ -605,8 +603,8 @@ native set_dhudmessage(red = 200, green = 100, blue = 0, Float:x = -1.0, Float:y * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native show_dhudmessage(index, const message[], any:...); @@ -614,16 +612,13 @@ native show_dhudmessage(index, const message[], any:...); * Displays a menu to the client. * * @note Keys is a bitflag value that represents which keys the user can press - * on the menu. If you want to display disabled menu options or skip - * certain number slots you should exclude that key from the bitflag. + * on the menu. If you want to display disabled menu options, or skip + * certain number slots, you should exclude that key from the bitflag. * amxconst.inc provides MENU_KEY_* constants for convenience. - * @note If a menu timeout is specified it does not automatically overwrite - * the menu on the client's screen. But if a client acts upon a timeouted - * displayed menu that action will not be sent to the plugin. * @note The title parameter is not displayed to the client and is only used for * identifying menus internally and assigning them to their callbacks. * The title corresponds to the menu name that you register with - * register_menuid(). + * register_menuid() * * @param index Client to display menu to, use 0 to display to all clients * @param keys Enabled keys @@ -633,15 +628,15 @@ native show_dhudmessage(index, const message[], any:...); * * @return 1 on success, 0 if menu could not be displayed (client not * connected) - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native show_menu(index, keys, const menu[], time = -1, const title[] = ""); /** * Retrieves values from a client message. * - * @note For use within callbacks registered with register_event(). + * @note For use within callbacks registered with register_event() * @note Usage examples: * value = read_data(1); * read_data(2, floatvalue); @@ -669,7 +664,7 @@ native read_data(value, any:...); /** * Returns the number of values in the client message. * - * @note For use within callbacks registered with register_event(). + * @note For use within callbacks registered with register_event() * * @return Number of values in client message */ @@ -678,7 +673,7 @@ native read_datanum(); /** * Returns the message id of the client message. * - * @note For use within callbacks registered with register_event(). + * @note For use within callbacks registered with register_event() * * @return Message id of the client message */ @@ -721,7 +716,7 @@ native read_logargv(id, output[], len); /** * Parse log data about client. * - * @note When client actions are logged they appear in the the format + * @note When client actions are logged, they appear in the the format * "Name<#userid>", this native extracts the individual * pieces of information. * @@ -856,14 +851,14 @@ native get_amxx_verstring(buffer[], length); * was attacked by a non-client entity. * * @param index Client index - * @param ... If provided the attacker weapon will be stored in an + * @param ... If provided, the attacker weapon will be stored in an * optional second parameter, and the body hit place will be * stored in an optional third parameter * * @return Attacker client index, a non-client entity or 0 if no * attacker was found * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native get_user_attacker(index, ...); @@ -871,7 +866,7 @@ native get_user_attacker(index, ...); * Traces the client's current aim vector to see if it hits something. * * @note If the trace does not hit a client, id and body will be set to 0. - * @note If the trace hits nothing within the specified distance 0 is returned. + * @note If the trace hits nothing within the specified distance, 0 is returned. * * @param index Client index to trace aim from * @param id Variable to store hit client index (if applicable) @@ -880,14 +875,14 @@ native get_user_attacker(index, ...); * * @return Distance between the trace start and end point * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native Float:get_user_aiming(index, &id, &body, dist = 9999); /** * Returns the client's frags. * - * @note While this is mod-independent the mod may track frag count differently + * @note While this is mod-independent, the mod may track frag count differently, * so it can only be retrieved using another native or other methods. * @note This will actually return the client's overall score, which may or may * not be equal to their scored frags depending on the mod. @@ -903,7 +898,7 @@ native get_user_frags(index); /** * Returns the client's armor value. * - * @note While this is mod-independent the mod may track armor data differently + * @note While this is mod-independent, the mod may track armor data differently, * so it can only be retrieved using another native or other methods. * * @param index Client index @@ -917,7 +912,7 @@ native get_user_armor(index); /** * Returns the client's death count. * - * @note While this is mod-independent the mod may track death count differently + * @note While this is mod-independent, the mod may track death count differently, * so it can only be retrieved using another native or other methods. * * @param index Client index @@ -931,8 +926,8 @@ native get_user_deaths(index); /** * Returns the client's health points. * - * @note While this is mod-independent the mod may track health points - * differently so it can only be retrieved using another native or other + * @note While this is mod-independent, the mod may track health points + * differently, so it can only be retrieved using another native or other * methods. * * @param index Client index @@ -974,7 +969,7 @@ native get_user_ip(index, ip[], len, without_port = 0); * * @return 1 if the weapon is present, 0 if it is not * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native user_has_weapon(index, weapon, setweapon = -1); @@ -986,9 +981,9 @@ native user_has_weapon(index, weapon, setweapon = -1); * @param clip Optional variable to store clip ammo to * @param ammo Optional variable to store backpack ammo to * - * @return Weapon index on success, or 0 if the client is not connected + * @return Weapon index on success or 0 if the client is not connected * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native get_user_weapon(index, &clip = 0, &ammo = 0); @@ -1000,9 +995,9 @@ native get_user_weapon(index, &clip = 0, &ammo = 0); * @param clip Variable to store clip ammo to * @param ammo Variable to store backpack ammo to * - * @return 1 on success, or 0 if the client is not connected + * @return 1 on success or 0 if the client is not connected * @error If the client index is not within the range of 1 to - * MaxClients, or the weapon index is invalid, an error will + * MaxClients or the weapon index is invalid, an error will * be thrown. */ native get_user_ammo(index, weapon, &clip, &ammo); @@ -1012,8 +1007,8 @@ native get_user_ammo(index, weapon, &clip, &ammo); * * @note The conversion algorithm is limited to a certain range of numbers, but * is guaranteed to work correctly for all numbers from 0 to 999. Outside - * of that range the conversion will result in an incorrect string, but - * not fail. + * of that range, the conversion will result in an incorrect string, but + * will not fail. * @note The conversion is to english text, there is no way to change this. * * @param num Integer to convert @@ -1041,7 +1036,7 @@ native get_user_team(index, team[] = "", len = 0); * Returns client's playing time in seconds. * * @param index Client index - * @param flag If nonzero the result will not include the time it took + * @param flag If nonzero, the result will not include the time it took * the client to connect. * * @return Connection time in seconds, 0 if client index is invalid or @@ -1054,7 +1049,7 @@ native get_user_time(index, flag = 0); * * @param index Client index * @param ping Variable to store ping in - * @param loss Variable to sote loss in + * @param loss Variable to store loss in * * @return 1 on success, 0 if client index is invalid or the client * is not connected @@ -1073,17 +1068,17 @@ native get_user_ping(index, &ping, &loss); * 3 - aim end position from eyes (hit point for weapon) * 4 - position of last bullet hit (only for Counter-Strike) * - * @return 1 on succes, 0 if client is not connected + * @return 1 on success, 0 if client is not connected * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native get_user_origin(index, origin[3], mode = 0); /** - * Retrieves all weapons in the client inventory, stores them in an array and + * Retrieves all weapons in the client inventory, stores them in an array, and * returns the inventory as a bitflag sum. * - * @note Make sure that num has an initial value of 0, or the native will not + * @note Make sure that num has an initial value of 0 or the native will not * work correctly. * * @param index Client index @@ -1092,7 +1087,7 @@ native get_user_origin(index, origin[3], mode = 0); * * @return Bitflag sum of weapon indexes, 0 if client is not connected * @error If the client index is not within the range of 1 to - * MaxClients an error will be thrown. + * MaxClients, an error will be thrown. */ native get_user_weapons(index, weapons[32], &num); @@ -1151,7 +1146,7 @@ native get_user_userid(index); * of the slap power. The slap direction can be influenced by the third * parameter. * - * @param index Client idex + * @param index Client index * @param power Power of the slap * @param rnddir If set to zero the player will be slapped along it's aim * vector, otherwise the direction will be randomized @@ -1164,7 +1159,7 @@ native user_slap(index, power, rnddir = 1); * Kills a client. * * @param index Client index - * @param flag If nonzero the death will not affect the client's score + * @param flag If nonzero, the death will not affect the client's score * * @return 1 on success, 0 if client index is invalid or the client * is not connected @@ -1270,7 +1265,7 @@ native read_args(output[], len); * * @note Should only be used inside of the client_command() forward. * @note This count includes the command itself. I.e. in a command with 4 - * arguments this will return 5. + * arguments, this will return 5. * * @return Number of arguments in the command */ @@ -1279,7 +1274,7 @@ native read_argc(); /** * Converts a flag string to a bitflag value. * - * @note Example: The string "abcd" represents the sum of 1, 2, 4 and 8 - or + * @note Example: The string "abcd" represents the sum of 1, 2, 4, and 8 - or * (1<<0)|(1<<1)|(1<<2)|(1<<3). The function will return 15. * * @param flags Flag string to convert @@ -1330,8 +1325,8 @@ native find_player(const flags[], ...); /** * Removes double-quotes from the beginning and end of a string. * - * @note If the string only has a double-quote at either the start *or* the end - * and not both the function will do nothing. + * @note If the string only has a double-quote at either the start *or* the end, + * and not both, the function will do nothing. * @note The function does not perform any trimming per-se. But if a * double-quote is found at the beginning of the string, it will remove * one ^r (carriage return) character at the end of the string if present, @@ -1355,9 +1350,9 @@ native remove_quotes(text[]); * @param command Formatting rules * @param ... Variable number of formatting parameters * - * @return Lenght of formatted command string - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @return Length of formatted command string + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native client_cmd(index, const command[], any:...); @@ -1368,9 +1363,9 @@ native client_cmd(index, const command[], any:...); * @note This emulates a client command on the server side, and is an excellent * tool to force a client to do certain actions related to the game. * @note The command has to stand alone in the command parameter, only add - * arguments using the designated paramters. + * arguments using the designated parameters. * @note Commands emulated using this function will not trigger plugin command - * hooks. For an alternative that does, see amxclient_cmd(). + * hooks. For an alternative that does, see amxclient_cmd() * * @param index Client index, use 0 to execute from all clients * @param command Client command to execute on @@ -1378,8 +1373,8 @@ native client_cmd(index, const command[], any:...); * @param arg2 Optional command arguments * * @noreturn - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); @@ -1390,9 +1385,9 @@ native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = " * @note This emulates a client command on the server side, and is an excellent * tool to force a client to do certain actions related to the game. * @note The command has to stand alone in the command parameter, only add - * arguments using the designated paramters. + * arguments using the designated parameters. * @note Commands emulated using this function will trigger other plugin's - * command hooks. For an alternative that doesn't, see engclient_cmd(). + * command hooks. For an alternative that doesn't, see engclient_cmd() * * @param index Client index, use 0 to execute from all clients * @param command Client command to execute on @@ -1400,8 +1395,8 @@ native engclient_cmd(index, const command[], const arg1[] = "", const arg2[] = " * @param arg2 Optional command arguments * * @noreturn - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); @@ -1412,7 +1407,7 @@ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = " * client-controlled input (including client names) to this function * without sanitizing it first. * @note The queued commands will be executed by the engine on the next frame. - * If you require them to be executed immediately, see server_exec(). + * If you require them to be executed immediately, see server_exec() * * @param command Formatting rules * @param ... Variable number of formatting parameters @@ -1453,7 +1448,7 @@ native Float:get_gametime(); * Returns the maxplayers setting of the current server, that is how many * clients it supports. * - * @note As of AMXX 1.8.3 this value is also exposed through a dynamic constant + * @note As of AMXX 1.8.3, this value is also exposed through a dynamic constant * via the MaxClients variable, declared in amxconst.inc * * @return Maxplayers setting @@ -1463,7 +1458,7 @@ native get_maxplayers(); /** * Retrieves the name of the currently played mod. * - * @note This retrieves the short name of the mod. Example: for Counter-Strike + * @note This retrieves the short name of the mod. Example: for Counter-Strike, * it will copy "cstrike" to the buffer. * * @param name Buffer to copy mod name to @@ -1489,7 +1484,7 @@ native get_modname(name[], len); native get_time(const format[], output[], len); /** - * Retrieves the provided time using using the specified format string. + * Retrieves the provided time using the specified format string. * * @note Uses the strftime C function. For a list of valid format parameters, * see: http://cplusplus.com/reference/clibrary/ctime/strftime.html @@ -1512,12 +1507,11 @@ native format_time(output[], len, const format[], time = -1); * @param offset Optional offset value in seconds * * @return Unix time stamp - * @error */ native get_systime(offset = 0); /** - * Converts time string to unix time stamp. + * Converts time strings to unix time stamp. * * @note Uses the strptime C function. For a list of valid format parameters, * see: http://www.cplusplus.com/reference/ctime/strftime/ @@ -1528,7 +1522,7 @@ native get_systime(offset = 0); * * @param input Time string to convert * @param format Formatting information for conversion - * @param time If different from -1 the converted time will be added to + * @param time If different from -1, the converted time will be added to * this time stamp * * @return Unix time stamp @@ -1551,7 +1545,7 @@ native parse_time(const input[], const format[], time = -1); * map start * "d" - time interval is treated as absolute time before * map change - * @param repeat If the "a" flag is set the task will be repeated this + * @param repeat If the "a" flag is set, the task will be repeated this * many times * * @noreturn @@ -1594,9 +1588,9 @@ native task_exists(id = 0, outside = 0); /** * Sets the specified admin flags to a client. * - * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc + * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc * @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. + * has run, the flags may not exactly equal the specified bitflag sum. * @note AMXX stores multiple sets of flags internally, but only flag set * 0 is actively used. You should not change the value of the third * parameter from the default. @@ -1614,7 +1608,7 @@ native set_user_flags(index, flags = -1, id = 0); /** * Returns the client's admin flags as a bitflag sum. * - * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc + * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc * @note AMXX stores multiple sets of flags internally, but only flag set * 0 is actively used. You should not change the value of the second * parameter from the default. @@ -1631,7 +1625,7 @@ native get_user_flags(index, id = 0); /** * Removes the specified admin flags from a client. * - * @note For a list of possible flags see the ADMIN_* constants in amxconst.inc + * @note For a list of possible flags, see the ADMIN_* constants in amxconst.inc * @note This function just removes the flags using a bitwise-and operation. * @note AMXX stores multiple sets of flags internally, but only flag set * 0 is actively used. You should not change the value of the third @@ -1651,7 +1645,7 @@ native remove_user_flags(index, flags = -1, id = 0); * Registers a callback to be called when the client executes a command from the * console. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * @note Opting in to FlagManager enables the admin privileges to be overwritten * by the end user via the cmdaccess.ini config file. @@ -1676,7 +1670,7 @@ native register_clcmd(const client_cmd[], const function[], flags = -1, const in * Registers a callback to be called when the client or server executes a * command from the console. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * @note Opting in to FlagManager enables the admin privileges to be overwritten * by the end user via the cmdaccess.ini config file. @@ -1701,7 +1695,7 @@ native register_concmd(const cmd[], const function[], flags = -1, const info[] = * Registers a callback to be called when the server executes a command from the * console. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param client_cmd Command to register @@ -1718,7 +1712,7 @@ native register_srvcmd(const server_cmd[], const function[], flags = -1, const i /** * Retrieves information about a client command. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1730,27 +1724,27 @@ native register_srvcmd(const server_cmd[], const function[], flags = -1, const i * @param flag Only considers commands that can be accessed with * the specified privilege flags * - * @return 1 on succes, 0 if command was not found + * @return 1 on success, 0 if command was not found */ native get_clcmd(index, command[], len1, &flags, info[], len2, flag); /** * Returns number of registered client commands. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with * the specified privilege flags * - * @return Number of registered client commants + * @return Number of registered client commands */ native get_clcmdsnum(flag); /** * Retrieves information about a server command. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1762,27 +1756,27 @@ native get_clcmdsnum(flag); * @param flag Only considers commands that can be accessed with * the specified privilege flags * - * @return 1 on succes, 0 if command was not found + * @return 1 on success, 0 if command was not found */ native get_srvcmd(index, server_cmd[], len1, &flags, info[], len2, flag); /** * Returns number of registered server commands. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with * the specified privilege flags * - * @return Number of registered server commants + * @return Number of registered server commands */ native get_srvcmdsnum(flag); /** * Retrieves information about a console command. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param index Command index @@ -1797,14 +1791,14 @@ native get_srvcmdsnum(flag); * positive will only consider client commands, otherwise * all console commands will be considered * - * @return 1 on succes, 0 if command was not found + * @return 1 on success, 0 if command was not found */ native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id = -1); /** * Returns the parent plugin id of a console command. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param cid Command index @@ -1821,7 +1815,7 @@ native get_concmd_plid(cid, flag_mask, id_type); /** * Returns number of registered console commands. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc * * @param flag Only considers commands that can be accessed with @@ -1830,7 +1824,7 @@ native get_concmd_plid(cid, flag_mask, id_type); * positive will only consider client commands, otherwise * all console commands will be considered * - * @return Number of registered console commants + * @return Number of registered console commands */ native get_concmdsnum(flag, id = -1); @@ -1860,8 +1854,8 @@ native register_menucmd(menuid, keys, const function[]); /** * Returns if the client is watching a menu. * - * @note If there is no menu the id is 0. If the id is negative then the client - * views a VGUI menu. Otherwise the id is an id acquired from the + * @note If there is no menu, the id is 0. If the id is negative, then the client + * views a VGUI menu. Otherwise, the id is an id acquired from the * register_menuid() function. * * @param index Client index @@ -1877,7 +1871,7 @@ native get_user_menu(index, &id, &keys); /** * Forces the server to execute the command queue immediately. * - * @note Commands can be added to the queue using server_cmd(). + * @note Commands can be added to the queue using server_cmd() * * @noreturn */ @@ -1888,7 +1882,7 @@ native server_exec(); * * @note The sample must be precached using precache_sound() so it is available * in the engine's sound table. - * @note For a list of available channels see CHAN_* constants in amxconst.inc, + * @note For a list of available channels, see CHAN_* constants in amxconst.inc, * sounds emitted from the same channel will override each other. * @note There are helpful reference constants in amxconst.inc for sound volume * (VOL_*), attenuation (ATTN_*), flags (SND_*), and pitch (PITCH_*). @@ -1954,7 +1948,7 @@ native get_user_msgname(msgid, name[], len); * * @note Variables declared with the "public" specifier are accessible by-name * from outside of the declaring plugin. - * @note If multiple plugins declare the same public variable this native will + * @note If multiple plugins declare the same public variable, this native will * still return a unique id. * * @param name Variable name @@ -1975,7 +1969,7 @@ native xvar_exists(const name[]); /** * Returns the integer value of a public variable. * - * @note If multiple plugins declare the same public variable they are not + * @note If multiple plugins declare the same public variable, they are not * automatically synchronized. The xvar system accesses only one of all * public variables directly. Xvars have to be read through the natives or * the value will be incorrect. @@ -1989,7 +1983,7 @@ native get_xvar_num(id); /** * Returns the float value of a public variable. * - * @note If multiple plugins declare the same public variable they are not + * @note If multiple plugins declare the same public variable, they are not * automatically synchronized. The xvar system accesses only one of all * public variables directly. Xvars have to be read through the natives or * the value will be incorrect. @@ -2003,7 +1997,7 @@ native Float:get_xvar_float(id); /** * Sets the integer value of a public variable. * - * @note If multiple plugins declare the same public variable they are not + * @note If multiple plugins declare the same public variable, they are not * automatically synchronized. The xvar system accesses only one of all * public variables directly. Xvars have to be set through the natives or * the xvar will not be updated. @@ -2012,14 +2006,14 @@ native Float:get_xvar_float(id); * @param value Value to set * * @noreturn - * @error If an invalid xvar id is specified an error will be thrown. + * @error If an invalid xvar id is specified, an error will be thrown. */ native set_xvar_num(id, value = 0); /** * Sets the float value of a public variable. * - * @note If multiple plugins declare the same public variable they are not + * @note If multiple plugins declare the same public variable, they are not * automatically synchronized. The xvar system accesses only one of all * public variables directly. Xvars have to be set through the natives or * the xvar will not be updated. @@ -2028,7 +2022,7 @@ native set_xvar_num(id, value = 0); * @param value Value to set * * @noreturn - * @error If an invalid xvar id is specified an error will be thrown. + * @error If an invalid xvar id is specified, an error will be thrown. */ native set_xvar_float(id, Float:value = 0.0); @@ -2044,7 +2038,7 @@ native is_module_loaded(const name[]); /** * Retrieves info about a module by module index. * - * @note For a list of possible status flags see module_* constants in + * @note For a list of possible status flags, see module_* constants in * amxconst.inc * * @param id Module id @@ -2056,7 +2050,7 @@ native is_module_loaded(const name[]); * @param versionLen Maximum version buffer size * @param status Variable to store module status to * - * @return Module id on succes, -1 on invalid module + * @return Module id on success, -1 on invalid module */ native get_module(id, name[], nameLen, author[], authorLen, version[], versionLen, &status); @@ -2070,11 +2064,11 @@ native get_modulesnum(); /** * Returns if a plugin is loaded by registered name or filename. * - * @note An example for a registered name would be "Admin Base" while a possible - * filename would be "admin.amxx" - * @note Prior to AMXX 1.80 this function would only search for plugins + * @note An example for a registered name would be "Admin Base", while a possible + * filename would be "admin.amxx". + * @note Prior to AMXX 1.80, this function would only search for plugins * registered names, not the filename. - * @note The plugin name matching is case insensitive while the filename + * @note The plugin name matching is case insensitive, while the filename * matching is case sensitive. * * @param name Plugin name or filename @@ -2116,7 +2110,7 @@ native get_pluginsnum(); /** * Pauses a plugin so it will not be executed until it is unpaused. * - * @note This used to be able to pause specific functions but this functionality + * @note This used to be able to pause specific functions, but this functionality * (along with the flags "b" and "e") has been deprecated. * @note If used without flag "c" this will pause the calling plugin. * @@ -2136,7 +2130,7 @@ native pause(const flag[], const param1[] = "", const param2[] = ""); /** * Unpauses a plugin so it will resume execution if it was previously paused. * - * @note This used to be able to unpause specific functions but this + * @note This used to be able to unpause specific functions, but this * functionality (along with the flags "b" and "e") has been deprecated. * @note Without specifying flag "c" this function will do nothing, as a plugin * is incapable of unpausing itself. This is a relict of the deprecated @@ -2159,10 +2153,10 @@ native unpause(const flag[], const param1[] = "", const param2[] = ""); * * @note This only sets up the function call and covers the pre-requisites. * Push parameters using the callfunc_push_* set of functions. The call - * will be executed only upon using callfunc_end(). + * will be executed only upon using callfunc_end() * * @param func Function name - * @param plugin Plugin filename. If empty the calling plugin is targeted. + * @param plugin Plugin filename, if empty the calling plugin is targeted * The filename has to be the full exact name (e.g. stats.amxx) * * @return 1 on success @@ -2179,11 +2173,11 @@ native callfunc_begin(const func[], const plugin[] = ""); * * @note This only sets up the function call and covers the pre-requisites. * Push parameters using the callfunc_push_* set of functions. The call - * will be executed only upon using callfunc_end(). - * @note The function id can be retrieved by get_func_id(). + * will be executed only upon using callfunc_end() + * @note The function id can be retrieved by get_func_id() * * @param func Function id - * @param plugin Plugin filename. If empty the calling plugin is targeted. + * @param plugin Plugin filename, if empty the calling plugin is targeted * The filename has to be the full exact name (e.g. stats.amxx) * * @return 1 on success @@ -2195,11 +2189,11 @@ native callfunc_begin(const func[], const plugin[] = ""); native callfunc_begin_i(func, plugin = -1); /** - * Retrieves a functions id for use with callfunc_begin_i(). + * Retrieves a functions id for use with callfunc_begin_i() * * @param funcName Function name - * @param pluginId Plugin id. If -1 the calling plugin is targeted. The plugin - * id can be retrieved using find_plugin_byfile() + * @param pluginId Plugin id, if -1 the calling plugin is targeted + * The plugin id can be retrieved using find_plugin_byfile() * * @return >0 Function id on success * -1 if plugin or function was not found @@ -2263,7 +2257,7 @@ native callfunc_push_floatrf(&Float:value); * only kept for special backwards compatibility. * * @param VALUE String to push - * @param copyback If true any changes made in the called function will be + * @param copyback If true, any changes made in the called function will be * copied back to the calling plugin * * @noreturn @@ -2280,7 +2274,7 @@ native callfunc_push_str(const VALUE[], bool:copyback = true); * * @param VALUE Array to push * @param array_size Size of the array - * @param copyback If true any changes made in the called function will be + * @param copyback If true, any changes made in the called function will be * copied back to the calling plugin * * @noreturn @@ -2295,7 +2289,7 @@ native callfunc_push_array(const VALUE[], array_size, bool:copyback = true); * @return 1 on success * -1 if the plugin was not found * -2 if the function was not found - * @error If called without initiating a callfunc an error is thrown. + * @error If called without initiating a callfunc, an error is thrown. */ native callfunc_end(); @@ -2315,7 +2309,7 @@ forward inconsistent_file(id, const filename[], reason[64]); * Forces the clients and server to be running with the same version of a * specified file. * - * @note For a list of possible enforcement types see the force_* constants + * @note For a list of possible enforcement types, see the force_* constants * in amxconst.inc * * @param force_type Enforcement type @@ -2351,7 +2345,7 @@ native md5_file(const file[], md5buffer[34]); /** * Returns the internal flags set on the plugin's state. * - * @param hdr If nonzero the function will return the pcode rather than + * @param hdr If nonzero, the function will return the pcode rather than * state flags * @param plid Plugin id, -1 to target calling plugin * @@ -2360,7 +2354,7 @@ native md5_file(const file[], md5buffer[34]); native plugin_flags(hdr = 0, plid = -1); /** - * Allows plugins to declare module dependencies using require_module(). + * Allows plugins to declare module dependencies using require_module() * * @deprecated Module dependency has been automatically handled by the compiler * since AMXX 1.50, released in 2005. This forward is no longer @@ -2385,7 +2379,7 @@ native require_module(const module[]); /** * Returns if the server is 64 bit. * - * @deprecated As a result of Valve dropping support for 64bit binaries AMXX is + * @deprecated As a result of Valve dropping support for 64bit binaries, AMXX is * also not shipping 64bit builds anymore. This native is basically * guaranteed to return 0. * @@ -2425,8 +2419,8 @@ forward plugin_natives(); * @note Style 1 natives are deprecated. Plugins should not use them, they might * break. * @note Style 1 natives work a little different. Instead of passing plugin id - * and number of parameters the handler should be prototyped just like the - * native would be called. For each by-reference parameter the plugin + * and number of parameters, the handler should be prototyped just like the + * native would be called. For each by-reference parameter, the plugin * then has to use param_convert() to properly use them. * @note A native should *never* recurse. Bad things will happen. * @@ -2476,14 +2470,14 @@ native log_error(error, const fmt[], any:...); * @deprecated Style 1 natives are deprecated and should be converted to * style 0. This should not be used. * - * @note Only needs to be called this if the native was registered with style 1. + * @note This only needs to be called if the native was registered with style 1. * @note Remember that arrays (and strings) are always by-reference and need to * be converted. * * @param num Argument to convert, starting from 1 * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 0, an error will be thrown. */ native param_convert(num); @@ -2496,7 +2490,7 @@ native param_convert(num); * @param maxlen Maximum size of buffer * * @return Number of cells copied to buffer - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native get_string(param, dest[], maxlen); @@ -2509,7 +2503,7 @@ native get_string(param, dest[], maxlen); * @param maxlen Maximum size of buffer * * @return Number of cells copied from buffer - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native set_string(param, dest[], maxlen); @@ -2520,7 +2514,7 @@ native set_string(param, dest[], maxlen); * @param param Argument to retrieve, starting from 1 * * @return Integer value - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native get_param(param); @@ -2531,7 +2525,7 @@ native get_param(param); * @param param Argument to retrieve, starting from 1 * * @return Float value - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native Float:get_param_f(param); @@ -2543,7 +2537,7 @@ native Float:get_param_f(param); * @param param Argument to retrieve, starting from 1 * * @return Integer value - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native get_param_byref(param); @@ -2555,7 +2549,7 @@ native get_param_byref(param); * @param param Argument to retrieve, starting from 1 * * @return Float value - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native Float:get_float_byref(param); @@ -2568,7 +2562,7 @@ native Float:get_float_byref(param); * @param value Value to set parameter to * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native set_param_byref(param, value); @@ -2581,7 +2575,7 @@ native set_param_byref(param, value); * @param value Value to set parameter to * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native set_float_byref(param, Float:value); @@ -2594,7 +2588,7 @@ native set_float_byref(param, Float:value); * @param maxlen Size of buffer * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native get_array(param, dest[], size); @@ -2607,7 +2601,7 @@ native get_array(param, dest[], size); * @param maxlen Size of buffer * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native get_array_f(param, Float:dest[], size); @@ -2620,7 +2614,7 @@ native get_array_f(param, Float:dest[], size); * @param maxlen Size of buffer * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native set_array(param, const source[], size); @@ -2633,7 +2627,7 @@ native set_array(param, const source[], size); * @param maxlen Size of buffer * * @noreturn - * @error If used outside of a native callback or the native was + * @error If used outside of a native callback, or the native was * created with style 1, an error will be thrown. */ native set_array_f(param, const Float:source[], size); @@ -2665,7 +2659,7 @@ native set_error_filter(const handler[]); /** * Returns a trace handle for the item at the top of the traced call stack. * - * @note Intended for use inside an error handler set with set_error_filter(). + * @note Intended for use inside an error handler set with set_error_filter() * * @return Trace handle, 0 if no debugging information is available */ @@ -2734,7 +2728,7 @@ native dbg_fmt_error(buffer[], maxLength); * * @return 1 if handler is set successfully, 0 otherwise (called * outside of plugin_native() forward) - * @error If an invalid callback function is provided an error is + * @error If an invalid callback function is provided, an error is * thrown. */ native set_native_filter(const handler[]); @@ -2776,7 +2770,7 @@ native set_module_filter(const handler[]); * plugin_natives() forward. * @note The message will automatically be tagged with the plugin's name and the * log will include a timestamp with the message. - * @note For a list of possible error codes see AMX_* constants in amxconst.inc + * @note For a list of possible error codes, see AMX_* constants in amxconst.inc * * @param error Error code * @param fmt Formatting rules @@ -2805,9 +2799,9 @@ native module_exists(const logtag[]); * Returns if a specific library or class is loaded. * * @note This is the newer version of module_exists(), enabling users to - * distinguish between libraries and classes while module_exists() always + * distinguish between libraries and classes, while module_exists() always * checks for both types. - * @note For a list of possible types see the LibType enum in amxconst.inc + * @note For a list of possible types, see the LibType enum in amxconst.inc * * @param library Library/Class shortname * @param type Type to search for @@ -2826,7 +2820,7 @@ native LibraryExists(const library[], LibType:type); * * @return Valid hudchannel (1-4) * @error If the index is not within the range of 1 to MaxClients or - * the client is not connected an error will be thrown. + * the client is not connected, an error will be thrown. */ native next_hudchannel(player); @@ -2862,7 +2856,7 @@ native CreateHudSyncObj(num = 0, ...); * @note This functions return value behaves differently depending on what is * used as the client index: If 0 is specified, then the function will * return 0 if nothing has been sent (no client connected). If either a - * single client is specified or there is at least one client connected, + * single client is specified, or there is at least one client connected, * the number of printed characters will refer to the message that is sent * last, to the client with the highest index. * @@ -2872,8 +2866,8 @@ native CreateHudSyncObj(num = 0, ...); * @param ... Variable number of formatting parameters * * @return Number of printed characters - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); @@ -2890,8 +2884,8 @@ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); * @param syncObj HUD sync object handle * * @noreturn - * @error If a single client is specified and the index is not - * within the range of 1 to MaxClients an error will be thrown. + * @error If a single client is specified and the index is not within + * the range of 1 to MaxClients, an error will be thrown. */ native ClearSyncHud(target, syncObj); @@ -2940,7 +2934,7 @@ native get_var_addr(any:...); /** * Returns the value of an address. * - * @note Addresses can be acquired using get_var_addr(). + * @note Addresses can be acquired using get_var_addr() * * @param addr Variable address * @@ -2953,7 +2947,7 @@ native get_addr_val(addr); /** * Sets the value of an address. * - * @note Addresses can be acquired using get_var_addr(). + * @note Addresses can be acquired using get_var_addr() * * @param addr Variable address * @param val Value to set @@ -2967,8 +2961,8 @@ native set_addr_val(addr, val); /** * Creates a global forward that will be called in all plugins. * - * @note For a list of valid stop types see the ET_* constants in amxconst.inc - * @note For a list of valid parameter types see the FP_* constants in + * @note For a list of valid stop types, see the ET_* constants in amxconst.inc + * @note For a list of valid parameter types, see the FP_* constants in * amxconst.inc * * @param name Function name to call @@ -2983,7 +2977,7 @@ native CreateMultiForward(const name[], stop_type, ...); * Creates a private forward that will be called in a single plugin. * * @note Unlike other natives expecting a plugin id, specifying -1 will not - * select the calling plugin and instead throw an error. + * select the calling plugin, and instead throw an error. * * @param plugin_id Plugin to call forward in. The plugin id can be * retrieved using find_plugin_byfile() @@ -2991,7 +2985,7 @@ native CreateMultiForward(const name[], stop_type, ...); * @param ... List of parameter types * * @return Forward handle, -1 on failure - * @error If an invalid plugin id is specified an error will be + * @error If an invalid plugin id is specified, an error will be * thrown. */ native CreateOneForward(plugin_id, const name[], ...); @@ -3002,7 +2996,7 @@ native CreateOneForward(plugin_id, const name[], ...); * * @param array Array to prepare * @param size Size of array - * @param copyback If nonzero modifications made by the called plugin(s) + * @param copyback If nonzero, modifications made by the called plugin(s) * will be copied back to the caller * * @return Special handle for use in ExecuteForward() @@ -3012,7 +3006,7 @@ native PrepareArray(const array[], size, copyback = 0); /** * Executes a forward. * - * @note Passing arrays requires them to be prepared using PrepareArray(). + * @note Passing arrays requires them to be prepared using PrepareArray() * * @param forward_handle Forward handle * @param ret Variable to store return value in @@ -3061,9 +3055,9 @@ native get_weaponid(const name[]); /** * Adds an admin to the dynamic admin storage for lookup at a later time. * - * @note For a list of possible access flags see the ADMIN_* constants in + * @note For a list of possible access flags, see the ADMIN_* constants in * amxconst.inc - * @note For a list of possible auth flags see the FLAG_* constants in + * @note For a list of possible auth flags, see the FLAG_* constants in * amxconst.inc * * @param AuthData Auth information to set (can be name, IP or SteamID) @@ -3085,11 +3079,11 @@ native admins_num(); /** * Retrieves information about a dynamically stored admin. * - * @note For a list of possible props see the AdminProp enum in amxconst.inc + * @note For a list of possible props, see the AdminProp enum in amxconst.inc * * @param num Admin storage index * @param Property Admin property to retrieve - * @param Buffer Buffer to copy property information to if AdminProp_Auth + * @param Buffer Buffer to copy property information to, if AdminProp_Auth * or AdminProp_Password is specified * @param BufferSize Maximum buffer size *