GitHub/amxmodx
2
0
Fork 0
mirror of https://github.com/alliedmodders/amxmodx.git synced 2025-01-23 20:28:03 +03:00
Code Issues Projects Releases Wiki Activity

amxmodx: First batch of documentation updates

Browse Source
This commit is contained in:
Valentin Grünbacher 2014-08-04 00:48:37 +02:00
parent 9544364116
commit 8ba288cfb1
1 changed files with 512 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

599
plugins/include/amxmodx.inc
View File

@ -27,158 +27,493 @@
#include <datapack>
#include <newmenus>
/* Function is called just after server activation.
* Good place for configuration loading, commands and cvars registration. */
/**
* 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 when the plugin is paused. */
/**
* Called just before the plugin is paused from execution.
*
* @noreturn
*/
forward plugin_pause();
/* Called when the plugin is unpaused. */
forward plugin_unpause();
/* Called when the mod tries to change the map. */
forward server_changelevel(map[]);
/* Function is called when all plugin_init from plugins
* were called, so all commmands and cvars should be already registered. */
forward plugin_cfg();
/* Function called before plugin unloading (server deactivation) */
forward plugin_end();
/* Called on log message. */
forward plugin_log();
/* Use here model_precache() and sound_precache() functions. */
forward plugin_precache();
/* Whenever player info is changed, this function is called. */
forward client_infochanged(id);
/* Called on client connection. */
forward client_connect(id);
/* Called when client gets valid STEAM id (usually
* between client_connect() and client_putinserver()). */
forward client_authorized(id);
/* Called when client is disconnecting from server. */
forward client_disconnect(id);
/* Called when client is sending command. */
forward client_command(id);
/* Called when client is entering to a game. */
forward client_putinserver(id);
/* Sets informations about plugin. Returns the plugin id of the calling plugin. */
native register_plugin(const plugin_name[],const version[],const author[]);
/* Precache model. Can be used only in plugin_precache() function.*/
native precache_model(const name[]);
/* Precache sound. Can be used only in plugin_precache() function.*/
native precache_sound(const name[]);
/* Precaches any file. */
native precache_generic(const szFile[]);
/* Sets info for player. */
native set_user_info(index,const info[],const value[]);
/* Gets info from player. */
native get_user_info(index,const info[],output[],len);
/* Sets info for server. */
native set_localinfo(const info[],const value[]);
/* Gets info from server. */
native get_localinfo(const info[],output[],len);
/* Shows text in MOTD window. When there is no header, the MOTD title
* will be the name of server. If message is filename, then a contents
* of this file will be displayed as MOTD. */
native show_motd(player,const message[],const header[]="");
/* Sends message to player. Set index to 0 to send text globaly. */
native client_print(index,type,const message[],any:...);
/**
* Sends colored message to player. Set index to 0 to send text globally.
* This works only under Counter-Strike 1.6 and Counter-Strike: Condition Zero.
* Called just after the plugin is unpaused.
*
* The available colors identifiers are :
* green ^4 ; use location color from this point forward
* red/blue/grey ^3 ; use team color from this point forward
* red/blue/grey ^2 ; use team color up to the end of the player name. This only works at the start of the string, and precludes using the other control characters.
* normal ^1 ; use normal color from this point forward
* @noreturn
*/
forward plugin_unpause();
/**
* Called when the mod tries to change the map.
*
* The team color is defined either with a sender's index, or a specific team color using print_team_* constants (print_team_blue, print_team_red, print_team_grey).
* A message must start with a default color.
* @note This is *only* called if the mod itself handles the map change. The
* server command "changelevel" which is also used by plugins will not
* trigger this forward. Unfortunately this means that in practice this
* forward is very unreliable, and will not be called in many situations.
*
* An example would be: client_print_color(id, print_team_red, "^4This is green ^3this is red, ^1this is your default chat text color");
* Another with index : client_print_color(id, idOther, "^4This is green ^3this idOther's team color, ^1this is your default chat text color");
* In multilingual file : KEY = ^1This is normal color, ^4this is green, ^1normal again ^3and now team color.
* @param map Map that the mod tries to change to
*
* @param index This is the player index (1 to maxplayer) you want to send the message, use 0 to send to all players.
* @param sender This is the player index you want to use the team color, see print_team_* constants if you want to force a color.
* @param fmt Format string in which patterns gonna be replaced with argument list.
* @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
*
* @return 1 if the message has been sent,
* 0 if the index specified is a not connected player,
* or if a global message has not been sent because there are no humans players.
* @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
*/
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
*/
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 tables.
*
* @param szFile Path to the file
*
* @return Cache id of the file, even if the file was already precached
*/
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.
*/
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 players
* @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 players
* @param type Message type, see print_* destination constants in amxconst
* @param message Formatting rules
* @param ... Variable number of formatting parameters
*
* @return The 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 player 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 players
* @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 The 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 message to player by engine. Set index to 0 to send text globaly. */
native engclient_print(player,type,const message[],any:...);
/* Sends message to console. */
native console_print(id,const message[],any:...);
/* Sends command to console. */
native console_cmd(id,const cmd[],any:...);
/* Registers event on which a given function will be called
* Flags:
* "a" - global event.
* "b" - specified to client (human player and bot).
* "c" - send only once when repeated to other players.
* "d" - call if is send to dead player.
* "e" - to alive.
* "f" - to human player only ("b" flag must be set).
* "g" - to bot only ("b" flag must be set).
* NOTE: Due to a long-standing bug that would break compatibility with old plugins,
* the client id should be checked for alive/dead state if you use d or e.
* Examples for conditions:
* "2=c4" - 2nd parameter of message must be sting "c4".
* "3>10" - 3rd parameter must be greater then 10.
* "3!4" - 3rd must be different from 4.
* "2&Buy" - 2nd parameter of message must contain "Buy" substring.
* "2!Buy" - 2nd parameter of message can't contain "Buy" substring. */
native register_event(const event[],const function[],const flags[],const cond[]="", ... );
/* Registers log event on which the given function will be called
* Examples for conditions:
* "0=World triggered" "1=Game_Commencing"
* "1=say"
* "3=Terrorists_Win"
* "1=entered the game"
* "0=Server cvar"
*/
native register_logevent(const function[], argsnum, ... );
/**
* Sends a message to the client via the engine.
*
* @param player Client index, use 0 to display to all players
* @param type Message type, see print_* destination constants in amxconst
* @param message Formatting rules
* @param ... Variable number of formatting parameters
*
* @return The 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:...);
/**
* Sets format for hudmessage.
* Note - as of AMX Mod X 1.61, setting the channel to -1
* will automatically choose the next available HUD channel for a player.
* Note - if you plan to make a permanent message, don't forget to specify a channel (1-4)
* to avoid flickering effect due to auto-channeling.
* 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 The 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 player
* "e" - Call only if sent to alive player
* "f" - Call only if sent to human player ("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.
*
* @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 for the message to fully appear (fade-in)
* @param fadeouttime Time it takes for 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 HUD message to given player. */
/**
* 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 The 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:...);
/**