amxmodx/plugins/include/amxmodx.inc

2973 lines
103 KiB
PHP
Executable File

/* AMX Mod X functions
*
* by the AMX Mod X Development Team
* originally developed by OLO
*
* This file is provided as is (no warranties).
*/
#if defined _amxmodx_included
#endinput
#endif
#define _amxmodx_included
#include <core>
#include <float>
#include <amxconst>
#include <string>
#include <file>
#include <vault>
#include <lang>
#include <messages>
#include <vector>
#include <sorting>
#include <cellarray>
#include <cellstack>
#include <celltrie>
#include <datapack>
#include <newmenus>
/**
* 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.
*
* @noreturn
*/
forward plugin_init();
/**
* Called just before the plugin is paused from execution.
*
* @noreturn
*/
forward plugin_pause();
/**
* Called just after the plugin is unpaused.
*
* @noreturn
*/
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 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
*
* @return PLUGIN_CONTINUE to let the mod change the map
* PLUGIN_HANDLED or higher to prevent the map change
*/
forward server_changelevel(map[]);
/**
* Called when all plugins went through plugin_init
*
* @note When this forward is called most plugins should have registered their
* cvars and commands already.
*
* @noreturn
*/
forward plugin_cfg();
/**
* 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
* in the plugin and AMXX leaking memory.
*
* @noreturn
*/
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.
*
* @return PLUGIN_CONTINUE to let the log message through
* PLUGIN_HANDLED or higher to stop the log message
*/
forward plugin_log();
/**
* This forward allows you to add models, sounds and generic files to the
* precache tables using the precache_* set of functions.
*
* @note Adding files to the precaching tables will trigger the client to
* download them to its local filesystem.
* @note There is a hard upper limit of entries in the precaching tables for
* every game, this limit is 512 in most cases. The entries will be filled
* and indexed incrementally. Going over this limit will crash the server.
*
* @noreturn
*/
forward plugin_precache();
/**
* Called when a clients info has changed
*
* @param id Client index
*
* @noreturn
*/
forward client_infochanged(id);
/**
* Called when a client is connecting.
*
* @note This forward is called too early to do anything that directly affects
* the client.
*
* @param id Client index
*
* @noreturn
*/
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"
*
* @param id Client index
*
* @noreturn
*/
forward client_authorized(id);
/**
* Called when a client is disconnecting from the server.
*
* @note By this point it is already too late to do anything that directly
* affects the client.
*
* @param id Client index
*
* @noreturn
*/
forward client_disconnect(id);
/**
* Called when a client attempts to execute a command.
*
* @note The command and its arguments can be read using the read_arg* set of
* functions.
*
* @param id Client index
*
* @return PLUGIN_CONTINUE to let the client execute the command
* PLUGIN_HANDLED or higher to stop the command
*/
forward client_command(id);
/**
* Called when a client is entering the game.
*
* @note It is not defined whether the client already has a SteamID when this
* forward is called. client_authorized may occur either before or after
* this.
*
* @param id Client index
*
* @noreturn
*/
forward client_putinserver(id);
/**
* Sets informations about the calling plugin.
*
* @param plugin_name Name of the plugin
* @param version Version of the plugin
* @param author Author of the plugin
*
* @return Plugin id of the calling plugin
*/
native register_plugin(const plugin_name[], const version[], const author[]);
/**
* Precaches a model file.
*
* @note Can only be used inside of the plugin_precache() forward.
*
* @param name Path to the model file
*
* @return Cache id of the model, even if the file was already precached
* @error If called outside of the plugin_precache() forward, an error is
* thrown.
*/
native precache_model(const name[]);
/**
* Precaches a sound file.
*
* @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.
* @note Precaching other filetypes (such as mp3 music), optionally in different
* locations, has to be done with precache_generic.
*
*
* @param name Path to the sound file
*
* @return Cache id of the sound, even if the file was already precached
* @error If called outside of the plugin_precache() forward, an error is
* thrown.
*/
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
*
* @param szFile Path to the file
*
* @return Cache id of the file, even if the file was already precached
* @error If called outside of the plugin_precache() forward, an error
* is thrown.
*/
native precache_generic(const szFile[]);
/**
* Sets info on the client.
*
* @param index Client index
* @param info Info key
* @param value New value
*
* @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.
* @error If called outside of the plugin_precache() forward, an error
* is thrown.
*/
native set_user_info(index,const info[], const value[]);
/**
* Gets info from the client.
*
* @param index Client index
* @param info Info key
* @param output Buffer to copy value to
* @param len Maximum size of the buffer
*
* @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.
*/
native get_user_info(index, const info[], output[], len);
/**
* Sets info on the server.
*
* @param info Info key
* @param value New value
*
* @noreturn
*/
native set_localinfo(const info[], const value[]);
/**
* Gets info from the server.
*
* @param info Info key
* @param output Buffer to copy value to
* @param len Maximum size of the buffer
*
* @return Number of cells written to buffer
*/
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.
*
* @noreturn
*/
native show_motd(player, const message[], const header[]="");
/**
* Sends a message to the client.
*
* @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
*/
native client_print(index, type, const message[], any:...);
/**
* Sends colored chat messages to clients.
*
* @note This only works in Counter-Strike 1.6 and Condition Zero.
* @note The colors can be modified inside of the format string using special
* characters. These characters can be included using the escape character
* green x04 ; use location color from this point forward
* red/blue/grey x03 ; use team color from this point forward
* red/blue/grey x02 ; use team color to the end of the client name
* ; 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 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.
*
* @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 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 client_print_color(index, sender, const message[], any:...);
/**
* Sends a message to the client via the engine.
*
* @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
*/
native engclient_print(player, type, const message[], any:...);
/**
* Sends a message to the console of a client or the server.
*
* @param index Client index, or 0 to print to the server console
* @param message Formatting rules
* @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
*/
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 cmd Formatting rules
* @param ... Variable number of formatting parameters
*
* @return The length of the formatted command.
*/
native console_cmd(id, const cmd[], any:...);
/**
* Registers a function to be called on a given game event.
*
* @note Examples for event conditions:
* "2=c4" - Second parameter of message must be the string "c4"
* "3>10" - Third parameter of message must be greater than 10
* "3!4" - Third parameter of message must not be equal to 4
* "2&Buy" - Second parameter of message must contain "Buy" substring
* "2!Buy" - Second parameter of message must not equal "Buy"
* @note Due to a long-standing bug that would break compatibility with older
* plugins, the client id should be checked for alive/dead state if you
* use flags "d" or "e".
*
* @param event Name of event that should be hooked
* @param function Name of callback function
* @param flags Flags used for filtering events, the valid flags are:
* "a" - Global event (sent to every client)
* "b" - Event sent to single client
* "c" - Call only once when repeated to multiple clients
* "d" - Call only if sent to dead client
* "e" - Call only if sent to alive client
* "f" - Call only if sent to human client ("b" flag required)
* "g" - Call only if sent to bot ("b" flag required)
* @param cond Condition string used for filtering events, built as:
* "<argument number><comparison operator><value>"
* Argument number is the argument position to be filtered
* The comparison operator may be:
* - "=" for equality comparison (all argument types)
* - "!" for inequality comparison (all argument types)
* - "&" for bitwise and (int argument) or substring
* comparison (string argument)
* - "<" for less than comparison (int/float arguments)
* - ">" for greater than comparison (int/float arguments)
* The argument is compared to the specified value accordingly
* @param ... Any number of additional conditions
*
* @return 1 on successfully registering event
* 0 on failure
* @error Invalid event name or invalid callback function
*/
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"
*
* @param function Name of callback function
* @param argsnum Number of arguments of the log event
* @param ... Any number of conditions used for filtering events
* A condition string is built as:
* "<argument number><comparison operator><string>"
* Argument number is the argument position to be filtered
* The comparison operator may be:
* - "=" for equality comparison
* - "&" for substring comparison
* The argument is compared to the specified string accordingly
*
* @return 1 on successfully registering event, 0 on failure
* @error Invalid callback function
*/
native register_logevent(const function[], argsnum, ...);
/**
* Sets display parameters for hudmessages.
*
* @note As of AMXX 1.61, setting the channel to -1 will automatically choose
* the next available HUD channel for the client.
* @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 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
* them. Multiple calls to show_hudmessage will therefore re-use the same
* parameters. The parameters are not stored per-plugin, so other plugins
* can overwrite them.
*
* @param red Red component of hudmessage color
* @param green Green component of hudmessage color
* @param blue Blue component of hudmessage color
* @param x Location of the message on the x axis in percent
* @param y Location of the message on the y axis in percent
* @param effects Display effect
* @param fxtime Duration of the effect
* @param holdtime Time the message stays on screen
* @param fadeintime Time it takes the message to fully appear (fade-in)
* @param fadeouttime Time it takes the message to fully disappear (fade-out)
* @param channel Channel to use on the client
*
* @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);
/**
* Displays a message on the client HUD.
*
* @note Use set_hudmessage to define how the message should look on screen.
*
* @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
*/
native show_hudmessage(index, const message[], any:...);
/**
* Sets display parameters for director hudmessages.
*
* @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_dhudmessage overwrites
* them. Multiple calls to show_dhudmessage will therefore re-use the same
* parameters. The parameters are not stored per-plugin, so other plugins
* can overwrite them.
*
* @param red Red component of hudmessage color
* @param green Green component of hudmessage color
* @param blue Blue component of hudmessage color
* @param x Location of the message on the x axis in percent
* @param y Location of the message on the y axis in percent
* @param effects Display effect
* @param fxtime Duration of the effect
* @param holdtime Time the message stays on screen
* @param fadeintime Time it takes the message to fully appear (fade-in)
* @param fadeouttime Time it takes the message to fully disappear (fade-out)
*
* @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);
/**
* 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
* messages are stack-based. You can have up to 8 messages displaying at
* once, if you add more they will be overwtitten 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.
*
* @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
*/
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.
* 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().
*
* @param index Client to display menu to, use 0 to display to all clients
* @param keys Enabled keys
* @param menu Menu body
* @param time Menu timeout in seconds, -1 to disable
* @param title Name of the menu for internal tracking purposes
*/
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 Usage examples:
* value = read_data(1);
* 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.
*
* @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.
*/
native read_data(value, any:... );
/**
* Returns the number of values in the client message.
*
* @note For use within callbacks registered with register_event().
*
* @return Number of values in client message
*/
native read_datanum();
/**
* Returns the message id of the client message.
*
* @note For use within callbacks registered with register_event().
*
* @return Message id of the client message
*/
native read_datatype();
/**
* Retrieves current log message.
*
* @note Can 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.
*
* @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.
*
* @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);
/**
* Parse log data about client.
*
* @note When client actions are logged they appear in the the format
* "Name<#userid><SteamID><teamname>", this native extracts the individual
* pieces of information.
*
* @param text String to process
* @param name Buffer to copy client name to
* @param nlen Maximum name buffer size
* @param userid Variable to store userid in
* @param authid Buffer to copy client authid to
* @param alen Maximum auth buffer size
* @param team Buffer to copy client team to
* @param tlen Maximum team buffer size
*
* @noreturn
* @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);
/**
* Sends a message to the console of the server.
*
* @param message Formatting rules
* @param ... Variable number of formatting parameters
*
* @return Number of printed characters
*/
native server_print(const message[], any:...);
/**
* Returns if the given mapname is deemed valid by the engine.
*
* @param mapname Name of the map
*
* @return 1 if the map name is valid, 0 otherwise
*/
native is_map_valid(const mapname[]);
/**
* Returns if the client is a bot.
*
* @param index Client index
*
* @return 1 if client is a bot, 0 otherwise
*/
native is_user_bot(index);
/**
* Returns if the client is a HLTV proxy.
*
* @param index Client index
*
* @return 1 if client is a HLTV proxy, 0 otherwise
*/
native is_user_hltv(index);
/**
* Returns if the client is connected.
*
* @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.
*
* @param index Client index
*
* @return 1 if client is connected, 0 otherwise
*/
native is_user_connected(index);
/**
* Returns if the client is connecting.
*
* @param index Client index
*
* @return 1 if client is connecting, 0 otherwise
*/
native is_user_connecting(index);
/**
* Returns if the client is alive.
*
* @note This will never return true if a client is not connected. If you need
* to know whether a client is alive, an additional call to
* is_user_connected() is unnecessary.
*
* @param index Client index
*
* @return 1 if client is alive, 0 otherwise
*/
native is_user_alive(index);
/**
* Returns if the server is a dedicated server.
*
* @param index Client index
*
* @return 1 if server is a dedicated server, 0 otherwise
*/
native is_dedicated_server();
/**
* Returns if the server is running on Linux.
*
* @param index Client index
*
* @return 1 if server is running on Linux, 0 otherwise
*/
native is_linux_server();
/**
* Returns if the AMXX installation has the JIT enabled.
*
* @param index Client index
*
* @return 1 if JIT is enabled, 0 otherwise
*/
native is_jit_enabled();
/**
* Retrieves the version string of the AMXX installation.
*
* @param buffer Buffer to copy version to
* @param length Maximum buffer size
*
* @return Number of cells written to the buffer
*/
native get_amxx_verstring(buffer[], length);
/**
* Returns the last known attacker of a client.
*
* @note As of AMXX 1.75 this can return a non-client entity index if the client
* 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.
*
* @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.
*/
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
*
* @param index Client index to trace aim from
* @param id Variable to store hit client index (if applicable)
* @param body Variable to store hit client body part (if applicable)
* @param dist Maximum distance of the trace
*
* @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.
*/
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
* 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.
*
* @param index Client index
*
* @return Frags/Score of the client. Also returns 0 if the client is
* not connected or the index is not within the range of
* 1 to MaxClients
*/
native get_user_frags(index);
/**
* Returns the client's armor value.
*
* @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
*
* @return Amount of armor the client has. Also returns 0 if the client
* is not connected or the index is not within the range of
* 1 to MaxClients
*/
native get_user_armor(index);
/**
* Returns the client's death count.
*
* @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
*
* @return Amount of deaths the client has. Also returns 0 if the
* client is not connected or the index is not within the range
* of 1 to MaxClients
*/
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
* methods.
*
* @param index Client index
*
* @return Amount of health points the client has. Also returns 0 if
* the client is not connected or the index is not within the
* range of 1 to MaxClients
*/
native get_user_health(index);
/**
* Retrieve a client's index by name.
*
* @param name Name to search for
*
* @return Client index on success, 0 otherwise
*/
native get_user_index(const name[]);
/**
* Retrieves the IP of a client or the server.
*
* @param index Client index, use 0 to retrieve the server IP
* @param ip Buffer to copy IP to
* @param len Maximum buffer size
* @param without_port Remove the port from the IP if nonzero
*
* @return Number of cells written to the buffer
*/
native get_user_ip(index, ip[], len, without_port = 0);
/**
* Returns if the client has the specified weapon in their inventory.
*
* @param index Client index
* @param weapon Weapon index
* @param setweapon If zero the weapon bit will be removed from the client's
* inventory, if 1 it will be set
*
* @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.
*/
native user_has_weapon(index, weapon, setweapon=-1);
/**
* Returns weapon index of the currently carried weapon. Also allows retrieval
* of ammo in the clip and backpack.
*
* @param index Client index
* @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
* @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);
/**
* Retrieves ammo in the clip and backpack of the specified weapon.
*
* @param index Client index
* @param weapon Weapon index
* @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
* @error If the client index is not within the range of 1 to
* MaxClients, or the weapon index is invalid, an error will
* be thrown.
*/
native get_user_ammo(index, weapon, &clip, &ammo);
/**
* Converts an integer to a text string.
*
* @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.
* @note The conversion is to english text, there is no way to change this.
*
* @param num Integer to convert
* @param output Buffer to copy string to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native num_to_word(num, output[], len);
/**
* Returns the team id of the client, and optionally retrieves the name of
* the team.
*
* @param index Client index
* @param team Buffer to copy team name to
* @param len Maximum size of buffer
*
* @return Team index on success, -1 if client index is invalid or
* the client is not connected.
*/
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
* the client to connect.
*
* @return Connection time in seconds, 0 if client index is invalid or
* client is not connected
*/
native get_user_time(index, flag = 0);
/**
* Retrieves the ping and loss of a client.
*
* @param index Client index
* @param ping Variable to store ping in
* @param loss Variable to sote loss in
*
* @return 1 on success, 0 if client index is invalid or the client
* is not connected.
*/
native get_user_ping(index, &ping, &loss);
/**
* Retrieves an origin related to the client.
*
* @param index Client index
* @param origin Array to store origin in
* @param mode What type of origin to retrieve:
* 0 - current position
* 1 - position of eyes (and weapon)
* 2 - aim end position from client position
* 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
* @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);
/**
* 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
* work correctly.
*
* @param index Client index
* @param weapons Array to store weapon indexes in
* @param num Variable to store number of weapons in the inventory to
*
* @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.
*/
native get_user_weapons(index, weapons[32], &num);
/**
* Retrieves the full name of a weapon.
*
* @param id Weapon index
* @param weapon Buffer to copy name to
* @param len Maximum buffer size
*/
native get_weaponname(id, weapon[], len);
/**
* Retrieves the name of a client or the server.
*
* @param index Client index, or 0 to retrieve the server hostname
* @param name Buffer to copy name to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native get_user_name(index, name[], len);
/**
* Retrieves the SteamID of a client.
*
* @note The SteamID is only available once the client_authorized() forward has
* been called for the client.
*
* @param index Client index
* @param authid Buffer to copy auth to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native get_user_authid(index, authid[] ,len);
/**
* Returns the userid of a client.
*
* @param index Client index
*
* @return Client userid, 0 if the userid is not available or the
* client index is invalid.
*/
native get_user_userid(index);
/**
* Slaps the client with specified power. Killing the client if applicable.
*
* @note This removes "power" amount of health from the client, performing
* a kill if they have no health left after the slap.
* @note The function will apply a velocity to the client that is independent
* of the slap power. The slap direction can be influenced by the third
* parameter.
*
* @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.
*/
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
*
* @return 1 on success, 0 if client index is invalid or the client
* is not connected.
*/
native user_kill(index, flag=0);
/**
* Logs a message to the current AMXX log file.
*
* @note The message will automatically be tagged with the plugin's name and the
* log will include a timestamp with the message.
*
* @param string Formatting rules
* @param ... Variable number of formatting parameters
*
* @noreturn
*/
native log_amx(const string[], any:...);
/**
* Logs a message to the current server log file.
*
* @note The log will include a timestamp with the message.
*
* @param string Formatting rules
* @param ... Variable number of formatting parameters
*
* @return Number of printed characters
*/
native log_message(const message[], any:...);
/**
* Logs a message to the specified file
*
* @note The log will include a timestamp with the message.
*
* @param string Formatting rules
* @param ... Variable number of formatting parameters
*
* @noreturn
*/
native log_to_file(const file[], const message[], any:...);
/**
* Returns the number of clients on the server.
*
* @param flag Count clients still in the connecting process if nonzero
*
* @return Number of clients on the server
*/
native get_playersnum(flag=0);
/**
* Stores a filtered list of client indexes to an array.
*
* @note Example retrieving all alive CTs: get_players(players, num "ae", "CT")
*
* @param players Array to store indexes to
* @param num Variable to store number of indexes to
* @param flags Optional list of filtering flags:
* "a" - do not include dead clients
* "b" - do not include alive clients
* "c" - do not include bots
* "d" - do not include human clients
* "e" - match with team
* "f" - match with part of name
* "g" - match case insensitive
* "h" - do not include HLTV proxies
* @param team String to match against if the "e" or "f" flag is specified
*
* @noreturn
*/
native get_players(players[32], &num, const flags[]="", const team[]="");
/**
* Retrieves argument of client command.
*
* @note Should only be used inside of the client_command() forward.
*
* @param id Argument index starting from 1, 0 returns the command itself
* @param output Buffer to copy command argument to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native read_argv(id, output[], len);
/**
* Retrieves full client command string.
*
* @note Should only be used inside of the client_command() forward.
*
* @param output Buffer to copy command line to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native read_args(output[], len);
/**
* Returns number of client command arguments.
*
* @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.
*
* @return Number of arguments in the command
*/
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
* (1<<0)|(1<<1)|(1<<2)|(1<<3). The function will return 15.
*
* @param flags Flag string to convert
*
* @return Bitflag value
*/
native read_flags(const flags[]);
/**
* Converts a bitflag value to a flag string.
*
* @note Example: The value 3 will yield the string "ab"
*
* @param flags Bitflag value to convert
* @param output Buffer to copy flag string to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native get_flags(flags, output[], len);
/**
* Find a player given a filter.
*
* @note If matching by userid, do not also specify the "a", "b" or "c" flags,
* or the function may not return a correct result.
*
* @param flags List of filtering flags:
* "a" - match with name
* "b" - match with name substring
* "c" - match with authid
* "d" - match with ip
* "e" - match with team name
* "f" - do not include dead clients
* "g" - do not include alive clients
* "h" - do not include bots
* "i" - do not include human clients
* "j" - return last matched client instead of the first
* "k" - match with userid
* "l" - match case insensitively
* @param ... String to match against (integer if "k" flag is specified)
*
*/
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 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,
* even if no matching double-quote is found. This is for convenience.
*
* @param text String to remove double-quotes from
*
* @return 1 if matching double-quotes have been removed, 0 otherwise
*/
native remove_quotes(text[]);
/**
* Executes a command on the client.
*
* @note Executing malicious commands on the client ("slowhacking") is frowned
* upon.
* @note Valve has introduced a command filter to Counter-Strike 1.6. It is not
* possible to execute many commands if the client has opted in to this.
*
* @param index Client index, use 0 to execute on all clients
* @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
*/
native client_cmd(index, const command[], any:...);
/**
* Execute a command from the client without actually sending it to the client's
* DLL.
*
* @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.
* @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 command The 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
*/
native engclient_cmd(index, const command[], const arg1[]="", const arg2[]="");
/**
* Execute a command from the client without actually sending it to the client's
* DLL. This triggers plugin command hooks.
*
* @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.
* @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 command The 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
*/
native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = "");
/**
* Queues a command to be executed from the server console.
*
* @note Warning: This is a potential source of command injection. Do not feed
* 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().
*
* @param command Formatting rules
* @param ... Variable number of formatting parameters
*
* @noreturn
*/
native server_cmd(const command[],any:...);
/**
* 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.
*
* @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 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[]);
/**
* 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 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.
*
*
* @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);
/**
* 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 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.
*
* @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);
/**
* 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 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.
*
* @param cvar Cvar name to retrieve flags from
*
* @return 1 on success, 0 if cvar does not exist or is not permitted
*/
native get_cvar_flags(const cvar[]);
/**
* 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.
*
* @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 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.
*
* @param cvarname Cvar name to retrieve value from
*
* @return Cvar value, converted to float
*/
native Float:get_cvar_float(const cvarname[]);
/**
* 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.
*
* @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 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.
*
* @param cvar Cvar name to set value of
* @param value Value to set cvar to
*
* @noreturn
*/
native set_cvar_num(const cvarname[], value);
/**
* 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.
*
* @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);
/**
* Retrieves the name of the currently played map.
*
* @param name Buffer to copy map name to
* @param len Maximum buffer size
*
* @return Number of cells written to buffer
*/
native get_mapname(name[], len);
/**
* Returns time remaining on map.
*
* @return Time left on map, in seconds
*/
native get_timeleft();
/**
* Returns the game time based on the game tick.
*
* @note This time is counted up from map start. If the engine is not processing
* this function will return the same value between calls, which makes it
* unusable for profiling purposes.
*
* @return Game time, in seconds
*/
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
* via the MaxClients variable, declared in amxconst.inc
*
* @return Maxplayers setting
*/
native get_maxplayers();
/**
* Retrieves the name of the currently played mod.
*
* @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
* @param len Maximum size of the buffer
*
* @return Number of cells written to buffer
*/
native get_modname(name[], len);
/**
* Retrieves the current 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
* A common example for a format string would be: "%m/%d/%Y - %H:%M:%S"
*
* @param format Format string
* @param output Buffer to copy formatted time string to
* @param len Maximum size of buffer
*
* @return Number of cells written to buffer
*/
native get_time(const format[], output[], len);
/**
* Retrieves the provided time using 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
* A common example for a format string would be: "%m/%d/%Y - %H:%M:%S"
*
* @param output Buffer to copy formatted time string to
* @param len Maximum size of buffer
* @param format Format string
* @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
*/
native format_time(output[], len, const format[], time = -1);
/**
* Returns the system time as a unix timestamp (number of seconds since unix
* epoch)
*
* @param offset Optional offset value in seconds
*
* @return Unix time stamp
* @error
*/
native get_systime(offset = 0);
/**
* Converts time string 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/
* An example for a input/format combination would be:
* Input: "10:32:54 04/02/2013" Format: "%H:%M:%S %m:%d:%Y"
* @note Information missing from the input will be filled with the current
* time and date.
*
* @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.
*
* @return Unix time stamp
* @error If the conversion process fails, an error will be thrown
*/
native parse_time(const input[], const format[], time = -1);
/**
* Calls a function after a specified time has elapsed.
*
* @param time Time interval to assign
* @param function Function to execute
* @param id Task id to assign
* @param parameter Data to pass through to callback
* @param len Size of data
* @param flags Optional set of flags:
* "a" - repeat timer a set amount of times
* "b" - loop indefinitely until timer is stopped
* "c" - time interval is treated as absolute time after
* 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
* many times
*/
native set_task(Float:time, const function[], id = 0, const parameter[]="", len = 0, const flags[]="", repeat = 0);
/**
* Removes all tasks with the specified id.
*
* @param id Task id to search for
* @param outside Will remove tasks set by other plugins if nonzero
*
* @return Number of removed tasks
*/
native remove_task(id = 0, outside = 0);
/**
* Modifies the time interval of all tasks with the specified id.
*
* @param id Task id to search for
* @param newTime New time interval to set
* @param outside Will affect tasks set by other plugins if nonzero
*
* @return Number of affected tasks
*/
native change_task(id = 0, Float:newTime=1.0, outside = 0);
/**
* Returns if a task with the specified id exists.
*
* @param id Task id to search for
* @param outside Search for tasks set by other plugins if nonzero
*
* @return 1 if a task was found, 0 otherwise
*/
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 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 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.
*
* @param index Client index, 0 to set flags of server
* @param flags Admin flags
* @param id Flag set id, ranging from 0 to 31
*
* @noreturn
* @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);
/**
* 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 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.
*
* @param index Client index, 0 to set flags of server
* @param id Flag set id, ranging from 0 to 31
*
* @noreturn
* @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);
/**
* Removes the specified admin flags from a client.
*
* @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
* parameter from the default.
*
* @param index Client index, 0 to set flags of server
* @param flags Admin flags
* @param id Flag set id, ranging from 0 to 31
*
* @noreturn
* @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);
/* Registers function which will be called from client console.
* Set FlagManager to 1 to make FlagManager always include this command
* Set FlagManager to 0 to make FlagManager never include this command
* Returns the command ID.
*/
native register_clcmd(const client_cmd[], const function[], flags=-1, const info[]="", FlagManager=-1);
/* Registers function which will be called from any console.
* Set FlagManager to 1 to make FlagManager always include this command
* Set FlagManager to 0 to make FlagManager never include this command
* Returns the command ID.
*/
native register_concmd(const cmd[], const function[], flags=-1, const info[]="", FlagManager=-1);
/* Registers function which will be called from server console.
* Returns the command ID.
*/
native register_srvcmd(const server_cmd[], const function[], flags=-1, const info[]="");
/* Gets info about client command. */
native get_clcmd(index, command[], len1, &flags, info[], len2, flag);
/* Returns number of registered client commands. */
native get_clcmdsnum(flag);
/* Gets info about server command. */
native get_srvcmd(index,server_cmd[],len1,&flags, info[],len2, flag);
/* Returns number of registered server commands. */
native get_srvcmdsnum(flag);
/* Gets info about console command. If id is set to 0,
then function returns only server cmds, if positive then
returns only client cmds. in other case returns all console commands. */
native get_concmd(index,cmd[],len1,&flags, info[],len2, flag, id = -1);
/* Gets the parent plugin id of a console command. */
native get_concmd_plid(cid, flag_mask, id_type);
/* Returns number of registered console commands. */
native get_concmdsnum(flag,id = -1);
/* Returns the number of plugin-registered cvars. */
native get_plugins_cvarsnum();
/* Returns information about a plugin-registered cvar. */
native get_plugins_cvar(num, name[], namelen, &flags=0, &plugin_id=0, &pcvar_handle=0);
/* Gets unique id of menu. Outside set to 1 allows
* to catch menus outside a plugin where register_menuid is called. */
native register_menuid(const menu[], outside=0 );
/* Calls function when player uses specified menu and proper keys. */
native register_menucmd(menuid,keys, const function[] );
/* Gets what menu the player is watching and what keys for menu he have.
* When there is no menu the index is 0. If the id is negative then the menu
* is VGUI in other case the id is from register_menuid() function. */
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().
*
* @noreturn
*/
native server_exec();
/**
* 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);
/**
* Registers a new cvar 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 Unused
*
* @return Unique cvar pointer
*/
native register_cvar(const name[], const string[], flags = 0, Float:fvalue = 0.0);
/**
* Returns a random floating point value generated by the engine.
*
* @param a Minimum value (inclusive)
* @param b Maximum value (inclusive)
*
* @return Generated random value
*/
native Float:random_float(Float:a, Float:b);
/**
* Returns a random integer value generated by the engine.
*
* @param a Minimum value (inclusive)
* @param b Maximum value (inclusive)
*
* @return Generated random value
*/
native random_num(a, b);
/**
* 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[]);
/**
* 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);
/**
* 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 if a public variable exists in any loaded plugin.
*
* @param name Variable name
*
* @return 1 if public cvar exists, 0 otherwise
*/
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
* 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 the float value of a public variable.
*
* @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 the integer value of a public variable.
*
* @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 the float value of a public variable.
*
* @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);
/**
* 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[]);
/**
* 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);
/**
* Returns the number of currently registered modules.
*
* @return Number of modules
*/
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
* registered names, not the filename.
* @note The plugin name matching is case insensitive while the filename
* matching is case sensitive.
*
* @param name Plugin name or filename
* @param usefilename If true searches for plugin filename, false searches for
* plugin name
*
* @return Plugin id of the matching plugin, -1 otherwise
*/
native is_plugin_loaded(const name[], bool:usefilename=false);
/**
* Retrieves info about a plugin by plugin index.
*
* @param index Plugin index, -1 to target calling plugin
* @param filename Buffer to copy plugin filename to
* @param len1 Maximum filename buffer size
* @param name Buffer to copy plugin name to
* @param len2 Maximum name buffer size
* @param version Buffer to copy plugin version to
* @param len3 Maximum version buffer size
* @param author Buffer to copy plugin author to
* @param len4 Maximum author buffer size
* @param status Buffer to copy plugin status flags to
* @param len5 Maximum status buffer size
* @param ... Unused and ignored
*
* @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,...);
/**
* Returns the number of loaded AMXX plugins.
*
* @return The number of loaded plugins
*/
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
* (along with the flags "b" and "e") has been deprecated.
* @note If used without flag "c" this will pause the calling plugin.
*
* @param flag Pause flags
* "a" - pause plugin
* "c" - search for other plugins using param1
* "d" - stop plugin, making it unavailable to unpause
* @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[]="");
/**
* 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
* 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[]="");
/**
* 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()
*
* @param func Function name
* @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
* 0 on runtime error
* -1 if plugin was not found
* -2 if function was not found
* @error If called while another callfunc has not yet been finished,
* an error is thrown.
*/
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()
*
* @param func Function id
* @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
* -1 if plugin was not found
* -2 if function is not executable
* @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);
/**
* Retrieve 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()
*
* @return >0 Function id on success
* -1 if plugin or function was not found
*/
native get_func_id(const funcName[], pluginId = -1);
/**
* Pushes an int value onto the current call.
*
* @param value Int value to push
*
* @noreturn
* @error If called without initiating a callfunc, or the maximum
* amount of parameters is reached, an error is thrown.
*/
native callfunc_push_int(value);
/**
* Pushes a float value onto the current call.
*
* @param value Float value to push
*
* @noreturn
* @error If called without initiating a callfunc, or the maximum
* amount of parameters is reached, an error is thrown.
*/
native callfunc_push_float(Float: value);
/**
* Pushes an int value reference onto the current call.
*
* @note Changes made to this value by the called function will be reflected
* in the calling plugin.
*
* @param value Int value to push
*
* @noreturn
* @error If called without initiating a callfunc, or the maximum
* amount of parameters is reached, an error is thrown.
*/
native callfunc_push_intrf(&value);
/**
* Pushes a float value reference onto the current call.
*
* @note Changes made to this value by the called function will be reflected
* in the calling plugin.
*
* @param value Float value to push
*
* @noreturn
* @error If called without initiating a callfunc, or the maximum
* amount of parameters is reached, an error is thrown.
*/
native callfunc_push_floatrf(&Float:value);
/**
* Pushes a string onto the current call.
*
* @note This will defy the "const" specifier if copyback is true, which is
* only kept for special backwards compatibility.
*
* @param VALUE String to push
* @param copyback If true any changes made in the called function will be
* 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);
/**
* Pushes an array onto the current call.
*
* @note This will defy the "const" specifier if copyback is true, which is
* only kept for special backwards compatibility.
*
* @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.
*
* @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);
/**
* Completes the call to a function.
*
* @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.
*/
native callfunc_end();
/**
* 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] );
/**
* 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[]);
/**
* Calculates the MD5 keysum of a string.
*
* @param szString String to calculate keysum of
* @param md5buffer Buffer to copy the MD5 hash to
*
* @return Number of cells written to the buffer (always 32)
*/
native md5(const szString[], md5buffer[34]);
/**
* Calculates the MD5 keysum of a file.
*
* @param file Path to file to calculate keysum of
* @param md5buffer Buffer to copy the MD5 hash to
*
* @return Number of cells written to the buffer (always 32)
* @error If the file can not be opened, and error is thrown.
*/
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
* state flags
* @param plid Plugin id, -1 to target calling plugin
*/
native plugin_flags(hdr=0, plid=-1);
/**
* 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
* called.
*
* @noreturn
*/
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[]);
/**
* 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();
/**
* 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);
/**
* Called before plugin_init(), allowing the plugin to register natives.
*
* @noreturn
*/
forward plugin_natives();
/* Registers a NATIVE. When a plugin uses your native (you should distribute a .inc),
* the handler will be called with two parameters: the calling plugin id, and the
* number of parameters.
* If you set style=1, the method of parameter passing is a tad more efficient.
* Instead of "id, numParams", you label the native exactly as how the parameters
* should, in theory, be sent. Then for each byreference parameter, you call
* param_convert(num). This is theoretically more efficient but quite hacky.
* The method was discovered by dJeyL, props to him!
*/
native register_native(const name[], const handler[], style=0);
/* Registers a library. To mark a library as required, place the following
* in your include file:
* #pragma reqlib <name>
* #if !defined AMXMODX_NOAUTOLOAD
* #pragma loadlib <name>
* #endif
*/
native register_library(const library[]);
/* Logs an error in your native, and breaks into the debugger.
* Acts as if the calling plugin had the error.
*/
native log_error(error, const fmt[], any:...);
// More Dynamic Native System Stuff
// Each of these natives affects one of the parameters sent to your native.
// Parameters go from 1 to n, just like in modules, and it is important to
// remember two things: The parameters are actually coming from another plugin
// (and just like modules, you must use these special natives).
// two: you CANNOT call your native from inside your native. This is very bad.
//This function should only be called if you registered with style=1
//You only need to use it on by-reference parameters.
native param_convert(num);
// Gets a string from the calling plugin
native get_string(param, dest[], maxlen);
// Sets a string in the calling plugin
native set_string(param, dest[], maxlen);
// Gets a normal int or float parameter
native get_param(param);
native Float:get_param_f(param);
// Gets/Sets a float or int parameter by reference
native get_param_byref(param);
native Float:get_float_byref(param);
native set_param_byref(param, value);
native set_float_byref(param, Float:value);
// Copies an array either from the calling plugin to you
// Or copies an array from you to the calling plugin
native get_array(param, dest[], size);
native get_array_f(param, Float:dest[], size);
native set_array(param, const source[], size);
native set_array_f(param, const Float:source[], size);
// Dispatches a client cvar query
// id: Player id
// cvar: cvar name
// resultFunc: public handler function
// paramLen + params: optional array parameter
// resultFunc looks like:
// public callbackCvarValue(id, const cvar[], const value[])
// or if you use the optional parameter:
// public callbackCvarValue(id, const cvar[], const value[], const param[])
native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[] = "");
/**
* Allows you to trap error messages that occur in your plugin.
* You can use this to override the debug messages that occur when your plugin
* causes some sort of runtime error. Your handler will be called in this style:
*
* public error_filter(error_code, bool:debugging, message[])
* error_code is the AMX_ERR code. debugging is whether or not the plugin is in debug mode.
* message[] is any message that was sent along with the error.
* Return PLUGIN_CONTINUE to let the error pass through the filter.
* Return PLUGIN_HANDLED to block the error from displaying.
*/
native set_error_filter(const handler[]);
/**
* Gets a trace handle for the item at the top of the traced call stack.
* Returns 0 if no debugging information is available.
*/
native dbg_trace_begin();
/**
* Gets the next item in a traced call stack. Returns 0 if no more traces exist.
*/
native dbg_trace_next(trace);
/**
* Gets the call stack info for a trace.
*/
native dbg_trace_info(trace, &line, function[], maxLength1, file[], maxLength2);
/**
* Gets the formatted error string, which looks like "Run time error X: (description)"
*/
native dbg_fmt_error(buffer[], maxLength);
/**
* The following two natives are useful for creating cross-mod plugins
* where instead of #define flags to compile separate versions, you can
* filter out the natives and modules depending on the current mod.
* Examples of this usage are in plmenu.sma, which filters out the cstrike module.
*
*
*
*
*
* Sets a native filter. This must be first set in plugin_natives(), but future calls will
* simply set a new filter.
* This filter will allow your plugin to load even if its modules aren't loaded. For example,
* if Fun isn't loaded and you use set_user_frags, your plugin will still load. However, if you
* attempt to call this native, your filter will intercept it with these parameters:
*
* public function native_filter(const native[], index, trap)
* native - name of native
* index - index of native
* trap - 0 if native couldn't be found, 1 if native use was attempted
*
* If you return PLUGIN_HANDLED, no error is thrown. If you return PLUGIN_CONTINUE,
* your plugin will have a run-time-error. To print your own error, or change the default,
* you can return PLUGIN_HANDLED or return PLUGIN_CONTINUE and use set_error_filter.
* If you return PLUGIN_CONTINUE when trap is 0, the plugin will ABORT AND FAIL TO LOAD!
* When trap is 0, it is unsafe to use natives that modify the server or use other plugins.
*/
native set_native_filter(const handler[]);
/**
* This function sets a module/library filter. It will let you intercept the automatic requirement
* of a module and return PLUGIN_CONTINUE to fail load or PLUGIN_HANDLED to imply that load
* can continue even without the module.
*
* This is the most unforgiving of the filter functions. You can ONLY call it during plugin_natives,
* and any error that occurs is not filtered -- instead your plugin will fail to load as if you
* returned PLUGIN_CONTINUE.
*
* Your handler will be called with this prototype:
*
* public module_filter(const library[], LibType:type);
* library - library or class name of the module that is required
* libtype - The type of requirement being checked (library/module or class).
*
*
* set_module_filter() returns 0 on success (unlike most natives).
*/
native set_module_filter(const handler[]);
/**
* Aborts execution of the current callback by throwing an error.
*
* @note Warning: This function should not be used inside error filters, module
* filters (native filters are safe if trap equals 1) or the
* 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
*
* @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:...);
/**
* Returns if a specific module is loaded.
*
* @note This uses the same method AMXX uses internally to see if a module is
* 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[]);
/**
* 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);
/**
* 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);
/**
* 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, ...);
/**
* Displays a synchronized HUD message.
*
* @note This will check that your HUD object has its previous display on the
* screen cleared before it proceeds to write another message. It will
* only do this in the case of that channel not having been cleared
* already.
* @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:...);
/**
* Clears the display on a HUD sync object.
*
* @note This sends an empty message to the previously occupied HUD channel.
* It is not quite the same as manually sending an empty message to the
* sync object as that would send out two separate messages, one for
* 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);
/**
* 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();
/**
* Sets the calling plugin to a failed state.
*
* @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:...);
/**
* Returns the reference address of the variable passed in.
*
* @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:...);
/**
* Returns the value of an address.
*
* @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);
/**
* 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);
/**
* 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
* 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, ...);
/**
* 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.
*
* @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[], ...);
/**
* Prepares an array for use in a forward. Pass the result ExecuteForward()
* 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);
/**
* Executes a forward.
*
* @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:...);
/**
* Destroys and deallocates a forward.
*
* @note Does not distinguish between private and global forwards.
*
* @param forward_handle Forward handle
*
* @noreturn
*/
native DestroyForward(forward_handle);
/**
* Returns the cvar pointer of the specified cvar.
*
* @note A pointer is also returned by register_cvar(). You 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[]);
/**
* 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 specified, an error is 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 specified, an error is 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 specified, an error is thrown.
*/
native get_pcvar_num(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 specified, an error is thrown.
*/
native set_pcvar_num(pcvar, 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 specified, an error is 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 specified, an error is 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 specified, an error is 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 specified, an error is thrown.
*/
native set_pcvar_string(pcvar, const string[]);
/**
* Sets all elements of array to a specified value.
*
* @param array Array to modify
* @param value Value to set each element to
* @param size Size of array
*
* @noreturn
*/
native arrayset(array[], value, size);
/**
* Returns the weapon id associated with a weapon name.
*
* @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[]);
/**
* 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
* amxconst.inc
* @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)
* @param Password Password to set
* @param Access Admin access flags
* @param Flags Auth behavior flags
*
* @noreturn
*/
native admins_push(const AuthData[], const Password[], Access, Flags);
/**
* Returns the number of admins in the dynamic admin storage
*
* @return Number of admins
*/
native admins_num();
/**
* Retrieves information about a dynamically stored admin.
*
* @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
* or AdminProp_Password is specified
* @param BufferSize Maximum buffer size
*
* @return Property value if AdminProp_Access or AdminProp_Flags
* 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);
/**
* Clears the list of dynamically stored admins
*
* @noreturn
*/
native admins_flush();
/**
* Returns if a map contains at least one entity with the provided class name.
*
* @param classname Entity classname to match
*
* @return True if an entity is found, false otherwise
*/
native bool:has_map_ent_class(const classname[]);
// Always keep this at the bottom of this file
#include <message_stocks>