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[] = "");