From 5aef27a3abf328feb266b49e97e50ab6da86a045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Sun, 3 Aug 2014 16:33:08 +0200 Subject: [PATCH 01/27] amxconst: Add proper headings for all constant types --- plugins/include/amxconst.inc | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index 9528a8ff..6b6f2342 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -335,8 +335,14 @@ enum #define AMX_FLAG_BROWSE 0x4000 /* busy browsing */ #define AMX_FLAG_RELOC 0x8000 /* jump/call addresses relocated */ +/** + * Invalid plugin id + */ #define INVALID_PLUGIN_ID -1 +/** + * Menu and menu item status codes + */ #define MENU_TIMEOUT -4 #define MENU_EXIT -3 #define MENU_BACK -2 @@ -345,6 +351,9 @@ enum #define ITEM_ENABLED 1 #define ITEM_DISABLED 2 +/** + * AMX error codes + */ #define AMX_ERR_NATIVE 10 #define AMX_ERR_MEMACCESS 5 #define AMX_ERR_NONE 0 @@ -357,18 +366,30 @@ enum #define AMX_ERR_PARAMS 25 #define AMX_ERR_GENERAL 27 +/** + * Generic invalid handle value + */ #define INVALID_HANDLE -1 +/** + * Stop types for plugin forwards + */ #define ET_IGNORE 0 //ignore return val #define ET_STOP 1 //stop on PLUGIN_HANDLED #define ET_STOP2 2 //same, except return biggest #define ET_CONTINUE 3 //no stop, return biggest +/** + * Parameter types for plugin forwards + */ #define FP_CELL 0 #define FP_FLOAT 1 #define FP_STRING 2 #define FP_ARRAY 4 +/** + * Sound behavior constants + */ #define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients #define SND_STOP (1<<5) // stop sound #define SND_CHANGE_VOL (1<<6) // change sound vol From 79f15d56213edb0188396cdff40b718d04cdf98a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 00:30:49 +0200 Subject: [PATCH 02/27] amxconst: Fix up the headings some more and move long descriptions to @note --- plugins/include/amxconst.inc | 41 ++++++++++++++++++++++++------------ 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index 6b6f2342..8cef6bde 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -14,27 +14,40 @@ #include /** - * This is the buffer size AMX Mod X uses internally to retrieve strings from plugins. - * Most natives that take strings as arguments will implicitly truncate those to this maximum length. - * This has been raised to the current value with AMXX 1.8.3. Previously the limit was 3072. + * Internal AMXX buffer size for string retrieval. * - * @note This is here mainly for documentation purposes. By default plugins don't even have enough - * memory available to create an array of this size. You probably should not use this to - * actually *declare* a buffer unless you *absolutely* have to. Look at #pragma dynamic - * to increase a plugins available memory. + * @note This is the buffer size AMX Mod X uses internally to retrieve strings + * from plugins. Most natives that take strings as arguments will + * implicitly truncate them to this maximum length. This has been raised + * to the current value with AMXX 1.8.3. Previously the limit was 3072. + * @note This is here mainly for documentation purposes. By default plugins + * don't have enough memory available to allocate an array of this size. + * You probably should not use this to actually declare a buffer unless + * you *absolutely* have to. Look at #pragma dynamic to increase a plugins + * available memory. */ #define MAX_STRING_LENGTH 16384 /** - * MAX_PLAYERS is not the same as MaxClients. - * MAX_PLAYERS is a hardcoded value as an upper limit. MaxClients changes based on the server. + * Defines and constants related to the maximum number of clients. + * + * @note MAX_PLAYERS is not the same as MaxClients. MAX_PLAYERS is a hardcoded + * value as an upper limit, used mainly to declare arrays big enough for + * all possible server situations. MaxClients changes based on the + * server the plugin is deployed on.. */ -#define MAX_PLAYERS 33 /* Maximum number of players AMX Mod X supports */ -#define MAX_NAME_LENGTH 32 /* Maximum buffer required to store a client name */ +#define MAX_PLAYERS 33 /* Maximum number of players AMX Mod X supports */ -public stock const MaxClients; /* Maximum number of players the server supports (dynamic) */ +public stock const MaxClients; /* Maximum number of players the server supports */ +/** + * The maximum buffer size required to store a clients name. + */ +#define MAX_NAME_LENGTH 32 +/** + * Ï€ + */ #define M_PI 3.1415926535 /** @@ -239,7 +252,7 @@ enum /** * Color types for client_print_color() */ -enum +enum { print_team_default = 0, print_team_grey = -1, @@ -390,7 +403,7 @@ enum /** * Sound behavior constants */ -#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients +#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients #define SND_STOP (1<<5) // stop sound #define SND_CHANGE_VOL (1<<6) // change sound vol #define SND_CHANGE_PITCH (1<<7) // change sound pitch From 954436411686d35035dc1d22376ccac2d887c9a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 00:35:52 +0200 Subject: [PATCH 03/27] amxconst: Purge tabs --- plugins/include/amxconst.inc | 454 +++++++++++++++++------------------ 1 file changed, 227 insertions(+), 227 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index 8cef6bde..a28a7a3b 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -36,7 +36,7 @@ * all possible server situations. MaxClients changes based on the * server the plugin is deployed on.. */ -#define MAX_PLAYERS 33 /* Maximum number of players AMX Mod X supports */ +#define MAX_PLAYERS 33 /* Maximum number of players AMX Mod X supports */ public stock const MaxClients; /* Maximum number of players the server supports */ @@ -53,128 +53,128 @@ public stock const MaxClients; /* Maximum number of players the server supports /** * Admin level constants */ -#define ADMIN_ALL 0 /* everyone */ -#define ADMIN_IMMUNITY (1<<0) /* flag "a" */ -#define ADMIN_RESERVATION (1<<1) /* flag "b" */ -#define ADMIN_KICK (1<<2) /* flag "c" */ -#define ADMIN_BAN (1<<3) /* flag "d" */ -#define ADMIN_SLAY (1<<4) /* flag "e" */ -#define ADMIN_MAP (1<<5) /* flag "f" */ -#define ADMIN_CVAR (1<<6) /* flag "g" */ -#define ADMIN_CFG (1<<7) /* flag "h" */ -#define ADMIN_CHAT (1<<8) /* flag "i" */ -#define ADMIN_VOTE (1<<9) /* flag "j" */ -#define ADMIN_PASSWORD (1<<10) /* flag "k" */ -#define ADMIN_RCON (1<<11) /* flag "l" */ -#define ADMIN_LEVEL_A (1<<12) /* flag "m" */ -#define ADMIN_LEVEL_B (1<<13) /* flag "n" */ -#define ADMIN_LEVEL_C (1<<14) /* flag "o" */ -#define ADMIN_LEVEL_D (1<<15) /* flag "p" */ -#define ADMIN_LEVEL_E (1<<16) /* flag "q" */ -#define ADMIN_LEVEL_F (1<<17) /* flag "r" */ -#define ADMIN_LEVEL_G (1<<18) /* flag "s" */ -#define ADMIN_LEVEL_H (1<<19) /* flag "t" */ -#define ADMIN_MENU (1<<20) /* flag "u" */ -#define ADMIN_BAN_TEMP (1<<21) /* flag "v" */ -#define ADMIN_ADMIN (1<<24) /* flag "y" */ -#define ADMIN_USER (1<<25) /* flag "z" */ +#define ADMIN_ALL 0 /* everyone */ +#define ADMIN_IMMUNITY (1<<0) /* flag "a" */ +#define ADMIN_RESERVATION (1<<1) /* flag "b" */ +#define ADMIN_KICK (1<<2) /* flag "c" */ +#define ADMIN_BAN (1<<3) /* flag "d" */ +#define ADMIN_SLAY (1<<4) /* flag "e" */ +#define ADMIN_MAP (1<<5) /* flag "f" */ +#define ADMIN_CVAR (1<<6) /* flag "g" */ +#define ADMIN_CFG (1<<7) /* flag "h" */ +#define ADMIN_CHAT (1<<8) /* flag "i" */ +#define ADMIN_VOTE (1<<9) /* flag "j" */ +#define ADMIN_PASSWORD (1<<10) /* flag "k" */ +#define ADMIN_RCON (1<<11) /* flag "l" */ +#define ADMIN_LEVEL_A (1<<12) /* flag "m" */ +#define ADMIN_LEVEL_B (1<<13) /* flag "n" */ +#define ADMIN_LEVEL_C (1<<14) /* flag "o" */ +#define ADMIN_LEVEL_D (1<<15) /* flag "p" */ +#define ADMIN_LEVEL_E (1<<16) /* flag "q" */ +#define ADMIN_LEVEL_F (1<<17) /* flag "r" */ +#define ADMIN_LEVEL_G (1<<18) /* flag "s" */ +#define ADMIN_LEVEL_H (1<<19) /* flag "t" */ +#define ADMIN_MENU (1<<20) /* flag "u" */ +#define ADMIN_BAN_TEMP (1<<21) /* flag "v" */ +#define ADMIN_ADMIN (1<<24) /* flag "y" */ +#define ADMIN_USER (1<<25) /* flag "z" */ -#define FLAG_KICK (1<<0) /* flag "a" */ -#define FLAG_TAG (1<<1) /* flag "b" */ -#define FLAG_AUTHID (1<<2) /* flag "c" */ -#define FLAG_IP (1<<3) /* flag "d" */ -#define FLAG_NOPASS (1<<4) /* flag "e" */ -#define FLAG_CASE_SENSITIVE (1<<10) /* flag "k" */ +#define FLAG_KICK (1<<0) /* flag "a" */ +#define FLAG_TAG (1<<1) /* flag "b" */ +#define FLAG_AUTHID (1<<2) /* flag "c" */ +#define FLAG_IP (1<<3) /* flag "d" */ +#define FLAG_NOPASS (1<<4) /* flag "e" */ +#define FLAG_CASE_SENSITIVE (1<<10) /* flag "k" */ /** * Return codes */ -#define PLUGIN_CONTINUE 0 /* Results returned by public functions */ -#define PLUGIN_HANDLED 1 /* stop other plugins */ -#define PLUGIN_HANDLED_MAIN 2 /* to use in client_command(), continue all plugins but stop the command */ +#define PLUGIN_CONTINUE 0 /* Results returned by public functions */ +#define PLUGIN_HANDLED 1 /* stop other plugins */ +#define PLUGIN_HANDLED_MAIN 2 /* to use in client_command(), continue all plugins but stop the command */ /** * CVAR constants for register_cvar() */ -#define FCVAR_ARCHIVE 1 /* set to cause it to be saved to vars.rc */ -#define FCVAR_USERINFO 2 /* changes the client's info string */ -#define FCVAR_SERVER 4 /* notifies players when changed */ -#define FCVAR_EXTDLL 8 /* defined by external DLL */ -#define FCVAR_CLIENTDLL 16 /* defined by the client dll */ -#define FCVAR_PROTECTED 32 /* It's a server cvar, but we don't send the data since it's a password, etc. Sends 1 if it's not bland/zero, 0 otherwise as value */ -#define FCVAR_SPONLY 64 /* This cvar cannot be changed by clients connected to a multiplayer server. */ -#define FCVAR_PRINTABLEONLY 128 /* This cvar's string cannot contain unprintable characters ( e.g., used for player name etc ). */ -#define FCVAR_UNLOGGED 256 /* If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */ +#define FCVAR_ARCHIVE 1 /* set to cause it to be saved to vars.rc */ +#define FCVAR_USERINFO 2 /* changes the client's info string */ +#define FCVAR_SERVER 4 /* notifies players when changed */ +#define FCVAR_EXTDLL 8 /* defined by external DLL */ +#define FCVAR_CLIENTDLL 16 /* defined by the client dll */ +#define FCVAR_PROTECTED 32 /* It's a server cvar, but we don't send the data since it's a password, etc. Sends 1 if it's not bland/zero, 0 otherwise as value */ +#define FCVAR_SPONLY 64 /* This cvar cannot be changed by clients connected to a multiplayer server. */ +#define FCVAR_PRINTABLEONLY 128 /* This cvar's string cannot contain unprintable characters ( e.g., used for player name etc ). */ +#define FCVAR_UNLOGGED 256 /* If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */ /** * IDs of weapons in CS */ -#define CSW_P228 1 -#define CSW_SCOUT 3 -#define CSW_HEGRENADE 4 -#define CSW_XM1014 5 -#define CSW_C4 6 -#define CSW_MAC10 7 -#define CSW_AUG 8 -#define CSW_SMOKEGRENADE 9 -#define CSW_ELITE 10 -#define CSW_FIVESEVEN 11 -#define CSW_UMP45 12 -#define CSW_SG550 13 -#define CSW_GALI 14 -#define CSW_GALIL 14 -#define CSW_FAMAS 15 -#define CSW_USP 16 -#define CSW_GLOCK18 17 -#define CSW_AWP 18 -#define CSW_MP5NAVY 19 -#define CSW_M249 20 -#define CSW_M3 21 -#define CSW_M4A1 22 -#define CSW_TMP 23 -#define CSW_G3SG1 24 -#define CSW_FLASHBANG 25 -#define CSW_DEAGLE 26 -#define CSW_SG552 27 -#define CSW_AK47 28 -#define CSW_KNIFE 29 -#define CSW_P90 30 -#define CSW_VEST 31 // Custom -#define CSW_VESTHELM 32 // Custom -#define CSW_SHIELDGUN 99 +#define CSW_P228 1 +#define CSW_SCOUT 3 +#define CSW_HEGRENADE 4 +#define CSW_XM1014 5 +#define CSW_C4 6 +#define CSW_MAC10 7 +#define CSW_AUG 8 +#define CSW_SMOKEGRENADE 9 +#define CSW_ELITE 10 +#define CSW_FIVESEVEN 11 +#define CSW_UMP45 12 +#define CSW_SG550 13 +#define CSW_GALI 14 +#define CSW_GALIL 14 +#define CSW_FAMAS 15 +#define CSW_USP 16 +#define CSW_GLOCK18 17 +#define CSW_AWP 18 +#define CSW_MP5NAVY 19 +#define CSW_M249 20 +#define CSW_M3 21 +#define CSW_M4A1 22 +#define CSW_TMP 23 +#define CSW_G3SG1 24 +#define CSW_FLASHBANG 25 +#define CSW_DEAGLE 26 +#define CSW_SG552 27 +#define CSW_AK47 28 +#define CSW_KNIFE 29 +#define CSW_P90 30 +#define CSW_VEST 31 // Custom +#define CSW_VESTHELM 32 // Custom +#define CSW_SHIELDGUN 99 /** * HI weapon constants */ -#define HIW_BERETTA 1 -#define HIW_SPAS12 2 -#define HIW_M4A1 3 -#define HIW_MP5A4 4 -#define HIW_MP5SD5 5 -#define HIW_AK47 6 -#define HIW_AKS74U 7 -#define HIW_GLOCK 8 -#define HIW_M11 9 -#define HIW_M11SD 10 -#define HIW_PSG1 11 -#define HIW_ZASTAVA 12 -#define HIW_M16A2 13 -#define HIW_REMINGTON 14 -#define HIW_NATOGREN 15 -#define HIW_TANGOGREN 16 -#define HIW_FLASHBANG 17 +#define HIW_BERETTA 1 +#define HIW_SPAS12 2 +#define HIW_M4A1 3 +#define HIW_MP5A4 4 +#define HIW_MP5SD5 5 +#define HIW_AK47 6 +#define HIW_AKS74U 7 +#define HIW_GLOCK 8 +#define HIW_M11 9 +#define HIW_M11SD 10 +#define HIW_PSG1 11 +#define HIW_ZASTAVA 12 +#define HIW_M16A2 13 +#define HIW_REMINGTON 14 +#define HIW_NATOGREN 15 +#define HIW_TANGOGREN 16 +#define HIW_FLASHBANG 17 /** * Parts of body for hits */ -#define HIT_GENERIC 0 /* none */ -#define HIT_HEAD 1 -#define HIT_CHEST 2 -#define HIT_STOMACH 3 -#define HIT_LEFTARM 4 -#define HIT_RIGHTARM 5 -#define HIT_LEFTLEG 6 -#define HIT_RIGHTLEG 7 +#define HIT_GENERIC 0 /* none */ +#define HIT_HEAD 1 +#define HIT_CHEST 2 +#define HIT_STOMACH 3 +#define HIT_LEFTARM 4 +#define HIT_RIGHTARM 5 +#define HIT_LEFTLEG 6 +#define HIT_RIGHTLEG 7 /** * @section Constants for emit_sound() @@ -183,35 +183,35 @@ public stock const MaxClients; /* Maximum number of players the server supports /** * Channels */ -#define CHAN_AUTO 0 -#define CHAN_WEAPON 1 -#define CHAN_VOICE 2 -#define CHAN_ITEM 3 -#define CHAN_BODY 4 -#define CHAN_STREAM 5 /* allocate stream channel from the static or dynamic area */ -#define CHAN_STATIC 6 /* allocate channel from the static area */ -#define CHAN_NETWORKVOICE_BASE 7 /* voice data coming across the network */ -#define CHAN_NETWORKVOICE_END 500 /* network voice data reserves slots (CHAN_NETWORKVOICE_BASE through CHAN_NETWORKVOICE_END). */ +#define CHAN_AUTO 0 +#define CHAN_WEAPON 1 +#define CHAN_VOICE 2 +#define CHAN_ITEM 3 +#define CHAN_BODY 4 +#define CHAN_STREAM 5 /* allocate stream channel from the static or dynamic area */ +#define CHAN_STATIC 6 /* allocate channel from the static area */ +#define CHAN_NETWORKVOICE_BASE 7 /* voice data coming across the network */ +#define CHAN_NETWORKVOICE_END 500 /* network voice data reserves slots (CHAN_NETWORKVOICE_BASE through CHAN_NETWORKVOICE_END). */ /** *Attenuation values */ -#define ATTN_NONE 0.00 -#define ATTN_NORM 0.80 -#define ATTN_IDLE 2.00 -#define ATTN_STATIC 1.25 +#define ATTN_NONE 0.00 +#define ATTN_NORM 0.80 +#define ATTN_IDLE 2.00 +#define ATTN_STATIC 1.25 /** * Pitch values */ -#define PITCH_NORM 100 /* non-pitch shifted */ -#define PITCH_LOW 95 /* other values are possible - 0-255, where 255 is very high */ -#define PITCH_HIGH 120 +#define PITCH_NORM 100 /* non-pitch shifted */ +#define PITCH_LOW 95 /* other values are possible - 0-255, where 255 is very high */ +#define PITCH_HIGH 120 /** * Volume values */ -#define VOL_NORM 1.0 +#define VOL_NORM 1.0 /** * @endsection @@ -220,33 +220,33 @@ public stock const MaxClients; /* Maximum number of players the server supports /** * Menu keys */ -#define MENU_KEY_1 (1<<0) -#define MENU_KEY_2 (1<<1) -#define MENU_KEY_3 (1<<2) -#define MENU_KEY_4 (1<<3) -#define MENU_KEY_5 (1<<4) -#define MENU_KEY_6 (1<<5) -#define MENU_KEY_7 (1<<6) -#define MENU_KEY_8 (1<<7) -#define MENU_KEY_9 (1<<8) -#define MENU_KEY_0 (1<<9) +#define MENU_KEY_1 (1<<0) +#define MENU_KEY_2 (1<<1) +#define MENU_KEY_3 (1<<2) +#define MENU_KEY_4 (1<<3) +#define MENU_KEY_5 (1<<4) +#define MENU_KEY_6 (1<<5) +#define MENU_KEY_7 (1<<6) +#define MENU_KEY_8 (1<<7) +#define MENU_KEY_9 (1<<8) +#define MENU_KEY_0 (1<<9) /** * Language constants */ -#define LANG_SERVER 0 -#define LANG_PLAYER -1 +#define LANG_SERVER 0 +#define LANG_PLAYER -1 /** * Destination types for client_print() */ enum { - print_notify = 1, - print_console, - print_chat, - print_center, - print_radio /* Counter-Strike only */ + print_notify = 1, + print_console, + print_chat, + print_center, + print_radio /* Counter-Strike only */ }; /** @@ -254,10 +254,10 @@ enum */ enum { - print_team_default = 0, - print_team_grey = -1, - print_team_red = -2, - print_team_blue = -3, + print_team_default = 0, + print_team_grey = -1, + print_team_red = -2, + print_team_blue = -3, }; /** @@ -265,9 +265,9 @@ enum */ enum { - engprint_console = 0, - engprint_center, - engprint_chat, + engprint_console = 0, + engprint_center, + engprint_chat, }; /** @@ -275,12 +275,12 @@ enum */ enum { - kRenderNormal = 0, /* src */ - kRenderTransColor, /* c*a+dest*(1-a) */ - kRenderTransTexture, /* src*a+dest*(1-a) */ - kRenderGlow, /* src*a+dest -- No Z buffer checks */ - kRenderTransAlpha, /* src*srca+dest*(1-srca) */ - kRenderTransAdd, /* src*a+dest */ + kRenderNormal = 0, /* src */ + kRenderTransColor, /* c*a+dest*(1-a) */ + kRenderTransTexture, /* src*a+dest*(1-a) */ + kRenderGlow, /* src*a+dest -- No Z buffer checks */ + kRenderTransAlpha, /* src*srca+dest*(1-srca) */ + kRenderTransAdd, /* src*a+dest */ }; /** @@ -288,27 +288,27 @@ enum */ enum { - kRenderFxNone = 0, - kRenderFxPulseSlow, - kRenderFxPulseFast, - kRenderFxPulseSlowWide, - kRenderFxPulseFastWide, - kRenderFxFadeSlow, - kRenderFxFadeFast, - kRenderFxSolidSlow, - kRenderFxSolidFast, - kRenderFxStrobeSlow, - kRenderFxStrobeFast, - kRenderFxStrobeFaster, - kRenderFxFlickerSlow, - kRenderFxFlickerFast, - kRenderFxNoDissipation, - kRenderFxDistort, /* Distort/scale/translate flicker */ - kRenderFxHologram, /* kRenderFxDistort + distance fade */ - kRenderFxDeadPlayer, /* kRenderAmt is the player index */ - kRenderFxExplode, /* Scale up really big! */ - kRenderFxGlowShell, /* Glowing Shell */ - kRenderFxClampMinScale, /* Keep this sprite from getting very small (SPRITES only!) */ + kRenderFxNone = 0, + kRenderFxPulseSlow, + kRenderFxPulseFast, + kRenderFxPulseSlowWide, + kRenderFxPulseFastWide, + kRenderFxFadeSlow, + kRenderFxFadeFast, + kRenderFxSolidSlow, + kRenderFxSolidFast, + kRenderFxStrobeSlow, + kRenderFxStrobeFast, + kRenderFxStrobeFaster, + kRenderFxFlickerSlow, + kRenderFxFlickerFast, + kRenderFxNoDissipation, + kRenderFxDistort, /* Distort/scale/translate flicker */ + kRenderFxHologram, /* kRenderFxDistort + distance fade */ + kRenderFxDeadPlayer, /* kRenderAmt is the player index */ + kRenderFxExplode, /* Scale up really big! */ + kRenderFxGlowShell, /* Glowing Shell */ + kRenderFxClampMinScale, /* Keep this sprite from getting very small (SPRITES only!) */ }; /** @@ -316,9 +316,9 @@ enum */ enum { - force_exactfile = 0, /* File on client must exactly match server's file */ - force_model_samebounds, /* For model files only, the geometry must fit in the same bbox */ - force_model_specifybounds, /* For model files only, the geometry must fit in the specified bbox */ + force_exactfile = 0, /* File on client must exactly match server's file */ + force_model_samebounds, /* For model files only, the geometry must fit in the same bbox */ + force_model_specifybounds, /* For model files only, the geometry must fit in the specified bbox */ }; /** @@ -326,95 +326,95 @@ enum */ enum { - module_none = 0, - module_query, - module_badload, - module_loaded, - module_noinfo, - module_noquery, - module_noattach, - module_old, + module_none = 0, + module_query, + module_badload, + module_loaded, + module_noinfo, + module_noquery, + module_noattach, + module_old, }; /** * AMX flag constants */ -#define AMX_FLAG_DEBUG 0x02 /* symbolic info. available */ -#define AMX_FLAG_COMPACT 0x04 /* compact encoding */ -#define AMX_FLAG_BYTEOPC 0x08 /* opcode is a byte (not a cell) */ -#define AMX_FLAG_NOCHECKS 0x10 /* no array bounds checking; no STMT opcode */ -#define AMX_FLAG_NTVREG 0x1000 /* all native functions are registered */ -#define AMX_FLAG_JITC 0x2000 /* abstract machine is JIT compiled */ -#define AMX_FLAG_BROWSE 0x4000 /* busy browsing */ -#define AMX_FLAG_RELOC 0x8000 /* jump/call addresses relocated */ +#define AMX_FLAG_DEBUG 0x02 /* symbolic info. available */ +#define AMX_FLAG_COMPACT 0x04 /* compact encoding */ +#define AMX_FLAG_BYTEOPC 0x08 /* opcode is a byte (not a cell) */ +#define AMX_FLAG_NOCHECKS 0x10 /* no array bounds checking; no STMT opcode */ +#define AMX_FLAG_NTVREG 0x1000 /* all native functions are registered */ +#define AMX_FLAG_JITC 0x2000 /* abstract machine is JIT compiled */ +#define AMX_FLAG_BROWSE 0x4000 /* busy browsing */ +#define AMX_FLAG_RELOC 0x8000 /* jump/call addresses relocated */ /** * Invalid plugin id */ -#define INVALID_PLUGIN_ID -1 +#define INVALID_PLUGIN_ID -1 /** * Menu and menu item status codes */ -#define MENU_TIMEOUT -4 -#define MENU_EXIT -3 -#define MENU_BACK -2 -#define MENU_MORE -1 -#define ITEM_IGNORE 0 -#define ITEM_ENABLED 1 -#define ITEM_DISABLED 2 +#define MENU_TIMEOUT -4 +#define MENU_EXIT -3 +#define MENU_BACK -2 +#define MENU_MORE -1 +#define ITEM_IGNORE 0 +#define ITEM_ENABLED 1 +#define ITEM_DISABLED 2 /** * AMX error codes */ -#define AMX_ERR_NATIVE 10 -#define AMX_ERR_MEMACCESS 5 -#define AMX_ERR_NONE 0 -#define AMX_ERR_BOUNDS 4 -#define AMX_ERR_STACKERR 3 -#define AMX_ERR_STACKLOW 7 -#define AMX_ERR_HEAPLOW 8 -#define AMX_ERR_DIVIDE 11 -#define AMX_ERR_NOTFOUND 19 -#define AMX_ERR_PARAMS 25 -#define AMX_ERR_GENERAL 27 +#define AMX_ERR_NATIVE 10 +#define AMX_ERR_MEMACCESS 5 +#define AMX_ERR_NONE 0 +#define AMX_ERR_BOUNDS 4 +#define AMX_ERR_STACKERR 3 +#define AMX_ERR_STACKLOW 7 +#define AMX_ERR_HEAPLOW 8 +#define AMX_ERR_DIVIDE 11 +#define AMX_ERR_NOTFOUND 19 +#define AMX_ERR_PARAMS 25 +#define AMX_ERR_GENERAL 27 /** * Generic invalid handle value */ -#define INVALID_HANDLE -1 +#define INVALID_HANDLE -1 /** * Stop types for plugin forwards */ -#define ET_IGNORE 0 //ignore return val -#define ET_STOP 1 //stop on PLUGIN_HANDLED -#define ET_STOP2 2 //same, except return biggest -#define ET_CONTINUE 3 //no stop, return biggest +#define ET_IGNORE 0 //ignore return val +#define ET_STOP 1 //stop on PLUGIN_HANDLED +#define ET_STOP2 2 //same, except return biggest +#define ET_CONTINUE 3 //no stop, return biggest /** * Parameter types for plugin forwards */ -#define FP_CELL 0 -#define FP_FLOAT 1 -#define FP_STRING 2 -#define FP_ARRAY 4 +#define FP_CELL 0 +#define FP_FLOAT 1 +#define FP_STRING 2 +#define FP_ARRAY 4 /** * Sound behavior constants */ -#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients -#define SND_STOP (1<<5) // stop sound -#define SND_CHANGE_VOL (1<<6) // change sound vol -#define SND_CHANGE_PITCH (1<<7) // change sound pitch +#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients +#define SND_STOP (1<<5) // stop sound +#define SND_CHANGE_VOL (1<<6) // change sound vol +#define SND_CHANGE_PITCH (1<<7) // change sound pitch /** * LibType constants */ enum LibType { - LibType_Library, - LibType_Class + LibType_Library, + LibType_Class }; /** @@ -422,8 +422,8 @@ enum LibType */ enum AdminProp { - AdminProp_Auth = 0, - AdminProp_Password, - AdminProp_Access, - AdminProp_Flags + AdminProp_Auth = 0, + AdminProp_Password, + AdminProp_Access, + AdminProp_Flags }; From 8ba288cfb163df2eb14e1ba1472c254dc97f901a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 00:48:37 +0200 Subject: [PATCH 04/27] amxmodx: First batch of documentation updates --- plugins/include/amxmodx.inc | 689 +++++++++++++++++++++++++++--------- 1 file changed, 512 insertions(+), 177 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 6c11fddd..2ababc78 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -27,168 +27,503 @@ #include #include -/* 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 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. + * @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 + */ +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 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 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:...); /** - * Sets the Director HUD parameters for drawing text. + * Sets the Director HUD parameters for drawing text. * - * These parameters are stored globally, although nothing other than this function and set_hudmessage modify them. - * You must call this function before drawing text. If you are drawing text to multiple clients, you can set the - * parameters once, since they won't be modified. However, as soon as you pass control back to other plugins, + * These parameters are stored globally, although nothing other than this function and set_hudmessage modify them. + * You must call this function before drawing text. If you are drawing text to multiple clients, you can set the + * parameters once, since they won't be modified. However, as soon as you pass control back to other plugins, * you must reset the parameters next time you draw. - * + * * @param red The red color value. * @param green The green color value. * @param blue The blue color value. @@ -197,14 +532,14 @@ native show_hudmessage(index,const message[],any:...); * @param effects The effect value. 0 = fade in/fade out, 1 is flickery credits, 2 is write out (training room). * @param fxtime The duration of chosen effect (may not apply to all effects). * @param holdtime The Number of seconds to hold the text. - * @param fadeintime The number of seconds to spend fading in. - * @param fadeoutime The number of seconds to spend fading out. + * @param fadeintime The number of seconds to spend fading in. + * @param fadeoutime The number of seconds to spend fading out. */ 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); /** * Shows a Director HUD message to a client. Usually such message has a bigger letter size. - * Ideally used to show static/persistent message. + * Ideally used to show static/persistent message. * * Unlike classic HUD message which is channel-based, Director HUD message is stack-based. Don't expect same behavior. * You can have up to 8 messages displatying at once. If you try more, the first will be overwritten, then second, etc. @@ -236,7 +571,7 @@ native read_datatype(); /* Gets log message. Can be called only in plugin_log() forward function. */ native read_logdata(output[],len); -/* Returns number of log arguments. +/* Returns number of log arguments. * Can be called only in plugin_log() forward function. */ native read_logargc(); @@ -284,7 +619,7 @@ native get_amxx_verstring(buffer[], length); /* If player is not attacked function returns 0, in other * case returns index of attacking player. On second and third * parameter you may get info about weapon and body hit place. - * As of 1.75, get_user_attacker can return a non-player index if the player was attacked by a non-player entity. + * As of 1.75, get_user_attacker can return a non-player index if the player was attacked by a non-player entity. */ native get_user_attacker(index,...); @@ -315,7 +650,7 @@ native get_user_ip(index,ip[],len, without_port = 0); set "setweapon" to 0 to turn the bit off, set to 1 to turn it on. */ native user_has_weapon(index,weapon,setweapon=-1); -/* Returns id of currently carried weapon. Gets also +/* Returns id of currently carried weapon. Gets also * ammount of ammo in clip and backpack. */ native get_user_weapon(index,&clip=0,&ammo=0); @@ -329,7 +664,7 @@ native num_to_word(num,output[],len); * then a name of team is set. */ native get_user_team(index, team[]="", len = 0); -/* Returns player playing time in seconds. +/* Returns player playing time in seconds. * If flag is set then result is without connection time. */ native get_user_time(index, flag = 0); @@ -341,17 +676,17 @@ native get_user_ping(index, &ping, &loss); * 0 - current position. * 1 - position from eyes (weapon aiming). * 2 - end position from player position. -* 3 - end position from eyes (hit point for weapon). +* 3 - end position from eyes (hit point for weapon). * 4 - position of last bullet hit (only CS). */ native get_user_origin(index, origin[3], mode = 0); /* Returns all carried weapons as bit sum. Gets * also theirs indexes. * Note that num is incremental - if you pass 0, you get - * 32 weapons towards the total. Afterwards, num will + * 32 weapons towards the total. Afterwards, num will * will contain the number of weapons retrieved. * However, subsequent calls to get_user_weapons() will - * return the next batch of weapons, in case the mod + * return the next batch of weapons, in case the mod * supports more than 32 weapons. * This means to call get_user_weapons() on the same * inputs twice, you must reset num to 0 to get the @@ -391,7 +726,7 @@ native log_message(const message[],any:...); /* Sends log message to specified file. */ native log_to_file(const file[],const message[],any:...); -/* Returns number of players put in server. +/* Returns number of players put in server. * If flag is set then also connecting are counted. */ native get_playersnum(flag=0); @@ -436,7 +771,7 @@ native get_flags(flags,output[],len); * "g" - don't look in alive players. * "h" - skip bots. * "i" - skip real players. -* "j" - return index of last found player. +* "j" - return index of last found player. * "k" - with given userid. * "l" - ignore case sensitivity. */ native find_player(const flags[], ... ); @@ -455,9 +790,9 @@ native client_cmd(index,const command[],any:...); * * @param index Index of the client, use 0 to send to all clients. * @param command The client command to execute on. - * @param arg1 Optionnal. The command arguments. + * @param arg1 Optionnal. The command arguments. * @param arg2 Optionnal. The command arguments. - * @noreturn + * @noreturn */ native engclient_cmd(index,const command[],const arg1[]="",const arg2[]=""); @@ -467,14 +802,14 @@ native engclient_cmd(index,const command[],const arg1[]="",const arg2[]=""); * Function is excellent for forcing to do an action related to a game (not settings!). * The command must stand alone but in arguments you can use spaces. * - * @note This is similar to engclient_cmd with the difference all plugins hooking + * @note This is similar to engclient_cmd with the difference all plugins hooking * the command will be notified as well. * * @param index Index of the client, use 0 to send to all clients. * @param command The client command to execute on. - * @param arg1 Optionnal. The command arguments. + * @param arg1 Optionnal. The command arguments. * @param arg2 Optionnal. The command arguments. - * @noreturn + * @noreturn */ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); @@ -535,7 +870,7 @@ native get_time(const format[],output[],len); * Last parameter sets time to format. */ native format_time(output[],len, const format[],time = -1); -/* Returns system time in seconds elapsed since 00:00:00 on January 1, 1970. +/* Returns system time in seconds elapsed since 00:00:00 on January 1, 1970. * Offset is given in seconds.*/ native get_systime(offset = 0); @@ -555,7 +890,7 @@ native parse_time(const input[],const format[], time = -1); * "d" - do task on time before a map timelimit. */ native set_task(Float:time,const function[],id = 0,const parameter[]="",len = 0,const flags[]="", repeat = 0); -/* Removes all tasks with given id. If outside var is +/* Removes all tasks with given id. If outside var is * set then a task can be removed also when * was set in another plugin. */ native remove_task(id = 0, outside = 0); @@ -575,21 +910,21 @@ native get_user_flags(index,id=0); /* Removes flags for player. */ native remove_user_flags(index,flags=-1,id=0); -/* Registers function which will be called from client console. +/* 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. +/* 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. +/* 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[]=""); @@ -725,7 +1060,7 @@ native get_modulesnum(); native is_plugin_loaded(const name[], bool:usefilename=false); /* Gets info about plugin by given index. - * Function returns -1 if plugin doesn't exist with given index. + * Function returns -1 if plugin doesn't exist with given index. * Note: the [...] portion should not be used, and is only for backward compatibility. * Use index of -1 to use the calling plugin's ID. */ @@ -742,7 +1077,7 @@ native get_pluginsnum(); * "c" - look outside the plugin (by given plugin name). * "d" - set "stopped" status when pausing whole plugin. * In this status plugin is unpauseable. -* Example: pause("ac","myplugin.amxx") +* Example: pause("ac","myplugin.amxx") * * Note: There used to be the b and e flags as well, * which have been deprecated and are no longer used. @@ -794,7 +1129,7 @@ native callfunc_push_intrf(&value); native callfunc_push_floatrf(& Float: value); /* If copyback is 1 (default), any changes are copied back. - * Note that this will defy the 'const' specifier for push_str(), + * Note that this will defy the 'const' specifier for push_str(), * which is only kept for special backwards compatibility. */ native callfunc_push_str(const VALUE[], bool:copyback=true); @@ -868,7 +1203,7 @@ 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 +// 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. @@ -877,7 +1212,7 @@ native log_error(error, const fmt[], any:...); //You only need to use it on by-reference parameters. native param_convert(num); -// Gets a string from the calling plugin +// Gets a string from the calling plugin native get_string(param, dest[], maxlen); // Sets a string in the calling plugin @@ -913,7 +1248,7 @@ native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const /** - * Allows you to trap error messages that occur in your plugin. + * 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: * @@ -957,15 +1292,15 @@ native dbg_fmt_error(buffer[], maxLength); * 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 + * 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, + * + * 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! @@ -974,20 +1309,20 @@ native dbg_fmt_error(buffer[], maxLength); native set_native_filter(const handler[]); /** - * This function sets a module/library filter. It will let you intercept the automatic requirement + * 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. - * + * 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. + * 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). */ @@ -1005,7 +1340,7 @@ native set_module_filter(const handler[]); native abort(error, const fmt[]="", any:...); /** - * Checks if a specific module is loaded. This is the exact same method AMX Mod X + * Checks if a specific module is loaded. This is the exact same method AMX Mod X * uses to see if a module is required by a plugin. For example: * module_exists("cstrike") * module_exists("dbi") @@ -1027,7 +1362,7 @@ native next_hudchannel(player); * 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 can potentially overlap, each side counts as a synchronizable area. - * You can then use ShowSyncHudMsg() to correctly synchronize displaying the + * You can then use ShowSyncHudMsg() to correctly synchronize displaying the * HUD message with any other messages potentially in its class. Note that this * does not yet do anything like reserve screen area, its sole purpose is to be * able to wipe an old message on an auto-channel and ensure that it will not @@ -1042,7 +1377,7 @@ native CreateHudSyncObj(num=0, ...); * it proceeds to write another. It will only do this in the case * of that channel not having been cleared already. * Target can be 0 for all players or 1-get_maxplayers(). - * You must use set_hudmessage, although the channel parameter is + * You must use set_hudmessage, although the channel parameter is * entirely ignored. */ native ShowSyncHudMsg(target, syncObj, const fmt[], any:...); From c9316542be3fea58b12e98c59c783cac2bccaad9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 02:32:12 +0200 Subject: [PATCH 05/27] amxconst: Grant @xPaw his beloved tabs --- plugins/include/amxconst.inc | 112 +++++++++++++++++------------------ 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index a28a7a3b..7550c2ec 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -242,11 +242,11 @@ public stock const MaxClients; /* Maximum number of players the server supports */ enum { - print_notify = 1, - print_console, - print_chat, - print_center, - print_radio /* Counter-Strike only */ + print_notify = 1, + print_console, + print_chat, + print_center, + print_radio /* Counter-Strike only */ }; /** @@ -254,10 +254,10 @@ enum */ enum { - print_team_default = 0, - print_team_grey = -1, - print_team_red = -2, - print_team_blue = -3, + print_team_default = 0, + print_team_grey = -1, + print_team_red = -2, + print_team_blue = -3, }; /** @@ -265,9 +265,9 @@ enum */ enum { - engprint_console = 0, - engprint_center, - engprint_chat, + engprint_console = 0, + engprint_center, + engprint_chat, }; /** @@ -275,12 +275,12 @@ enum */ enum { - kRenderNormal = 0, /* src */ - kRenderTransColor, /* c*a+dest*(1-a) */ - kRenderTransTexture, /* src*a+dest*(1-a) */ - kRenderGlow, /* src*a+dest -- No Z buffer checks */ - kRenderTransAlpha, /* src*srca+dest*(1-srca) */ - kRenderTransAdd, /* src*a+dest */ + kRenderNormal = 0, /* src */ + kRenderTransColor, /* c*a+dest*(1-a) */ + kRenderTransTexture, /* src*a+dest*(1-a) */ + kRenderGlow, /* src*a+dest -- No Z buffer checks */ + kRenderTransAlpha, /* src*srca+dest*(1-srca) */ + kRenderTransAdd, /* src*a+dest */ }; /** @@ -288,27 +288,27 @@ enum */ enum { - kRenderFxNone = 0, - kRenderFxPulseSlow, - kRenderFxPulseFast, - kRenderFxPulseSlowWide, - kRenderFxPulseFastWide, - kRenderFxFadeSlow, - kRenderFxFadeFast, - kRenderFxSolidSlow, - kRenderFxSolidFast, - kRenderFxStrobeSlow, - kRenderFxStrobeFast, - kRenderFxStrobeFaster, - kRenderFxFlickerSlow, - kRenderFxFlickerFast, - kRenderFxNoDissipation, - kRenderFxDistort, /* Distort/scale/translate flicker */ - kRenderFxHologram, /* kRenderFxDistort + distance fade */ - kRenderFxDeadPlayer, /* kRenderAmt is the player index */ - kRenderFxExplode, /* Scale up really big! */ - kRenderFxGlowShell, /* Glowing Shell */ - kRenderFxClampMinScale, /* Keep this sprite from getting very small (SPRITES only!) */ + kRenderFxNone = 0, + kRenderFxPulseSlow, + kRenderFxPulseFast, + kRenderFxPulseSlowWide, + kRenderFxPulseFastWide, + kRenderFxFadeSlow, + kRenderFxFadeFast, + kRenderFxSolidSlow, + kRenderFxSolidFast, + kRenderFxStrobeSlow, + kRenderFxStrobeFast, + kRenderFxStrobeFaster, + kRenderFxFlickerSlow, + kRenderFxFlickerFast, + kRenderFxNoDissipation, + kRenderFxDistort, /* Distort/scale/translate flicker */ + kRenderFxHologram, /* kRenderFxDistort + distance fade */ + kRenderFxDeadPlayer, /* kRenderAmt is the player index */ + kRenderFxExplode, /* Scale up really big! */ + kRenderFxGlowShell, /* Glowing Shell */ + kRenderFxClampMinScale, /* Keep this sprite from getting very small (SPRITES only!) */ }; /** @@ -316,9 +316,9 @@ enum */ enum { - force_exactfile = 0, /* File on client must exactly match server's file */ - force_model_samebounds, /* For model files only, the geometry must fit in the same bbox */ - force_model_specifybounds, /* For model files only, the geometry must fit in the specified bbox */ + force_exactfile = 0, /* File on client must exactly match server's file */ + force_model_samebounds, /* For model files only, the geometry must fit in the same bbox */ + force_model_specifybounds, /* For model files only, the geometry must fit in the specified bbox */ }; /** @@ -326,14 +326,14 @@ enum */ enum { - module_none = 0, - module_query, - module_badload, - module_loaded, - module_noinfo, - module_noquery, - module_noattach, - module_old, + module_none = 0, + module_query, + module_badload, + module_loaded, + module_noinfo, + module_noquery, + module_noattach, + module_old, }; /** @@ -413,8 +413,8 @@ enum */ enum LibType { - LibType_Library, - LibType_Class + LibType_Library, + LibType_Class }; /** @@ -422,8 +422,8 @@ enum LibType */ enum AdminProp { - AdminProp_Auth = 0, - AdminProp_Password, - AdminProp_Access, - AdminProp_Flags + AdminProp_Auth = 0, + AdminProp_Password, + AdminProp_Access, + AdminProp_Flags }; From f134ff9fdf2d7acfe0394647e47635c4e04b0f14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 16:29:01 +0200 Subject: [PATCH 06/27] amxmodx: Second batch of documentation updates --- plugins/include/amxmodx.inc | 744 +++++++++++++++++++++++++++++------- 1 file changed, 616 insertions(+), 128 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 2ababc78..d65e9104 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -205,6 +205,8 @@ native register_plugin(const plugin_name[], const version[], const author[]); * @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[]); @@ -222,6 +224,8 @@ native precache_model(const name[]); * @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[]); @@ -229,11 +233,13 @@ 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. + * @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[]); @@ -247,6 +253,8 @@ native precache_generic(const szFile[]); * @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[]); @@ -306,7 +314,7 @@ native show_motd(player, const message[], const header[]=""); * @param message Formatting rules * @param ... Variable number of formatting parameters * - * @return The number of printed characters. + * @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 @@ -343,7 +351,7 @@ native client_print(index, type, const message[], any:...); * @param fmt Formatting rules * @param ... Variable number of formatting parameters * - * @return The number of printed characters. + * @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 @@ -361,7 +369,7 @@ native client_print_color(index, sender, const message[], any:...); * @param message Formatting rules * @param ... Variable number of formatting parameters * - * @return The number of printed characters. + * @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 @@ -378,7 +386,7 @@ native engclient_print(player, type, const message[], any:...); * @param message Formatting rules * @param ... Variable number of formatting parameters * - * @return The number of printed characters. + * @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 */ @@ -458,8 +466,7 @@ native register_event(const event[], const function[], const flags[], const cond * - "&" for substring comparison * The argument is compared to the specified string accordingly * - * @return 1 on successfully registering event - * 0 on failure + * @return 1 on successfully registering event, 0 on failure * @error Invalid callback function */ native register_logevent(const function[], argsnum, ...); @@ -478,7 +485,8 @@ native register_logevent(const function[], argsnum, ...); * 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. + * 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 @@ -488,15 +496,14 @@ native register_logevent(const function[], argsnum, ...); * @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 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 HUD message to given player. */ /** * Displays a message on the client HUD. * @@ -506,7 +513,7 @@ native set_hudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, ef * @param message Formatting rules * @param ... Variable number of formatting parameters * - * @return The number of printed characters. + * @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 @@ -514,137 +521,414 @@ native set_hudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, ef * @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:...); +native show_hudmessage(index, const message[], any:...); /** - * Sets the Director HUD parameters for drawing text. + * Sets display parameters for director hudmessages. * - * These parameters are stored globally, although nothing other than this function and set_hudmessage modify them. - * You must call this function before drawing text. If you are drawing text to multiple clients, you can set the - * parameters once, since they won't be modified. However, as soon as you pass control back to other plugins, - * you must reset the parameters next time you draw. + * @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 The red color value. - * @param green The green color value. - * @param blue The blue color value. - * @param x The x coordinate (abscissa). From 0,0 to 1.0. -1.0 is the center. - * @param y The y coordinate (ordinate). From 0,0 to 1.0. - 1.0 is the center. - * @param effects The effect value. 0 = fade in/fade out, 1 is flickery credits, 2 is write out (training room). - * @param fxtime The duration of chosen effect (may not apply to all effects). - * @param holdtime The Number of seconds to hold the text. - * @param fadeintime The number of seconds to spend fading in. - * @param fadeoutime The number of seconds to spend fading out. + * @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); /** - * Shows a Director HUD message to a client. Usually such message has a bigger letter size. - * Ideally used to show static/persistent message. + * Displays a director message on the client HUD. * - * Unlike classic HUD message which is channel-based, Director HUD message is stack-based. Don't expect same behavior. - * You can have up to 8 messages displatying at once. If you try more, the first will be overwritten, then second, etc. - * Each message is limited to 128 characters. This will be automatically truncated by the native. - * Due to its way for working, there is no native to clear a specific message. + * @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 THe client index to send the message to. Use 0 to send to all connected clients. - * @param message The message text or formatting rules. - * @param ... The message formatting parameters. - * @return On success, the formatted message length. Otherwise 0. + * @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 menu. Keys have bit values (key 1 is (1<<0), key 5 is (1<<4) etc.). */ +/** + * 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[] = ""); -/* Gets value from client messages. -* When you are asking for string the array and length is needed (read_data(2,name,len)). -* Integer is returned by function (new me = read_data(3)). -* Float is set in second parameter (read_data(3,value)). */ +/** + * 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 number of values in client message. */ +/** + * 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 message id of client message */ +/** + * 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(); -/* Gets log message. Can be called only in plugin_log() forward function. */ +/** + * 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 arguments. -* Can be called only in plugin_log() forward function. */ +/** + * 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(); -/* Gets log argument indexed from 0. -* Can be called only in plugin_log() forward function. */ -native read_logargv(id,output[],len); +/** + * 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 arguments in the log message + * @error If called outside of the plugin_log() forward, an error is + * thrown. + */ +native read_logargv(id, output[], len); -/* Parse log data about user ( "Butcher<5>" etc. ). */ +/** + * Parse log data about client. + * + * @note When client actions are logged they appear in the the format + * "Name<#userid>", 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); -/* Prints message to server console. -* You may use text formating (f.e. server_print("%-32s %.2f!","hello",7.345)) */ +/** + * 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 1 or 0. */ +/** + * 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 1 or 0. */ +/** + * 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 1 or 0. */ +/** + * 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 1 or 0. */ +/** + * 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 player index. + * + * @param index Client index + * + * @return 1 if client is connected, 0 otherwise + */ native is_user_connected(index); -/* Returns 1 or 0. */ +/** + * Returns if the client is connecting. + * + * @param index Client index + * + * @return 1 if client is connecting, 0 otherwise + */ native is_user_connecting(index); -/* Returns 1 or 0. */ +/** + * Returns if the client is alive. + * + * @note This will never return true if a player is not connected. If you need + * to know whether a player 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 1 or 0. */ +/** + * 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 1 or 0. */ +/** + * 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 1 or 0. */ +/** + * 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(); -/* Returns AMXX's version string of the current gameserver */ +/** + * 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); -/* If player is not attacked function returns 0, in other - * case returns index of attacking player. On second and third - * parameter you may get info about weapon and body hit place. - * As of 1.75, get_user_attacker can return a non-player index if the player was attacked by a non-player entity. +/** + * Returns the last known attacker of a player. + * + * @note As of AMXX 1.75 this can return a non-player entity index if the player + * was attacked by a non-player 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-player 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,...); -/* If player doesn't hit at anything function returns 0.0, -* in other case the distance between hit point and player is returned. -* If player is aiming at another player then the id and part of body are set. */ -native Float:get_user_aiming(index,&id,&body,dist=9999); +native get_user_attacker(index, ...); -/* Returns player frags. */ +/** + * Traces the client's current aim vector to see if it hits something. + * + * @note If the trace does not hit a player 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 player index (if applicable) + * @param body Variable to store hit player 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 player'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 player'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 player. 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 player armor. */ +/** + * Returns the player'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 player 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 player deaths. */ +/** + * Returns the player'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 player 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 player health. */ +/** + * Returns the player'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 player 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); -/* Returns 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[]); -/* Returns ip. */ -native get_user_ip(index,ip[],len, without_port = 0); +/** + * 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 player has the weapon or not in their pev->weapons field. set "setweapon" to 0 to turn the bit off, set to 1 to turn it on. */ @@ -726,8 +1010,13 @@ native log_message(const message[],any:...); /* Sends log message to specified file. */ native log_to_file(const file[],const message[],any:...); -/* Returns number of players put in server. -* If flag is set then also connecting are counted. */ +/** + * Returns the number of players on the server. + * + * @param flag Count clients still in the connecting process if nonzero + * + * @return Number of players on the server + */ native get_playersnum(flag=0); /* Sets indexes of players. @@ -752,12 +1041,29 @@ native read_args(output[],len); /* Returns number of arguments (+ one as command). */ native read_argc(); -/* Converts string to sum of bits. -* Example: "abcd" is a sum of 1, 2, 4 and 8. */ +/** + * 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 sum of bits to string. -* Example: 3 will return "ab". */ +/** + * 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 player. @@ -816,7 +1122,19 @@ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = " /* Executes command on a server console. */ native server_cmd(const command[],any:...); -/* Sets a cvar to given value. */ +/** + * 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 + * engines 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_* set of functions. + * + * @param cvar cvar name to set + * @param value value to set cvar to + * + * @noreturn + */ native set_cvar_string(const cvar[],const value[]); /* If a cvar exists returns 1, in other case 0 */ @@ -833,19 +1151,78 @@ native set_cvar_flags(const cvar[],flags); /* Returns a cvar flags. */ native get_cvar_flags(const cvar[]); -/* Sets a cvar to given float. */ -native set_cvar_float(const cvar[],Float:value); +/** + * 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 + * engines 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_* set of functions. + * + * @param cvar cvar name to set + * @param value value to set cvar to + * + * @noreturn + */ +native set_cvar_float(const cvar[], Float:value); -/* Gets a cvar float. */ +/** + * Gets 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 + * engines 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_* set of functions. + * + * @param cvarname cvar name to get value from + * + * @return Cvar value, converted to float + */ native Float:get_cvar_float(const cvarname[]); -/* Gets a cvar integer value. */ +/** + * Gets 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 + * engines 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_* set of functions. + * + * @param cvarname cvar name to get value from + * + * @return Cvar value, converted to int + */ native get_cvar_num(const cvarname[]); -/* Sets a cvar with integer value. */ +/** + * 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 + * engines 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_* set of functions. + * + * @param cvarname cvar name to set + * @param value value to set cvar to + * + * @noreturn + */ native set_cvar_num(const cvarname[],value); -/* Reads a cvar 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 + * engines 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_* set of functions. + * + * @param cvar cvar name to get 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); /* Returns a name of currently played map. */ @@ -1090,53 +1467,149 @@ native pause(const flag[], const param1[]="",const param2[]=""); * "c" - look outside the plugin (by given plugin name). */ native unpause(const flag[], const param1[]="",const param2[]=""); -/* Call a function in this / an another plugin by name. -* Parameters: -* plugin - plugin filename; if "", the caller plugin is used. -* If specified, it has to be the exact filename (for example stats.amxx) -* func - function name -* Return value: -* 1 - Success -* 0 - Runtime error -* -1 - Plugin not found -* -2 - Function not found */ +/** + * 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[]=""); -/* Call a function in this / an another plugin by id. -* Parameters: -* plugin - plugin id; the id you would pass to get_plugin -* If < 0, the current plugin is taken -* func - function id -* Return value: -* 1 - Success -* -1 - Plugin not found -* -2 - Function not executable */ +/** + * 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); -/* Get a function id (for callfunc_begin_i) - To get the plugin id, use the find_plugin stock -*/ +/** + * 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); -/* Push a parameter (integer, string, float) - * Note that none of these values are const. - * Anything pushed by intrf, floatrf, array, or str - * can be modified by the called function. +/** + * 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); -native callfunc_push_float(Float: value); -native callfunc_push_intrf(&value); -native callfunc_push_floatrf(& Float: value); -/* If copyback is 1 (default), any changes are copied back. - * Note that this will defy the 'const' specifier for push_str(), - * which is only kept for special backwards compatibility. +/** + * 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); -/* Make the actual call. -* Return value of the function called. */ +/** + * 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 on inconsistent file. You can put any text @@ -1147,10 +1620,25 @@ forward inconsistent_file(id,const filename[], reason[64] ); * version of the specified file ( e.g., a player model ). */ native force_unmodified(force_type, const mins[3] , const maxs[3], const filename[]); -/* Calculates the md5 keysum of a string */ +/** + * 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 */ +/** + * 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 From b5aef1856de0c31fdc00a4fc09e7cda1759c87da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 19:24:36 +0200 Subject: [PATCH 07/27] amxmodx: Third batch of documentation updates --- plugins/include/amxmodx.inc | 612 ++++++++++++++++++++++++++---------- 1 file changed, 445 insertions(+), 167 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index d65e9104..087b0fd9 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -296,7 +296,7 @@ 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 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 @@ -309,7 +309,7 @@ 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 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 @@ -332,7 +332,7 @@ native client_print(index, type, const message[], any:...); * 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 + * 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 @@ -344,7 +344,7 @@ native client_print(index, type, const message[], any:...); * @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 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. @@ -364,7 +364,7 @@ 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 players + * @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 @@ -422,9 +422,9 @@ native console_cmd(id, const cmd[], any:...); * "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) + * "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: * "" @@ -677,7 +677,7 @@ native read_logargc(); * @param output Buffer to copy log argument to * @param len Maximum buffer size * - * @return Number of arguments in the log message + * @return Number of cells written to buffer * @error If called outside of the plugin_log() forward, an error is * thrown. */ @@ -747,7 +747,7 @@ native is_user_hltv(index); * * @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 player index. + * without manually verifying an index to be a valid client index. * * @param index Client index * @@ -767,8 +767,8 @@ native is_user_connecting(index); /** * Returns if the client is alive. * - * @note This will never return true if a player is not connected. If you need - * to know whether a player is alive, an additional call to + * @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 @@ -815,17 +815,17 @@ native is_jit_enabled(); native get_amxx_verstring(buffer[], length); /** - * Returns the last known attacker of a player. + * Returns the last known attacker of a client. * - * @note As of AMXX 1.75 this can return a non-player entity index if the player - * was attacked by a non-player entity. + * @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-player entity or 0 if no + * @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. @@ -836,12 +836,12 @@ 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 player id and body will be set to 0. + * @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 player index (if applicable) - * @param body Variable to store hit player body part (if applicable) + * @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 @@ -851,51 +851,51 @@ native get_user_attacker(index, ...); native Float:get_user_aiming(index, &id, &body, dist=9999); /** - * Returns the player's frags. + * 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 player's overall score, which may or may + * @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 player. Also returns 0 if the client is + * @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 player's armor value. + * 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 player has. Also returns 0 if the client + * @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 player's death count. + * 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 player has. Also returns 0 if the + * @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 player's health points. + * 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 @@ -903,7 +903,7 @@ native get_user_deaths(index); * * @param index Client index * - * @return Amount of health points the player has. Also returns 0 if + * @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 */ @@ -921,12 +921,12 @@ 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 + * @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 + * @return Number of cells written to the buffer */ native get_user_ip(index, ip[], len, without_port = 0); @@ -941,104 +941,268 @@ native get_user_weapon(index,&clip=0,&ammo=0); /* Gets ammo and clip from current weapon. */ native get_user_ammo(index,weapon,&clip,&ammo); -/* Converts numbers from range 0 - 999 to words. */ -native num_to_word(num,output[],len); +/** + * 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 team id. When length is greater then 0 -* then a name of team is set. */ +/** + * 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 player playing time in seconds. -* If flag is set then result is without connection time. */ +/** + * 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); -/* Gets ping and loss at current time. */ +/** + * 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); -/* Gets origin from player. -* Modes: -* 0 - current position. -* 1 - position from eyes (weapon aiming). -* 2 - end position from player position. -* 3 - end position from eyes (hit point for weapon). -* 4 - position of last bullet hit (only CS). */ +/** + * 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); -/* Returns all carried weapons as bit sum. Gets - * also theirs indexes. - * Note that num is incremental - if you pass 0, you get - * 32 weapons towards the total. Afterwards, num will - * will contain the number of weapons retrieved. - * However, subsequent calls to get_user_weapons() will - * return the next batch of weapons, in case the mod - * supports more than 32 weapons. - * This means to call get_user_weapons() on the same - * inputs twice, you must reset num to 0 to get the - * original output again. +/** + * 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); -/* Returns weapon name. */ -native get_weaponname(id,weapon[],len); - -/* Returns player name. */ -native get_user_name(index,name[],len); - -/* Gets player authid. */ -native get_user_authid(index, authid[] ,len); - -/* Returns player userid. */ -native get_user_userid(index); - -/* Slaps player with given power. */ -native user_slap(index,power,rnddir=1); - -/* Kills player. When flag is set to 1 then death won't decrase frags. */ -native user_kill(index,flag=0); - -/* Logs something into the current amx logfile -* Parameters: -* string[] - format string -* ... - optional parameters -* Return value: -* always 0 */ -native log_amx(const string[], any:...); - -/* Sends message to standard HL logs. */ -native log_message(const message[],any:...); - -/* Sends log message to specified file. */ -native log_to_file(const file[],const message[],any:...); +/** + * 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); /** - * Returns the number of players on the server. + * 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 players on the server + * @return Number of clients on the server */ native get_playersnum(flag=0); -/* Sets indexes of players. -* Flags: -* "a" - don't collect dead players. -* "b" - don't collect alive players. -* "c" - skip bots. -* "d" - skip real players. -* "e" - match with team. -* "f" - match with part of name. -* "g" - ignore case sensitivity. -* "h" - skip HLTV. -* Example: Get all alive CTs: get_players(players,num,"ae","CT") */ +/** + * 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[]=""); -/* Gets argument from command. */ -native read_argv(id,output[],len); +/** + * 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); -/* Gets line of all arguments. */ +/** + * 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 arguments (+ one as command). */ +/** + * 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(); /** @@ -1066,101 +1230,215 @@ native read_flags(const flags[]); */ native get_flags(flags,output[],len); -/* Find player. -* Flags: -* "a" - with given name. -* "b" - with given part of name. -* "c" - with given authid. -* "d" - with given ip. -* "e" - with given team name. -* "f" - don't look in dead players. -* "g" - don't look in alive players. -* "h" - skip bots. -* "i" - skip real players. -* "j" - return index of last found player. -* "k" - with given userid. -* "l" - ignore case sensitivity. */ +/** + * 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 quotes from sentence. */ +/** + * 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 + * all ^r (carriage return) characters at the end of the string, even if + * no matching double-quote is found. + * + * @param text String to remove double-quotes from + * + * @return 1 if matching double-quotes have been removed, 0 otherwise + */ native remove_quotes(text[]); -/* Executes command on player. */ -native client_cmd(index,const command[],any:...); +/** + * 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:...); /** - * This is an emulation of a client command (commands aren't send to client!). - * It allows to execute some commands on players and bots. - * Function is excellent for forcing to do an action related to a game (not settings!). - * The command must stand alone but in arguments you can use spaces. + * 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 * - * @param index Index of the client, use 0 to send to all clients. - * @param command The client command to execute on. - * @param arg1 Optionnal. The command arguments. - * @param arg2 Optionnal. The 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[]=""); /** - * This is an emulation of a client command (commands aren't send to client!). - * It allows to execute some commands on players and bots. - * Function is excellent for forcing to do an action related to a game (not settings!). - * The command must stand alone but in arguments you can use spaces. + * Execute a command from the client without actually sending it to the client's + * DLL. This triggers plugin command hooks. * - * @note This is similar to engclient_cmd with the difference all plugins hooking - * the command will be notified as well. + * @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 * - * @param index Index of the client, use 0 to send to all clients. - * @param command The client command to execute on. - * @param arg1 Optionnal. The command arguments. - * @param arg2 Optionnal. The 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[] = ""); -/* Executes command on a server console. */ +/** + * Executes a command 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. + * + * @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 - * engines cvar list every time, which can result in a considerable waste + * @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_* set of functions. * - * @param cvar cvar name to set - * @param value value to set cvar to + * @param cvar Cvar name to set value of + * @param value Value to set cvar to * * @noreturn */ -native set_cvar_string(const cvar[],const value[]); +native set_cvar_string(const cvar[], const value[]); -/* If a cvar exists returns 1, in other case 0 */ +/** + * Returns if a cvar is registered on the server. + * + * @param cvar Cvar name to check + * + * @return 1 if the cvar exists, 0 otherwise + */ native cvar_exists(const cvar[]); -/* Removes a cvar flags (not allowed for amx_version, -* fun_version and sv_cheats cvars). */ -native remove_cvar_flags(const cvar[],flags = -1); +/** + * Removes specified flags from a cvar + * + * @note Not permitted for the "amx_version", "fun_version" and "sv_cheats" + * cvars. + * @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 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 a cvar flags (not allowed for amx_version, -* fun_version and sv_cheats cvars). */ -native set_cvar_flags(const cvar[],flags); +/** + * Sets specified flags to a cvar + * + * @note Not permitted for the "amx_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-and 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 a cvar flags. */ +/** + * Returns flags of a cvar + * + * @note Not permitted for the "amx_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-and 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 get_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 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 - * engines cvar list every time, which can result in a considerable waste + * 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_* set of functions. * - * @param cvar cvar name to set - * @param value value to set cvar to + * @param cvar Cvar name to set value of + * @param value Value to set cvar to * * @noreturn */ @@ -1170,11 +1448,11 @@ native set_cvar_float(const cvar[], Float:value); * Gets 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 - * engines cvar list every time, which can result in a considerable waste + * 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_* set of functions. * - * @param cvarname cvar name to get value from + * @param cvarname Cvar name to get value from * * @return Cvar value, converted to float */ @@ -1184,11 +1462,11 @@ native Float:get_cvar_float(const cvarname[]); * Gets 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 - * engines cvar list every time, which can result in a considerable waste + * 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_* set of functions. * - * @param cvarname cvar name to get value from + * @param cvarname Cvar name to get value from * * @return Cvar value, converted to int */ @@ -1198,22 +1476,22 @@ 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 - * engines cvar list every time, which can result in a considerable waste + * 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_* set of functions. * - * @param cvarname cvar name to set - * @param value value to set cvar to + * @param cvar Cvar name to set value of + * @param value Value to set cvar to * * @noreturn */ -native set_cvar_num(const cvarname[],value); +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 - * engines cvar list every time, which can result in a considerable waste + * 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_* set of functions. * From bc3808cb3fbb3d47b02b9e6fa1196584db74929a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 19:39:40 +0200 Subject: [PATCH 08/27] ham_const: Fix up headings for proper display in api reference --- plugins/include/ham_const.inc | 112 ++++++++++++++++------------------ 1 file changed, 54 insertions(+), 58 deletions(-) diff --git a/plugins/include/ham_const.inc b/plugins/include/ham_const.inc index ac7f5167..619206bf 100644 --- a/plugins/include/ham_const.inc +++ b/plugins/include/ham_const.inc @@ -6,9 +6,9 @@ /** * Ham return types. * - * Return these from hooks to disable calling the target function. - * Numbers match up with fakemeta's FMRES_* for clarity. They are interchangable. - * 0 (or no return) is also interpretted as HAM_IGNORED. + * @note Return these from hooks to disable calling the target function. + * Numbers match up with fakemeta's FMRES_* for clarity. They are + * interchangable. 0 (or no return) is also interpretted as HAM_IGNORED. */ #define HAM_IGNORED 1 /**< Calls target function, returns normal value */ #define HAM_HANDLED 2 /**< Tells the module you did something, still calls target function and returns normal value */ @@ -16,30 +16,27 @@ #define HAM_SUPERCEDE 4 /**< Block the target call, and use your return value (if applicable) (Set with SetHamReturn*()) */ /** - * A few notes about all of the following functions: - * - Not all functions will do as you expect on all mods. - * If a function does not do what you would believe it should - * DO NOT file a bug report, you will be ignored. + * List of virtual functions made available through the hamsandwich module. * - * - Passing invalid parameters has potential to crash the server - * So be careful, and adequately test! - * - * - All functions take (and pass) a "this" index as the first param. - * This is the entity from which the function is being executed on. - * - * - All functions and forwards (eg: {Register,Execute}Ham[B]) require - * the mod to have the pev and base keys in addition to the function - * keys for the corresponding mod/operating system in hamdata.ini - * - * - Some functions that return booleans may need to be logically ANDed - * to get the results desired. e.g: if (ExecuteHam(Ham_TS_IsObjective, this) & 0x0000FFFF != 0) { // true.. } - * because the module will return the full integer value. + * @note Not all functions will do as you expect on all mods. If a function does + * not do what you would believe it should DO NOT file a bug report, you + * will be ignored. + * @note Passing invalid parameters has potential to crash the server, so be + * careful, and test carefully and adequately! + * @note All functions take (and pass) a "this" index as the first param. + * This is the entity from which the function is being executed on. + * @note All functions and forwards (eg: {Register,Execute}Ham[B]) require + * the mod to have the pev and base keys in addition to the function + * keys for the corresponding mod/operating system in hamdata.ini + * @note Some functions that return booleans may need to be logically ANDed + * to get the desired results because the mod will return the full integer + * value. E.g.: (ExecuteHam(Ham_TS_IsObjective, this) & 0x0000FFFF) != 0 */ enum Ham { /** - * Description: This is typically called whenever an entity is created. + * Description: This is typically called whenever an entity is created. * It is the virtual equivilent of spawn from the engine. * Some mods call this on player spawns too. * Forward params: function(this) @@ -249,7 +246,7 @@ enum Ham */ Ham_GetDelay, - /** + /** * Description: Whether or not the entity is moving. * Forward params: function(this); * Return type: Integer. @@ -305,7 +302,7 @@ enum Ham */ Ham_OnControls, - /** + /** * Description: Whether or not the entity is sneaking. * Forward params: function(this); * Return type: Integer (boolean). @@ -313,7 +310,7 @@ enum Ham */ Ham_IsSneaking, - /** + /** * Description: Whether or not the entity is alive. * Forward params: function(this); * Return type: Integer (boolean). @@ -321,7 +318,7 @@ enum Ham */ Ham_IsAlive, - /** + /** * Description: Whether or not the entity uses a BSP model. * Forward params: function(this); * Return type: Integer (boolean). @@ -329,7 +326,7 @@ enum Ham */ Ham_IsBSPModel, - /** + /** * Description: Whether or not the entity can reflect gauss shots.. * Forward params: function(this); * Return type: Integer (boolean). @@ -348,7 +345,7 @@ enum Ham */ Ham_HasTarget, - /** + /** * Description: Whether or not the entity is in the world. * Forward params: function(this); * Return type: Integer (boolean). @@ -356,7 +353,7 @@ enum Ham */ Ham_IsInWorld, - /** + /** * Description: Whether or not the entity is a player. * Forward params: function(this); * Return type: Integer (boolean). @@ -364,7 +361,7 @@ enum Ham */ Ham_IsPlayer, - /** + /** * Description: Whether or not the entity is a net client. * Forward params: function(this); * Return type: Integer (boolean). @@ -372,7 +369,7 @@ enum Ham */ Ham_IsNetClient, - /** + /** * Description: Get the entity's team id. * This function is not supported by Team Fortress Classic mod. * Forward params: function(this); @@ -1273,8 +1270,8 @@ enum Ham Ham_BestVisibleEnemy, /** - * Description: Returns true if the passed ent is in the caller's forward view cone. - * The dot product is performed in 2d, making the view cone infinitely tall. + * Description: Returns true if the passed ent is in the caller's forward view cone. + * The dot product is performed in 2d, making the view cone infinitely tall. * Forward params: function(this, idOther); * Return type: Integer (boolean). * Execute params: ExecuteHam(Ham_FInViewCone, this, idOther); @@ -1282,8 +1279,8 @@ enum Ham Ham_FInViewCone, /** - * Description: Returns true if the passed ent is in the caller's forward view cone. - * The dot product is performed in 2d, making the view cone infinitely tall. + * Description: Returns true if the passed ent is in the caller's forward view cone. + * The dot product is performed in 2d, making the view cone infinitely tall. * Forward params: function(this, const Float:origin[3]); * Return type: Integer (boolean). * Execute params: ExecuteHam(Ham_FVecInViewCone, this, const Float:origin[3]); @@ -1433,7 +1430,7 @@ enum Ham /** * Description: Determines whether or not the monster can play the scripted sequence or AI sequence that is - * trying to possess it. If DisregardState is set, the monster will be sucked into the script + * trying to possess it. If DisregardState is set, the monster will be sucked into the script * no matter what state it is in. ONLY Scripted AI ents should allow this. * This function is not supported by Counter-Strike, The Specialists and Natural Selection mods. * Forward params: function(this, bool:disregardState, interruptLevel); @@ -1497,7 +1494,7 @@ enum Ham Ham_SetActivity, /** - * Description: Part of the condition collection process gets and stores data and conditions + * Description: Part of the condition collection process gets and stores data and conditions * pertaining to a monster's enemy. Returns TRUE if Enemy LKP was updated. * This function is not supported by Counter-Strike, The Specialists and Natural Selection mods. * Forward params: function(this, idEnemy); @@ -1537,7 +1534,7 @@ enum Ham Ham_BuildNearestRoute, /** - * Description: Tries to find a nearby node that will hide the caller from its enemy. + * Description: Tries to find a nearby node that will hide the caller from its enemy. * If supplied, search will return a node at least as far away as MinDist from vecThreat, but no farther than minDist. * If maxDist isn't supplied, it defaults to a reasonable value. * This function is not supported by Counter-Strike, The Specialists and Natural Selection mods. @@ -1604,7 +1601,7 @@ enum Ham Ham_FCanActiveIdle, /** - * Description: Returns a bit mask indicating which types of sounds this monster regards. + * Description: Returns a bit mask indicating which types of sounds this monster regards. * In the base class implementation, monsters care about all sounds, but no scents. * This function is not supported by Counter-Strike, The Specialists and Natural Selection mods. * Forward params: function(this); @@ -1869,7 +1866,7 @@ enum Ham * The following functions are specific to Team Fortress Classic. */ - /** + /** * Description: Get the item name. * Forward params: function(this, const buffer[]); * Return type: String (string length returned and string byref'd in ExecuteHam). @@ -2845,8 +2842,8 @@ enum Ham */ /** - * Description: Returns the type of group (i.e, "houndeye", or "human military" - * so that monsters with different classnames still realize that they are teammates. + * Description: Returns the type of group (i.e, "houndeye", or "human military" + * so that monsters with different classnames still realize that they are teammates. * (overridden for monsters that form groups) * Classes list: * CLASS_NONE 0 @@ -2861,11 +2858,11 @@ enum Ham * CLASS_ALIEN_PREDATOR 9 * CLASS_INSECT 10 * CLASS_PLAYER_ALLY 11 - * CLASS_PLAYER_BIOWEAPON 12 - * CLASS_ALIEN_BIOWEAPON 13 - * CLASS_XRACE_PITDRONE 14 + * CLASS_PLAYER_BIOWEAPON 12 + * CLASS_ALIEN_BIOWEAPON 13 + * CLASS_XRACE_PITDRONE 14 * CLASS_XRACE_SHOCK 15 - * CLASS_BARNACLE 99 + * CLASS_BARNACLE 99 * Forward params: function(this, class) * Return type: Integer. * Execute params: ExecuteHam(Ham_SC_GetClassification, this, class) @@ -3022,7 +3019,7 @@ enum Ham Ham_SC_Revive, /** - * Description: Final bit of initization before a monster is turned over to the AI. + * Description: Final bit of initization before a monster is turned over to the AI. * Forward params: function(this) * Return type: None. * Execute params: ExecuteHam(Ham_SC_StartMonster, this) @@ -3095,7 +3092,7 @@ enum Ham /** * Description: Tries to find a nearby node that will hide the caller from its enemy. - * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. + * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. * If maxDist isn't supplied, it defaults to a reasonable value. * Forward params: function(this, const Float:threat[3], const Float:viewOffset[3], Float:minDist, Float:maxDist) * Return type: Integer (boolean). @@ -3105,7 +3102,7 @@ enum Ham /** * Description: Tries to find a nearby node that will hide the caller from its enemy. - * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. + * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. * If maxDist isn't supplied, it defaults to a reasonable value. * Forward params: function(this, const Float:threat[3], const Float:viewOffset[3], Float:minDist, Float:maxDist) * Return type: Integer (boolean). @@ -3115,7 +3112,7 @@ enum Ham /** * Description: Tries to find a nearby node that will hide the caller from its enemy. - * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. + * If supplied, search will return a node at least as far away as minDist, but no farther than maxDist. * If maxDist isn't supplied, it defaults to a reasonable value. * Forward params: function(this, const Float:threat[3], const Float:viewOffset[3], Float:minDist, Float:maxDist) * Return type: Integer (boolean). @@ -3124,7 +3121,7 @@ enum Ham Ham_SC_FindAttackPoint, /** - * Description: Determines whether or not the chosen cover location is a good one to move to. + * Description: Determines whether or not the chosen cover location is a good one to move to. * Currently based on proximity to others in the squad. * Forward params: function(this, const Float:coverLocation[3]) * Return type: Integer (boolean). @@ -3308,7 +3305,7 @@ enum Ham * Execute params: ExecuteHam(Ham_SC_MedicCallSound, this) */ Ham_SC_Player_MenuInputPerformed, - + /** * Description: - * Forward params: function(this) @@ -3486,7 +3483,7 @@ enum Ham * Execute params: ExecuteHam(Ham_SC_Weapon_BurstSupplement, this) */ Ham_SC_Weapon_BurstSupplement, - + /** * Description: - * Forward params: function(this, const alternative[] = "") @@ -3583,7 +3580,7 @@ enum Ham */ Ham_SC_Weapon_ChangeWeaponSkin, - + /** * LATE ADDITIONS (2013) */ @@ -3620,7 +3617,7 @@ enum Ham */ Ham_TFC_Weapon_GetNextAttackDelay, - + /** * Description: Usually called whenever an entity gets a form of a heal. * Forward params: function(this, Float:health, damagebits, health_cap); @@ -3715,7 +3712,7 @@ enum Ham */ Ham_Item_GetItemInfo, - + /** * DONT USE ME LOL */ @@ -3723,7 +3720,7 @@ enum Ham }; /** - * Ham errors types. + * Ham error types. */ enum HamError { @@ -3736,8 +3733,7 @@ enum HamError }; /** - * To be used with [Get|Set]HamItemInfo. - * Ham prefix to avoid collision. :( + * Constants for usage with [Get|Set]HamItemInfo */ enum HamItemInfo { From 63cf35b9040d6fcb199665ecb4cd23c90e46fee0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 19:55:45 +0200 Subject: [PATCH 09/27] hlsdk_const: Fix up headings for proper display in api reference --- plugins/include/hlsdk_const.inc | 307 ++++++++++++++++++++++++-------- 1 file changed, 228 insertions(+), 79 deletions(-) diff --git a/plugins/include/hlsdk_const.inc b/plugins/include/hlsdk_const.inc index 0d96958f..70dc8013 100644 --- a/plugins/include/hlsdk_const.inc +++ b/plugins/include/hlsdk_const.inc @@ -11,7 +11,9 @@ #endif #define _hlsdk_const_included -// pev(entity, pev_button) or pev(entity, pev_oldbuttons) values +/** + * pev(entity, pev_button) or pev(entity, pev_oldbuttons) values + */ #define IN_ATTACK (1<<0) #define IN_JUMP (1<<1) #define IN_DUCK (1<<2) @@ -29,7 +31,9 @@ #define IN_ALT1 (1<<14) #define IN_SCORE (1<<15) // Used by client.dll for when scoreboard is held down -// pev(entity, pev_flags) values +/** + * pev(entity, pev_flags) values + */ #define FL_FLY (1<<0) // Changes the SV_Movestep() behavior to not need to be on ground #define FL_SWIM (1<<1) // Changes the SV_Movestep() behavior to not need to be on ground (but stay in water) #define FL_CONVEYOR (1<<2) @@ -61,12 +65,16 @@ #define FL_KILLME (1<<30) // This entity is marked for death -- This allows the engine to kill ents at the appropriate time #define FL_DORMANT (1<<31) // Entity is dormant, no updates to client -// engfunc(EngFunc_WalkMove, entity, Float:yaw, Float:dist, iMode) iMode values +/** + * engfunc(EngFunc_WalkMove, entity, Float:yaw, Float:dist, iMode) iMode values + */ #define WALKMOVE_NORMAL 0 // Normal walkmove #define WALKMOVE_WORLDONLY 1 // Doesn't hit ANY entities, no matter what the solid type #define WALKMOVE_CHECKONLY 2 // Move, but don't touch triggers -// pev(entity, pev_movetype) values +/** + * pev(entity, pev_movetype) values + */ #define MOVETYPE_NONE 0 // Never moves #define MOVETYPE_WALK 3 // Player only - moving on the ground #define MOVETYPE_STEP 4 // Gravity, special edge handling -- monsters use this @@ -80,28 +88,38 @@ #define MOVETYPE_FOLLOW 12 // Track movement of aiment #define MOVETYPE_PUSHSTEP 13 // BSP model that needs physics/world collisions (uses nearest hull for world collision) -// pev(entity, pev_solid) values -// NOTE: Some movetypes will cause collisions independent of SOLID_NOT/SOLID_TRIGGER when the entity moves -// SOLID only effects OTHER entities colliding with this one when they move - UGH! +/** + * pev(entity, pev_solid) values + * + * @note Some movetypes will cause collisions independent of SOLID_NOT and + * SOLID_TRIGGER when the entity moves. SOLID only effects OTHER entities + * colliding with this one when they move - UGH! + */ #define SOLID_NOT 0 // No interaction with other objects #define SOLID_TRIGGER 1 // Touch on edge, but not blocking #define SOLID_BBOX 2 // Touch on edge, block #define SOLID_SLIDEBOX 3 // Touch on edge, but not an onground #define SOLID_BSP 4 // BSP clip, touch on edge, block -// pev(entity, pev_deadflag) values +/** + * pev(entity, pev_deadflag) values + */ #define DEAD_NO 0 // Alive #define DEAD_DYING 1 // Playing death animation or still falling off of a ledge waiting to hit ground #define DEAD_DEAD 2 // Dead, lying still #define DEAD_RESPAWNABLE 3 #define DEAD_DISCARDBODY 4 -// new Float:takedamage, pev(entity, pev_takedamage, takedamage) values +/** + * new Float:takedamage, pev(entity, pev_takedamage, takedamage) values + */ #define DAMAGE_NO 0.0 #define DAMAGE_YES 1.0 #define DAMAGE_AIM 2.0 -// pev(entity, pev_effects) values +/** + * pev(entity, pev_effects) values + */ #define EF_BRIGHTFIELD 1 // Swirling cloud of particles #define EF_MUZZLEFLASH 2 // Single frame ELIGHT on entity attachment 0 #define EF_BRIGHTLIGHT 4 // DLIGHT centered at entity origin @@ -112,12 +130,12 @@ #define EF_NODRAW 128 // Don't draw entity /** -* Spectating camera mode constants -* -* Those constants are linked to differents camera mode available when you are spectating. -* (death or spectator team) -* They are usually stored in pev_iuser1 field in Counter-Strike and Half-Life games. -*/ + * Spectating camera mode constants + * + * @node These constants are linked to different camera modes available when you + * are spectating (either dead or when in spectator team). Usually this is + * stored in the pev_iuser1 field in Counter-Strike and Half-Life games. + */ #define OBS_NONE 0 #define OBS_CHASE_LOCKED 1 // Locked Chase Cam #define OBS_CHASE_FREE 2 // Free Chase Cam @@ -126,7 +144,9 @@ #define OBS_MAP_FREE 5 // Free Overview #define OBS_MAP_CHASE 6 // Chase Overview -// engfunc(EngFunc_PointContents, Float:origin) return values +/** + * engfunc(EngFunc_PointContents, Float:origin) return values + */ #define CONTENTS_EMPTY -1 #define CONTENTS_SOLID -2 #define CONTENTS_WATER -3 @@ -147,7 +167,10 @@ #define CONTENT_GRAVITY_FLYFIELD -18 #define CONTENT_FOG -19 -// Instant damage values for use with gmsgDamage 3rd value write_long(BIT) +/** + * Instant damage values for use with the 3rd parameter of the "Damage" client + * message. + */ #define DMG_GENERIC 0 // Generic damage was done #define DMG_CRUSH (1<<0) // Crushed by falling or moving object #define DMG_BULLET (1<<1) // Shot @@ -159,7 +182,7 @@ #define DMG_CLUB (1<<7) // Crowbar, punch, headbutt #define DMG_SHOCK (1<<8) // Electric shock #define DMG_SONIC (1<<9) // Sound pulse shockwave -#define DMG_ENERGYBEAM (1<<10) // Laser or other high energy beam +#define DMG_ENERGYBEAM (1<<10) // Laser or other high energy beam #define DMG_NEVERGIB (1<<12) // With this bit OR'd in, no damage type will be able to gib victims upon death #define DMG_ALWAYSGIB (1<<13) // With this bit OR'd in, any damage type can be made to gib victims upon death. #define DMG_DROWN (1<<14) // Drowning @@ -175,61 +198,93 @@ #define DMG_GRENADE (1<<24) // Counter-Strike only - Hit by HE grenade #define DMG_TIMEBASED (~(0x3fff)) // Mask for time-based damage -// The fNoMonsters parameter of EngFunc_TraceLine, EngFunc_TraceMonsterHull, EngFunc_TraceHull, and EngFunc_TraceSphere +/** + * Valid constants for fNoMonsters parameter of EngFunc_TraceLine, + * EngFunc_TraceMonsterHull, EngFunc_TraceHull and EngFunc_TraceSphere. + */ #define DONT_IGNORE_MONSTERS 0 #define IGNORE_MONSTERS 1 #define IGNORE_MISSILE 2 #define IGNORE_GLASS 0x100 -// The hullnumber paramater of EngFunc_TraceHull, EngFunc_TraceModel and DLLFunc_GetHullBounds +/** + * The hullnumber paramater of EngFunc_TraceHull, EngFunc_TraceModel and + * DLLFunc_GetHullBounds + */ #define HULL_POINT 0 #define HULL_HUMAN 1 #define HULL_LARGE 2 #define HULL_HEAD 3 -// global_get(glb_trace_flags) +/** + * global_get(glb_trace_flags) + */ #define FTRACE_SIMPLEBOX (1<<0) // Traceline with a simple box -// Used with get/set_es(es_handle, ES_eFlags, ...) (entity_state data structure) +/** + * Used with get/set_es(es_handle, ES_eFlags, ...) (entity_state data structure) + */ #define EFLAG_SLERP 1 // Do studio interpolation of this entity -// pev(entity, pev_spawnflags) values -// Many of these flags apply to specific entities -// func_train +/** + * @section pev(entity, pev_spawnflags) values + * @note Many of these flags apply to specific entities + */ +/** + * func_train + */ #define SF_TRAIN_WAIT_RETRIGGER 1 #define SF_TRAIN_START_ON 4 // Train is initially moving #define SF_TRAIN_PASSABLE 8 // Train is not solid -- used to make water trains -// func_wall_toggle +/** + * func_wall_toggle + */ #define SF_WALL_START_OFF 0x0001 -// func_converyor +/** + * func_converyor + */ #define SF_CONVEYOR_VISUAL 0x0001 #define SF_CONVEYOR_NOTSOLID 0x0002 -// func_button +/** + * func_button + */ #define SF_BUTTON_DONTMOVE 1 #define SF_BUTTON_TOGGLE 32 // Button stays pushed until reactivated #define SF_BUTTON_SPARK_IF_OFF 64 // Button sparks in OFF state #define SF_BUTTON_TOUCH_ONLY 256 // Button only fires as a result of USE key. -// func_rot_button +/** + * func_rot_button + */ #define SF_ROTBUTTON_NOTSOLID 1 -// env_global +/** + * env_global + */ #define SF_GLOBAL_SET 1 // Set global state to initial state on spawn -// multisource +/** + * multisource + */ #define SF_MULTI_INIT 1 -// momentary_rot_button +/** + * momentary_rot_button + */ #define SF_MOMENTARY_DOOR 0x0001 -// button_target +/** + * button_target + */ #define SF_BTARGET_USE 0x0001 #define SF_BTARGET_ON 0x0002 -// func_door, func_water, func_door_rotating, momementary_door +/** + * func_door, func_water, func_door_rotating, momementary_door + */ #define SF_DOOR_ROTATE_Y 0 #define SF_DOOR_START_OPEN 1 #define SF_DOOR_ROTATE_BACKWARDS 2 @@ -242,32 +297,46 @@ #define SF_DOOR_NOMONSTERS 512 // Monster can't open #define SF_DOOR_SILENT 0x80000000 -// gibshooter +/** + * gibshooter + */ #define SF_GIBSHOOTER_REPEATABLE 1 // Allows a gibshooter to be refired -// env_funnel +/** + * env_funnel + */ #define SF_FUNNEL_REVERSE 1 // Funnel effect repels particles instead of attracting them -// env_bubbles +/** + * env_bubbles + */ #define SF_BUBBLES_STARTOFF 0x0001 -// env_blood +/** + * env_blood + */ #define SF_BLOOD_RANDOM 0x0001 #define SF_BLOOD_STREAM 0x0002 #define SF_BLOOD_PLAYER 0x0004 #define SF_BLOOD_DECAL 0x0008 -// env_shake +/** + * env_shake + */ #define SF_SHAKE_EVERYONE 0x0001 // Don't check radius #define SF_SHAKE_DISRUPT 0x0002 // Disrupt controls #define SF_SHAKE_INAIR 0x0004 // Shake players in air -// env_fade +/** + * env_fade + */ #define SF_FADE_IN 0x0001 // Fade in, not out #define SF_FADE_MODULATE 0x0002 // Modulate, don't blend #define SF_FADE_ONLYONE 0x0004 -// env_beam, env_lightning +/** + * env_beam, env_lightning + */ #define SF_BEAM_STARTON 0x0001 #define SF_BEAM_TOGGLE 0x0002 #define SF_BEAM_RANDOM 0x0004 @@ -279,16 +348,22 @@ #define SF_BEAM_SHADEOUT 0x0100 #define SF_BEAM_TEMPORARY 0x8000 -// env_sprite +/** + * env_sprite + */ #define SF_SPRITE_STARTON 0x0001 #define SF_SPRITE_ONCE 0x0002 #define SF_SPRITE_TEMPORARY 0x8000 -// env_message +/** + * env_message + */ #define SF_MESSAGE_ONCE 0x0001 // Fade in, not out #define SF_MESSAGE_ALL 0x0002 // Send to all clients -// env_explosion +/** + * env_explosion + */ #define SF_ENVEXPLOSION_NODAMAGE (1<<0) // When set, ENV_EXPLOSION will not actually inflict damage #define SF_ENVEXPLOSION_REPEATABLE (1<<1) // Can this entity be refired? #define SF_ENVEXPLOSION_NOFIREBALL (1<<2) // Don't draw the fireball @@ -296,7 +371,9 @@ #define SF_ENVEXPLOSION_NODECAL (1<<4) // Don't make a scorch mark #define SF_ENVEXPLOSION_NOSPARKS (1<<5) // Don't make a scorch mark -// func_tank +/** + * func_tank + */ #define SF_TANK_ACTIVE 0x0001 #define SF_TANK_PLAYER 0x0002 #define SF_TANK_HUMANS 0x0004 @@ -305,43 +382,65 @@ #define SF_TANK_CANCONTROL 0x0020 #define SF_TANK_SOUNDON 0x8000 -// grenade +/** + * grenade + */ #define SF_DETONATE 0x0001 -// item_suit +/** + * item_suit + */ #define SF_SUIT_SHORTLOGON 0x0001 -// game_score +/** + * game_score + */ #define SF_SCORE_NEGATIVE 0x0001 #define SF_SCORE_TEAM 0x0002 -// game_text +/** + * game_text + */ #define SF_ENVTEXT_ALLPLAYERS 0x0001 -// game_team_master +/** + * game_team_master + */ #define SF_TEAMMASTER_FIREONCE 0x0001 #define SF_TEAMMASTER_ANYTEAM 0x0002 -// game_team_set +/** + * game_team_set + */ #define SF_TEAMSET_FIREONCE 0x0001 #define SF_TEAMSET_CLEARTEAM 0x0002 -// game_player_hurt +/** + * game_player_hurt + */ #define SF_PKILL_FIREONCE 0x0001 -// game_counter +/** + * game_counter + */ #define SF_GAMECOUNT_FIREONCE 0x0001 #define SF_GAMECOUNT_RESET 0x0002 -// game_player_equip +/** + * game_player_equip + */ #define SF_PLAYEREQUIP_USEONLY 0x0001 -// game_player_team +/** + * game_player_team + */ #define SF_PTEAM_FIREONCE 0x0001 #define SF_PTEAM_KILL 0x0002 #define SF_PTEAM_GIB 0x0004 -// func_trackchange +/** + * func_trackchange + */ #define SF_PLAT_TOGGLE 0x0001 #define SF_TRACK_ACTIVATETRAIN 0x00000001 #define SF_TRACK_RELINK 0x00000002 @@ -349,7 +448,9 @@ #define SF_TRACK_STARTBOTTOM 0x00000008 #define SF_TRACK_DONT_MOVE 0x00000010 -// func_tracktrain +/** + * func_tracktrain + */ #define SF_TRACKTRAIN_NOPITCH 0x0001 #define SF_TRACKTRAIN_NOCONTROL 0x0002 #define SF_TRACKTRAIN_FORWARDONLY 0x0004 @@ -363,44 +464,66 @@ #define SF_CORNER_TELEPORT 0x002 #define SF_CORNER_FIREONCE 0x004 -// trigger_push +/** + * trigger_push + */ #define SF_TRIGGER_PUSH_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF -// trigger_hurt +/** + * trigger_hurt + */ #define SF_TRIGGER_HURT_TARGETONCE 1 // Only fire hurt target once #define SF_TRIGGER_HURT_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF #define SF_TRIGGER_HURT_NO_CLIENTS 8 // Spawnflag that makes trigger_push spawn turned OFF #define SF_TRIGGER_HURT_CLIENTONLYFIRE 16 // Trigger hurt will only fire its target if it is hurting a client #define SF_TRIGGER_HURT_CLIENTONLYTOUCH 32 // Only clients may touch this trigger -// trigger_auto +/** + * trigger_auto + */ #define SF_AUTO_FIREONCE 0x0001 -// trigger_relay +/** + * trigger_relay + */ #define SF_RELAY_FIREONCE 0x0001 -// multi_manager +/** + * multi_manager + */ #define SF_MULTIMAN_CLONE 0x80000000 #define SF_MULTIMAN_THREAD 0x00000001 -// env_render - Flags to indicate masking off various render parameters that are normally copied to the targets +/** + * env_render + * @note These are flags to indicate masking off various render parameters that + * are usually copied to the targets + */ #define SF_RENDER_MASKFX (1<<0) #define SF_RENDER_MASKAMT (1<<1) #define SF_RENDER_MASKMODE (1<<2) #define SF_RENDER_MASKCOLOR (1<<3) -// trigger_changelevel +/** + * trigger_changelevel + */ #define SF_CHANGELEVEL_USEONLY 0x0002 -// trigger_endsection +/** + * trigger_endsection + */ #define SF_ENDSECTION_USEONLY 0x0001 -// trigger_camera +/** + * trigger_camera + */ #define SF_CAMERA_PLAYER_POSITION 1 #define SF_CAMERA_PLAYER_TARGET 2 #define SF_CAMERA_PLAYER_TAKECONTROL 4 -// func_rotating +/** + * func_rotating + */ #define SF_BRUSH_ROTATE_Y_AXIS 0 #define SF_BRUSH_ROTATE_INSTANT 1 #define SF_BRUSH_ROTATE_BACKWARDS 2 @@ -412,29 +535,40 @@ #define SF_BRUSH_ROTATE_MEDIUMRADIUS 256 #define SF_BRUSH_ROTATE_LARGERADIUS 512 -// triggers +/** + * triggers + */ #define SF_TRIGGER_ALLOWMONSTERS 1 // Monsters allowed to fire this trigger #define SF_TRIGGER_NOCLIENTS 2 // Players not allowed to fire this trigger #define SF_TRIGGER_PUSHABLES 4 // Only pushables can fire this trigger #define SF_TRIG_PUSH_ONCE 1 -// func_breakable + +/** + * func_breakable + */ #define SF_BREAK_TRIGGER_ONLY 1 // May only be broken by trigger #define SF_BREAK_TOUCH 2 // Can be 'crashed through' by running player (plate glass) #define SF_BREAK_PRESSURE 4 // Can be broken by a player standing on it #define SF_BREAK_CROWBAR 256 // Instant break if hit with crowbar -// func_pushable (it's also func_breakable, so don't collide with those flags) +/** + * func_pushable (also func_breakable, so don't collide with those flags) + */ #define SF_PUSH_BREAKABLE 128 -// light_spawn +/** + * light_spawn + */ #define SF_LIGHT_START_OFF 1 #define SPAWNFLAG_NOMESSAGE 1 #define SPAWNFLAG_NOTOUCH 1 #define SPAWNFLAG_DROIDONLY 4 #define SPAWNFLAG_USEONLY 1 // Can't be touched, must be used (buttons) -// Monster Spawnflags +/** + * Monster Spawnflags + */ #define SF_MONSTER_WAIT_TILL_SEEN 1 // Spawnflag that makes monsters wait until player can see them before attacking #define SF_MONSTER_GAG 2 // No idle noises from this monster #define SF_MONSTER_HITMONSTERCLIP 4 @@ -447,18 +581,30 @@ #define SF_MONSTER_TURRET_STARTINACTIVE 64 #define SF_MONSTER_WAIT_UNTIL_PROVOKED 64 // Don't attack the player unless provoked -// info_decal +/** + * info_decal + */ #define SF_DECAL_NOTINDEATHMATCH 2048 -// worldspawn +/** + * worldspawn + */ #define SF_WORLD_DARK 0x0001 // Fade from black at startup #define SF_WORLD_TITLE 0x0002 // Display game title at startup #define SF_WORLD_FORCETEAM 0x0004 // Force teams -// Set this bit on guns and stuff that should never respawn +/** + * Set this bit on guns and stuff that should never respawn + */ #define SF_NORESPAWN (1<<30) -// Valve Mod Weapon Constants +/** + * @endsection + */ + +/** + * Valve Mod Weapon Constants + */ #define HLI_HEALTHKIT 1 #define HLI_ANTIDOTE 2 #define HLI_SECURITY 3 @@ -485,7 +631,7 @@ #define FEV_NOTHOST (1<<0) // Skip local host for event send. -#define FEV_RELIABLE (1<<1) // Send the event reliably. You must specify the origin and angles +#define FEV_RELIABLE (1<<1) // Send the event reliably. You must specify the origin and angles // for this to work correctly on the server for anything // that depends on the event origin/angles. I.e., the origin/angles are not // taken from the invoking edict for reliable events. @@ -496,7 +642,10 @@ #define FEV_SERVER (1<<5) // Only send if the event was created on the server. #define FEV_CLIENT (1<<6) // Only issue event client side ( from shared code ) -// These are caps bits to indicate what an object's capabilities (currently used for save/restore and level transitions) +/** + * Cap bits to indicate what an object's capabilities are, currently used for + * save/restore and level transitions. + */ #define FCAP_CUSTOMSAVE 0x00000001 #define FCAP_ACROSS_TRANSITION 0x00000002 // should transfer between transitions #define FCAP_MUST_SPAWN 0x00000004 // Spawn after restore From 9e9e3a9abde9d70bdc39bf4eece1037c676890d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Mon, 4 Aug 2014 23:54:07 +0200 Subject: [PATCH 10/27] hlsdk_const: Fix up section heading to make docgen happy, purge tabs --- plugins/include/hlsdk_const.inc | 249 ++++++++++++++++---------------- 1 file changed, 124 insertions(+), 125 deletions(-) diff --git a/plugins/include/hlsdk_const.inc b/plugins/include/hlsdk_const.inc index 70dc8013..df9591a9 100644 --- a/plugins/include/hlsdk_const.inc +++ b/plugins/include/hlsdk_const.inc @@ -7,7 +7,7 @@ */ #if defined _hlsdk_const_included - #endinput + #endinput #endif #define _hlsdk_const_included @@ -34,25 +34,25 @@ /** * pev(entity, pev_flags) values */ -#define FL_FLY (1<<0) // Changes the SV_Movestep() behavior to not need to be on ground -#define FL_SWIM (1<<1) // Changes the SV_Movestep() behavior to not need to be on ground (but stay in water) -#define FL_CONVEYOR (1<<2) -#define FL_CLIENT (1<<3) -#define FL_INWATER (1<<4) -#define FL_MONSTER (1<<5) -#define FL_GODMODE (1<<6) -#define FL_NOTARGET (1<<7) -#define FL_SKIPLOCALHOST (1<<8) // Don't send entity to local host, it's predicting this entity itself -#define FL_ONGROUND (1<<9) // At rest / on the ground -#define FL_PARTIALGROUND (1<<10) // Not all corners are valid -#define FL_WATERJUMP (1<<11) // Player jumping out of water +#define FL_FLY (1<<0) // Changes the SV_Movestep() behavior to not need to be on ground +#define FL_SWIM (1<<1) // Changes the SV_Movestep() behavior to not need to be on ground (but stay in water) +#define FL_CONVEYOR (1<<2) +#define FL_CLIENT (1<<3) +#define FL_INWATER (1<<4) +#define FL_MONSTER (1<<5) +#define FL_GODMODE (1<<6) +#define FL_NOTARGET (1<<7) +#define FL_SKIPLOCALHOST (1<<8) // Don't send entity to local host, it's predicting this entity itself +#define FL_ONGROUND (1<<9) // At rest / on the ground +#define FL_PARTIALGROUND (1<<10) // Not all corners are valid +#define FL_WATERJUMP (1<<11) // Player jumping out of water #define FL_FROZEN (1<<12) // Player is frozen for 3rd person camera #define FL_FAKECLIENT (1<<13) // JAC: fake client, simulated server side; don't send network messages to them #define FL_DUCKING (1<<14) // Player flag -- Player is fully crouched #define FL_FLOAT (1<<15) // Apply floating force to this entity when in water #define FL_GRAPHED (1<<16) // Worldgraph has this ent listed as something that blocks a connection #define FL_IMMUNE_WATER (1<<17) -#define FL_IMMUNE_SLIME (1<<18) +#define FL_IMMUNE_SLIME (1<<18) #define FL_IMMUNE_LAVA (1<<19) #define FL_PROXY (1<<20) // This is a spectator proxy #define FL_ALWAYSTHINK (1<<21) // Brush model flag -- call think every frame regardless of nextthink - ltime (for constantly changing velocity/path) @@ -68,62 +68,62 @@ /** * engfunc(EngFunc_WalkMove, entity, Float:yaw, Float:dist, iMode) iMode values */ -#define WALKMOVE_NORMAL 0 // Normal walkmove +#define WALKMOVE_NORMAL 0 // Normal walkmove #define WALKMOVE_WORLDONLY 1 // Doesn't hit ANY entities, no matter what the solid type #define WALKMOVE_CHECKONLY 2 // Move, but don't touch triggers /** * pev(entity, pev_movetype) values */ -#define MOVETYPE_NONE 0 // Never moves -#define MOVETYPE_WALK 3 // Player only - moving on the ground -#define MOVETYPE_STEP 4 // Gravity, special edge handling -- monsters use this -#define MOVETYPE_FLY 5 // No gravity, but still collides with stuff -#define MOVETYPE_TOSS 6 // Gravity/Collisions -#define MOVETYPE_PUSH 7 // No clip to world, push and crush -#define MOVETYPE_NOCLIP 8 // No gravity, no collisions, still do velocity/avelocity -#define MOVETYPE_FLYMISSILE 9 // Extra size to monsters -#define MOVETYPE_BOUNCE 10 // Just like Toss, but reflect velocity when contacting surfaces +#define MOVETYPE_NONE 0 // Never moves +#define MOVETYPE_WALK 3 // Player only - moving on the ground +#define MOVETYPE_STEP 4 // Gravity, special edge handling -- monsters use this +#define MOVETYPE_FLY 5 // No gravity, but still collides with stuff +#define MOVETYPE_TOSS 6 // Gravity/Collisions +#define MOVETYPE_PUSH 7 // No clip to world, push and crush +#define MOVETYPE_NOCLIP 8 // No gravity, no collisions, still do velocity/avelocity +#define MOVETYPE_FLYMISSILE 9 // Extra size to monsters +#define MOVETYPE_BOUNCE 10 // Just like Toss, but reflect velocity when contacting surfaces #define MOVETYPE_BOUNCEMISSILE 11 // Bounce w/o gravity #define MOVETYPE_FOLLOW 12 // Track movement of aiment -#define MOVETYPE_PUSHSTEP 13 // BSP model that needs physics/world collisions (uses nearest hull for world collision) +#define MOVETYPE_PUSHSTEP 13 // BSP model that needs physics/world collisions (uses nearest hull for world collision) /** * pev(entity, pev_solid) values * * @note Some movetypes will cause collisions independent of SOLID_NOT and - * SOLID_TRIGGER when the entity moves. SOLID only effects OTHER entities - * colliding with this one when they move - UGH! + * SOLID_TRIGGER when the entity moves. SOLID only effects OTHER entities + * colliding with this one when they move - UGH! */ -#define SOLID_NOT 0 // No interaction with other objects -#define SOLID_TRIGGER 1 // Touch on edge, but not blocking -#define SOLID_BBOX 2 // Touch on edge, block -#define SOLID_SLIDEBOX 3 // Touch on edge, but not an onground -#define SOLID_BSP 4 // BSP clip, touch on edge, block +#define SOLID_NOT 0 // No interaction with other objects +#define SOLID_TRIGGER 1 // Touch on edge, but not blocking +#define SOLID_BBOX 2 // Touch on edge, block +#define SOLID_SLIDEBOX 3 // Touch on edge, but not an onground +#define SOLID_BSP 4 // BSP clip, touch on edge, block /** * pev(entity, pev_deadflag) values */ -#define DEAD_NO 0 // Alive -#define DEAD_DYING 1 // Playing death animation or still falling off of a ledge waiting to hit ground -#define DEAD_DEAD 2 // Dead, lying still +#define DEAD_NO 0 // Alive +#define DEAD_DYING 1 // Playing death animation or still falling off of a ledge waiting to hit ground +#define DEAD_DEAD 2 // Dead, lying still #define DEAD_RESPAWNABLE 3 #define DEAD_DISCARDBODY 4 /** * new Float:takedamage, pev(entity, pev_takedamage, takedamage) values */ -#define DAMAGE_NO 0.0 -#define DAMAGE_YES 1.0 -#define DAMAGE_AIM 2.0 +#define DAMAGE_NO 0.0 +#define DAMAGE_YES 1.0 +#define DAMAGE_AIM 2.0 /** * pev(entity, pev_effects) values */ -#define EF_BRIGHTFIELD 1 // Swirling cloud of particles -#define EF_MUZZLEFLASH 2 // Single frame ELIGHT on entity attachment 0 -#define EF_BRIGHTLIGHT 4 // DLIGHT centered at entity origin -#define EF_DIMLIGHT 8 // Player flashlight +#define EF_BRIGHTFIELD 1 // Swirling cloud of particles +#define EF_MUZZLEFLASH 2 // Single frame ELIGHT on entity attachment 0 +#define EF_BRIGHTLIGHT 4 // DLIGHT centered at entity origin +#define EF_DIMLIGHT 8 // Player flashlight #define EF_INVLIGHT 16 // Get lighting from ceiling #define EF_NOINTERP 32 // Don't interpolate the next frame #define EF_LIGHT 64 // Rocket flare glow sprite @@ -132,9 +132,9 @@ /** * Spectating camera mode constants * - * @node These constants are linked to different camera modes available when you - * are spectating (either dead or when in spectator team). Usually this is - * stored in the pev_iuser1 field in Counter-Strike and Half-Life games. + * @note These constants are linked to different camera modes available when you + * are spectating (either dead or when in spectator team). Usually this is + * stored in the pev_iuser1 field in Counter-Strike and Half-Life games. */ #define OBS_NONE 0 #define OBS_CHASE_LOCKED 1 // Locked Chase Cam @@ -147,25 +147,25 @@ /** * engfunc(EngFunc_PointContents, Float:origin) return values */ -#define CONTENTS_EMPTY -1 -#define CONTENTS_SOLID -2 -#define CONTENTS_WATER -3 -#define CONTENTS_SLIME -4 -#define CONTENTS_LAVA -5 -#define CONTENTS_SKY -6 -#define CONTENTS_ORIGIN -7 // Removed at csg time -#define CONTENTS_CLIP -8 // Changed to contents_solid -#define CONTENTS_CURRENT_0 -9 -#define CONTENTS_CURRENT_90 -10 -#define CONTENTS_CURRENT_180 -11 -#define CONTENTS_CURRENT_270 -12 -#define CONTENTS_CURRENT_UP -13 -#define CONTENTS_CURRENT_DOWN -14 +#define CONTENTS_EMPTY -1 +#define CONTENTS_SOLID -2 +#define CONTENTS_WATER -3 +#define CONTENTS_SLIME -4 +#define CONTENTS_LAVA -5 +#define CONTENTS_SKY -6 +#define CONTENTS_ORIGIN -7 // Removed at csg time +#define CONTENTS_CLIP -8 // Changed to contents_solid +#define CONTENTS_CURRENT_0 -9 +#define CONTENTS_CURRENT_90 -10 +#define CONTENTS_CURRENT_180 -11 +#define CONTENTS_CURRENT_270 -12 +#define CONTENTS_CURRENT_UP -13 +#define CONTENTS_CURRENT_DOWN -14 #define CONTENTS_TRANSLUCENT -15 -#define CONTENTS_LADDER -16 -#define CONTENT_FLYFIELD -17 -#define CONTENT_GRAVITY_FLYFIELD -18 -#define CONTENT_FOG -19 +#define CONTENTS_LADDER -16 +#define CONTENT_FLYFIELD -17 +#define CONTENT_GRAVITY_FLYFIELD -18 +#define CONTENT_FOG -19 /** * Instant damage values for use with the 3rd parameter of the "Damage" client @@ -228,12 +228,11 @@ /** * @section pev(entity, pev_spawnflags) values - * @note Many of these flags apply to specific entities */ /** * func_train */ -#define SF_TRAIN_WAIT_RETRIGGER 1 +#define SF_TRAIN_WAIT_RETRIGGER 1 #define SF_TRAIN_START_ON 4 // Train is initially moving #define SF_TRAIN_PASSABLE 8 // Train is not solid -- used to make water trains @@ -252,8 +251,8 @@ * func_button */ #define SF_BUTTON_DONTMOVE 1 -#define SF_BUTTON_TOGGLE 32 // Button stays pushed until reactivated -#define SF_BUTTON_SPARK_IF_OFF 64 // Button sparks in OFF state +#define SF_BUTTON_TOGGLE 32 // Button stays pushed until reactivated +#define SF_BUTTON_SPARK_IF_OFF 64 // Button sparks in OFF state #define SF_BUTTON_TOUCH_ONLY 256 // Button only fires as a result of USE key. /** @@ -286,11 +285,11 @@ * func_door, func_water, func_door_rotating, momementary_door */ #define SF_DOOR_ROTATE_Y 0 -#define SF_DOOR_START_OPEN 1 +#define SF_DOOR_START_OPEN 1 #define SF_DOOR_ROTATE_BACKWARDS 2 #define SF_DOOR_PASSABLE 8 #define SF_DOOR_ONEWAY 16 -#define SF_DOOR_NO_AUTO_RETURN 32 +#define SF_DOOR_NO_AUTO_RETURN 32 #define SF_DOOR_ROTATE_Z 64 #define SF_DOOR_ROTATE_X 128 #define SF_DOOR_USE_ONLY 256 // Door must be opened by player's use button @@ -300,7 +299,7 @@ /** * gibshooter */ -#define SF_GIBSHOOTER_REPEATABLE 1 // Allows a gibshooter to be refired +#define SF_GIBSHOOTER_REPEATABLE 1 // Allows a gibshooter to be refired /** * env_funnel @@ -364,8 +363,8 @@ /** * env_explosion */ -#define SF_ENVEXPLOSION_NODAMAGE (1<<0) // When set, ENV_EXPLOSION will not actually inflict damage -#define SF_ENVEXPLOSION_REPEATABLE (1<<1) // Can this entity be refired? +#define SF_ENVEXPLOSION_NODAMAGE (1<<0) // When set, ENV_EXPLOSION will not actually inflict damage +#define SF_ENVEXPLOSION_REPEATABLE (1<<1) // Can this entity be refired? #define SF_ENVEXPLOSION_NOFIREBALL (1<<2) // Don't draw the fireball #define SF_ENVEXPLOSION_NOSMOKE (1<<3) // Don't draw the smoke #define SF_ENVEXPLOSION_NODECAL (1<<4) // Don't make a scorch mark @@ -467,15 +466,15 @@ /** * trigger_push */ -#define SF_TRIGGER_PUSH_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF +#define SF_TRIGGER_PUSH_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF /** * trigger_hurt */ #define SF_TRIGGER_HURT_TARGETONCE 1 // Only fire hurt target once -#define SF_TRIGGER_HURT_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF -#define SF_TRIGGER_HURT_NO_CLIENTS 8 // Spawnflag that makes trigger_push spawn turned OFF -#define SF_TRIGGER_HURT_CLIENTONLYFIRE 16 // Trigger hurt will only fire its target if it is hurting a client +#define SF_TRIGGER_HURT_START_OFF 2 // Spawnflag that makes trigger_push spawn turned OFF +#define SF_TRIGGER_HURT_NO_CLIENTS 8 // Spawnflag that makes trigger_push spawn turned OFF +#define SF_TRIGGER_HURT_CLIENTONLYFIRE 16 // Trigger hurt will only fire its target if it is hurting a client #define SF_TRIGGER_HURT_CLIENTONLYTOUCH 32 // Only clients may touch this trigger /** @@ -530,7 +529,7 @@ #define SF_BRUSH_ROTATE_Z_AXIS 4 #define SF_BRUSH_ROTATE_X_AXIS 8 #define SF_PENDULUM_AUTO_RETURN 16 -#define SF_PENDULUM_PASSABLE 32 +#define SF_PENDULUM_PASSABLE 32 #define SF_BRUSH_ROTATE_SMALLRADIUS 128 #define SF_BRUSH_ROTATE_MEDIUMRADIUS 256 #define SF_BRUSH_ROTATE_LARGERADIUS 512 @@ -538,8 +537,8 @@ /** * triggers */ -#define SF_TRIGGER_ALLOWMONSTERS 1 // Monsters allowed to fire this trigger -#define SF_TRIGGER_NOCLIENTS 2 // Players not allowed to fire this trigger +#define SF_TRIGGER_ALLOWMONSTERS 1 // Monsters allowed to fire this trigger +#define SF_TRIGGER_NOCLIENTS 2 // Players not allowed to fire this trigger #define SF_TRIGGER_PUSHABLES 4 // Only pushables can fire this trigger #define SF_TRIG_PUSH_ONCE 1 @@ -548,7 +547,7 @@ * func_breakable */ #define SF_BREAK_TRIGGER_ONLY 1 // May only be broken by trigger -#define SF_BREAK_TOUCH 2 // Can be 'crashed through' by running player (plate glass) +#define SF_BREAK_TOUCH 2 // Can be 'crashed through' by running player (plate glass) #define SF_BREAK_PRESSURE 4 // Can be broken by a player standing on it #define SF_BREAK_CROWBAR 256 // Instant break if hit with crowbar @@ -569,11 +568,11 @@ /** * Monster Spawnflags */ -#define SF_MONSTER_WAIT_TILL_SEEN 1 // Spawnflag that makes monsters wait until player can see them before attacking -#define SF_MONSTER_GAG 2 // No idle noises from this monster +#define SF_MONSTER_WAIT_TILL_SEEN 1 // Spawnflag that makes monsters wait until player can see them before attacking +#define SF_MONSTER_GAG 2 // No idle noises from this monster #define SF_MONSTER_HITMONSTERCLIP 4 #define SF_MONSTER_PRISONER 16 // Monster won't attack anyone, no one will attacke him -#define SF_MONSTER_WAIT_FOR_SCRIPT 128 // Spawnflag that makes monsters wait to check for attacking until the script is done or they've been attacked +#define SF_MONSTER_WAIT_FOR_SCRIPT 128 // Spawnflag that makes monsters wait to check for attacking until the script is done or they've been attacked #define SF_MONSTER_PREDISASTER 256 // This is a predisaster scientist or barney; influences how they speak #define SF_MONSTER_FADECORPSE 512 // Fade out corpse after death #define SF_MONSTER_FALL_TO_GROUND 0x80000000 @@ -605,53 +604,53 @@ /** * Valve Mod Weapon Constants */ -#define HLI_HEALTHKIT 1 -#define HLI_ANTIDOTE 2 -#define HLI_SECURITY 3 -#define HLI_BATTERY 4 +#define HLI_HEALTHKIT 1 +#define HLI_ANTIDOTE 2 +#define HLI_SECURITY 3 +#define HLI_BATTERY 4 -#define HLW_NONE 0 -#define HLW_CROWBAR 1 -#define HLW_GLOCK 2 -#define HLW_PYTHON 3 -#define HLW_MP5 4 -#define HLW_CHAINGUN 5 -#define HLW_CROSSBOW 6 -#define HLW_SHOTGUN 7 -#define HLW_RPG 8 -#define HLW_GAUSS 9 -#define HLW_EGON 10 -#define HLW_HORNETGUN 11 -#define HLW_HANDGRENADE 12 -#define HLW_TRIPMINE 13 -#define HLW_SATCHEL 14 -#define HLW_SNARK 15 -#define HLW_SUIT 31 -#define HLW_ALLWEAPONS (~(1< Date: Tue, 5 Aug 2014 01:39:16 +0200 Subject: [PATCH 11/27] amxmodx: Fourth batch of documentation updates --- plugins/include/amxmodx.inc | 533 ++++++++++++++++++++++++++++-------- 1 file changed, 426 insertions(+), 107 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 087b0fd9..2848783e 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -573,7 +573,6 @@ native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, e */ native show_dhudmessage(index, const message[], any:...); -/* Displays menu. Keys have bit values (key 1 is (1<<0), key 5 is (1<<4) etc.). */ /** * Displays a menu to the client. * @@ -595,7 +594,7 @@ native show_dhudmessage(index, const message[], any:...); * @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[] = ""); +native show_menu(index, keys, const menu[], time = -1, const title[] = ""); /** * Retrieves values from a client message. @@ -930,16 +929,48 @@ native get_user_index(const name[]); */ native get_user_ip(index, ip[], len, without_port = 0); -/* Returns if the player has the weapon or not in their pev->weapons field. - set "setweapon" to 0 to turn the bit off, set to 1 to turn it on. */ -native user_has_weapon(index,weapon,setweapon=-1); +/** + * 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 id of currently carried weapon. Gets also -* ammount of ammo in clip and backpack. */ -native get_user_weapon(index,&clip=0,&ammo=0); +/** + * 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); -/* Gets ammo and clip from current weapon. */ -native get_user_ammo(index,weapon,&clip,&ammo); +/** + * 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. @@ -1028,7 +1059,7 @@ native get_user_origin(index, origin[3], mode = 0); * @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); +native get_user_weapons(index, weapons[32], &num); /** * Retrieves the full name of a weapon. @@ -1088,7 +1119,7 @@ native get_user_userid(index); * @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); +native user_slap(index, power, rnddir=1); /** * Kills a client. @@ -1099,7 +1130,7 @@ native user_slap(index,power,rnddir=1); * @return 1 on success, 0 if client index is invalid or the client * is not connected. */ -native user_kill(index,flag=0); +native user_kill(index, flag=0); /** * Logs a message to the current AMXX log file. @@ -1167,7 +1198,7 @@ native get_playersnum(flag=0); * * @noreturn */ -native get_players(players[32], &num ,const flags[]="", const team[]=""); +native get_players(players[32], &num, const flags[]="", const team[]=""); /** * Retrieves argument of client command. @@ -1192,7 +1223,7 @@ native read_argv(id, output[], len); * * @return Number of cells written to buffer */ -native read_args(output[],len); +native read_args(output[], len); /** * Returns number of client command arguments. @@ -1228,7 +1259,7 @@ native read_flags(const flags[]); * * @return Number of cells written to buffer */ -native get_flags(flags,output[],len); +native get_flags(flags, output[], len); /** * Find a player given a filter. @@ -1261,8 +1292,8 @@ native find_player(const flags[], ... ); * 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 - * all ^r (carriage return) characters at the end of the string, even if - * no matching double-quote is found. + * 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 * @@ -1308,7 +1339,7 @@ native client_cmd(index, const command[], any:...); * @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[]=""); +native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); /** * Execute a command from the client without actually sending it to the client's @@ -1352,7 +1383,7 @@ native server_cmd(const command[],any:...); * @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_* set of functions. + * 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 @@ -1371,11 +1402,12 @@ native set_cvar_string(const cvar[], const value[]); native cvar_exists(const cvar[]); /** - * Removes specified flags from a cvar + * Removes specified flags from a cvar. The cvar is accessed by name. * - * @note Not permitted for the "amx_version", "fun_version" and "sv_cheats" - * cvars. + * @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 @@ -1390,12 +1422,12 @@ native cvar_exists(const cvar[]); native remove_cvar_flags(const cvar[], flags = -1); /** - * Sets specified flags to a cvar + * Sets specified flags to a cvar. The cvar is accessed by name. * - * @note Not permitted for the "amx_version", "fun_version" and "sv_cheats" - * cvars. + * @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-and operation. After + * @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 @@ -1410,20 +1442,15 @@ native remove_cvar_flags(const cvar[], flags = -1); native set_cvar_flags(const cvar[], flags); /** - * Returns flags of a cvar + * Returns flags of a cvar. The cvar is accessed by name. * - * @note Not permitted for the "amx_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-and 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 get_pcvar_flags function. * - * @param cvar Cvar name to remove flags from - * @param flags Bitflag sum of flags to set + * @param cvar Cvar name to retrieve flags from * * @return 1 on success, 0 if cvar does not exist or is not permitted */ @@ -1435,7 +1462,7 @@ native get_cvar_flags(const cvar[]); * @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_* set of functions. + * 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 @@ -1445,28 +1472,28 @@ native get_cvar_flags(const cvar[]); native set_cvar_float(const cvar[], Float:value); /** - * Gets a floating value from a cvar. The cvar is accessed by name. + * 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_* set of functions. + * a vastly superior alternative look at the get_pcvar_float function. * - * @param cvarname Cvar name to get value from + * @param cvarname Cvar name to retrieve value from * * @return Cvar value, converted to float */ native Float:get_cvar_float(const cvarname[]); /** - * Gets an integer value from a cvar. The cvar is accessed by name. + * 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_* set of functions. + * a vastly superior alternative look at the get_pcvar_num function. * - * @param cvarname Cvar name to get value from + * @param cvarname Cvar name to retrieve value from * * @return Cvar value, converted to int */ @@ -1478,7 +1505,7 @@ native get_cvar_num(const cvarname[]); * @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_* set of functions. + * 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 @@ -1493,77 +1520,237 @@ native set_cvar_num(const cvarname[], value); * @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_* set of functions. + * a vastly superior alternative look at the get_pcvar_string function. * - * @param cvar cvar name to get value from + * @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); +native get_cvar_string(const cvarname[], output[], iLen); -/* Returns a name of currently played map. */ -native get_mapname(name[],len); +/** + * 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 in seconds. */ +/** + * Returns time remaining on map. + * + * @return Time left on map, in seconds + */ native get_timeleft(); -/* Returns a game time. */ +/** + * 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 maxplayers setting. */ +/** + * 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(); -/* Returns a name of currently played mod. */ -native get_modname(name[],len); +/** + * 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); -/* Returns time in given format. The most popular is: "%m/%d/%Y - %H:%M:%S". */ -native get_time(const format[],output[],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); -/* Returns time in given format. The most popular is: "%m/%d/%Y - %H:%M:%S". -* Last parameter sets time to format. */ -native format_time(output[],len, const format[],time = -1); +/** + * 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 system time in seconds elapsed since 00:00:00 on January 1, 1970. -* Offset is given in seconds.*/ +/** + * 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); -/* Returns time in input and additionaly fills missing information -* with current time and date. If time is different than -1 then parsed -* time is added to given time. -* Example: -* parset_time( "10:32:54 04/02/2003", "%H:%M:%S %m:%d:%Y" ) -* For more information see strptime(...) function from C libraries. */ -native parse_time(const input[],const format[], time = -1); +/** + * 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 function on specified time. -* Flags: -* "a" - repeat. -* "b" - loop task. -* "c" - do task on time after a map timeleft. -* "d" - do task on time before a map timelimit. */ -native set_task(Float:time,const function[],id = 0,const parameter[]="",len = 0,const flags[]="", repeat = 0); +/** + * 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 given id. If outside var is -* set then a task can be removed also when -* was set in another plugin. */ +/** + * 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); -/* Changes the time of a task */ +/** + * 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 1 if task under given id exists. */ +/** + * 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 users flags with the assignment by bitwise OR operator. */ -native set_user_flags(index,flags=-1,id=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); -/* Gets flags from player. Set index to 0 if you want to read flags from server. */ +/** + * 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 flags for player. */ -native remove_user_flags(index,flags=-1,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 @@ -1714,14 +1901,32 @@ native get_modulesnum(); */ native is_plugin_loaded(const name[], bool:usefilename=false); -/* Gets info about plugin by given index. - * Function returns -1 if plugin doesn't exist with given index. - * Note: the [...] portion should not be used, and is only for backward compatibility. - * Use index of -1 to use the calling plugin's ID. +/** + * 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 number of all loaded plugins. */ +/** + * Returns the number of loaded AMXX plugins. + * + * @return The number of loaded plugins + */ native get_pluginsnum(); /* Pauses function or plugin so it won't be executed. @@ -2213,28 +2418,118 @@ native ExecuteForward(forward_handle, &ret, any:...); */ native DestroyForward(forward_handle); - -/* CVAR Pointer natives. Use these for - * more optimized CVAR usage. - * register_cvar() returns a pointer you can use. - */ - /** - * Get a cvar pointer. Returns 0 if not found. + * 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 a whole array to a certain value. + * 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); @@ -2245,36 +2540,60 @@ native arrayset(array[], value, size); native get_weaponid(const name[]); /** - * Adds an admin to the dynamic admin storage - * for lookup at a later time + * 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); /** - * Gets the number of admins in the dynamic admin - * storage list + * Returns the number of admins in the dynamic admin storage + * + * @return Number of admins */ native admins_num(); /** - * Gets information about a dynamically stored admin - * Use the enum AdminProp - * Returns an integer value: AdminProp_Access, AdminProp_Flags - * Sets the buffer string: AdminProp_Auth, AdminProp_Password + * 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(); /** - * Searches whether a map contains at least one entity with the provided class name. + * Returns if a map contains at least one entity with the provided class name. * - * @param classname The entity classname to check. + * @param classname Entity classname to match * - * @return Returns true if an entity is found, otherwise false. + * @return True if an entity is found, false otherwise */ native bool:has_map_ent_class(const classname[]); From 566596f7b49fd7dfe17600301aebf164ca28843c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 5 Aug 2014 16:05:19 +0200 Subject: [PATCH 12/27] cellarray: Touch up documentation to make the parser happy and make it consistent --- plugins/include/cellarray.inc | 485 +++++++++++++++++++--------------- 1 file changed, 272 insertions(+), 213 deletions(-) diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc index 53466aab..226d87da 100644 --- a/plugins/include/cellarray.inc +++ b/plugins/include/cellarray.inc @@ -5,23 +5,28 @@ #define _cellarray_included /** - * These arrays are intended to be used for a form of global storage without - * requiring a #define that needs to be increased each time a person needs more - * storage. - * These are not designed to be used as a replacement for normal arrays, as - * normal arrays are faster and should be used whenever possible. + * Cellarray tag declaration + * + * @note These dynamic arrays are intended to be used for a form of global + * storage without requiring a #define that needs to be increased each + * time the plugin author requires more storage. These are not designed + * to be a full replacement for normal arrays, as those are faster and + * should be used whenever possible. + * @note Plugins are responsible for freeing all Array handles they acquire, + * including those from ArrayClone. Failing to free handles will result + * in the plugin and AMXX leaking memory. */ - enum Array { Invalid_Array = 0 }; - /** - * Given a maximum string size (including the null terminator), - * returns the number of cells required to fit that string. +/** + * Returns the number of cells required to fit a string of the specified size + * (including the null terminator). * * @param size Number of bytes. + * * @return Minimum number of cells required to fit the byte count. */ stock ByteCountToCells(size) @@ -30,368 +35,419 @@ stock ByteCountToCells(size) { return 1; } - + return (size + 3) / 4; } /** * Creates a handle to a dynamically sized array. - * It is very important that the cellsize you provide matches up with the buffer sizes - * that you pass with subsequent Array{Get,Set,Push} calls. * - * @param cellsize How many cells each entry in the array is. - * @param reserved How many blank entries are created immediately when the array is created. - * These entries are not valid to read from until called with ArraySet. + * @note It is very important that the provided cellsize matches up with the + * buffer sizes that you pass with subsequent Array[Get|Set|Push] calls. + * + * @param cellsize Size of each array entry in cells + * @param reserver Amount of blank entries that are inserted immediately + * upon creation of the array. These are not readable until + * initialized with an ArraySet* function. * * @return Handle to the array. */ native Array:ArrayCreate(cellsize = 1, reserved = 0); /** - * Clones an array, returning a new handle with the same size and data. - * You must close it. + * Clones an array, returning a new handle with the same size and data. * - * @param which Array handle to be cloned. + * @param which Array handle * - * @return New handle to the cloned array object on success, 0 on failure. - * @error Invalid handle. + * @return Handle to the cloned array on success, 0 otherwise + * @error If an invalid handle is provided an error will be thrown */ native Array:ArrayClone(Array:which); /** * Clears all entries from the array. * - * @param which The array to clear. + * @param which Array handle * * @noreturn - * @error Invalid handle. + * @error Invalid handle */ native ArrayClear(Array:which); /** * Returns the number of elements in the array. * - * @param which The array to check. + * @param which Array handle * - * @return How many elements are in the array. - * @error Invalid handle. + * @return Number of elements in the array + * @error If an invalid handle is provided an error will be thrown */ native ArraySize(Array:which); /** - * Resizes an array. If the size is smaller than the current size, - * the array is truncated. + * Resizes an array. * - * @param which Array handle. - * @param newsize New size. + * @note If the size is smaller than the current array size the array is + * truncated and data lost. + * + * @param which Array handle + * @param newsize New size * * @noreturn - * @error Invalid handle or out of memory. + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown */ native bool:ArrayResize(Array:which, newsize); /** - * Returns data within an array. - * Make sure the output buffer matches the size the array was created with! + * Retrieves an array of data from a cellarray. * - * @param which The array to retrieve the item from. - * @param item The item to retrieve (zero-based). - * @param output The output buffer to write. + * @note If the size parameter is specified as -1 the output buffer has to match + * the size the array was created with. + * + * @param which Array handle + * @param item Item index in the array + * @param output Buffer to copy value to * @param size If not set, assumes the buffer size is equal to the - * cellsize. Otherwise, the size passed is used. + * cellsize. Otherwise, the specified size is used. * - * @return Number of cells copied. - * @error Invalid handle or invalid index. + * @return Number of cells copied + * @error If an invalid handle or index is provided an error will + * be thrown. */ native ArrayGetArray(Array:which, item, any:output[], size = -1); /** - * Returns a single cell of data from an array. + * Returns a single cell of data from an array * - * @param which The array to retrieve the item from. - * @param item The item to retrieve (zero-based). - * @param block Optionally specify which block to read from - * (useful if the blocksize > 0). - * @param asChar Optionally read as a byte instead of a cell. + * @param which Array handle + * @param item Item index in the array + * @param block If the array has a cellsize >1 this optionally specifies + * which block to read from + * @param asChar If true reads the value as a byte instead of a cell * - * @return Value read. - * @error Invalid handle, invalid index, or invalid block. + * @return Integer value + * @error If an invalid handle, index or block is provided an + * error will be thrown */ native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false); /** - * Returns a string value from an array. + * Returieves string data from an array. * - * @param which The array to retrieve the item from. - * @param item The item to retrieve (zero-based). - * @param output The variable to store the value in. - * @param size Character size of the output buffer. + * @param which Array handle + * @param item Item index in the array + * @param output Buffer to copy value to + * @param size Maximum size of the buffer * - * @return Number of characters copied. - * @error Invalid handle or invalid index. + * @return Number of characters copied + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayGetString(Array:which, item, output[], size); /** - * Sets an item's data with that of a local buffer. - * The buffer size must match what the cellsize that the array was created with! - * The item must already exist, use ArrayPushArray to create a new item within the array. + * Fills an item's data with the contents of an array. * - * @param which The array to set the item from within. - * @param item The item to set (zero-based). - * @param input The input buffer to store. + * @note If the size parameter is specified as -1 the input buffer has to match + * the size the array was created with. + * @note The item index must already be valid. Use ArrayPushArray to create + * a new array item in the cellarray. + * + * @param which Array handle + * @param item Item index in the array + * @param input Array to copy to the cellarray * @param size If not set, assumes the buffer size is equal to the - * blocksize. Otherwise, the size passed is used. + * cellsize. Otherwise, the specified size is used. * - * @return Number of cells copied. - * @error Invalid handle or invalid index. + * @return Number of cells copied + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArraySetArray(Array:which, item, const any:input[], size =-1); /** - * Sets an array's single cell value. Use this only on array that were created with a cellsize of 1! - * The item must already exist, use ArrayPushCell to create a new item within the array. + * Sets an item's data to a single cell value. * - * @param which The array to set the item from within. - * @param item The item to set (zero-based). - * @param input The value to set. - * @param block Optionally specify which block to write to - * (useful if the blocksize > 0). - * @param asChar Optionally set as a byte instead of a cell. + * @note The item index must already be valid. Use ArrayPushArray to create + * a new array item in the cellarray. + * + * @param which Array handle + * @param item Item index in the array + * @param input Value to set + * @param block If the array has a cellsize >1 this optionally specifies + * which block to write to + * @param asChar If true writes the value as a byte instead of a cell * * @noreturn - * @error Invalid handle, invalid index, or invalid block. + * @error If an invalid handle, index or block is provided an + * error will be thrown */ native ArraySetCell(Array:which, item, any:input, block = 0, bool:asChar = false); /** - * Sets a string value from an array. - * The stored string will be truncated if it is longer than the cellsize the array was created with! - * The item must already exist, use ArrayPushString to create a new item within the array. + * Sets an item's data to a string value. * - * @param which The array to set the item from within. - * @param item The item to set (zero-based). - * @param input The string to set the item as. + * @note The input will be truncated if it is longer than the cellsize the array + * was created with. + * @note The item index must already be valid. Use ArrayPushString to create + * a new array item in the cellarray. * - * @return Number of characters copied. - * @error Invalid handle or invalid index. + * @param which Array handle + * @param item Item index in the array + * @param input String to copy to the array + * + * @return Number of characters copied + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArraySetString(Array:which, item, const input[]); /** - * Creates a new item at the end of the array and sets its data with that of a local buffer. - * The buffer size must match what the cellsize that the array was created with! + * Creates a new item at the end of the cellarray and copies the provided array + * into it. * - * @param which The array to add the item to. - * @param input The input buffer to store. - * @param size If not set, the number of elements copied from the array - * will be equal to the blocksize. If set higher than the - * blocksize, the operation will be truncated. + * @note The input will be truncated if it is bigger than the cellsize the array + * was created with. * - * @return Index of the new entry. - * @error Invalid handle or out of memory. + * @param which Array handle + * @param input Array to copy to the cellarray + * @param size If not set, assumes the buffer size is equal to the + * cellsize. Otherwise, the specified size is used. + * + * @return Index of the new entry + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown */ native ArrayPushArray(Array:which, const any:input[], size = -1); /** - * Creates a new item and sets the array's single cell value. - * Use this only on array that were created with a cellsize of 1! + * Creates a new item ath the end of the array and sets the item's single cell + * value. * - * @param which The array to add the item to. - * @param input The value to set. + * @param which Array handle + * @param input Value to set * - * @return Index of the new entry. - * @error Invalid handle or out of memory. + * @return Index of the new entry + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown */ native ArrayPushCell(Array:which, any:input); /** - * Creates a new element in the array and sets its value to the input buffer. - * The stored string will be truncated if it is longer than the cellsize the array was created with! + * Creates a new item at the end of the array and copies the provided string + * into it. * - * @param which The array to add the item to. - * @param input The string to set the item as. + * @note The input will be truncated if it is longer than the cellsize the array + * was created with. * - * @return Index of the new entry. - * @error Invalid handle or out of memory. + * @param which Array handle + * @param input String to copy to the array + * + * @return Index of the new entry + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown */ native ArrayPushString(Array:which, const input[]); /** - * Inserts an item after the selected item. All items beyond it get shifted up 1 space. - * The buffer size must match what the cellsize that the array was created with! + * Creates a new item behind the specified item and copies the provided array + * into it. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert after. - * @param input The input buffer to store. + * @param which Array handle + * @param item Item index in the array + * @param input Array to copy to the cellarray * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertArrayAfter(Array:which, item, const any:input[]); /** - * Inserts an item after the selected item. All items beyond it get shifted up 1 space. - * Use this only on an array that was created with a cellsize of 1! + * Creates a new item behind the specified item and sets the item's single cell + * value. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert after. + * @param which Array handle + * @param item Item index in the array * @param input The value to set. * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertCellAfter(Array:which, item, any:input); /** - * Inserts an item after the selected item. All items beyond it get shifted up 1 space. - * The stored string will be truncated if it is longer than the cellsize the array was created with! + * Creates a new item behind the specified item and copies the provided string + * into it. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert after. - * @param input The value to set. + * @note The input will be truncated if it is longer than the cellsize the array + * was created with. + * + * @param which Array handle + * @param item Item index in the array + * @param input String to copy to the array * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertStringAfter(Array:which, item, const input[]); /** - * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. - * The buffer size must match what the cellsize that the array was created with! + * Creates a new item in front of the specified item and copies the provided + * array into it. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert before. - * @param input The input buffer to store. + * @param which Array handle + * @param item Item index in the array + * @param input Array to copy to the cellarray * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertArrayBefore(Array:which, item, const any:input[]); /** - * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. - * Use this only on an array that was created with a cellsize of 1! + * Creates a new item in front of the specified item and sets the item's single + * cell value. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert after. - * @param input The value to set. + * @param which Array handle + * @param item Item index in the array + * @param input Value to set * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertCellBefore(Array:which, item, const any:input); /** - * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. - * The stored string will be truncated if it is longer than the cellsize the array was created with! + * Creates a new item in front of the specified item and copies the provided + * string into it. All items beyond it get shifted up by one. * - * @param which The array to add the item to. - * @param item The item to insert before. - * @param input The value to set. + * @note The input will be truncated if it is longer than the cellsize the array + * was created with. + * + * @param which Array handle + * @param item Item index in the array + * @param input String to copy to the array * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayInsertStringBefore(Array:which, item, const input[]); /** * Swaps the position of two items. * - * @param which The array that contains the items. - * @param item1 The first item to swap. - * @param item2 The second item to swap. + * @param which Array handle + * @param item1,item2 Item pair to swap * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArraySwap(Array:which, item1, item2); /** - * Deletes an item from the array. All items beyond it get shifted down 1 space. + * Deletes an item from the array. All items beyond it get shifted down by one. * * @param which The array that contains the item to delete. * @param item The item to delete. * * @noreturn - * @error Invalid handle or invalid index. + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native ArrayDeleteItem(Array:which, item); /** - * Returns the index for the first occurance of the provided string. If the string - * cannot be located, -1 will be returned. + * Searches through the array and returns the index of the first occurance of + * the specified string. * - * @param which Array handle. - * @param item String to search for. + * @param which Array handle + * @param item String to search for * - * @return Array index, or -1 on failure. + * @return Array index on success, -1 if the string can't be found * @error Invalid handle. */ native ArrayFindString(Array:which, const item[]); - -/** - * Returns the index for the first occurance of the provided value. If the value - * cannot be located, -1 will be returned. - * - * @param which Array handle. - * @param item Value to search for. - * - * @return Array index, or -1 on failure. - * @error Invalid handle. - */ -native ArrayFindValue(Array:which, any:item); /** - * Creates a handle that is passable to a format compliant routine for printing as a string (with the %a format option). - * It is suggested to pass the function directly as a parameter to the format routine. - * The array contents must be a null-terminated string! + * Searches through the array and returns the index of the first occurance of + * the specified value. * - * An example usage: client_print(id, print_chat, "%a", ArrayGetStringHandle(MessageArray, i)); + * @param which Array handle. + * @param item Value to search for * - * @param which The array the string is stored in. - * @param item Which item to print the string value of. + * @return Array index on success, -1 if the value can't be found + * @error Invalid handle. + */ +native ArrayFindValue(Array:which, any:item); + +/** + * Creates a special handle that can be passed to a string format routine for + * printing as a string (with the %a format option). * - * @return Handle to the item directly. Do not use or save stale handles. - * @error Invalid handle or invalid index. + * @note It is recommended to pass the function as a parameter to the format + * routine directly. The array item must contain a null-terminated string! + * @note Do not save or otherwise use the handles returned by this function. + * @note Example usage: + * console_print(id, "%a", ArrayGetStringHandle(MessageArray, i)); + * + * @param which Array handle + * @param item Item to retrieve handle of + * + * @return Handle to the item + * @error If an invalid handle or an invalid index is provided an + * error will be thrown */ native DoNotUse:ArrayGetStringHandle(Array:which, item); /** - * Destroys the array, and resets the handle to 0 to prevent accidental usage after it is destroyed. + * Destroys the array and frees its memory. + * + * @note The function automatically sets the variable passed to it to 0 to aid + * in preventing accidental usage after destroy. * * @param which The array to destroy. * - * @noreturn - * @error Invalid handle. + * @return 1 if the array was destroyed, 0 if nothing had to be + * destroyed (invalid handle) */ native ArrayDestroy(&Array:which); /** - * Similar to sorting.inc's CustomSort. - * The sorting algorithm then uses your comparison function to sort the data. - * The function is called in the following manner: - * + * Similar to sorting.inc's CustomSort, the sorting algorithm then uses your + * custom comparison function to sort the data. + * + * @note The function is called in the following manner: + * * public MySortFunc(Array:array, item1, item2, const data[], data_size) * - * array - Array handle in its current un-sorted state. + * array - Array handle in its current un-sorted state * item1, item2 - Current item pair being compared - * data[] - Extra data array you passed to the sort func. - * data_size - Size of extra data you passed to the sort func. + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * - * Your function should return: - * -1 if item1 should go before item2 - * 0 if item1 and item2 are equal - * 1 if item1 should go after item2 + * @note The comparison function should return: + * -1 if item1 should go before item2 + * 0 if item1 and item2 are equal + * 1 if item1 should go after item2 * - * Note that the parameters after item2 are all optional and you do not need to specify them. - * Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state. + * @note All parameters after item2 are optional and you do not need to specify + * and use them. + * @note Unlike the sorting.inc version, the array passed to the callback is not + * in mid-sorted state. * - * @param array Array handle. - * @param comparefunc A callback function used for comparison. - * @param data Extra data array you passed to the sort func. - * @param data_size Size of extra data you passed to the sort func. + * @param array Array handle + * @param comparefunc Callback function used for comparison + * @param data Extra data that is passed through to the callback + * @param data_size Size of extra data * * @noreturn * @error Invalid handle or invalid callback. @@ -399,47 +455,50 @@ native ArrayDestroy(&Array:which); native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); /** - * A faster version of ArraySort. - * The sorting algorithm then uses your comparison function to sort the data. + * A faster version of ArraySort, the sorting algorithm then uses your custom + * comparison function to sort the data. + * + * @note The advantage of this function is that the data of the elements being + * compared is directly passed to your function, instead of the item + * indexes that are passed by ArraySort. This removes the need for calling + * ArrayGet[Cell|String|Array] every time before being able to compare the + * elements. + * + * @note For Arrays with a cellsize of 1 (used for storing integers and floats), + * the function is called in the following manner: * - * The advantage of this native is that the Array elements being compared are - * directly passed into your function, instead of the item indexes that are passed by ArraySort. - * This removes the need for calling ArrayGet[Cell|String|Array] every time before being - * able to compare the elements. - * - * For Arrays with a cellsize of 1 (used for storing integers and floats), - * the function is called in the following manner: - * * public MySortFunc(Array:array, elem1, elem2, const data[], data_size) * - * array - Array handle in its current un-sorted state. + * array - Array handle in its current un-sorted state * elem1, elem2 - Current element pair being compared - * data[] - Extra data array you passed to the sort func. - * data_size - Size of extra data you passed to the sort func. + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * - * For Arrays with a cellsize larger than 1 (used for storing arrays and strings), - * the function is called in the following manner: + * @note For Arrays with a cellsize larger than 1 (used for storing arrays and + * strings), the function is called in the following manner: * * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * * array - Array handle in its current un-sorted state. * elem1[], elem2[] - Current element pair being compared - * data[] - Extra data array you passed to the sort func. - * data_size - Size of extra data you passed to the sort func. + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * - * In both cases your function should return: - * -1 if elem1 should go before elem2 - * 0 if elem1 and elem2 are equal - * 1 if elem1 should go after elem2 + * @note The comparison function should return: + * -1 if elem1 should go before elem2 + * 0 if elem1 and elem2 are equal + * 1 if elem1 should go after elem2 * - * Note that the parameters after elem2 are all optional and you do not need to specify them. - * Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state. + * @note All parameters after item2 are optional and you do not need to specify + * and use them. + * @note Unlike the sorting.inc version, the array passed to the callback is not + * in mid-sorted state. * - * @param array Array handle. - * @param comparefunc A callback function used for comparison. - * @param data Extra data array you passed to the sort func. - * @param data_size Size of extra data you passed to the sort func. + * @param array Array handle + * @param comparefunc Callback function used for comparison + * @param data Extra data that is passed through to the callback + * @param data_size Size of extra data * * @noreturn * @error Invalid handle, invalid callback or out of memory. From d9b20d78967bf569f6b755829855739fb21aa257 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 5 Aug 2014 18:48:37 +0200 Subject: [PATCH 13/27] amxconst: Move SND_* constants where they belong --- plugins/include/amxconst.inc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index 7550c2ec..d4d51087 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -213,6 +213,14 @@ public stock const MaxClients; /* Maximum number of players the server supports */ #define VOL_NORM 1.0 +/** + * Sound behavior constants + */ +#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients +#define SND_STOP (1<<5) // stop sound +#define SND_CHANGE_VOL (1<<6) // change sound vol +#define SND_CHANGE_PITCH (1<<7) // change sound pitch + /** * @endsection */ @@ -400,14 +408,6 @@ enum #define FP_STRING 2 #define FP_ARRAY 4 -/** - * Sound behavior constants - */ -#define SND_SPAWNING (1<<8) // we're spawing, used in some cases for ambients -#define SND_STOP (1<<5) // stop sound -#define SND_CHANGE_VOL (1<<6) // change sound vol -#define SND_CHANGE_PITCH (1<<7) // change sound pitch - /** * LibType constants */ From 2659e63483c2d456764a066b43609344a2fc2733 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 5 Aug 2014 18:59:08 +0200 Subject: [PATCH 14/27] amxconst: Add some more structure --- plugins/include/amxconst.inc | 43 ++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/plugins/include/amxconst.inc b/plugins/include/amxconst.inc index d4d51087..f82ffefd 100755 --- a/plugins/include/amxconst.inc +++ b/plugins/include/amxconst.inc @@ -50,6 +50,10 @@ public stock const MaxClients; /* Maximum number of players the server supports */ #define M_PI 3.1415926535 +/** + * @section Admin privilege and authentication constants + */ + /** * Admin level constants */ @@ -79,6 +83,9 @@ public stock const MaxClients; /* Maximum number of players the server supports #define ADMIN_ADMIN (1<<24) /* flag "y" */ #define ADMIN_USER (1<<25) /* flag "z" */ +/** + * Admin authentication behavior flags + */ #define FLAG_KICK (1<<0) /* flag "a" */ #define FLAG_TAG (1<<1) /* flag "b" */ #define FLAG_AUTHID (1<<2) /* flag "c" */ @@ -86,6 +93,10 @@ public stock const MaxClients; /* Maximum number of players the server supports #define FLAG_NOPASS (1<<4) /* flag "e" */ #define FLAG_CASE_SENSITIVE (1<<10) /* flag "k" */ +/** + * @endsection + */ + /** * Return codes */ @@ -94,7 +105,7 @@ public stock const MaxClients; /* Maximum number of players the server supports #define PLUGIN_HANDLED_MAIN 2 /* to use in client_command(), continue all plugins but stop the command */ /** - * CVAR constants for register_cvar() + * CVAR flags for register_cvar() */ #define FCVAR_ARCHIVE 1 /* set to cause it to be saved to vars.rc */ #define FCVAR_USERINFO 2 /* changes the client's info string */ @@ -177,7 +188,7 @@ public stock const MaxClients; /* Maximum number of players the server supports #define HIT_RIGHTLEG 7 /** - * @section Constants for emit_sound() + * @section emit_sound() constants */ /** @@ -245,6 +256,10 @@ public stock const MaxClients; /* Maximum number of players the server supports #define LANG_SERVER 0 #define LANG_PLAYER -1 +/** + * @section Client print native constants + */ + /** * Destination types for client_print() */ @@ -279,7 +294,15 @@ enum }; /** - * Render for set_user_rendering() + * @endsection + */ + +/** + * @section Entity rendering constants + */ + +/** + * Rendering modes (i.e. for set_user_rendering()) */ enum { @@ -292,7 +315,7 @@ enum }; /** - * Fx for set_user_rendering() + * Rendering fx (i.e. for set_user_rendering()) */ enum { @@ -319,6 +342,10 @@ enum kRenderFxClampMinScale, /* Keep this sprite from getting very small (SPRITES only!) */ }; +/** + * @endsection + */ + /** * Type for force_unmodified() */ @@ -392,6 +419,10 @@ enum */ #define INVALID_HANDLE -1 +/** + * @section Plugin forward related constants + */ + /** * Stop types for plugin forwards */ @@ -408,6 +439,10 @@ enum #define FP_STRING 2 #define FP_ARRAY 4 +/** + * @endsection + */ + /** * LibType constants */ From 9885c926e93b5541ef9c65f87a21c4ec6cc7dcb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 5 Aug 2014 20:09:57 +0200 Subject: [PATCH 15/27] message_const: Fix up all headings and move notes into the new headings --- plugins/include/message_const.inc | 1530 +++++++++++++++++------------ 1 file changed, 924 insertions(+), 606 deletions(-) diff --git a/plugins/include/message_const.inc b/plugins/include/message_const.inc index 3624bd4a..01d7db51 100644 --- a/plugins/include/message_const.inc +++ b/plugins/include/message_const.inc @@ -5,13 +5,15 @@ * This file is provided as is (no warranties). * */ - + #if defined _message_const_included #endinput #endif #define _message_const_included -/* Destination types for message_begin() */ +/** + * Destination types for message_begin() + */ #define MSG_BROADCAST 0 // Unreliable to all #define MSG_ONE 1 // Reliable to one (msg_entity) #define MSG_ALL 2 // Reliable to all @@ -23,8 +25,10 @@ #define MSG_ONE_UNRELIABLE 8 // Send to one client, but don't put in reliable stream, put in unreliable datagram (could be dropped) #define MSG_SPEC 9 // Sends to all spectator proxies -/* Hardcoded message types for message_begin() - * Look in the actual HLSDK for details! +/** + * Hardcoded message types for message_begin() + * + * @note Look at the actual HLSDK for details */ #define SVC_NOP 1 #define SVC_DISCONNECT 2 @@ -82,12 +86,16 @@ #define SVC_SENDEXTRAINFO 54 #define SVC_TIMESCALE 55 -/* Message flags for set_msg_block() */ +/** + * Flags for set_msg_block() + */ #define BLOCK_NOT 0 #define BLOCK_ONCE 1 #define BLOCK_SET 2 -/* Used with get_msg_argtype() and set_msg_arg_ */ +/** + * Message argument types used with get_msg_argtype() and set_msg_arg_* + */ enum { ARG_BYTE = 1, /* int */ @@ -100,678 +108,987 @@ enum ARG_ENTITY, /* int */ }; -/* Temp entity message types for message_begin() */ -#define TE_BEAMPOINTS 0 // Beam effect between two points -// write_byte(TE_BEAMPOINTS) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * @section TempEntity messages for message_begin() + */ -#define TE_BEAMENTPOINT 1 // Beam effect between point and entity -// write_byte(TE_BEAMENTPOINT) -// write_short(start entity) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * Beam effect between two points + * + * @note + * write_byte(TE_BEAMPOINTS) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ +#define TE_BEAMPOINTS 0 -#define TE_GUNSHOT 2 // Particle effect plus ricochet sound -// write_byte(TE_GUNSHOT) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) +/** + * Beam effect between a point and an entity + * + * @note + * write_byte(TE_BEAMENTPOINT) + * write_short(start entity) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ -#define TE_EXPLOSION 3 // Additive sprite, 2 dynamic lights, flickering particles, explosion sound, move vertically 8 pps -// write_byte(TE_EXPLOSION) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(sprite index) -// write_byte(scale in 0.1's) -// write_byte(framerate) -// write_byte(flags) -// -// The Explosion effect has some flags to control performance/aesthetic features: +/** + * Particle effect plus ricochet sound + * + * @note + * write_byte(TE_GUNSHOT) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + */ +#define TE_GUNSHOT 2 + +/** + * Additive sprite, 2 dynamic lights, flickering particles, explosion sound, + * move vertically 8 pps + * + * @note + * write_byte(TE_EXPLOSION) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(sprite index) + * write_byte(scale in 0.1's) + * write_byte(framerate) + * write_byte(flags) + */ +#define TE_EXPLOSION 3 + +/** + * Flags for the TE_EXPLOSION effect, controlling its performance and aesthetic + * features + */ #define TE_EXPLFLAG_NONE 0 // All flags clear makes default Half-Life explosion #define TE_EXPLFLAG_NOADDITIVE 1 // Sprite will be drawn opaque (ensure that the sprite you send is a non-additive sprite) #define TE_EXPLFLAG_NODLIGHTS 2 // Do not render dynamic lights #define TE_EXPLFLAG_NOSOUND 4 // Do not play client explosion sound #define TE_EXPLFLAG_NOPARTICLES 8 // Do not draw particles -#define TE_TAREXPLOSION 4 // Quake1 "tarbaby" explosion with sound -// write_byte(TE_TAREXPLOSION) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) +/** + * Quake1 "tarbaby" explosion with sound + * + * @note + * write_byte(TE_TAREXPLOSION) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + */ +#define TE_TAREXPLOSION 4 -#define TE_SMOKE 5 // Alphablend sprite, move vertically 30 pps -// write_byte(TE_SMOKE) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(sprite index) -// write_byte(scale in 0.1's) -// write_byte(framerate) +/** + * Alphablend sprite, move vertically 30pps + * + * @note + * write_byte(TE_SMOKE) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(sprite index) + * write_byte(scale in 0.1's) + * write_byte(framerate) + */ +#define TE_SMOKE 5 -#define TE_TRACER 6 // Tracer effect from point to point -// write_byte(TE_TRACER) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) +/** + * Tracer effect from point to point + * + * @note + * write_byte(TE_TRACER) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + */ +#define TE_TRACER 6 -#define TE_LIGHTNING 7 // TE_BEAMPOINTS with simplified parameters -// write_byte(TE_LIGHTNING) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_byte(life in 0.1's) -// write_byte(width in 0.1's) -// write_byte(amplitude in 0.01's) -// write_short(sprite model index) +/** + * TE_BEAMPOINTS with simplified parameters + * + * @note + * write_byte(TE_LIGHTNING) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_byte(life in 0.1's) + * write_byte(width in 0.1's) + * write_byte(amplitude in 0.01's) + * write_short(sprite model index) + */ +#define TE_LIGHTNING 7 +/** + * + * + * @note + * write_byte(TE_BEAMENTS) + * write_short(start entity) + * write_short(end entity) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ #define TE_BEAMENTS 8 -// write_byte(TE_BEAMENTS) -// write_short(start entity) -// write_short(end entity) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) -#define TE_SPARKS 9 // 8 random tracers with gravity, ricochet sprite -// write_byte(TE_SPARKS) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) +/** + * 8 random tracers with gravity, ricochet sprite + * + * @note + * write_byte(TE_SPARKS) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + */ +#define TE_SPARKS 9 -#define TE_LAVASPLASH 10 // Quake1 lava splash -// write_byte(TE_LAVASPLASH) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) +/** + * Quake1 lava splash + * + * @note + * write_byte(TE_LAVASPLASH) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + */ +#define TE_LAVASPLASH 10 -#define TE_TELEPORT 11 // Quake1 teleport splash -// write_byte(TE_TELEPORT) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) +/** + * Quake1 teleport splash + * + * @note + * write_byte(TE_TELEPORT) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + */ +#define TE_TELEPORT 11 -#define TE_EXPLOSION2 12 // Quake1 colormaped (base palette) particle explosion with sound -// write_byte(TE_EXPLOSION2) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(starting color) -// write_byte(num colors) +/** + * Quake1 colormaped (base palette) particle explosion with sound + * + * @note + * write_byte(TE_EXPLOSION2) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(starting color) + * write_byte(num colors) + */ +#define TE_EXPLOSION2 12 -#define TE_BSPDECAL 13 // Decal from the .BSP file -// write_byte(TE_BSPDECAL) -// write_coord(position.x) decal position (center of texture in world) -// write_coord(position.y) -// write_coord(position.z) -// write_short(texture index of precached decal texture name) -// write_short(entity index) -// [optional - write_short(index of model of above entity) only included if previous short is non-zero (not the world)] +/** + * Decal from the .BSP file + * + * @note + * write_byte(TE_BSPDECAL) + * write_coord(position.x) decal position (center of texture in world) + * write_coord(position.y) + * write_coord(position.z) + * write_short(texture index of precached decal texture name) + * write_short(entity index) + * [optional - write_short(index of model of above entity) only included if previous short is non-zero (not the world)] + */ +#define TE_BSPDECAL 13 -#define TE_IMPLOSION 14 // Tracers moving toward a point -// write_byte(TE_IMPLOSION) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(radius) -// write_byte(count) -// write_byte(life in 0.1's) +/** + * Tracers moving toward a point + * + * @note + * write_byte(TE_IMPLOSION) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(radius) + * write_byte(count) + * write_byte(life in 0.1's) + */ +#define TE_IMPLOSION 14 -#define TE_SPRITETRAIL 15 // Line of moving glow sprites with gravity, fadeout, and collisions -// write_byte(TE_SPRITETRAIL) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_short(sprite index) -// write_byte(count) -// write_byte(life in 0.1's) -// write_byte(scale in 0.1's) -// write_byte(velocity along vector in 10's) -// write_byte(randomness of velocity in 10's) +/** + * Line of moving glow sprites with gravity, fadeout, and collisions + * + * @note + * write_byte(TE_SPRITETRAIL) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_short(sprite index) + * write_byte(count) + * write_byte(life in 0.1's) + * write_byte(scale in 0.1's) + * write_byte(velocity along vector in 10's) + * write_byte(randomness of velocity in 10's) + */ +#define TE_SPRITETRAIL 15 -#define TE_SPRITE 17 // Additive sprite, plays 1 cycle -// write_byte(TE_SPRITE) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(sprite index) -// write_byte(scale in 0.1's) -// write_byte(brightness) +/** + * Additive sprite, plays 1 cycle + * + * @note + * write_byte(TE_SPRITE) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(sprite index) + * write_byte(scale in 0.1's) + * write_byte(brightness) + */ +#define TE_SPRITE 17 -#define TE_BEAMSPRITE 18 // A beam with a sprite at the end -// write_byte(TE_BEAMSPRITE) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_short(beam sprite index) -// write_short(end sprite index) +/** + * A beam with a sprite at the end + * + * @note + * write_byte(TE_BEAMSPRITE) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_short(beam sprite index) + * write_short(end sprite index) + */ +#define TE_BEAMSPRITE 18 -#define TE_BEAMTORUS 19 // Screen aligned beam ring, expands to max radius over lifetime -// write_byte(TE_BEAMTORUS) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(axis.x) -// write_coord(axis.y) -// write_coord(axis.z) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * Screen aligned beam ring, expands to max radius over lifetime + * + * @note + * write_byte(TE_BEAMTORUS) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(axis.x) + * write_coord(axis.y) + * write_coord(axis.z) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ +#define TE_BEAMTORUS 19 -#define TE_BEAMDISK 20 // Disk that expands to max radius over lifetime -// write_byte(TE_BEAMDISK) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(axis.x) -// write_coord(axis.y) -// write_coord(axis.z) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * Disk that expands to max radius over lifetime + * + * @note + * write_byte(TE_BEAMDISK) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(axis.x) + * write_coord(axis.y) + * write_coord(axis.z) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ +#define TE_BEAMDISK 20 -#define TE_BEAMCYLINDER 21 // Cylinder that expands to max radius over lifetime -// write_byte(TE_BEAMCYLINDER) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(axis.x) -// write_coord(axis.y) -// write_coord(axis.z) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * Cylinder that expands to max radius over lifetime + * + * @note + * write_byte(TE_BEAMCYLINDER) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(axis.x) + * write_coord(axis.y) + * write_coord(axis.z) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ +#define TE_BEAMCYLINDER 21 -#define TE_BEAMFOLLOW 22 // Create a line of decaying beam segments until entity stops moving -// write_byte(TE_BEAMFOLLOW) -// write_short(entity:attachment to follow) -// write_short(sprite index) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) +/** + * Create a line of decaying beam segments until entity stops moving + * + * @note + * write_byte(TE_BEAMFOLLOW) + * write_short(entity:attachment to follow) + * write_short(sprite index) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + */ +#define TE_BEAMFOLLOW 22 +/** + * + * + * @note + * write_byte(TE_GLOWSPRITE) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(model index) + * write_byte(scale / 10) + * write_byte(size) + * write_byte(brightness) + */ #define TE_GLOWSPRITE 23 -// write_byte(TE_GLOWSPRITE) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(model index) -// write_byte(scale / 10) -// write_byte(size) -// write_byte(brightness) -#define TE_BEAMRING 24 // Connect a beam ring to two entities -// write_byte(TE_BEAMRING) -// write_short(start entity) -// write_short(end entity) -// write_short(sprite index) -// write_byte(starting frame) -// write_byte(frame rate in 0.1's) -// write_byte(life in 0.1's) -// write_byte(line width in 0.1's) -// write_byte(noise amplitude in 0.01's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(scroll speed in 0.1's) +/** + * Connect a beam ring to two entities + * + * @note + * write_byte(TE_BEAMRING) + * write_short(start entity) + * write_short(end entity) + * write_short(sprite index) + * write_byte(starting frame) + * write_byte(frame rate in 0.1's) + * write_byte(life in 0.1's) + * write_byte(line width in 0.1's) + * write_byte(noise amplitude in 0.01's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(scroll speed in 0.1's) + */ +#define TE_BEAMRING 24 -#define TE_STREAK_SPLASH 25 // Oriented shower of tracers -// write_byte(TE_STREAK_SPLASH) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(vector.x) -// write_coord(vector.y) -// write_coord(vector.z) -// write_byte(color) -// write_short(count) -// write_short(base speed) -// write_short(ramdon velocity) +/** + * Oriented shower of tracers + * + * @note + * write_byte(TE_STREAK_SPLASH) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(vector.x) + * write_coord(vector.y) + * write_coord(vector.z) + * write_byte(color) + * write_short(count) + * write_short(base speed) + * write_short(ramdon velocity) + */ +#define TE_STREAK_SPLASH 25 -#define TE_DLIGHT 27 // Dynamic light, effect world, minor entity effect -// write_byte(TE_DLIGHT) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(radius in 10's) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(brightness) -// write_byte(life in 10's) -// write_byte(decay rate in 10's) +/** + * Dynamic light, effect world, minor entity effect + * + * @note + * write_byte(TE_DLIGHT) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(radius in 10's) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(brightness) + * write_byte(life in 10's) + * write_byte(decay rate in 10's) + */ +#define TE_DLIGHT 27 -#define TE_ELIGHT 28 // Point entity light, no world effect -// write_byte(TE_ELIGHT) -// write_short(entity:attachment to follow) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(radius) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -// write_byte(life in 0.1's) -// write_coord(decay rate) +/** + * Point entity light, no world effect + * + * @note + * write_byte(TE_ELIGHT) + * write_short(entity:attachment to follow) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(radius) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + * write_byte(life in 0.1's) + * write_coord(decay rate) + */ +#define TE_ELIGHT 28 +/** + * + * + * @note + * write_byte(TE_TEXTMESSAGE) + * write_byte(channel) + * write_short(x) -1 = center) + * write_short(y) -1 = center) + * write_byte(effect) 0 = fade in/fade out, 1 is flickery credits, 2 is write out (training room) + * write_byte(red) - text color + * write_byte(green) + * write_byte(blue) + * write_byte(alpha) + * write_byte(red) - effect color + * write_byte(green) + * write_byte(blue) + * write_byte(alpha) + * write_short(fadein time) + * write_short(fadeout time) + * write_short(hold time) + * [optional] write_short(fxtime) time the highlight lags behing the leading text in effect 2 + * write_string(text message) 512 chars max string size + */ #define TE_TEXTMESSAGE 29 -// write_byte(TE_TEXTMESSAGE) -// write_byte(channel) -// write_short(x) -1 = center) -// write_short(y) -1 = center) -// write_byte(effect) 0 = fade in/fade out, 1 is flickery credits, 2 is write out (training room) -// write_byte(red) - text color -// write_byte(green) -// write_byte(blue) -// write_byte(alpha) -// write_byte(red) - effect color -// write_byte(green) -// write_byte(blue) -// write_byte(alpha) -// write_short(fadein time) -// write_short(fadeout time) -// write_short(hold time) -// [optional] write_short(fxtime) time the highlight lags behing the leading text in effect 2 -// write_string(text message) 512 chars max string size +/** + * + * + * @note + * write_byte(TE_LINE) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + * write_short(life in 0.1 s) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + */ #define TE_LINE 30 -// write_byte(TE_LINE) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) -// write_short(life in 0.1 s) -// write_byte(red) -// write_byte(green) -// write_byte(blue) +/** + * + * + * @note + * write_byte(TE_BOX) + * write_coord(boxmins.x) + * write_coord(boxmins.y) + * write_coord(boxmins.z) + * write_coord(boxmaxs.x) + * write_coord(boxmaxs.y) + * write_coord(boxmaxs.z) + * write_short(life in 0.1 s) + * write_byte(red) + * write_byte(green) + * write_byte(blue) + */ #define TE_BOX 31 -// write_byte(TE_BOX) -// write_coord(boxmins.x) -// write_coord(boxmins.y) -// write_coord(boxmins.z) -// write_coord(boxmaxs.x) -// write_coord(boxmaxs.y) -// write_coord(boxmaxs.z) -// write_short(life in 0.1 s) -// write_byte(red) -// write_byte(green) -// write_byte(blue) -#define TE_KILLBEAM 99 // Kill all beams attached to entity -// write_byte(TE_KILLBEAM) -// write_short(entity) +/** + * Kill all beams attached to entity + * + * @note + * write_byte(TE_KILLBEAM) + * write_short(entity) + */ +#define TE_KILLBEAM 99 +/** + * + * + * @note + * write_byte(TE_LARGEFUNNEL) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(sprite index) + * write_short(flags) + */ #define TE_LARGEFUNNEL 100 -// write_byte(TE_LARGEFUNNEL) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(sprite index) -// write_short(flags) -#define TE_BLOODSTREAM 101 // Particle spray -// write_byte(TE_BLOODSTREAM) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(vector.x) -// write_coord(vector.y) -// write_coord(vector.z) -// write_byte(color) -// write_byte(speed) +/** + * Particle spray + * + * @note + * write_byte(TE_BLOODSTREAM) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(vector.x) + * write_coord(vector.y) + * write_coord(vector.z) + * write_byte(color) + * write_byte(speed) + */ +#define TE_BLOODSTREAM 101 -#define TE_SHOWLINE 102 // Line of particles every 5 units, dies in 30 seconds -// write_byte(TE_SHOWLINE) -// write_coord(startposition.x) -// write_coord(startposition.y) -// write_coord(startposition.z) -// write_coord(endposition.x) -// write_coord(endposition.y) -// write_coord(endposition.z) +/** + * Line of particles every 5 units, dies in 30 seconds + * + * @note + * write_byte(TE_SHOWLINE) + * write_coord(startposition.x) + * write_coord(startposition.y) + * write_coord(startposition.z) + * write_coord(endposition.x) + * write_coord(endposition.y) + * write_coord(endposition.z) + */ +#define TE_SHOWLINE 102 -#define TE_BLOOD 103 // Particle spray -// write_byte(TE_BLOOD) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(vector.x) -// write_coord(vector.y) -// write_coord(vector.z) -// write_byte(color) -// write_byte(speed) +/** + * Particle spray + * + * @note + * write_byte(TE_BLOOD) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(vector.x) + * write_coord(vector.y) + * write_coord(vector.z) + * write_byte(color) + * write_byte(speed) + */ +#define TE_BLOOD 103 -#define TE_DECAL 104 // Decal applied to a brush entity (not the world) -// write_byte(TE_DECAL) -// write_coord(position.x) decal position (center of texture in world) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(texture index of precached decal texture name) -// write_short(entity index) +/** + * Decal applied to a brush entity (not the world) + * + * @note + * write_byte(TE_DECAL) + * write_coord(position.x) decal position (center of texture in world) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(texture index of precached decal texture name) + * write_short(entity index) + */ +#define TE_DECAL 104 -#define TE_FIZZ 105 // Create alpha sprites inside of entity, float upwards -// write_byte(TE_FIZZ) -// write_short(entity) -// write_short(sprite index) -// write_byte density) +/** + * Create alpha sprites inside of entity, float upwards + * + * @note + * write_byte(TE_FIZZ) + * write_short(entity) + * write_short(sprite index) + * write_byte density) + */ +#define TE_FIZZ 105 -#define TE_MODEL 106 // Create a moving model that bounces and makes a sound when it hits -// write_byte(TE_MODEL) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_angle(initial yaw) -// write_short(model index) -// write_byte(bounce sound type) -// write_byte(life in 0.1's) +/** + * Create a moving model that bounces and makes a sound when it hits + * + * @note + * write_byte(TE_MODEL) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_angle(initial yaw) + * write_short(model index) + * write_byte(bounce sound type) + * write_byte(life in 0.1's) + */ +#define TE_MODEL 106 -#define TE_EXPLODEMODEL 107 // Spherical shower of models, picks from set -// write_byte(TE_EXPLODEMODEL) -// write_coord(origin.x) -// write_coord(origin.y) -// write_coord(origin.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_short(model index) -// write_short(count) -// write_byte(life in 0.1's) +/** + * Spherical shower of models, picks from set + * + * @note + * write_byte(TE_EXPLODEMODEL) + * write_coord(origin.x) + * write_coord(origin.y) + * write_coord(origin.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_short(model index) + * write_short(count) + * write_byte(life in 0.1's) + */ +#define TE_EXPLODEMODEL 107 -#define TE_BREAKMODEL 108 // Box of models or sprites -// write_byte(TE_BREAKMODEL) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(size.x) -// write_coord(size.y) -// write_coord(size.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_byte(random velocity in 10's) -// write_short(sprite or model index) -// write_byte(count) -// write_byte(life in 0.1 secs) -// write_byte(flags) +/** + * Box of models or sprites + * + * @note + * write_byte(TE_BREAKMODEL) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(size.x) + * write_coord(size.y) + * write_coord(size.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_byte(random velocity in 10's) + * write_short(sprite or model index) + * write_byte(count) + * write_byte(life in 0.1 secs) + * write_byte(flags) + */ +#define TE_BREAKMODEL 108 -#define TE_GUNSHOTDECAL 109 // Decal and ricochet sound -// write_byte(TE_GUNSHOTDECAL) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(entity index???) -// write_byte(decal???) +/** + * Decal and ricochet sound + * + * @note + * write_byte(TE_GUNSHOTDECAL) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(entity index???) + * write_byte(decal???) + */ +#define TE_GUNSHOTDECAL 109 -#define TE_SPRITE_SPRAY 110 // Spray of alpha sprites -// write_byte(TE_SPRITE_SPRAY) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_short(sprite index) -// write_byte(count) -// write_byte(speed) -// write_byte(noise) +/** + * Spray of alpha sprites + * + * @note + * write_byte(TE_SPRITE_SPRAY) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_short(sprite index) + * write_byte(count) + * write_byte(speed) + * write_byte(noise) + */ +#define TE_SPRITE_SPRAY 110 -#define TE_ARMOR_RICOCHET 111 // Quick spark sprite, client ricochet sound. -// write_byte(TE_ARMOR_RICOCHET) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(scale in 0.1's) +/** + * Quick spark sprite, client ricochet sound. + * + * @note + * write_byte(TE_ARMOR_RICOCHET) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(scale in 0.1's) + */ +#define TE_ARMOR_RICOCHET 111 +/** + * + * + * @note + * write_byte(TE_PLAYERDECAL) + * write_byte(playerindex) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(entity???) + * write_byte(decal number) + * [optional] write_short(model index) + */ #define TE_PLAYERDECAL 112 -// write_byte(TE_PLAYERDECAL) -// write_byte(playerindex) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(entity???) -// write_byte(decal number) -// [optional] write_short(model index) -#define TE_BUBBLES 113 // Create alpha sprites inside of box, float upwards -// write_byte(TE_BUBBLES) -// write_coord(position.x) (min start position) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(position.x) (max start position) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(float height) -// write_short(model index) -// write_byte(count) -// write_coord(speed) +/** + * Create alpha sprites inside of box, float upwards + * + * @note + * write_byte(TE_BUBBLES) + * write_coord(position.x) (min start position) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(position.x) (max start position) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(float height) + * write_short(model index) + * write_byte(count) + * write_coord(speed) + */ +#define TE_BUBBLES 113 -#define TE_BUBBLETRAIL 114 // Create alpha sprites along a line, float upwards -// write_byte(TE_BUBBLETRAIL) -// write_coord(position.x) (min start position) -// write_coord(position.y) (min start position) -// write_coord(position.z) (min start position) -// write_coord(position.x) (max start position) -// write_coord(position.y) (max start position) -// write_coord(position.z) (max start position) -// write_coord(float height) -// write_short(model index) -// write_byte(count) -// write_coord(speed) +/** + * Create alpha sprites along a line, float upwards + * + * @note + * write_byte(TE_BUBBLETRAIL) + * write_coord(position.x) (min start position) + * write_coord(position.y) (min start position) + * write_coord(position.z) (min start position) + * write_coord(position.x) (max start position) + * write_coord(position.y) (max start position) + * write_coord(position.z) (max start position) + * write_coord(float height) + * write_short(model index) + * write_byte(count) + * write_coord(speed) + */ +#define TE_BUBBLETRAIL 114 -#define TE_BLOODSPRITE 115 // Spray of opaque sprite1's that fall, single sprite2 for 1..2 secs (this is a high-priority tent) -// write_byte(TE_BLOODSPRITE) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_short(sprite1 index) -// write_short(sprite2 index) -// write_byte(color) -// write_byte(scale) +/** + * Spray of opaque sprite1's that fall, single sprite2 for 1..2 secs (this is a high-priority tent) + * + * @note + * write_byte(TE_BLOODSPRITE) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_short(sprite1 index) + * write_short(sprite2 index) + * write_byte(color) + * write_byte(scale) + */ +#define TE_BLOODSPRITE 115 -#define TE_WORLDDECAL 116 // Decal applied to the world brush -// write_byte(TE_WORLDDECAL) -// write_coord(position.x) decal position (center of texture in world) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(texture index of precached decal texture name) +/** + * Decal applied to the world brush + * + * @note + * write_byte(TE_WORLDDECAL) + * write_coord(position.x) decal position (center of texture in world) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(texture index of precached decal texture name) + */ +#define TE_WORLDDECAL 116 -#define TE_WORLDDECALHIGH 117 // Decal (with texture index > 256) applied to world brush -// write_byte(TE_WORLDDECALHIGH) -// write_coord(position.x) decal position (center of texture in world) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(texture index of precached decal texture name - 256) +/** + * Decal (with texture index > 256) applied to world brush + * + * @note + * write_byte(TE_WORLDDECALHIGH) + * write_coord(position.x) decal position (center of texture in world) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(texture index of precached decal texture name - 256) + */ +#define TE_WORLDDECALHIGH 117 -#define TE_DECALHIGH 118 // Same as TE_DECAL, but the texture index was greater than 256 -// write_byte(TE_DECALHIGH) -// write_coord(position.x) decal position (center of texture in world) -// write_coord(position.y) -// write_coord(position.z) -// write_byte(texture index of precached decal texture name - 256) -// write_short(entity index) +/** + * Same as TE_DECAL, but the texture index was greater than 256 + * + * @note + * write_byte(TE_DECALHIGH) + * write_coord(position.x) decal position (center of texture in world) + * write_coord(position.y) + * write_coord(position.z) + * write_byte(texture index of precached decal texture name - 256) + * write_short(entity index) + */ +#define TE_DECALHIGH 118 -#define TE_PROJECTILE 119 // Makes a projectile (like a nail) (this is a high-priority tent) -// write_byte(TE_PROJECTILE) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_short(modelindex) -// write_byte(life) -// write_byte(owner) projectile won't collide with owner (if owner == 0, projectile will hit any client). +/** + * Makes a projectile (like a nail) (this is a high-priority tent) + * + * @note + * write_byte(TE_PROJECTILE) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_short(modelindex) + * write_byte(life) + * write_byte(owner) projectile won't collide with owner (if owner == 0, projectile will hit any client). + */ +#define TE_PROJECTILE 119 -#define TE_SPRAY 120 // Throws a shower of sprites or models -// write_byte(TE_SPRAY) -// write_coord(position.x) -// write_coord(position.y) -// write_coord(position.z) -// write_coord(direction.x) -// write_coord(direction.y) -// write_coord(direction.z) -// write_short(modelindex) -// write_byte(count) -// write_byte(speed) -// write_byte(noise) -// write_byte(rendermode) +/** + * Throws a shower of sprites or models + * + * @note + * write_byte(TE_SPRAY) + * write_coord(position.x) + * write_coord(position.y) + * write_coord(position.z) + * write_coord(direction.x) + * write_coord(direction.y) + * write_coord(direction.z) + * write_short(modelindex) + * write_byte(count) + * write_byte(speed) + * write_byte(noise) + * write_byte(rendermode) + */ +#define TE_SPRAY 120 -#define TE_PLAYERSPRITES 121 // Sprites emit from a player's bounding box (ONLY use for players!) -// write_byte(TE_PLAYERSPRITES) -// write_short(playernum) -// write_short(sprite modelindex) -// write_byte(count) -// write_byte(variance) (0 = no variance in size) (10 = 10% variance in size) +/** + * Sprites emit from a player's bounding box (ONLY use for players!) + * + * @note + * write_byte(TE_PLAYERSPRITES) + * write_short(playernum) + * write_short(sprite modelindex) + * write_byte(count) + * write_byte(variance) (0 = no variance in size) (10 = 10% variance in size) + */ +#define TE_PLAYERSPRITES 121 -#define TE_PARTICLEBURST 122 // Very similar to lavasplash -// write_byte(TE_PARTICLEBURST) -// write_coord(origin) -// write_short(radius) -// write_byte(particle color) -// write_byte(duration * 10) (will be randomized a bit) +/** + * Very similar to lavasplash + * + * @note + * write_byte(TE_PARTICLEBURST) + * write_coord(origin) + * write_short(radius) + * write_byte(particle color) + * write_byte(duration * 10) (will be randomized a bit) + */ +#define TE_PARTICLEBURST 122 -#define TE_FIREFIELD 123 // Makes a field of fire -// write_byte(TE_FIREFIELD) -// write_coord(origin) -// write_short(radius) (fire is made in a square around origin. -radius, -radius to radius, radius) -// write_short(modelindex) -// write_byte(count) -// write_byte(flags) -// write_byte(duration (in seconds) * 10) (will be randomized a bit) -// -// to keep network traffic low, this message has associated flags that fit into a byte: +/** + * Makes a field of fire + * + * @note + * write_byte(TE_FIREFIELD) + * write_coord(origin) + * write_short(radius) (fire is made in a square around origin. -radius, -radius to radius, radius) + * write_short(modelindex) + * write_byte(count) + * write_byte(flags) + * write_byte(duration (in seconds) * 10) (will be randomized a bit) + */ +#define TE_FIREFIELD 123 + +/** + * Flags for the TE_FIREFIELD effect, controlling its performance and aesthetic + * features + */ #define TEFIRE_FLAG_ALLFLOAT 1 // All sprites will drift upwards as they animate #define TEFIRE_FLAG_SOMEFLOAT 2 // Some of the sprites will drift upwards. (50% chance) #define TEFIRE_FLAG_LOOP 4 // If set, sprite plays at 15 fps, otherwise plays at whatever rate stretches the animation over the sprite's duration. #define TEFIRE_FLAG_ALPHA 8 // If set, sprite is rendered alpha blended at 50% else, opaque -#define TEFIRE_FLAG_PLANAR 16 // If set, all fire sprites have same initial Z instead of randomly filling a cube. +#define TEFIRE_FLAG_PLANAR 16 // If set, all fire sprites have same initial Z instead of randomly filling a cube. -#define TE_PLAYERATTACHMENT 124 // Attaches a TENT to a player (this is a high-priority tent) -// write_byte(TE_PLAYERATTACHMENT) -// write_byte(entity index of player) -// write_coord(vertical offset) (attachment origin.z = player origin.z + vertical offset) -// write_short(model index) -// write_short(life * 10 ) +/** + * Attaches a TENT to a player (this is a high-priority tent) + * + * @note + * write_byte(TE_PLAYERATTACHMENT) + * write_byte(entity index of player) + * write_coord(vertical offset) (attachment origin.z = player origin.z + vertical offset) + * write_short(model index) + * write_short(life * 10 ) + */ +#define TE_PLAYERATTACHMENT 124 -#define TE_KILLPLAYERATTACHMENTS 125 // Will expire all TENTS attached to a player. -// write_byte(TE_KILLPLAYERATTACHMENTS) -// write_byte(entity index of player) +/** + * + * + * @note + * write_byte(TE_KILLPLAYERATTACHMENTS) + * write_byte(entity index of player) + */ +#define TE_KILLPLAYERATTACHMENTS 125 * Will expire all TENTS attached to a player. -#define TE_MULTIGUNSHOT 126 // Much more compact shotgun message -// This message is used to make a client approximate a 'spray' of gunfire. -// Any weapon that fires more than one bullet per frame and fires in a bit of a spread is -// a good candidate for MULTIGUNSHOT use. (shotguns) -// -// NOTE: This effect makes the client do traces for each bullet, these client traces ignore -// entities that have studio models.Traces are 4096 long. -// -// write_byte(TE_MULTIGUNSHOT) -// write_coord(origin.x) -// write_coord(origin.y) -// write_coord(origin.z) -// write_coord(direction.x) -// write_coord(direction.y) -// write_coord(direction.z) -// write_coord(x noise * 100) -// write_coord(y noise * 100) -// write_byte(count) -// write_byte(bullethole decal texture index) +/** + * Much more compact shotgun message + * + * @note This message is used to make a client approximate a 'spray' of gunfire. + * Any weapon that fires more than one bullet per frame and fires in a bit + * of a spread is a good candidate for MULTIGUNSHOT use. (shotguns) + * @note This effect makes the client do traces for each bullet, these client + * traces ignore entities that have studio models.Traces are 4096 long. + * @note + * write_byte(TE_MULTIGUNSHOT) + * write_coord(origin.x) + * write_coord(origin.y) + * write_coord(origin.z) + * write_coord(direction.x) + * write_coord(direction.y) + * write_coord(direction.z) + * write_coord(x noise * 100) + * write_coord(y noise * 100) + * write_byte(count) + * write_byte(bullethole decal texture index) + */ +#define TE_MULTIGUNSHOT 126 -#define TE_USERTRACER 127 // Larger message than the standard tracer, but allows some customization. -// write_byte(TE_USERTRACER) -// write_coord(origin.x) -// write_coord(origin.y) -// write_coord(origin.z) -// write_coord(velocity.x) -// write_coord(velocity.y) -// write_coord(velocity.z) -// write_byte(life * 10) -// write_byte(color) this is an index into an array of color vectors in the engine. (0 - ) -// write_byte(length * 10) -// From hltv.h from the HLSDK, these are used in conjunction with SVC_DIRECTOR -// sub commands of svc_director: +/** + * Larger message than the standard tracer, but allows some customization. + * + * @note + */ +#define TE_USERTRACER 127 + * write_byte(TE_USERTRACER) + * write_coord(origin.x) + * write_coord(origin.y) + * write_coord(origin.z) + * write_coord(velocity.x) + * write_coord(velocity.y) + * write_coord(velocity.z) + * write_byte(life * 10) + * write_byte(color) this is an index into an array of color vectors in the engine. (0 - ) + * write_byte(length * 10) + +/** + * @endsection + */ + +/** + * From hltv.h from the HLSDK, these are used in conjunction with SVC_DIRECTOR + * sub commands of svc_director + */ #define DRC_CMD_NONE 0 // NULL director command #define DRC_CMD_START 1 // start director mode #define DRC_CMD_EVENT 2 // informs about director command @@ -788,9 +1105,11 @@ enum #define DRC_CMD_LAST 12 -// HLTV_EVENT event flags +/** + * HLTV_EVENT event flags + */ #define DRC_FLAG_PRIO_MASK 0x0F // priorities between 0 and 15 (15 most important) -#define DRC_FLAG_SIDE (1<<4) // +#define DRC_FLAG_SIDE (1<<4) // #define DRC_FLAG_DRAMATIC (1<<5) // is a dramatic scene #define DRC_FLAG_SLOWMOTION (1<<6) // would look good in SloMo #define DRC_FLAG_FACEPLAYER (1<<7) // player is doning something (reload/defuse bomb etc) @@ -798,6 +1117,5 @@ enum #define DRC_FLAG_FINAL (1<<9) // is a final scene #define DRC_FLAG_NO_RANDOM (1<<10) // don't randomize event data - #define MAX_DIRECTOR_CMD_PARAMETERS 4 #define MAX_DIRECTOR_CMD_STRING 128 From 3a232f1576c1a8ae2dc1b9290d6fae17db9103d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 5 Aug 2014 20:18:16 +0200 Subject: [PATCH 16/27] message_const: Add placeholder titles for TE_* messages missing a description --- plugins/include/message_const.inc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/include/message_const.inc b/plugins/include/message_const.inc index 01d7db51..0b2b1dc8 100644 --- a/plugins/include/message_const.inc +++ b/plugins/include/message_const.inc @@ -254,7 +254,7 @@ enum #define TE_LIGHTNING 7 /** - * + * TE_BEAMENTS * * @note * write_byte(TE_BEAMENTS) @@ -490,7 +490,7 @@ enum #define TE_BEAMFOLLOW 22 /** - * + * TE_GLOWSPRITE * * @note * write_byte(TE_GLOWSPRITE) @@ -580,7 +580,7 @@ enum #define TE_ELIGHT 28 /** - * + * TE_TEXTMESSAGE * * @note * write_byte(TE_TEXTMESSAGE) @@ -605,7 +605,7 @@ enum #define TE_TEXTMESSAGE 29 /** - * + * TE_LINE * * @note * write_byte(TE_LINE) @@ -623,7 +623,7 @@ enum #define TE_LINE 30 /** - * + * TE_BOX * * @note * write_byte(TE_BOX) @@ -650,7 +650,7 @@ enum #define TE_KILLBEAM 99 /** - * + * TE_LARGEFUNNEL * * @note * write_byte(TE_LARGEFUNNEL) @@ -833,7 +833,7 @@ enum #define TE_ARMOR_RICOCHET 111 /** - * + * TE_PLAYERDECAL * * @note * write_byte(TE_PLAYERDECAL) @@ -1032,7 +1032,7 @@ enum #define TE_PLAYERATTACHMENT 124 /** - * + * TE_KILLPLAYERATTACHMENTS * * @note * write_byte(TE_KILLPLAYERATTACHMENTS) From 37e22dc22f87020828a6bece97452c35d54650fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 00:19:24 +0200 Subject: [PATCH 17/27] amxmodx: Fifth batch of documentation updates --- plugins/include/amxmodx.inc | 688 ++++++++++++++++++++++++++++-------- 1 file changed, 542 insertions(+), 146 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 2848783e..79b7bb03 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -57,9 +57,12 @@ 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 also used by plugins will not + * server command "changelevel" which is used by many plugins will not * trigger this forward. Unfortunately this means that in practice this * 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 * @@ -1364,11 +1367,13 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = ""); /** - * Executes a command from the server console. + * Queues a command to be executed from the server console. * * @note Warning: This is a potential source of command injection. Do not feed * 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 @@ -1731,7 +1736,7 @@ native set_user_flags(index, flags=-1, id=0); * @error If the index is not within the range of 0 to MaxClients, an * error will be thrown. */ -native get_user_flags(index,id=0); +native get_user_flags(index, id=0); /** * Removes the specified admin flags from a client. @@ -1757,19 +1762,19 @@ native remove_user_flags(index, flags=-1, id=0); * 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); +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); +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[]=""); +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); @@ -1812,92 +1817,245 @@ native register_menucmd(menuid,keys, const function[] ); * is VGUI in other case the id is from register_menuid() function. */ native get_user_menu(index,&id,&keys); -/* Forces server to execute sent server command at current time. -* Very useful for map changes, setting cvars and other activities. */ +/** + * Forces the server to execute the command queue immediately. + * + * @note Commands can be added to the queue using server_cmd(). + * + * @noreturn + */ native server_exec(); -/* Emits sound. Sample must be precached. */ +/** + * Emits a sound from an entity from the engine. + * + * @note The sample must be precached using precache_sound() so it is available + * in the engine's sound table. + * @note For a list of available channels see CHAN_* constants in amxconst.inc, + * sounds emitted from the same channel will override each other. + * @note There are helpful reference constants in amxconst.inc for sound volume + * (VOL_*), attenuation (ATTN_*), flags (SND_*), and pitch (PITCH_*). + * + * @param index Entity index, use 0 to emit from all clients + * @param channel Channel to emit from + * @param sample Sound file to emit + * @param vol Volume in percent + * @param att Sound attenuation + * @param flags Emit flags + * @param pitch Sound pitch + */ native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pitch); -/* Registers new cvar for HL engine. - * Returns the cvar pointer for get/set_pcvar functions. +/** + * Registers a new ccvar for the engine. + * + * @note For a list of possible cvar flags see FCVAR_* constants in amxconst.inc + * @note If an already existing cvar is registered it will not be duplicated. + * @note The returned cvar pointer should be used with the get_pcvar_* and + * set_pcvar_* set of functions. + * + * @param name Cvar name + * @param string Default cvar value + * @param flags Cvar flags + * @param fvalue + * + * @return Unique cvar pointer */ -native register_cvar(const name[],const string[],flags = 0,Float:fvalue = 0.0); +native register_cvar(const name[], const string[], flags = 0, Float:fvalue = 0.0); -/* Generates random floating point number from a to b. */ -native Float:random_float(Float:a,Float:b); +/** + * Returns a random floating point value generated by the engine. + * + * @param a,b Range of generated value, inclusive + * + * @return Generated random value + */ +native Float:random_float(Float:a, Float:b); -/* Generates random integer from a to b. */ -native random_num(a,b); +/** + * Returns a random integer value generated by the engine. + * + * @param a,b Range of generated value, inclusive + * + * @return Generated random value + */ +native random_num(a, b); -/* Returns id of client message. -* Example: get_user_msgid("TextMsg"). */ +/** + * Returns unique id of a client message + * + * @note Example usage: get_user_msgid("TextMsg") + * @note The message id is unique as long as the server is running, but might + * change between updates. They should not be hardcoded into plugins. + * + * @param name Client message name + * + * @return Message id, 0 if message was not found + */ native get_user_msgid(const name[]); -/* Gets name of client message index. Return value is number of -* characters copied into name. Returns 0 on invalid msgid. */ +/** + * Retrieves the client message name from a message id. + * + * @param msgid Client message id + * @param name Buffer to copy message name to + * @param len Maximum buffer size + * + * @return Number of cells written to buffer, 0 on invalid message id + */ native get_user_msgname(msgid, name[], len); -/* Checks if public variable with given name exists in loaded plugins. */ -native xvar_exists( const name[] ); +/** + * Returns a unique id for a public variable. + * + * @note Variables declared with the "public" specifier are accessible by-name + * from outside of the declaring plugin. + * @note If multiple plugins declare the same public variable this native will + * still return a unique id. + * + * @param name Variable name + * + * @return Xvar id on success, -1 on failure + */ +native get_xvar_id(const name[]); -/* Returns an unique id for public variable specified by name. If such -* variable doesn't exist then returned value is -1. */ -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 an integer value of a public variable. Id is a value -* returned by get_xvar_id(...) native. */ -native get_xvar_num( id ); +/** + * 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 a float value of a public variable. Id is a value -* returned by get_xvar_id(...) native. */ -native Float:get_xvar_float( 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 a value of a public variable. Id is a value -* returned by get_xvar_id(...) native. */ -native set_xvar_num( id, value = 0 ); +/** + * 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 a float value of a public variable. Id is a value -* returned by get_xvar_id(...) native. */ -native set_xvar_float( id, Float:value = 0.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); -/* Checks whether a module is loaded. If it is not, the return value is -1, otherwise -* the return value is the module id. The function is case insensitive. */ +/** + * Returns if a module is loaded. + * + * @param name Module name + * + * @return Module id of the matching module, -1 otherwise + */ native is_module_loaded(const name[]); - -/* Gets info about a module. -* Parameters: -* id - the id of the module -* name[] - The name of the module will be stored here -* nameLen - maximal length of the name -* author[] - the author will be stored here -* authorLen - maximal length of the author -* version[] - the version of the module will be stored here -* versionLen - maximal length of the version -* status - the status of the module will be stored here -* Return value: -* id - success -* -1 - module not found */ +/** + * 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 + */ +/** + * 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 number of currently registered modules */ +/** + * Returns the number of currently registered modules. + * + * @return Number of modules + */ native get_modulesnum(); /** - * Checks whether a plugin is loaded by the given registered name (such as "Admin Base"), or, optionally - * the given filename ("admin.amxx"). + * Returns if a plugin is loaded by registered name or filename. * - * @param name Either the plugin name to lookup, or the plugin filename to lookup. - * @param usefilename Set to true if you want to search for the plugin by the filename, false to search - * by the plugin's registered name. + * @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. * - * @return Plugin ID of the matching plugin on a successful search, -1 on a failed search. + * @param name Plugin name or filename + * @param usefilename If true searches for plugin filename, false searches for + * plugin name * - * @note Prior to 1.8, this function would only search for plugins registered names, not - * the filename. - * - * @note The plugin registered name search is a case insensitive search, however, the plugin - * filename search is case sensitive. + * @return Plugin id of the matching plugin, -1 otherwise */ native is_plugin_loaded(const name[], bool:usefilename=false); @@ -1929,25 +2087,45 @@ native get_plugin(index,filename[]="",len1=0,name[]="",len2=0,version[]="",len3= */ native get_pluginsnum(); -/* Pauses function or plugin so it won't be executed. -* In most cases param1 is name of function and -* param2 name of plugin (all depends on flags). -* Flags: -* "a" - pause whole plugin. -* "c" - look outside the plugin (by given plugin name). -* "d" - set "stopped" status when pausing whole plugin. -* In this status plugin is unpauseable. -* Example: pause("ac","myplugin.amxx") -* -* Note: There used to be the b and e flags as well, -* which have been deprecated and are no longer used. -*/ +/** + * 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 function or plugin. -* Flags: -* "a" - unpause whole plugin. -* "c" - look outside the plugin (by given plugin name). */ +/** + * 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[]=""); /** @@ -2095,12 +2273,32 @@ native callfunc_push_array(const VALUE[], array_size, bool:copyback=true); */ native callfunc_end(); -/* Called on inconsistent file. You can put any text -* into reason to change an original message. */ +/** + * Called when an inconsistent file is encountered by the engine. + * + * @param id Client index + * @param filename Detected file + * @param reason Buffer storing the disconnect reason (can be overwritten) + * + * @return PLUGIN_CONTINUE to let the engine kick the client + * PLUGIN_HANDLED to block the inconsistency kick + */ forward inconsistent_file(id,const filename[], reason[64] ); -/* Forces the client and server to be running with the same -* version of the specified file ( e.g., a player model ). */ +/** + * Forces the clients and server to be running with the same version of a + * specified file. + * + * @note For a list of possible enforcement types see the force_* constants + * in amxconst.inc + * + * @param force_type Enforcement type + * @param mins Bounding box mins vector + * @param maxs Bounding box maxs vector + * @param filename Filename + * + * @return 1 on success, 0 otherwise + */ native force_unmodified(force_type, const mins[3] , const maxs[3], const filename[]); /** @@ -2124,27 +2322,63 @@ native md5(const szString[], md5buffer[34]); */ native md5_file(const file[], md5buffer[34]); -/* Returns the internal flags set on the plugin's state - * If hdr is 1, it will return the pcode flags rather than state flags. +/** + * Returns the internal flags set on the plugin's state. * - * Use a plid of -1 to get the flags for the calling plugin. + * @param hdr If nonzero the function will return the pcode rather than + * state flags + * @param plid Plugin id, -1 to target calling plugin */ native plugin_flags(hdr=0, plid=-1); /** - * @deprecated - * Do not use! + * 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 searched by file/name. Returns INVALID_PLUGIN_ID on failure. */ +/** + * Returns plugin id by filename. + * + * @param filename Filename to match + * @param ignoreCase If nonzero matches case insensitively, case sensitively + * otherwise + * + * @return Plugin id, -1 (INVALID_PLUGIN_ID) on failure + */ native find_plugin_byfile(const filename[], ignoreCase=1); -/* This is called before plugin_init and allows you to register natives. */ +/** + * Called before plugin_init(), allowing the plugin to register natives. + * + * @noreturn + */ forward plugin_natives(); /* Registers a NATIVE. When a plugin uses your native (you should distribute a .inc), @@ -2300,31 +2534,64 @@ native set_native_filter(const handler[]); native set_module_filter(const handler[]); /** - * Aborts execution of the current callback. Your script will throw a run time error. - * You can also specify an optional message. - * You should NOT call this function inside: - * - Error or module filters (native filters are safe if trap is 1) - * - plugin_natives() - * Note that the plugin's filename is prepending to your message: - * [myplugin.amxx] MESSAGE + * 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:...); /** - * Checks if a specific module is loaded. This is the exact same method AMX Mod X - * uses to see if a module is required by a plugin. For example: - * module_exists("cstrike") - * module_exists("dbi") + * 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[]); /** - * Checks if a library/class is loaded. This is the newer version of module_exists. + * Returns if a specific library or class is loaded. + * + * @note This is the newer version of module_exists(), enabling users to + * distinguish between libraries and classes while module_exists() always + * checks for both types. + * @note For a list of possible types see the LibType enum in amxconst.inc + * + * @param library Library/Class shortname + * @param type Type to search for + * + * @return 1 if module is loaded, 0 otherwise */ native LibraryExists(const library[], LibType:type); /** - * Returns the next valid hudchannel for a user, from 1-4. + * Returns the next valid hudchannel for the client. + * + * @note This function uses the same method set_hudmessage() uses to determine + * the next channel if it is set to auto-select. + * + * @param player Client index + * + * @return Valid hudchannel (1-4) + * @error If the index is not within the range of 1 to MaxClients or + * the client is not connected an error will be thrown. */ native next_hudchannel(player); @@ -2340,81 +2607,205 @@ native next_hudchannel(player); * clear a message from another plugin. * The parameters are kept blank for future use. */ +/** + * Creates a HUD synchronization object. + * + * @note Create one of these for each section of the screen that contains + * overlapping HUD messages. For example, if you use both sides of the + * screen to display three messages that could potentially overlap, + * each side is considered a synchronizable area. You can then use + * ShowSyncHudMsg() to correctly synchronize displaying the HUD message + * with any other messages potentially in its class. + * @note This does not do anything like reserving screen area. Its sole + * purpose is to be able to wipe an old message on an auto-channel and + * ensure that it will not clear a message from another plugin. + * + * @param num Unused and ignored + * @param ... Unused and ignored + * + * @return HUD sync object handle + */ native CreateHudSyncObj(num=0, ...); /** - * Displays a synchronized HUD message. This will check that your - * HUD object has its previous display on the screen cleared before - * it proceeds to write another. It will only do this in the case - * of that channel not having been cleared already. - * Target can be 0 for all players or 1-get_maxplayers(). - * You must use set_hudmessage, although the channel parameter is - * entirely ignored. + * 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 HudSync Object. This is essentially the same - * thing as: ShowSyncHudMsg(x, y, ""), except doing that would send - * out two messages and use up another channel. This re-uses the last - * channel and clears it at the same time. - * Note: for this you do not have to use set_hudmessage(). - * Note: target can be 0 for all players. + * 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); -//no +/** + * Triggers the software interrupt 3, used for breaking into an attached + * debugger. + * + * @note Warning: This is a debugging function that is not intended for general + * plugin use. Using this function will either halt the server and break + * into the attached debugger, or outright crash the server if no + * debugger is attached. + * + * @noreturn + */ native int3(); -//Sets your plugin to a failed/error state. -//If you use this, your plugin will cease operating. -//This is a good idea to fatally, but gracefully, handle errors. -//You can set a failed error message. +/** + * 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. -//This address is local to the plugin, and not a full CPU address -//pass the variable as the first parameter +/** + * 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. This dereferences something returned by -// get_var_addr(). Attempting to pass in a value beyond stack or heap limits -// will result in AMX_ERR_MEMACCESS. +/** + * 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. same as above, essentially +/** + * Sets the value of an address. + * + * @note Addresses can be acquired using get_var_addr(). + * + * @param addr Variable address + * @param val Value to set + * + * @error If the plugin attempts to access an address outside of the + * stack or heap limits of the plugin, an error will be thrown. + */ native set_addr_val(addr, val); - /** - * Creates a multi-plugin forward. - * Stop type must be one of the ET_ values in amxconst.inc - * results will be > 0 for success + * 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 forward for one plugin. - * Results will be > 0 for success. - * id should be an id such as returned by find_plugin_byfile. - * Unlike get_plugin(), negative numbers will not work. + * 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. use this and pass the result into - * ExecuteForward() instead of the array itself. + * 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. returns result in ret. - * returns 1 for success, 0 for failure. + * 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/deallocates any type of forward + * Destroys and deallocates a forward. + * + * @note Does not distinguish between private and global forwards. + * + * @param forward_handle Forward handle + * + * @noreturn */ native DestroyForward(forward_handle); @@ -2534,8 +2925,13 @@ native set_pcvar_string(pcvar, const string[]); native arrayset(array[], value, size); /** - * Returns the weapon id, otherwise 0 when no id found. - * The weapon name is case sensitive, and has the weapon_* form. + * 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[]); From 9a0a52b7b273e10fe146e11097206b2a325c61db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 00:46:16 +0200 Subject: [PATCH 18/27] amxmodx: Fix typos, touch up some descriptions, remove/merge lonely comments --- plugins/include/amxmodx.inc | 52 ++++++++++--------------------------- 1 file changed, 13 insertions(+), 39 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 79b7bb03..5cb45829 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -1847,7 +1847,7 @@ native server_exec(); native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pitch); /** - * Registers a new ccvar for the engine. + * 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. @@ -1857,7 +1857,7 @@ native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pi * @param name Cvar name * @param string Default cvar value * @param flags Cvar flags - * @param fvalue + * @param fvalue Unused * * @return Unique cvar pointer */ @@ -1866,7 +1866,8 @@ 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,b Range of generated value, inclusive + * @param a Minimum value (inclusive) + * @param b Maximum value (inclusive) * * @return Generated random value */ @@ -1875,7 +1876,8 @@ native Float:random_float(Float:a, Float:b); /** * Returns a random integer value generated by the engine. * - * @param a,b Range of generated value, inclusive + * @param a Minimum value (inclusive) + * @param b Maximum value (inclusive) * * @return Generated random value */ @@ -1996,25 +1998,7 @@ native set_xvar_float(id, Float:value = 0.0); * @return Module id of the matching module, -1 otherwise */ native is_module_loaded(const name[]); -/** - * 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 - */ + /** * Retrieves info about a module by module index. * @@ -2491,9 +2475,11 @@ native dbg_fmt_error(buffer[], maxLength); * 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, @@ -2595,18 +2581,6 @@ native LibraryExists(const library[], LibType:type); */ native next_hudchannel(player); -/** - * Creates a HUD Synchronization Object. 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 can potentially overlap, each side counts as a synchronizable area. - * You can then use ShowSyncHudMsg() to correctly synchronize displaying the - * HUD message with any other messages potentially in its class. Note that this - * does not yet do anything like reserve 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. - * The parameters are kept blank for future use. - */ /** * Creates a HUD synchronization object. * @@ -2994,5 +2968,5 @@ native admins_flush(); native bool:has_map_ent_class(const classname[]); -// Keep this always at the bottom of this file +// Always keep this at the bottom of this file #include From c1ed795196f149c706b274e420e27cdeb9dac119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 00:51:17 +0200 Subject: [PATCH 19/27] sockets: Convert file to UTF-8 --- plugins/include/sockets.inc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/include/sockets.inc b/plugins/include/sockets.inc index 7eda92b0..aba6df8d 100755 --- a/plugins/include/sockets.inc +++ b/plugins/include/sockets.inc @@ -2,10 +2,10 @@ * * AMX Mod X Module * Basic Socket Functions - * + * * Codebase from Ivan, -g-s-ivan@web.de (AMX 0.9.3) * Modification by Olaf Reusch, kenterfie@hlsw.de (AMXX 0.16, AMX 0.96) - * + * */ #if defined _socket_included @@ -36,7 +36,7 @@ * 0 - no error * 1 - error while creating socket * 2 - couldn't resolve hostname - * 3 - couldn't connect to given hostname:port + * 3 - couldn't connect to given hostname:port */ native socket_open(const _hostname[], _port, _protocol = SOCKET_TCP, &_error); @@ -58,7 +58,7 @@ native socket_send(_socket, const _data[], _length); native socket_send2(_socket, const _data[], _length); /* This function will return true if the state (buffer content) have changed within the last recieve or -* the timeout, where timeout is a value in µSeconds, (1 sec =1000000 µsec). +* the timeout, where timeout is a value in µSeconds, (1 sec =1000000 µsec). * Use to check if new data is in your socket. */ native socket_change(_socket, _timeout=100000); From 88b69ea8a1db8196382a3485f7f2bd6eda5d41b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 01:46:11 +0200 Subject: [PATCH 20/27] amxmodx: Update change_level doc for consistency --- plugins/include/amxmodx.inc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index b853c394..30dbc1d9 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -250,14 +250,15 @@ native precache_sound(const name[]); native precache_generic(const szFile[]); /** - * Changes map. + * Changes the map. * * @note This calls the pfnChangelLevel engine function. - * @note This has the same behavior as calling the "changelevel" server command, - * but this will also trigger the server_changelevel() forward in AMXX plugins. - * It will also notify any Metamod plugins that are hooking pfnChangeLevel. + * @note This has the same behavior as using the "changelevel" server command, + * but will also trigger the server_changelevel() forward in AMXX + * plugins. It will also notify any Metamod plugins that are hooking + * the pfnChangeLevel function. * - * @param map The map name to change. + * @param map Map name to change to * * @noreturn */ From bbffcbf739f671bdb3892e69e6c19792e0985f31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 21:17:45 +0200 Subject: [PATCH 21/27] cellarray: Update lying ArrayCreate doc --- plugins/include/cellarray.inc | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc index 09d4444f..1ea1b3ef 100644 --- a/plugins/include/cellarray.inc +++ b/plugins/include/cellarray.inc @@ -1,12 +1,12 @@ -// vim: set ts=4 sw=4 tw=99 noet: -// -// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO"). -// Copyright (C) The AMX Mod X Development Team. -// -// This software is licensed under the GNU General Public License, version 3 or higher. -// Additional exceptions apply. For full license details, see LICENSE.txt or visit: -// https://alliedmods.net/amxmodx-license - +// vim: set ts=4 sw=4 tw=99 noet: +// +// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO"). +// Copyright (C) The AMX Mod X Development Team. +// +// This software is licensed under the GNU General Public License, version 3 or higher. +// Additional exceptions apply. For full license details, see LICENSE.txt or visit: +// https://alliedmods.net/amxmodx-license + #if defined _cellarray_included #endinput #endif @@ -53,15 +53,19 @@ stock ByteCountToCells(size) * * @note It is very important that the provided cellsize matches up with the * buffer sizes that you pass with subsequent Array[Get|Set|Push] calls. + * @note Initially the "reserved" parameter was intended to create blank entries + * that would immediately be usable with Array[Get|Set] functions. This + * functionality was never working as intended, and can now be achieved + * using ArrayResize(). * * @param cellsize Size of each array entry in cells - * @param reserver Amount of blank entries that are inserted immediately - * upon creation of the array. These are not readable until - * initialized with an ArraySet* function. + * @param reserved Pre-allocates space in the array for the specified + * number of items. The items are not valid to read or set + * until they have actually been pushed into the array. * * @return Handle to the array. */ -native Array:ArrayCreate(cellsize = 1, reserved = 0); +native Array:ArrayCreate(cellsize = 1, reserved = 32); /** * Clones an array, returning a new handle with the same size and data. From 4231c5a6aea763e9d08410d46358abab9b8d67af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 21:26:37 +0200 Subject: [PATCH 22/27] amxmodx: Sixth and final batch of documentation updates --- plugins/include/amxmodx.inc | 716 ++++++++++++++++++++++++++++-------- 1 file changed, 564 insertions(+), 152 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 30dbc1d9..1a727ea4 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -108,7 +108,7 @@ forward plugin_end(); forward plugin_log(); /** - * This forward allows you to add models, sounds and generic files to the + * This forward allows plugins 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 @@ -277,7 +277,7 @@ native change_level(const map[]); * @error If called outside of the plugin_precache() forward, an error * is thrown. */ -native set_user_info(index,const info[], const value[]); +native set_user_info(index, const info[], const value[]); /** * Gets info from the client. @@ -434,8 +434,8 @@ native console_cmd(id, const cmd[], any:...); * "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". + * plugins, the client id should be checked for alive/dead state if using + * flags "d" or "e". * * @param event Name of event that should be hooked * @param function Name of callback function @@ -523,7 +523,7 @@ native register_logevent(const function[], argsnum, ...); * * @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); +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. @@ -575,7 +575,7 @@ native set_dhudmessage(red=200, green=100, blue=0, Float:x=-1.0, Float:y=0.35, e * @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 + * once, if more are added they will be overwritten 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. @@ -643,7 +643,7 @@ native show_menu(index, keys, const menu[], time = -1, const title[] = ""); * If two additional parameters are provided, the function * will return the number of cells written to the buffer. */ -native read_data(value, any:... ); +native read_data(value, any:...); /** * Returns the number of values in the client message. @@ -675,7 +675,7 @@ native read_datatype(); * @error If called outside of the plugin_log() forward, an error is * thrown. */ -native read_logdata(output[],len); +native read_logdata(output[], len); /** * Returns number of log message arguments. @@ -1114,7 +1114,7 @@ native get_user_name(index, name[], len); * * @return Number of cells written to buffer */ -native get_user_authid(index, authid[] ,len); +native get_user_authid(index, authid[], len); /** * Returns the userid of a client. @@ -1304,7 +1304,7 @@ native get_flags(flags, output[], len); * @param ... String to match against (integer if "k" flag is specified) * */ -native find_player(const flags[], ... ); +native find_player(const flags[], ...); /** * Removes double-quotes from the beginning and end of a string. @@ -1398,7 +1398,7 @@ native amxclient_cmd(index, const command[], const arg1[] = "", const arg2[] = " * * @noreturn */ -native server_cmd(const command[],any:...); +native server_cmd(const command[], any:...); /** * Sets a cvar to a given string value. The cvar is accessed by name. @@ -1775,65 +1775,255 @@ native get_user_flags(index, id=0); */ 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. +/** + * Registers a callback to be called when the client executes a command from the + * console. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * @note Opting in to FlagManager enables the admin privileges to be overwritten + * by the end user via the cmdaccess.ini config file. + * @note Automatic detection for FlagManager will only include a command if it + * has required privileges (flags is not -1) and it is not a command + * starting with "say". + * + * @param client_cmd Command to register + * @param function Callback function + * @param flags Admin privilege flags required + * @param info Command description + * @param FlagManager 0 opts out of flag manager, 1 opts in, -1 selects + * automatically + * + * @return Command id, 0 on failure + * @error If an invalid callback function is specified, an error + * will be thrown. */ 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. +/** + * Registers a callback to be called when the client or server executes a + * command from the console. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * @note Opting in to FlagManager enables the admin privileges to be overwritten + * by the end user via the cmdaccess.ini config file. + * @note Automatic detection for FlagManager will only include a command if it + * has required privileges (flags is not -1) and it is not a command + * starting with "say". + * + * @param client_cmd Command to register + * @param function Callback function + * @param flags Admin privilege flags required + * @param info Command description + * @param FlagManager 0 opts out of flag manager, 1 opts in, -1 selects + * automatically + * + * @return Command id, 0 on failure + * @error If an invalid callback function is specified, an error + * will be thrown. */ 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. +/** + * Registers a callback to be called when the server executes a command from the + * console. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param client_cmd Command to register + * @param function Callback function + * @param flags Admin privilege flags required + * @param info Command description + * + * @return Command id, 0 on failure + * @error If an invalid callback function is specified, an error + * will be thrown. */ native register_srvcmd(const server_cmd[], const function[], flags=-1, const info[]=""); -/* Gets info about client command. */ +/** + * Retrieves information about a client command. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param index Command index + * @param command Buffer to copy command name to + * @param len1 Maximum name buffer size + * @param flags Variable to store privilege flags to + * @param info Buffer to copy command description to + * @param len2 Maximum description buffer size + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * + * @return 1 on succes, 0 if command was not found + */ native get_clcmd(index, command[], len1, &flags, info[], len2, flag); -/* Returns number of registered client commands. */ +/** + * Returns number of registered client commands. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * + * @return Number of registered client commants + */ native get_clcmdsnum(flag); -/* Gets info about server command. */ -native get_srvcmd(index,server_cmd[],len1,&flags, info[],len2, flag); +/** + * Retrieves information about a server command. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param index Command index + * @param command Buffer to copy command name to + * @param len1 Maximum name buffer size + * @param flags Variable to store privilege flags to + * @param info Buffer to copy command description to + * @param len2 Maximum description buffer size + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * + * @return 1 on succes, 0 if command was not found + */ +native get_srvcmd(index, server_cmd[], len1, &flags, info[], len2, flag); -/* Returns number of registered server commands. */ +/** + * Returns number of registered server commands. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * + * @return Number of registered server commants + */ 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); +/** + * Retrieves information about a console command. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param index Command index + * @param command Buffer to copy command name to + * @param len1 Maximum name buffer size + * @param flags Variable to store privilege flags to + * @param info Buffer to copy command description to + * @param len2 Maximum description buffer size + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * @param id If set to 0 only server commands will be considered, + * positive will only consider client commands, otherwise + * all console commands will be considered. + * + * @return 1 on succes, 0 if command was not found + */ +native get_concmd(index, cmd[], len1, &flags, info[], len2, flag, id=-1); -/* Gets the parent plugin id of a console command. */ +/** + * Returns the parent plugin id of a console command + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param cid Command index + * @param flag_mask Only considers commands that can be accessed with + * the specified privilege flags. + * @param id_type If set to 0 only server commands will be considered, + * positive will only consider client commands, otherwise + * all console commands will be considered. + */ native get_concmd_plid(cid, flag_mask, id_type); -/* Returns number of registered console commands. */ -native get_concmdsnum(flag,id = -1); +/** + * Returns number of registered console commands. + * + * @note For a list of possible access flags see the ADMIN_* constans in + * amxconst.inc + * + * @param flag Only considers commands that can be accessed with + * the specified privilege flags. + * @param id If set to 0 only server commands will be considered, + * positive will only consider client commands, otherwise + * all console commands will be considered. + * + * @return Number of registered console commants + */ +native get_concmdsnum(flag, id = -1); -/* Returns the number of plugin-registered cvars. */ +/** + * Returns the number of plugin-registered cvars. + * + * @return Number of registered cvars + */ native get_plugins_cvarsnum(); -/* Returns information about a plugin-registered cvar. */ +/** + * Retrieves information about a plugin-registered cvar. + * + * @note The returned cvar pointer should be used with the get_pcvar_* and + * set_pcvar_* set of functions. + * + * @param num Cvar index, this does not equal the cvar pointer, it is + * the internal index, incremented for each registered cvar + * @param name Buffer to copy cvar name to + * @param namelen Maximum buffer size + * @param flags Variable to store cvar flags to + * @param plugin_id Variable to store id of the registering plugin to + * @param pcvar_handle Variable to store cvar pointer to + * + * @return 1 on success, 0 if index is invalid + */ 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 ); +/** + * Returns unique menu id of a menu. + * + * @param menu Menu name + * @param outside Catch menus outside the calling plugin + * + * @return Menu id + */ +native register_menuid(const menu[], outside=0); -/* Calls function when player uses specified menu and proper keys. */ -native register_menucmd(menuid,keys, const function[] ); +/** + * Registers a callback function to a menu id and keys. + * + * @param menuid Menu id + * @param keys Key flags + * @param function Callback function + * + * @noreturn + * @error If an invalid callback function is specified, an error + * will be thrown. + */ +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); +/** + * Returns if the client is watching a menu. + * + * @note If there is no menu the id is 0. If the id is negative then the client + * views a VGUI menu. Otherwise the id is an id acquired from the + * register_menuid() function. + * + * @param index Client index + * @param id Variable to store menu id to + * @param keys Variable to store menu keys to + * + * @return 1 if client views a menu, 0 otherwise + * @error If the client index is not within the range of 1 to + * MaxClients, an error will be thrown. + */ +native get_user_menu(index, &id, &keys); /** * Forces the server to execute the command queue immediately. @@ -1862,7 +2052,7 @@ native server_exec(); * @param flags Emit flags * @param pitch Sound pitch */ -native emit_sound(index, channel, const sample[], Float:vol, Float:att,flags, pitch); +native emit_sound(index, channel, const sample[], Float:vol, Float:att, flags, pitch); /** * Registers a new cvar for the engine. @@ -2080,7 +2270,7 @@ native is_plugin_loaded(const name[], bool:usefilename=false); * @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,...); +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. @@ -2107,7 +2297,7 @@ native get_pluginsnum(); * @error If it is attempted to use the deprecated functionality, * an error is thrown. */ -native pause(const flag[], const param1[]="",const param2[]=""); +native pause(const flag[], const param1[]="", const param2[]=""); /** * Unpauses a plugin so it will resume execution if it was previously paused. @@ -2128,7 +2318,7 @@ native pause(const flag[], const param1[]="",const param2[]=""); * @error If it is attempted to use the deprecated functionality, * an error is thrown. */ -native unpause(const flag[], const param1[]="",const param2[]=""); +native unpause(const flag[], const param1[]="", const param2[]=""); /** * Initiates a function call to this or another plugin by function name. @@ -2285,7 +2475,7 @@ native callfunc_end(); * @return PLUGIN_CONTINUE to let the engine kick the client * PLUGIN_HANDLED to block the inconsistency kick */ -forward inconsistent_file(id,const filename[], reason[64] ); +forward inconsistent_file(id, const filename[], reason[64]); /** * Forces the clients and server to be running with the same version of a @@ -2301,7 +2491,7 @@ forward inconsistent_file(id,const filename[], reason[64] ); * * @return 1 on success, 0 otherwise */ -native force_unmodified(force_type, const mins[3] , const maxs[3], const filename[]); +native force_unmodified(force_type, const mins[3], const maxs[3], const filename[]); /** * Calculates the MD5 keysum of a string. @@ -2377,163 +2567,385 @@ native is_amd64_server(); native find_plugin_byfile(const filename[], ignoreCase=1); /** - * Called before plugin_init(), allowing the plugin to register natives. + * Called before plugin_init(), allows 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! +/** + * Registers a native. + * + * @note Stlye 0 natives call the handler in the following manner: + * + * public native_handler(plugin_id, argc) + * + * plugin_id - plugin calling the native + * argc - number of parameters + * + * @note Style 1 natives are deprecated. Plugins should not use them, they might + * break. + * @note Style 1 natives work a little different. Instead of passing plugin id + * and number of parameters the handler should be prototyped just like the + * native would be called. For each by-reference parameter the plugin + * then has to use param_convert() to properly use them. + * @note A native should *never* recurse. Bad things will happen. + * + * @param name Native name + * @param handler Callback function + * @param style Native style + * + * @noreturn + * @error If an invalid callback is specified, an error is thrown. */ 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 - * #if !defined AMXMODX_NOAUTOLOAD - * #pragma loadlib - * #endif +/** + * Registers the plugin as a library. + * + * @note To mark a library as required, place the following in the include + * file: + * #pragma reqlib + * #if !defined AMXMODX_NOAUTOLOAD + * #pragma loadlib + * #endif + * + * @noreturn */ 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. +/** + * Logs an error in the native and breaks into the AMXX debugger. + * + * @note This acts as if the calling plugin - the plugin that is calling the + * native, not the plugin calling this function - triggered the error, + * just like when AMXX natives error. + * + * @param error Error number + * @param fmt Formatting rules + * @param ... Variable number of formatting parameters + * + * @noreturn + * @error The function is guaranteed to throw an error, but will make + * it appear as if the plugin calling the native triggered it. */ 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. +/** + * Converts a parameter to work as a by-reference parameter. + * + * @deprecated Style 1 natives are deprecated and should be converted to + * style 0. This should not be used. + * + * @note Only needs to be called this if the native was registered with style 1. + * @note Remember that arrays (and strings) are always by-reference and need to + * be converted. + * + * @param num Argument to convert, starting from 1 + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 0, an error will be thrown. + */ native param_convert(num); -// Gets a string from the calling plugin +/** + * Retrieves a string from the plugin calling the native. + * + * @param param Argument to retrieve, starting from 1 + * @param dest Buffer to copy string to + * @param maxlen Maximum size of buffer + * + * @return Number of cells copied to buffer + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ native get_string(param, dest[], maxlen); -// Sets a string in the calling plugin +/** + * Copies a string to the plugin calling the native. + * + * @param param Argument to set, starting from 1 + * @param dest Buffer to copy string from + * @param maxlen Maximum size of buffer + * + * @return Number of cells copied from buffer + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ native set_string(param, dest[], maxlen); -// Gets a normal int or float parameter +/** + * Returns the integer value of a parameter from the plugin calling the native. + * + * @param param Argument to retrieve, starting from 1 + * + * @return Integer value + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ 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: + * Returns the float value of a parameter from the plugin calling the native. + * + * @param param Argument to retrieve, starting from 1 + * + * @return Float value + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native Float:get_param_f(param); + +/** + * Returns the integer value of a by-reference parameter from the plugin calling + * the native. + * + * @param param Argument to retrieve, starting from 1 + * + * @return Integer value + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native get_param_byref(param); + +/** + * Returns the float value of a by-reference parameter from the plugin calling + * the native. + * + * @param param Argument to retrieve, starting from 1 + * + * @return Float value + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native Float:get_float_byref(param); + +/** + * Sets the integer value of a by-reference parameter to the plugin calling the + * native. + * + * @param param Argument to set, starting from 1 + * @param value Value to set parameter to + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native set_param_byref(param, value); + +/** + * Sets the float value of a by-reference parameter to the plugin calling the + * native. + * + * @param param Argument to set, starting from 1 + * @param value Value to set parameter to + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native set_float_byref(param, Float:value); + +/** + * Retrieves an array from the plugin calling the native. + * + * @param param Argument to retrieve, starting from 1 + * @param dest Buffer to copy array to + * @param maxlen Size of buffer + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native get_array(param, dest[], size); + +/** + * Retrieves a float array from the plugin calling the native. + * + * @param param Argument to retrieve, starting from 1 + * @param dest Buffer to copy array to + * @param maxlen Size of buffer + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native get_array_f(param, Float:dest[], size); + +/** + * Copies an array to the plugin calling the native. + * + * @param param Argument to set, starting from 1 + * @param source Buffer to copy array from + * @param maxlen Size of buffer + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native set_array(param, const source[], size); + +/** + * Copies a float array to the plugin calling the native. + * + * @param param Argument to set, starting from 1 + * @param source Buffer to copy array from + * @param maxlen Size of buffer + * + * @noreturn + * @error If used outside of a native callback or the native was + * created with style 1, an error will be thrown. + */ +native set_array_f(param, const Float:source[], size); + +/** + * Dispatches a client cvar query, allowing the plugin to query for its value on + * the client. + * + * @note The callback will be called in the following manner: + * + * public cvar_query_callback(id, const cvar[], const value[], const param[]) + * + * id - Client index + * cvar - Cvar queried + * value - Cvar value on the client + * param - Extra data [optional] + * + * @param id Client index + * @param cvar Cvar to query + * @param resultFunc Callback function + * @param paramlen Size of extra data + * @param params Extra data to pass through to callback + * + * @noreturn + * @error If the client index is not within the range of 1 to + * MaxClients or the client is not connected, an error + * will be thrown. + * If the callback function is invalid, cvar querying is + * unavailable or the querying process runs out of memory, + * an error will be thrown. + */ +native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[] = ""); + +/** + * Allows to trap error messages that occur in a plugin. + * + * @note This can be used to override the debug messages that occur when the + * plugin causes some kind of runtime error. + * @note The handler will be called in the following manner: * * 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. + * + * error_code - AMX_ERR_* code. + * debugging - True if the plugin is in debug mode, false otherwise + * message[] - Message sent along with the error + * + * @note The handler should return PLUGIN_CONTINUE to let the error through the + * filter, or PLUGIN_HANDLED to block the error from displaying. + * + * @param handler Callback function + * + * @error If an invalid callback is specified, an error is thrown. */ 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. + * Returns a trace handle for the item at the top of the traced call stack. + * + * @note Intended for use inside an error handler set with set_error_filter(). + * + * @return Trace handle, 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. + * Returns the next item in a traced call stack. + * + * @param trace Trace handle + * + * @return New trace handle, 0 if no more traces exist */ native dbg_trace_next(trace); /** - * Gets the call stack info for a trace. + * Retrieves the call stack info for a trace. + * + * @param trace Trace handle + * @param line Variable to set line at which plugin failed to + * @param function Buffer to copy function to + * @param maxLength1 Maximum function buffer size + * @param file Buffer to copy filename to + * @param maxLength2 Maximum filename buffer size + * + * @return 1 on success, 0 if no trace data is available */ native dbg_trace_info(trace, &line, function[], maxLength1, file[], maxLength2); /** - * Gets the formatted error string, which looks like "Run time error X: (description)" + * Retrieves the formatted error string from a trace. + * + * @note The string format is generally: "Run time error : " + * + * @param buffer Buffer to copy error message to + * @param maxLength Maximum buffer size + * + * @return 1 on success, 0 if no trace data is available */ 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, letting the plugin intercept and handle an + * automatic native requirement. * + * @note This has to be used inside the plugin_native() forward, otherwise it + * has no effect. + * @note This is useful for creating plugins that can dynamically decide which + * modules or features to use at runtime, often necessary for cross-mod + * plugins. It allows to deploy a single version of the plugin instead + * of compiling multiple versions for each use-case. + * @note The handler will be called in the following manner: * + * public native_filter(const native[], index, trap) * + * native - Native name + * index - Native index + * trap - 0 if native couldn't be found, 1 if native use was attempted * - * - * 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. + * @note The handler should return PLUGIN_CONTINUE to let the error through the + * filter (which will throw a run-time error), or return PLUGIN_HANDLED + * to continue operation. + * @note Returning PLUGIN_CONTINUE if trap is 0 will result in the plugin + * failing to load! */ 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. + * Sets a module/library filter, letting the plugin intercept and handle an + * automatic module requirement. * - * 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. + * @note This has to be used inside the plugin_native() forward, otherwise it + * has no effect. + * @note This is useful for creating plugins that can dynamically decide which + * modules or features to use at runtime, often necessary for cross-mod + * plugins. It allows to deploy a single version of the plugin instead + * of compiling multiple versions for each use-case. + * @note For a list of possible libtypes see the LibType enum in amxconst.inc + * @note The handler will be called in the following manner: * - * Your handler will be called with this prototype: + * public module_filter(const library[], LibType:type) * - * 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). + * library - Shortname of library or class that is required + * libtrype - Type of requirement being checked (library/module or class) * + * @note The handler should return PLUGIN_CONTINUE to let the error through the + * filter (which will result in the plugin failing to load), or + * PLUGIN_HANDLED to imply that load can continue without the module. + * @note Errors occuring inside the handler will not be filtered and cause the + * plugin to fail load as if the handler returned PLUGIN_CONTINUE. * - * set_module_filter() returns 0 on success (unlike most natives). + * @return 0 on success, -1 if filtering is not available, -2 if handler + * could not be found. */ native set_module_filter(const handler[]); @@ -2603,7 +3015,7 @@ 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 + * overlapping HUD messages. For example, if using 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 @@ -2622,7 +3034,7 @@ native CreateHudSyncObj(num=0, ...); /** * Displays a synchronized HUD message. * - * @note This will check that your HUD object has its previous display on the + * @note This will check that the 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. @@ -2804,7 +3216,7 @@ 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) + * @note A pointer is also returned by register_cvar(). Plugins can (and should) * retrieve and use pointers for already existing mod cvars. * * @param cvar Cvar name to find From 08315a4329670da0e24fe10862e513ffc83f2478 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 21:42:18 +0200 Subject: [PATCH 23/27] message_const: Move TE_USERTRACER example into the comment block --- plugins/include/message_const.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/include/message_const.inc b/plugins/include/message_const.inc index c0574cfb..b4ff53f7 100644 --- a/plugins/include/message_const.inc +++ b/plugins/include/message_const.inc @@ -1073,8 +1073,6 @@ enum * Larger message than the standard tracer, but allows some customization. * * @note - */ -#define TE_USERTRACER 127 * write_byte(TE_USERTRACER) * write_coord(origin.x) * write_coord(origin.y) @@ -1085,6 +1083,8 @@ enum * write_byte(life * 10) * write_byte(color) this is an index into an array of color vectors in the engine. (0 - ) * write_byte(length * 10) + */ +#define TE_USERTRACER 127 /** * @endsection From 20a173d8a34f4b370be6bfedb3abde5afbaa0133 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 21:49:56 +0200 Subject: [PATCH 24/27] amxmodx: Improve precache comments --- plugins/include/amxmodx.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 1a727ea4..f8d487a8 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -210,7 +210,7 @@ native register_plugin(const plugin_name[], const version[], const author[]); * * @param name Path to the model file * - * @return Cache id of the model, even if the file was already precached + * @return Unique ache id of the model * @error If called outside of the plugin_precache() forward, an error is * thrown. */ @@ -229,7 +229,7 @@ native precache_model(const name[]); * * @param name Path to the sound file * - * @return Cache id of the sound, even if the file was already precached + * @return Unique cache id of the sound * @error If called outside of the plugin_precache() forward, an error is * thrown. */ @@ -243,7 +243,7 @@ native precache_sound(const name[]); * * @param szFile Path to the file * - * @return Cache id of the file, even if the file was already precached + * @return Unique cache id of the file * @error If called outside of the plugin_precache() forward, an error * is thrown. */ From 8b42767b194617c8ffe89e36a4db33ba703b2798 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 22:01:21 +0200 Subject: [PATCH 25/27] amxmodx: Precaching documentation is the bane of my existence --- plugins/include/amxmodx.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index f8d487a8..7ebebdcb 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -210,7 +210,7 @@ native register_plugin(const plugin_name[], const version[], const author[]); * * @param name Path to the model file * - * @return Unique ache id of the model + * @return Unique cache id of the model * @error If called outside of the plugin_precache() forward, an error is * thrown. */ From a63042d961b4c77c043a7c5f6dccbf8f00f5abe6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 23:02:39 +0200 Subject: [PATCH 26/27] amxmodx/cellarray: Assorted consistency updates and typo fixes --- plugins/include/amxmodx.inc | 54 +++++++++++----------- plugins/include/cellarray.inc | 84 ++++++++++++++++++----------------- 2 files changed, 71 insertions(+), 67 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 7ebebdcb..4166c6e4 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -420,7 +420,7 @@ native console_print(id, const message[], any:...); * @param cmd Formatting rules * @param ... Variable number of formatting parameters * - * @return The length of the formatted command. + * @return Length of the formatted command */ native console_cmd(id, const cmd[], any:...); @@ -615,7 +615,7 @@ native show_dhudmessage(index, const message[], any:...); * @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[] = ""); +native show_menu(index, keys, const menu[], time=-1, const title[]=""); /** * Retrieves values from a client message. @@ -723,7 +723,7 @@ native read_logargv(id, output[], len); * @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); +native parse_loguser(const text[], name[], nlen, &userid=-2, authid[]="", alen=0, team[]="", tlen=0); /** * Sends a message to the console of the server. @@ -930,7 +930,7 @@ native get_user_deaths(index); native get_user_health(index); /** - * Retrieve a client's index by name. + * Retrieves a client's index by name. * * @param name Name to search for * @@ -948,7 +948,7 @@ native get_user_index(const name[]); * * @return Number of cells written to the buffer */ -native get_user_ip(index, ip[], len, without_port = 0); +native get_user_ip(index, ip[], len, without_port=0); /** * Returns if the client has the specified weapon in their inventory. @@ -1021,7 +1021,7 @@ native num_to_word(num, output[], len); * @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); +native get_user_team(index, team[]="", len=0); /** * Returns client's playing time in seconds. @@ -1033,7 +1033,7 @@ native get_user_team(index, team[]="", len = 0); * @return Connection time in seconds, 0 if client index is invalid or * client is not connected */ -native get_user_time(index, flag = 0); +native get_user_time(index, flag=0); /** * Retrieves the ping and loss of a client. @@ -1063,7 +1063,7 @@ native get_user_ping(index, &ping, &loss); * @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); +native get_user_origin(index, origin[3], mode=0); /** * Retrieves all weapons in the client inventory, stores them in an array and @@ -1374,7 +1374,7 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); * 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 command Client command to execute on * @param arg1 Optional command arguments * @param arg2 Optional command arguments * @@ -1382,7 +1382,7 @@ native engclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); * @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[] = ""); +native amxclient_cmd(index, const command[], const arg1[]="", const arg2[]=""); /** * Queues a command to be executed from the server console. @@ -1442,7 +1442,7 @@ native cvar_exists(const cvar[]); * * @return 1 on success, 0 if cvar does not exist or is not permitted */ -native remove_cvar_flags(const cvar[], flags = -1); +native remove_cvar_flags(const cvar[], flags=-1); /** * Sets specified flags to a cvar. The cvar is accessed by name. @@ -1635,7 +1635,7 @@ native get_time(const format[], output[], len); * @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); +native format_time(output[], len, const format[], time=-1); /** * Returns the system time as a unix timestamp (number of seconds since unix @@ -1646,7 +1646,7 @@ native format_time(output[], len, const format[], time = -1); * @return Unix time stamp * @error */ -native get_systime(offset = 0); +native get_systime(offset=0); /** * Converts time string to unix time stamp. @@ -1666,7 +1666,7 @@ native get_systime(offset = 0); * @return Unix time stamp * @error If the conversion process fails, an error will be thrown */ -native parse_time(const input[], const format[], time = -1); +native parse_time(const input[], const format[], time=-1); /** * Calls a function after a specified time has elapsed. @@ -1686,7 +1686,7 @@ native parse_time(const input[], const format[], time = -1); * @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); +native set_task(Float:time, const function[], id=0, const parameter[]="", len=0, const flags[]="", repeat=0); /** * Removes all tasks with the specified id. @@ -1696,7 +1696,7 @@ native set_task(Float:time, const function[], id = 0, const parameter[]="", len * * @return Number of removed tasks */ -native remove_task(id = 0, outside = 0); +native remove_task(id=0, outside=0); /** * Modifies the time interval of all tasks with the specified id. @@ -1707,7 +1707,7 @@ native remove_task(id = 0, outside = 0); * * @return Number of affected tasks */ -native change_task(id = 0, Float:newTime=1.0, outside = 0); +native change_task(id=0, Float:newTime=1.0, outside=0); /** * Returns if a task with the specified id exists. @@ -1717,7 +1717,7 @@ native change_task(id = 0, Float:newTime=1.0, outside = 0); * * @return 1 if a task was found, 0 otherwise */ -native task_exists(id = 0, outside = 0); +native task_exists(id=0, outside=0); /** * Sets the specified admin flags to a client. @@ -1958,7 +1958,7 @@ native get_concmd_plid(cid, flag_mask, id_type); * * @return Number of registered console commants */ -native get_concmdsnum(flag, id = -1); +native get_concmdsnum(flag, id=-1); /** * Returns the number of plugin-registered cvars. @@ -2069,7 +2069,7 @@ native emit_sound(index, channel, const sample[], Float:vol, Float:att, flags, p * * @return Unique cvar pointer */ -native register_cvar(const name[], const string[], flags = 0, Float:fvalue = 0.0); +native register_cvar(const name[], const string[], flags=0, Float:fvalue=0.0); /** * Returns a random floating point value generated by the engine. @@ -2180,7 +2180,7 @@ native Float:get_xvar_float(id); * @noreturn * @error If an invalid xvar id is specified an error will be thrown. */ -native set_xvar_num(id, value = 0); +native set_xvar_num(id, value=0); /** * Sets the float value of a public variable. @@ -2196,7 +2196,7 @@ native set_xvar_num(id, value = 0); * @noreturn * @error If an invalid xvar id is specified an error will be thrown. */ -native set_xvar_float(id, Float:value = 0.0); +native set_xvar_float(id, Float:value=0.0); /** * Returns if a module is loaded. @@ -2275,7 +2275,7 @@ native get_plugin(index, filename[]="", len1=0, name[]="", len2=0, version[]="", /** * Returns the number of loaded AMXX plugins. * - * @return The number of loaded plugins + * @return Number of loaded plugins */ native get_pluginsnum(); @@ -2358,10 +2358,10 @@ native callfunc_begin(const func[], const plugin[]=""); * @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); +native callfunc_begin_i(func, plugin=-1); /** - * Retrieve a functions id for use with callfunc_begin_i() + * Retrieves 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 @@ -2370,7 +2370,7 @@ native callfunc_begin_i(func, plugin = -1); * @return >0 Function id on success * -1 if plugin or function was not found */ -native get_func_id(const funcName[], pluginId = -1); +native get_func_id(const funcName[], pluginId=-1); /** * Pushes an int value onto the current call. @@ -2826,7 +2826,7 @@ native set_array_f(param, const Float:source[], size); * unavailable or the querying process runs out of memory, * an error will be thrown. */ -native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[] = ""); +native query_client_cvar(id, const cvar[], const resultFunc[], paramlen=0, const params[]=""); /** * Allows to trap error messages that occur in a plugin. diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc index 1ea1b3ef..3c52a233 100644 --- a/plugins/include/cellarray.inc +++ b/plugins/include/cellarray.inc @@ -52,7 +52,7 @@ stock ByteCountToCells(size) * Creates a handle to a dynamically sized array. * * @note It is very important that the provided cellsize matches up with the - * buffer sizes that you pass with subsequent Array[Get|Set|Push] calls. + * buffer sizes that are passed with subsequent Array[Get|Set|Push] calls. * @note Initially the "reserved" parameter was intended to create blank entries * that would immediately be usable with Array[Get|Set] functions. This * functionality was never working as intended, and can now be achieved @@ -73,7 +73,8 @@ native Array:ArrayCreate(cellsize = 1, reserved = 32); * @param which Array handle * * @return Handle to the cloned array on success, 0 otherwise - * @error If an invalid handle is provided an error will be thrown + * @error If an invalid handle is provided an error will be + * thrown. */ native Array:ArrayClone(Array:which); @@ -93,7 +94,8 @@ native ArrayClear(Array:which); * @param which Array handle * * @return Number of elements in the array - * @error If an invalid handle is provided an error will be thrown + * @error If an invalid handle is provided an error will be + * thrown. */ native ArraySize(Array:which); @@ -108,7 +110,7 @@ native ArraySize(Array:which); * * @noreturn * @error If an invalid handle is provided or the resizing - * operation runs out of memory, an error will be thrown + * operation runs out of memory, an error will be thrown. */ native bool:ArrayResize(Array:which, newsize); @@ -141,7 +143,7 @@ native ArrayGetArray(Array:which, item, any:output[], size = -1); * * @return Integer value * @error If an invalid handle, index or block is provided an - * error will be thrown + * error will be thrown. */ native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false); @@ -155,7 +157,7 @@ native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false); * * @return Number of characters copied * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayGetString(Array:which, item, output[], size); @@ -175,7 +177,7 @@ native ArrayGetString(Array:which, item, output[], size); * * @return Number of cells copied * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArraySetArray(Array:which, item, const any:input[], size =-1); @@ -194,7 +196,7 @@ native ArraySetArray(Array:which, item, const any:input[], size =-1); * * @noreturn * @error If an invalid handle, index or block is provided an - * error will be thrown + * error will be thrown. */ native ArraySetCell(Array:which, item, any:input, block = 0, bool:asChar = false); @@ -212,7 +214,7 @@ native ArraySetCell(Array:which, item, any:input, block = 0, bool:asChar = false * * @return Number of characters copied * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArraySetString(Array:which, item, const input[]); @@ -230,7 +232,7 @@ native ArraySetString(Array:which, item, const input[]); * * @return Index of the new entry * @error If an invalid handle is provided or the resizing - * operation runs out of memory, an error will be thrown + * operation runs out of memory, an error will be thrown. */ native ArrayPushArray(Array:which, const any:input[], size = -1); @@ -243,7 +245,7 @@ native ArrayPushArray(Array:which, const any:input[], size = -1); * * @return Index of the new entry * @error If an invalid handle is provided or the resizing - * operation runs out of memory, an error will be thrown + * operation runs out of memory, an error will be thrown. */ native ArrayPushCell(Array:which, any:input); @@ -259,7 +261,7 @@ native ArrayPushCell(Array:which, any:input); * * @return Index of the new entry * @error If an invalid handle is provided or the resizing - * operation runs out of memory, an error will be thrown + * operation runs out of memory, an error will be thrown. */ native ArrayPushString(Array:which, const input[]); @@ -273,7 +275,7 @@ native ArrayPushString(Array:which, const input[]); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertArrayAfter(Array:which, item, const any:input[]); @@ -283,11 +285,11 @@ native ArrayInsertArrayAfter(Array:which, item, const any:input[]); * * @param which Array handle * @param item Item index in the array - * @param input The value to set. + * @param input Value to set * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertCellAfter(Array:which, item, any:input); @@ -304,7 +306,7 @@ native ArrayInsertCellAfter(Array:which, item, any:input); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertStringAfter(Array:which, item, const input[]); @@ -318,7 +320,7 @@ native ArrayInsertStringAfter(Array:which, item, const input[]); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertArrayBefore(Array:which, item, const any:input[]); @@ -332,7 +334,7 @@ native ArrayInsertArrayBefore(Array:which, item, const any:input[]); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertCellBefore(Array:which, item, const any:input); @@ -349,7 +351,7 @@ native ArrayInsertCellBefore(Array:which, item, const any:input); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayInsertStringBefore(Array:which, item, const input[]); @@ -361,24 +363,24 @@ native ArrayInsertStringBefore(Array:which, item, const input[]); * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArraySwap(Array:which, item1, item2); /** * Deletes an item from the array. All items beyond it get shifted down by one. * - * @param which The array that contains the item to delete. - * @param item The item to delete. + * @param which Array handle + * @param item Item to delete * * @noreturn * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native ArrayDeleteItem(Array:which, item); /** - * Searches through the array and returns the index of the first occurance of + * Searches through the array and returns the index of the first occurence of * the specified string. * * @param which Array handle @@ -390,14 +392,15 @@ native ArrayDeleteItem(Array:which, item); native ArrayFindString(Array:which, const item[]); /** - * Searches through the array and returns the index of the first occurance of + * Searches through the array and returns the index of the first occurence of * the specified value. * - * @param which Array handle. + * @param which Array handle * @param item Value to search for * * @return Array index on success, -1 if the value can't be found - * @error Invalid handle. + * @error If an invalid handle is provided an error will be + * thrown. */ native ArrayFindValue(Array:which, any:item); @@ -416,7 +419,7 @@ native ArrayFindValue(Array:which, any:item); * * @return Handle to the item * @error If an invalid handle or an invalid index is provided an - * error will be thrown + * error will be thrown. */ native DoNotUse:ArrayGetStringHandle(Array:which, item); @@ -426,16 +429,15 @@ native DoNotUse:ArrayGetStringHandle(Array:which, item); * @note The function automatically sets the variable passed to it to 0 to aid * in preventing accidental usage after destroy. * - * @param which The array to destroy. + * @param which Array to destroy * * @return 1 if the array was destroyed, 0 if nothing had to be * destroyed (invalid handle) */ native ArrayDestroy(&Array:which); - /** - * Similar to sorting.inc's CustomSort, the sorting algorithm then uses your + * Similar to sorting.inc's CustomSort, the sorting algorithm then uses the * custom comparison function to sort the data. * * @note The function is called in the following manner: @@ -452,8 +454,8 @@ native ArrayDestroy(&Array:which); * 0 if item1 and item2 are equal * 1 if item1 should go after item2 * - * @note All parameters after item2 are optional and you do not need to specify - * and use them. + * @note All parameters after item2 are optional and do not need to be specified + * and used. * @note Unlike the sorting.inc version, the array passed to the callback is not * in mid-sorted state. * @@ -463,16 +465,17 @@ native ArrayDestroy(&Array:which); * @param data_size Size of extra data * * @noreturn - * @error Invalid handle or invalid callback. + * @error If an invalid handle or an invalid callback is provided + * an error will be thrown. */ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); /** - * A faster version of ArraySort, the sorting algorithm then uses your custom + * A faster version of ArraySort, the sorting algorithm then uses the custom * comparison function to sort the data. * * @note The advantage of this function is that the data of the elements being - * compared is directly passed to your function, instead of the item + * compared is directly passed to the function, instead of the item * indexes that are passed by ArraySort. This removes the need for calling * ArrayGet[Cell|String|Array] every time before being able to compare the * elements. @@ -492,7 +495,7 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); * * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * - * array - Array handle in its current un-sorted state. + * array - Array handle in its current un-sorted state * elem1[], elem2[] - Current element pair being compared * data[] - Extra data array passed to the sort func * data_size - Size of extra data @@ -503,8 +506,8 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); * 0 if elem1 and elem2 are equal * 1 if elem1 should go after elem2 * - * @note All parameters after item2 are optional and you do not need to specify - * and use them. + * @note All parameters after item2 are optional and do not need to be specified + * and used. * @note Unlike the sorting.inc version, the array passed to the callback is not * in mid-sorted state. * @@ -514,6 +517,7 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); * @param data_size Size of extra data * * @noreturn - * @error Invalid handle, invalid callback or out of memory. + * @error If an invalid handle or an invalid callback is provided + * an error will be thrown. */ native ArraySortEx(Array:array, const comparefunc[], data[]="", data_size=0); From b096f94ca4fc59f548f373c57a369eb3099a973e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Thu, 7 Aug 2014 23:13:03 +0200 Subject: [PATCH 27/27] amxconst: Purge tabs --- plugins/include/amxmodx.inc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/include/amxmodx.inc b/plugins/include/amxmodx.inc index 4166c6e4..7ca7a418 100755 --- a/plugins/include/amxmodx.inc +++ b/plugins/include/amxmodx.inc @@ -1351,10 +1351,10 @@ native client_cmd(index, const command[], any:...); * @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 + * @param index Client index, use 0 to execute from all clients. + * @param command 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 @@ -3391,9 +3391,9 @@ native admins_flush(); /** * Returns if a map contains at least one entity with the provided class name. * - * @param classname Entity classname to match + * @param classname Entity classname to match * - * @return True if an entity is found, false otherwise + * @return True if an entity is found, false otherwise */ native bool:has_map_ent_class(const classname[]);