File content in cvars.inc // vim: set ts=4 sw=4 tw=99 noet: // // AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO"). // Copyright (C) The AMX Mod X Development Team. // // This software is licensed under the GNU General Public License, version 3 or higher. // Additional exceptions apply. For full license details, see LICENSE.txt or visit: // https://alliedmods.net/amxmodx-license #if defined _cvars_included #endinput #endif #define _cvars_included /** * CVAR flags for create_cvar() and register_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 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 * * @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); /** * Registers a new cvar for the engine. * * @note Deprecated. Consider to use create_cvar for more options. * @note For a list of possible cvar flags see FCVAR_* constants in cvars.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. * * @param name Cvar name * @param string Default cvar value * @param flags Optional bitsum of flags specifying cvar behavior * @param fvalue Unused * * @return Unique cvar pointer */ native register_cvar(const name[], const string[], flags = FCVAR_NONE, Float:fvalue = 0.0); /** * Returns if a cvar is registered on the server. * * @param cvar Cvar name to check * * @return 1 if the cvar exists, 0 otherwise */ native cvar_exists(const cvar[]); /** * Returns the cvar pointer of the specified cvar. * * @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 * * @return Cvar pointer on success, 0 if cvar was not found */ native get_cvar_pointer(const cvar[]); /** * Creates a hook for when a cvar's value is changed. * * @note Changing the cvar value from within this forward can lead to infinite * recursion and should be avoided. * @note The callback will be called in the following manner: * * public cvar_change_callback(pcvar, const old_value[], const new_value[]) * * 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 * * @param pcvar Pointer to cvar * @param callback Name of 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[]); /** * Disables a cvar hook, stopping it from being called. * * @note Use the handle returned by hook_cvar_change as the parameter here. * * @param handle Forward to disable * @error If an invalid hook handle is provided, an error will be * thrown. */ native disable_cvar_hook(cvarhook:handle); /** * Enables a cvar hook, restoring it to being called. * * @note Use the handle returned by hook_cvar_change as the parameter here. * * @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. * * @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 * why the otherwise equivalent get_pcvar_flags() function should be used * instead. * * @param cvar Cvar name to retrieve flags from * * @return Flag value */ native get_cvar_flags(const cvar[]); /** * Sets specified flags to a cvar. The cvar is accessed by name. * * @note Not permitted for the "amx_version", "amxmodx_version", "fun_version" * and "sv_cheats" cvars. * @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 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 * * @return 1 on success, 0 if cvar does not exist or is not permitted */ native set_cvar_flags(const cvar[], flags); /** * Removes specified flags from a cvar. The cvar is accessed by name. * * @note Not permitted for the "amx_version", "amxmodx_version", "fun_version" * 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 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 * * @return 1 on success, 0 if cvar does not exist or is not permitted */ 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 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 * @param iLen Maximum size of the buffer * * @return Number of cells written to buffer. */ 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 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 * * @noreturn */ 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 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 * * @return Cvar value, converted to float */ 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 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 * * @noreturn */ 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 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 * * @return Cvar value, converted to int */ 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 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 * * @noreturn */ native set_cvar_num(const cvarname[], value); /** * Returns flags of a cvar via direct pointer access. * * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc * * @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 provided, an error will be * thrown. */ native get_pcvar_flags(pcvar); /** * Sets specified flags to a cvar via direct pointer access. * * @note For a list of possible flags see the FCVAR_* constants in amxconst.inc * @note This function directly sets the provided bitflag, unlike set_cvar_flags * which adds them using a bitwise OR. * * @param pcvar Pointer to cvar to set flags of * @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 provided, an error will be * thrown. */ native set_pcvar_flags(pcvar, flags); /** * Returns an integer value from a cvar via direct pointer access. * * @param pcvar Pointer to cvar to retrieve value from * * @return Cvar value, converted to int * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native get_pcvar_num(pcvar); /** * Returns an boolean value from a cvar via direct pointer access. * * @param pcvar Pointer to cvar to retrieve value from * * @return Cvar value, converted to bool * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native bool:get_pcvar_bool(pcvar); /** * Sets an integer value to a cvar via direct pointer access. * * @param pcvar Pointer to cvar to set value of * @param num Value to set cvar to * * @noreturn * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native set_pcvar_num(pcvar, num); /** * Sets a boolean value to a cvar via direct pointer access. * * @param pcvar Pointer to cvar to set value of * @param num Value to set cvar to * * @noreturn * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native set_pcvar_bool(pcvar, bool:num); /** * Returns a float value from a cvar via direct pointer access. * * @param pcvar Pointer to cvar to retrieve value from * * @return Cvar value, converted to float * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native Float:get_pcvar_float(pcvar); /** * Sets a float value to a cvar via direct pointer access. * * @param pcvar Pointer to cvar to set value of * @param num Value to set cvar to * * @noreturn * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native set_pcvar_float(pcvar, Float:num); /** * Returns a string value from a cvar via direct pointer access. * * @param pcvar Pointer to cvar to retrieve value from * @param string Buffer to copy cvar value to * @param maxlen Maximum size of the buffer * * @return Number of cells written to buffer. * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native get_pcvar_string(pcvar, string[], maxlen); /** * Sets a string value to a cvar via direct pointer access. * * @param pcvar Pointer to cvar to retrieve value from * @param string Value to set cvar to * * @noreturn * @error If an invalid cvar pointer is provided, an error will be * thrown. */ native set_pcvar_string(pcvar, const string[]); /** * Retrieves the specified value boundary of a cvar. * * @param pcvar Pointer to cvar * @param type Type of boundary to retrieve * @param value Variable to store the specified boundary to * * @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 boundary of a cvar. * * @param pcvar Pointer to cvar * @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 * * @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); /** * Binds a cvar's integer value to a global variable. The variable will then * always contain the current cvar value as it is automatically kept up to date. * * @note The variable *has* to be a global or a static variable. Local variables * created within functions can not be used for technical reasons. * @note Variables can not be bound to multiple cvars. * * @param pcvar Pointer to cvar * @param var Global variable to keep updated * * @noreturn * @error If an invalid cvar pointer or variable is provided, an error * will be thrown. */ native bind_pcvar_num(pcvar, &any:var); /** * Binds a cvar's float value to a global variable. The variable will then * always contain the current cvar value as it is automatically kept up to date. * * @note The variable *has* to be a global or a static variable. Local variables * created within functions can not be used for technical reasons. * @note Variables can not be bound to multiple cvars. * * @param pcvar Pointer to cvar * @param var Global variable to keep updated * * @noreturn * @error If an invalid cvar pointer or variable is provided, an error * will be thrown. */ native bind_pcvar_float(pcvar, &Float:var); /** * Binds a cvar's string value to a global array. The array will then * always contain the current cvar value as it is automatically kept up to date. * * @note The array *has* to be a global or a static array. Local arrays * created within functions can not be used for technical reasons. * @note Arrays can not be bound to multiple cvars. * * @param pcvar Pointer to cvar * @param var Global array to keep updated * @param varlen Maximum length of string array * * @noreturn * @error If an invalid cvar pointer or variable is provided, an error * will be thrown. */ native bind_pcvar_string(pcvar, any:var[], varlen); /** * Returns the number of plugin-registered cvars. * * @return Number of registered cvars */ native get_plugins_cvarsnum(); /** * 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 Index to retrieve * @param name Buffer to copy cvar name to * @param namelen Maximum buffer size * @param flags Variable to store cvar flags to * @param plugin_id Variable to store id of the registering plugin to * @param pcvar_handle Variable to store cvar pointer to * @param description Variable to store cvar description to * @param desc_len Maximum length of string buffer * * @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); /** * Dispatches a client cvar query, allowing the plugin to query for its value on * the client. * * @note The callback will be called in the following manner: * * public cvar_query_callback(id, const cvar[], const value[], const param[]) * * 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 * @param resultFunc Callback function * @param paramlen Size of extra data * @param params Extra data to pass through to callback * * @noreturn * @error If the client index is not within the range of 1 to * 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[] = "");