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

amxmodx: Fifth batch of documentation updates

Browse Source
This commit is contained in:
Valentin Grünbacher 2014-08-07 00:19:24 +02:00
parent 3a232f1576
commit 37e22dc22f
1 changed files with 542 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

688
plugins/include/amxmodx.inc
View File

@ -57,9 +57,12 @@ forward plugin_unpause();
* Called when the mod tries to change the map. * Called when the mod tries to change the map.
* *
* @note This is *only* called if the mod itself handles the map change. The * @note This is *only* called if the mod itself handles the map change. The
* server command "changelevel" which is also used by plugins will not * server command "changelevel" which is used by many plugins will not
* trigger this forward. Unfortunately this means that in practice this * trigger this forward. Unfortunately this means that in practice this
* forward is very unreliable, and will not be called in many situations. * forward is very unreliable, and will not be called in many situations.
* @note AMXX 1.8.3 has added the change_level() 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 * @param map Map that the mod tries to change to
* *
@ -1364,11 +1367,13 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]="");
native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
/** /**
* Executes a command from the server console. * Queues a command to be executed from the server console.
* *
* @note Warning: This is a potential source of command injection. Do not feed * @note Warning: This is a potential source of command injection. Do not feed
* client-controlled input (including client names) to this function * client-controlled input (including client names) to this function
* without sanitizing it first. * 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().
* *
* @param command Formatting rules * @param command Formatting rules
* @param ... Variable number of formatting parameters * @param ... Variable number of formatting parameters
@ -1731,7 +1736,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 If the index is not within the range of 0 to MaxClients, an
* error will be thrown. * 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. * Removes the specified admin flags from a client.
@ -1757,19 +1762,19 @@ native remove_user_flags(index, flags=-1, id=0);
* Set FlagManager to 0 to make FlagManager never include this command * Set FlagManager to 0 to make FlagManager never include this command
* Returns the command ID. * Returns the command ID.
*/ */
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 function which will be called from any console. /* Registers function which will be called from any console.
* Set FlagManager to 1 to make FlagManager always include this command * Set FlagManager to 1 to make FlagManager always include this command
* Set FlagManager to 0 to make FlagManager never include this command * Set FlagManager to 0 to make FlagManager never include this command
* Returns the command ID. * Returns the command ID.
*/ */
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 function which will be called from server console. /* Registers function which will be called from server console.
* Returns the command ID. * Returns the command ID.
*/ */
native register_srvcmd(const server_cmd[],const function[],flags=-1, const info[]=""); native register_srvcmd(const server_cmd[], const function[], flags=-1, const info[]="");
/* Gets info about client command. */ /* Gets info about client command. */
native get_clcmd(index, command[], len1, &flags, info[], len2, flag); native get_clcmd(index, command[], len1, &flags, info[], len2, flag);
@ -1812,92 +1817,245 @@ native register_menucmd(menuid,keys, const function[] );
* is VGUI in other case the id is from register_menuid() function. */ * is VGUI in other case the id is from register_menuid() function. */
native get_user_menu(index,&id,&keys); native get_user_menu(index,&id,&keys);
/* Forces server to execute sent server command at current time. /**
* Very useful for map changes, setting cvars and other activities. */ * Forces the server to execute the command queue immediately.
*
* @note Commands can be added to the queue using server_cmd().
*
* @noreturn
*/
native server_exec(); native server_exec();
/* Emits sound. Sample must be precached. */ /**
* Emits a sound from an entity from the engine.
*
* @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,
* 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_*).
*
* @param index Entity index, use 0 to emit from all clients
* @param channel Channel to emit from
* @param sample Sound file to emit
* @param vol Volume in percent
* @param att Sound attenuation
* @param flags Emit flags
* @param pitch Sound pitch
*/
native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pitch); native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pitch);
/* Registers new cvar for HL engine. /**
* Returns the cvar pointer for get/set_pcvar functions. * Registers a new ccvar for the engine.
*
* @note For a list of possible cvar flags see FCVAR_* constants in amxconst.inc
* @note If an already existing cvar is registered it will not be duplicated.
* @note 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 Cvar flags
* @param fvalue
*
* @return Unique cvar pointer
*/ */
native register_cvar(const name[],const string[],flags = 0,Float:fvalue = 0.0); native register_cvar(const name[], const string[], flags = 0, Float:fvalue = 0.0);
/* Generates random floating point number from a to b. */ /**
native Float:random_float(Float:a,Float:b); * Returns a random floating point value generated by the engine.
*
* @param a,b Range of generated value, inclusive
*
* @return Generated random value
*/
native Float:random_float(Float:a, Float:b);
/* Generates random integer from a to b. */ /**
native random_num(a,b); * Returns a random integer value generated by the engine.
*
* @param a,b Range of generated value, inclusive
*
* @return Generated random value
*/
native random_num(a, b);
/* Returns id of client message. /**
* Example: get_user_msgid("TextMsg"). */ * 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
* change between updates. They should not be hardcoded into plugins.
*
* @param name Client message name
*
* @return Message id, 0 if message was not found
*/
native get_user_msgid(const name[]); native get_user_msgid(const name[]);
/* Gets name of client message index. Return value is number of /**
* characters copied into name. Returns 0 on invalid msgid. */ * Retrieves the client message name from a message id.
*
* @param msgid Client message id
* @param name Buffer to copy message name to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer, 0 on invalid message id
*/
native get_user_msgname(msgid, name[], len); native get_user_msgname(msgid, name[], len);
/* Checks if public variable with given name exists in loaded plugins. */ /**
native xvar_exists( const name[] ); * Returns a unique id for a public variable.
*
* @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
* still return a unique id.
*
* @param name Variable name
*
* @return Xvar id on success, -1 on failure
*/
native get_xvar_id(const name[]);
/* Returns an unique id for public variable specified by name. If such /**
* variable doesn't exist then returned value is -1. */ * Returns if a public variable exists in any loaded plugin.
native get_xvar_id( const name[] ); *
* @param name Variable name
*
* @return 1 if public cvar exists, 0 otherwise
*/
native xvar_exists(const name[]);
/* Returns an integer value of a public variable. Id is a value /**
* returned by get_xvar_id(...) native. */ * Returns the integer value of a public variable.
native get_xvar_num( id ); *
* @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.
*
* @param id Xvar id, an xvar id can be retrieved using get_xvar_id()
*
* @return Xvar integer value
*/
native get_xvar_num(id);
/* Returns a float value of a public variable. Id is a value /**
* returned by get_xvar_id(...) native. */ * Returns the float value of a public variable.
native Float:get_xvar_float( id ); *
* @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.
*
* @param id Xvar id, an xvar id can be retrieved using get_xvar_id()
*
* @return Xvar float value
*/
native Float:get_xvar_float(id);
/* Sets a value of a public variable. Id is a value /**
* returned by get_xvar_id(...) native. */ * Sets the integer value of a public variable.
native set_xvar_num( id, value = 0 ); *
* @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.
*
* @param id Xvar id, an xvar id can be retrieved using get_xvar_id()
* @param value Value to set
*
* @noreturn
* @error If an invalid xvar id is specified an error will be thrown.
*/
native set_xvar_num(id, value = 0);
/* Sets a float value of a public variable. Id is a value /**
* returned by get_xvar_id(...) native. */ * Sets the float value of a public variable.
native set_xvar_float( id, Float:value = 0.0 ); *
* @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.
*
* @param id Xvar id, an xvar id can be retrieved using get_xvar_id()
* @param value Value to set
*
* @noreturn
* @error If an invalid xvar id is specified an error will be thrown.
*/
native set_xvar_float(id, Float:value = 0.0);
/* Checks whether a module is loaded. If it is not, the return value is -1, otherwise /**
* the return value is the module id. The function is case insensitive. */ * Returns if a module is loaded.
*
* @param name Module name
*
* @return Module id of the matching module, -1 otherwise
*/
native is_module_loaded(const name[]); native is_module_loaded(const name[]);
/**
/* Gets info about a module. * Retrieves info about a plugin by plugin index.
* Parameters: *
* id - the id of the module * @param index Plugin index, -1 to target calling plugin
* name[] - The name of the module will be stored here * @param filename Buffer to copy plugin filename to
* nameLen - maximal length of the name * @param len1 Maximum filename buffer size
* author[] - the author will be stored here * @param name Buffer to copy plugin name to
* authorLen - maximal length of the author * @param len2 Maximum name buffer size
* version[] - the version of the module will be stored here * @param version Buffer to copy plugin version to
* versionLen - maximal length of the version * @param len3 Maximum version buffer size
* status - the status of the module will be stored here * @param author Buffer to copy plugin author to
* Return value: * @param len4 Maximum author buffer size
* id - success * @param status Buffer to copy plugin status flags to
* -1 - module not found */ * @param len5 Maximum status buffer size
* @param ... Unused and ignored
*
* @return Plugin index on success, -1 if there is no plugin with given
* index
*/
/**
* Retrieves info about a module by module index.
*
* @note For a list of possible status flags see module_* constants in
* amxconst.inc
*
* @param id Module id
* @param name Buffer to copy module name to
* @param nameLen Maximum name buffer size
* @param author Buffer to copy module author to
* @param authorLen Maximum author buffer size
* @param version Buffer to copy module version to
* @param versionLen Maximum version buffer size
* @param status Variable to store module status to
*
* @return Module id on succes, -1 on invalid module
*/
native get_module(id, name[], nameLen, author[], authorLen, version[], versionLen, &status); native get_module(id, name[], nameLen, author[], authorLen, version[], versionLen, &status);
/* Returns number of currently registered modules */ /**
* Returns the number of currently registered modules.
*
* @return Number of modules
*/
native get_modulesnum(); native get_modulesnum();
/** /**
* Checks whether a plugin is loaded by the given registered name (such as "Admin Base"), or, optionally * Returns if a plugin is loaded by registered name or filename.
* the given filename ("admin.amxx").
* *
* @param name Either the plugin name to lookup, or the plugin filename to lookup. * @note An example for a registered name would be "Admin Base" while a possible
* @param usefilename Set to true if you want to search for the plugin by the filename, false to search * filename would be "admin.amxx"
* by the plugin's registered name. * @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
* matching is case sensitive.
* *
* @return Plugin ID of the matching plugin on a successful search, -1 on a failed search. * @param name Plugin name or filename
* @param usefilename If true searches for plugin filename, false searches for
* plugin name
* *
* @note Prior to 1.8, this function would only search for plugins registered names, not * @return Plugin id of the matching plugin, -1 otherwise
* the filename.
*
* @note The plugin registered name search is a case insensitive search, however, the plugin
* filename search is case sensitive.
*/ */
native is_plugin_loaded(const name[], bool:usefilename=false); native is_plugin_loaded(const name[], bool:usefilename=false);
@ -1929,25 +2087,45 @@ native get_plugin(index,filename[]="",len1=0,name[]="",len2=0,version[]="",len3=
*/ */
native get_pluginsnum(); native get_pluginsnum();
/* Pauses function or plugin so it won't be executed. /**
* In most cases param1 is name of function and * Pauses a plugin so it will not be executed until it is unpaused.
* param2 name of plugin (all depends on flags). *
* Flags: * @note This used to be able to pause specific functions but this functionality
* "a" - pause whole plugin. * (along with the flags "b" and "e") has been deprecated.
* "c" - look outside the plugin (by given plugin name). * @note If used without flag "c" this will pause the calling plugin.
* "d" - set "stopped" status when pausing whole plugin. *
* In this status plugin is unpauseable. * @param flag Pause flags
* Example: pause("ac","myplugin.amxx") * "a" - pause plugin
* * "c" - search for other plugins using param1
* Note: There used to be the b and e flags as well, * "d" - stop plugin, making it unavailable to unpause
* which have been deprecated and are no longer used. * @param param1 Plugin filename
*/ * @param param2 Unused and ignored
*
* @return 1 on success, 0 otherwise
* @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 function or plugin. /**
* Flags: * Unpauses a plugin so it will resume execution if it was previously paused.
* "a" - unpause whole plugin. *
* "c" - look outside the plugin (by given plugin name). */ * @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
* functionality.
*
* @param flag Pause flags
* "a" - pause plugin
* "c" - search for other plugins using param1
* @param param1 Plugin filename
* @param param2 Unused and ignored
*
* @return 1 on success, 0 otherwise
* @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[]="");
/** /**
@ -2095,12 +2273,32 @@ native callfunc_push_array(const VALUE[], array_size, bool:copyback=true);
*/ */
native callfunc_end(); native callfunc_end();
/* Called on inconsistent file. You can put any text /**
* into reason to change an original message. */ * Called when an inconsistent file is encountered by the engine.
*
* @param id Client index
* @param filename Detected file
* @param reason Buffer storing the disconnect reason (can be overwritten)
*
* @return PLUGIN_CONTINUE to let the engine kick the client
* PLUGIN_HANDLED to block the inconsistency kick
*/
forward inconsistent_file(id,const filename[], reason[64] ); forward inconsistent_file(id,const filename[], reason[64] );
/* Forces the client and server to be running with the same /**
* version of the specified file ( e.g., a player model ). */ * 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
* in amxconst.inc
*
* @param force_type Enforcement type
* @param mins Bounding box mins vector
* @param maxs Bounding box maxs vector
* @param filename Filename
*
* @return 1 on success, 0 otherwise
*/
native force_unmodified(force_type, const mins[3] , const maxs[3], const filename[]); native force_unmodified(force_type, const mins[3] , const maxs[3], const filename[]);
/** /**
@ -2124,27 +2322,63 @@ native md5(const szString[], md5buffer[34]);
*/ */
native md5_file(const file[], md5buffer[34]); native md5_file(const file[], md5buffer[34]);
/* Returns the internal flags set on the plugin's state /**
* If hdr is 1, it will return the pcode flags rather than state flags. * Returns the internal flags set on the plugin's state.
* *
* Use a plid of -1 to get the flags for the calling plugin. * @param hdr If nonzero the function will return the pcode rather than
* state flags
* @param plid Plugin id, -1 to target calling plugin
*/ */
native plugin_flags(hdr=0, plid=-1); native plugin_flags(hdr=0, plid=-1);
/** /**
* @deprecated * Allows plugins to declare module dependencies using require_module()
* Do not use! *
* @deprecated Module dependency has been automatically handled by the compiler
* since AMXX 1.50, released in 2005. This forward is no longer
* called.
*
* @noreturn
*/ */
forward plugin_modules(); forward plugin_modules();
/**
* 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.
*
* @noreturn
*/
native require_module(const module[]); 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
* also not shipping 64bit builds anymore. This native is basically
* guaranteed to return 0.
*
* @return 1 if the server is 64 bit, 0 otherwise
*/
native is_amd64_server(); native is_amd64_server();
/* Returns plugin id searched by file/name. Returns INVALID_PLUGIN_ID on failure. */ /**
* Returns plugin id by filename.
*
* @param filename Filename to match
* @param ignoreCase If nonzero matches case insensitively, case sensitively
* otherwise
*
* @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);
/* This is called before plugin_init and allows you to register natives. */ /**
* Called before plugin_init(), allowing the plugin to register natives.
*
* @noreturn
*/
forward plugin_natives(); forward plugin_natives();
/* Registers a NATIVE. When a plugin uses your native (you should distribute a .inc), /* Registers a NATIVE. When a plugin uses your native (you should distribute a .inc),
@ -2300,31 +2534,64 @@ native set_native_filter(const handler[]);
native set_module_filter(const handler[]); native set_module_filter(const handler[]);
/** /**
* Aborts execution of the current callback. Your script will throw a run time error. * Aborts execution of the current callback by throwing an error.
* You can also specify an optional message. *
* You should NOT call this function inside: * @note Warning: This function should not be used inside error filters, module
* - Error or module filters (native filters are safe if trap is 1) * filters (native filters are safe if trap equals 1) or the
* - plugin_natives() * plugin_natives() forward.
* Note that the plugin's filename is prepending to your message: * @note The message will automatically be tagged with the plugin's name and the
* [myplugin.amxx] MESSAGE * log will include a timestamp with the message.
* @note For a list of possible error codes see AMX_* constants in amxconst.inc
*
* @param error Error code
* @param fmt Formatting rules
* @param ... Variable list of formatting parameters
*
* @noreturn
* @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:...);
/** /**
* Checks if a specific module is loaded. This is the exact same method AMX Mod X * Returns if a specific module is loaded.
* uses to see if a module is required by a plugin. For example: *
* module_exists("cstrike") * @note This uses the same method AMXX uses internally to see if a module is
* module_exists("dbi") * required by a plugin.
* @note Example usage: module_exists("cstrike")
*
* @param logtag Module shortname
*
* @return 1 if module is loaded, 0 otherwise
*/ */
native module_exists(const logtag[]); native module_exists(const logtag[]);
/** /**
* Checks if a library/class is loaded. This is the newer version of module_exists. * 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
* checks for both types.
* @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
*
* @return 1 if module is loaded, 0 otherwise
*/ */
native LibraryExists(const library[], LibType:type); native LibraryExists(const library[], LibType:type);
/** /**
* Returns the next valid hudchannel for a user, from 1-4. * Returns the next valid hudchannel for the client.
*
* @note This function uses the same method set_hudmessage() uses to determine
* the next channel if it is set to auto-select.
*
* @param player Client index
*
* @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.
*/ */
native next_hudchannel(player); native next_hudchannel(player);
@ -2340,81 +2607,205 @@ native next_hudchannel(player);
* clear a message from another plugin. * clear a message from another plugin.
* The parameters are kept blank for future use. * The parameters are kept blank for future use.
*/ */
/**
* Creates a HUD synchronization object.
*
* @note Create one of these for each section of the screen that contains
* overlapping HUD messages. For example, if you use both sides of the
* screen to display three messages that could potentially overlap,
* each side is considered a synchronizable area. You can then use
* ShowSyncHudMsg() to correctly synchronize displaying the HUD message
* with any other messages potentially in its class.
* @note This does not do anything like reserving screen area. Its sole
* purpose is to be able to wipe an old message on an auto-channel and
* ensure that it will not clear a message from another plugin.
*
* @param num Unused and ignored
* @param ... Unused and ignored
*
* @return HUD sync object handle
*/
native CreateHudSyncObj(num=0, ...); native CreateHudSyncObj(num=0, ...);
/** /**
* Displays a synchronized HUD message. This will check that your * Displays a synchronized HUD message.
* HUD object has its previous display on the screen cleared before *
* it proceeds to write another. It will only do this in the case * @note This will check that your HUD object has its previous display on the
* of that channel not having been cleared already. * screen cleared before it proceeds to write another message. It will
* Target can be 0 for all players or 1-get_maxplayers(). * only do this in the case of that channel not having been cleared
* You must use set_hudmessage, although the channel parameter is * already.
* entirely ignored. * @note This uses the display parameters set with set_hudmessage(), ignoring
* the selected channel in favor of its own synchronization.
*
* @param target Client index, use 0 to display to all clients
* @param syncObj HUD sync object handle
* @param fmt 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
*/ */
native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); native ShowSyncHudMsg(target, syncObj, const fmt[], any:...);
/** /**
* Clears the display on a HudSync Object. This is essentially the same * Clears the display on a HUD sync object.
* thing as: ShowSyncHudMsg(x, y, ""), except doing that would send *
* out two messages and use up another channel. This re-uses the last * @note This sends an empty message to the previously occupied HUD channel.
* channel and clears it at the same time. * It is not quite the same as manually sending an empty message to the
* Note: for this you do not have to use set_hudmessage(). * sync object as that would send out two separate messages, one for
* Note: target can be 0 for all players. * clearing the occupied channel and another using a new channel, which
* will subsequently not mark the sync object as cleared.
*
* @param target Client index, use 0 to display to all clients
* @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
*/ */
native ClearSyncHud(target, syncObj); native ClearSyncHud(target, syncObj);
//no /**
* Triggers the software interrupt 3, used for breaking into an attached
* debugger.
*
* @note Warning: This is a debugging function that is not intended for general
* plugin use. Using this function will either halt the server and break
* into the attached debugger, or outright crash the server if no
* debugger is attached.
*
* @noreturn
*/
native int3(); native int3();
//Sets your plugin to a failed/error state. /**
//If you use this, your plugin will cease operating. * Sets the calling plugin to a failed state.
//This is a good idea to fatally, but gracefully, handle errors. *
//You can set a failed error message. * @note Calling this will cause the calling plugin to completely cease
* operation. It is not possible to recover.
* @note This should be used to gracefully handle fatal errors. The log message
* will appear in the AMXX error log.
*
* @param fmt Formatting rules
* @param ... Variable number of formatting parameters
*
* @noreturn
* @error The function is guaranteed to throw a fatal error, ceasing
* further operation of the plugin.
*/
native set_fail_state(const fmt[], any:...); native set_fail_state(const fmt[], any:...);
//Returns the reference address of the variable passed in. /**
//This address is local to the plugin, and not a full CPU address * Returns the reference address of the variable passed in.
//pass the variable as the first parameter *
* @note Addresses are local to the plugin and do not represent a full CPU
* address.
*
* @param ... Variable to retrieve address from
*
* @return Variable address
*/
native get_var_addr(any:...); native get_var_addr(any:...);
//Returns the value of an address. This dereferences something returned by /**
// get_var_addr(). Attempting to pass in a value beyond stack or heap limits * Returns the value of an address.
// will result in AMX_ERR_MEMACCESS. *
* @note Addresses can be acquired using get_var_addr().
*
* @param addr Variable 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.
*/
native get_addr_val(addr); native get_addr_val(addr);
//Sets the value of an address. same as above, essentially /**
* Sets the value of an address.
*
* @note Addresses can be acquired using get_var_addr().
*
* @param addr Variable address
* @param val Value to set
*
* @error If the plugin attempts to access an address outside of the
* stack or heap limits of the plugin, an error will be thrown.
*/
native set_addr_val(addr, val); native set_addr_val(addr, val);
/** /**
* Creates a multi-plugin forward. * Creates a global forward that will be called in all plugins.
* Stop type must be one of the ET_ values in amxconst.inc *
* results will be > 0 for success * @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
* @param stop_type Treatment of the plugin return values
* @param ... List of parameter types
*
* @return Forward handle, -1 on failure
*/ */
native CreateMultiForward(const name[], stop_type, ...); native CreateMultiForward(const name[], stop_type, ...);
/** /**
* Creates a forward for one plugin. * Creates a private forward that will be called in a single plugin.
* Results will be > 0 for success. *
* id should be an id such as returned by find_plugin_byfile. * @note Unlike other natives expecting a plugin id, specifying -1 will not
* Unlike get_plugin(), negative numbers will not work. * 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()
* @param name Function name to call
* @param ... List of parameter types
*
* @return Forward handle, -1 on failure
* @error If an invalid plugin id is specified an error will be
* thrown.
*/ */
native CreateOneForward(plugin_id, const name[], ...); native CreateOneForward(plugin_id, const name[], ...);
/** /**
* prepares an array. use this and pass the result into * Prepares an array for use in a forward. Pass the result ExecuteForward()
* ExecuteForward() instead of the array itself. * instead of the array itself.
*
* @param array Array to prepare
* @param size Size of array
* @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()
*/ */
native PrepareArray(const array[], size, copyback=0); native PrepareArray(const array[], size, copyback=0);
/** /**
* executes a forward. returns result in ret. * Executes a forward.
* returns 1 for success, 0 for failure. *
* @note Passing arrays requires them to be prepared using PrepareArray().
*
* @param forward_handle Forward handle
* @param ret Variable to store return value in
* @param ... Variable number of parameters to pass through
*
* @return 1 on success, 0 if forward can't be executed
* @error If the number of parameters mismatch from the number
* of parameters that the forward was declared with,
* an error is thrown.
*/ */
native ExecuteForward(forward_handle, &ret, any:...); native ExecuteForward(forward_handle, &ret, any:...);
/** /**
* Destroys/deallocates any type of forward * Destroys and deallocates a forward.
*
* @note Does not distinguish between private and global forwards.
*
* @param forward_handle Forward handle
*
* @noreturn
*/ */
native DestroyForward(forward_handle); native DestroyForward(forward_handle);
@ -2534,8 +2925,13 @@ native set_pcvar_string(pcvar, const string[]);
native arrayset(array[], value, size); native arrayset(array[], value, size);
/** /**
* Returns the weapon id, otherwise 0 when no id found. * Returns the weapon id associated with a weapon name.
* The weapon name is case sensitive, and has the weapon_* form. *
* @note The weapon name is case sensitive and has the weapon_* form.
*
* @param name Weapon name
*
* @return Weapon id, or 0 if no id was found
*/ */
native get_weaponid(const name[]); native get_weaponid(const name[]);