wvusZJmU

1/*  SA-MP Functions
2 *
3 *  (c) Copyright 2005-2017, SA-MP Team
4 *
5 */
6
7#if defined _INC_a_samp
8	#endinput
9#endif
10#define _INC_a_samp
11#define _samp_included
12
13#define SAMP_CONST_CORRECT
14
15#pragma tabsize 4
16// Ignores warning 217 for properly indented PAWNO code
17// It's tab size is 4 and often uses 4 spaces instead, PAWNCC's is 8
18
19// --------------------------------------------------
20// Defines
21// --------------------------------------------------
22
23// Limits
24#if !defined MAX_PLAYER_NAME
25	#define MAX_PLAYER_NAME                    (24)
26#endif
27
28#if !defined MAX_PLAYERS
29	#define MAX_PLAYERS                        (1000)
30#endif
31
32#if !defined MAX_VEHICLES
33	#define MAX_VEHICLES                       (2000)
34#endif
35
36#if !defined MAX_ACTORS
37	#define MAX_ACTORS                         (1000)
38#endif
39
40#if !defined MAX_OBJECTS
41	#define MAX_OBJECTS                        (2000)
42#endif
43
44#if !defined MAX_GANG_ZONES
45	#define MAX_GANG_ZONES                     (1024)
46#endif
47
48#if !defined MAX_TEXT_DRAWS
49	#define MAX_TEXT_DRAWS                     (Text:2048)
50#endif
51
52#if !defined MAX_PLAYER_TEXT_DRAWS
53	#define MAX_PLAYER_TEXT_DRAWS              (PlayerText:256)
54#endif
55
56#if !defined MAX_MENUS
57	#define MAX_MENUS                          (Menu:128)
58#endif
59
60#if !defined MAX_3DTEXT_GLOBAL
61	#define MAX_3DTEXT_GLOBAL                  (Text3D:1024)
62#endif
63
64#if !defined MAX_3DTEXT_PLAYER
65	#define MAX_3DTEXT_PLAYER                  (PlayerText3D:1024)
66#endif
67
68#if !defined MAX_PICKUPS
69	#define MAX_PICKUPS                        (4096)
70#endif
71
72// Invalids
73#define NO_TEAM                                (255)
74
75#define INVALID_PLAYER_ID                      (0xFFFF)
76#define INVALID_VEHICLE_ID                     (0xFFFF)
77#define INVALID_ACTOR_ID                       (0xFFFF)
78#define INVALID_OBJECT_ID                      (0xFFFF)
79#define INVALID_MENU                           (Menu:0xFF)
80#define INVALID_TEXT_DRAW                      (Text:0xFFFF)
81#define INVALID_PLAYER_TEXT_DRAW               (PlayerText:0xFFFF)
82#define INVALID_GANG_ZONE                      (-1)
83#define INVALID_3DTEXT_ID                      (Text3D:0xFFFF)
84#define INVALID_PLAYER_3DTEXT_ID               (PlayerText3D:0xFFFF)
85
86// States
87#define PLAYER_STATE_NONE                      (0)
88#define PLAYER_STATE_ONFOOT                    (1)
89#define PLAYER_STATE_DRIVER                    (2)
90#define PLAYER_STATE_PASSENGER                 (3)
91#define PLAYER_STATE_EXIT_VEHICLE              (4) // (used internally)
92#define PLAYER_STATE_ENTER_VEHICLE_DRIVER      (5) // (used internally)
93#define PLAYER_STATE_ENTER_VEHICLE_PASSENGER   (6) // (used internally)
94#define PLAYER_STATE_WASTED                    (7)
95#define PLAYER_STATE_SPAWNED                   (8)
96#define PLAYER_STATE_SPECTATING                (9)
97
98// Marker modes used by ShowPlayerMarkers()
99#define PLAYER_MARKERS_MODE_OFF                (0)
100#define PLAYER_MARKERS_MODE_GLOBAL             (1)
101#define PLAYER_MARKERS_MODE_STREAMED           (2)
102
103// Weapons
104#define WEAPON_BRASSKNUCKLE                    (1)
105#define WEAPON_GOLFCLUB                        (2)
106#define WEAPON_NITESTICK                       (3)
107#define WEAPON_KNIFE                           (4)
108#define WEAPON_BAT                             (5)
109#define WEAPON_SHOVEL                          (6)
110#define WEAPON_POOLSTICK                       (7)
111#define WEAPON_KATANA                          (8)
112#define WEAPON_CHAINSAW                        (9)
113#define WEAPON_DILDO                           (10)
114#define WEAPON_DILDO2                          (11)
115#define WEAPON_VIBRATOR                        (12)
116#define WEAPON_VIBRATOR2                       (13)
117#define WEAPON_FLOWER                          (14)
118#define WEAPON_CANE                            (15)
119#define WEAPON_GRENADE                         (16)
120#define WEAPON_TEARGAS                         (17)
121#define WEAPON_MOLTOV                          (18)
122#define WEAPON_COLT45                          (22)
123#define WEAPON_SILENCED                        (23)
124#define WEAPON_DEAGLE                          (24)
125#define WEAPON_SHOTGUN                         (25)
126#define WEAPON_SAWEDOFF                        (26)
127#define WEAPON_SHOTGSPA                        (27)
128#define WEAPON_UZI                             (28)
129#define WEAPON_MP5                             (29)
130#define WEAPON_AK47                            (30)
131#define WEAPON_M4                              (31)
132#define WEAPON_TEC9                            (32)
133#define WEAPON_RIFLE                           (33)
134#define WEAPON_SNIPER                          (34)
135#define WEAPON_ROCKETLAUNCHER                  (35)
136#define WEAPON_HEATSEEKER                      (36)
137#define WEAPON_FLAMETHROWER                    (37)
138#define WEAPON_MINIGUN                         (38)
139#define WEAPON_SATCHEL                         (39)
140#define WEAPON_BOMB                            (40)
141#define WEAPON_SPRAYCAN                        (41)
142#define WEAPON_FIREEXTINGUISHER                (42)
143#define WEAPON_CAMERA                          (43)
144#define WEAPON_PARACHUTE                       (46)
145#define WEAPON_VEHICLE                         (49)
146#define WEAPON_DROWN                           (53)
147#define WEAPON_COLLISION                       (54)
148
149// Keys
150#define KEY_ACTION                             (1)
151#define KEY_CROUCH                             (2)
152#define KEY_FIRE                               (4)
153#define KEY_SPRINT                             (8)
154#define KEY_SECONDARY_ATTACK                   (16)
155#define KEY_JUMP                               (32)
156#define KEY_LOOK_RIGHT                         (64)
157#define KEY_HANDBRAKE                          (128)
158#define KEY_LOOK_LEFT                          (256)
159#define KEY_SUBMISSION                         (512)
160#define KEY_LOOK_BEHIND                        (512)
161#define KEY_WALK                               (1024)
162#define KEY_ANALOG_UP                          (2048)
163#define KEY_ANALOG_DOWN                        (4096)
164#define KEY_ANALOG_LEFT                        (8192)
165#define KEY_ANALOG_RIGHT                       (16384)
166#define KEY_YES                                (65536)
167#define KEY_NO                                 (131072)
168#define KEY_CTRL_BACK                          (262144)
169
170#define KEY_UP                                 (-128)
171#define KEY_DOWN                               (128)
172#define KEY_LEFT                               (-128)
173#define KEY_RIGHT                              (128)
174
175// Player GUI Dialog
176#define DIALOG_STYLE_MSGBOX                    (0)
177#define DIALOG_STYLE_INPUT                     (1)
178#define DIALOG_STYLE_LIST                      (2)
179#define DIALOG_STYLE_PASSWORD                  (3)
180#define DIALOG_STYLE_TABLIST                   (4)
181#define DIALOG_STYLE_TABLIST_HEADERS           (5)
182
183// Text Draw
184#define TEXT_DRAW_FONT_SPRITE_DRAW             (4)
185#define TEXT_DRAW_FONT_MODEL_PREVIEW           (5)
186
187// SVar enumeration
188#define	SERVER_VARTYPE_NONE                    (0)
189#define SERVER_VARTYPE_INT                     (1)
190#define SERVER_VARTYPE_STRING                  (2)
191#define SERVER_VARTYPE_FLOAT                   (3)
192
193// Artwork/NetModels
194#define DOWNLOAD_REQUEST_EMPTY                 (0)
195#define DOWNLOAD_REQUEST_MODEL_FILE            (1)
196#define DOWNLOAD_REQUEST_TEXTURE_FILE          (2)
197
198#define CLICK_SOURCE_SCOREBOARD                (0)
199
200#define EDIT_RESPONSE_CANCEL                   (0)
201#define EDIT_RESPONSE_FINAL                    (1)
202#define EDIT_RESPONSE_UPDATE                   (2)
203
204#define SELECT_OBJECT_GLOBAL_OBJECT            (1)
205#define SELECT_OBJECT_PLAYER_OBJECT            (2)
206
207#define BULLET_HIT_TYPE_NONE                   (0)
208#define BULLET_HIT_TYPE_PLAYER                 (1)
209#define BULLET_HIT_TYPE_VEHICLE                (2)
210#define BULLET_HIT_TYPE_OBJECT                 (3)
211#define BULLET_HIT_TYPE_PLAYER_OBJECT          (4)
212
213// Limits
214#if MAX_PLAYER_NAME < 1 || MAX_PLAYER_NAME > 24
215	#error MAX_PLAYER_NAME must be >= 1 and <= 24
216#endif
217
218#if MAX_PLAYERS < 1 || MAX_PLAYERS > 1000
219	#error MAX_PLAYERS must be >= 1 and <= 1000
220#endif
221
222#if MAX_VEHICLES < 1 || MAX_VEHICLES > 2000
223	#error MAX_VEHICLES must be >= 1 and <= 2000
224#endif
225
226#if MAX_ACTORS < 1 || MAX_ACTORS > 1000
227	#error MAX_ACTORS must be >= 1 and <= 1000
228#endif
229
230#if MAX_OBJECTS < 1 || MAX_OBJECTS > 2000
231	#error MAX_OBJECTS must be >= 1 and <= 2000
232#endif
233
234#if MAX_GANG_ZONES < 1 || MAX_GANG_ZONES > 1024
235	#error MAX_GANG_ZONES must be >= 1 and <= 1024
236#endif
237
238#if MAX_TEXT_DRAWS < Text:1 || MAX_TEXT_DRAWS > Text:2048
239	#error MAX_TEXT_DRAWS must be >= 1 and <= 2048
240#endif
241
242#if MAX_PLAYER_TEXT_DRAWS < PlayerText:1 || MAX_PLAYER_TEXT_DRAWS > PlayerText:256
243	#error MAX_PLAYER_TEXT_DRAWS must be >= 1 and <= 256
244#endif
245
246#if MAX_MENUS < Menu:1 || MAX_MENUS > Menu:128
247	#error MAX_MENUS must be >= 1 and <= 128
248#endif
249
250#if MAX_3DTEXT_GLOBAL < Text3D:1 || MAX_3DTEXT_GLOBAL > Text3D:1024
251	#error MAX_3DTEXT_GLOBAL must be >= 1 and <= 1024
252#endif
253
254#if MAX_3DTEXT_PLAYER < PlayerText3D:1 || MAX_3DTEXT_PLAYER > PlayerText3D:1024
255	#error MAX_3DTEXT_PLAYER must be >= 1 and <= 1024
256#endif
257
258#if MAX_PICKUPS < 1 || MAX_PICKUPS > 4096
259	#error MAX_PICKUPS must be >= 1 and <= 4096
260#endif
261
262public const SAMP_INCLUDES_VERSION = 0x037030;
263
264#include <core>
265#include <float>
266#include <string>
267#include <file>
268#include <time>
269#include <datagram>
270#tryinclude <console>
271#include <a_players>
272#include <a_vehicles>
273#include <a_objects>
274#include <a_actor>
275#include <a_sampdb>
276#include <a_http>
277
278/*
279
280Version examples:
281
2820.3.DL R1       - 03D010
283
2840.3.7 R3        - 037030
2850.3.7 R2-2      - 037022
2860.3.7 R1-2      - 037012
2870.3.7           - 037000
288
2890.3z R4         - 030700
2900.3z R3         - 030700
2910.3z R2-1       - 030700
2920.3z R1-2       - 030700
2930.3z            - 030700
2940.3x R2 patch 1 - 030621
2950.3x R2         - 030620
2960.3x R1-2       - 030612
2970.3x            - 030600
2980.3e            - 030500
2990.3d            - 030400
3000.3c            - 030300
3010.3b            - 030200
3020.3a            - 030100
303
3040.2X            - 02A000
3050.2.2 R3        - 022300
306
307Rough rules:
308
309Uses (roughtly) BCD.  Special versions are denoted outside 0-9.
310
3110.1.2c R4-5
312| | ||  | |
3130 1 23  4 5
314=
3150x012345
316
317(assuming c is the third revision)
318
3190.2X becomes 02A000 because it is basically 0.2.3, but not, while higher than
3200.2.2 so can't be 020400 (for example).  Also, its a capital letter, so doesn't
321use the revision method.
322
323P.S.  Making a consistent scheme for SA:MP versions is REALLY hard.
324
325open.mp releases can use `A` as the first digit.
326
327*/
328
329// --------------------------------------------------
330// Natives
331// --------------------------------------------------
332
333// Util
334
335#if !defined _console_included
336	/// <summary>Prints a string to the server console (not in-game chat) and logs (server_log.txt).</summary>
337	/// <param name="string">The string to print</param>
338	/// <seealso name="printf"/>
339	native print(const string[]);
340
341	/// <summary>Outputs a formatted string on the console (the server window, not the in-game chat).</summary>
342	/// <param name="format">The format string</param>
343	/// <param name="">Indefinite number of arguments of any tag</param>
344	/// <seealso name="print"/>
345	/// <seealso name="format"/>
346	/// <remarks>The format string or its output should not exceed 1024 characters. Anything beyond that length can lead to a server to crash.</remarks>
347	/// <remarks>This function doesn't support <a href="#strpack">packed</a> strings.</remarks>
348	/// <remarks>
349	///   <b>Format Specifiers:</b><p/>
350	///   <ul>
351	///     <li><b><c>%i</c></b> - integer (whole number)</li>
352	///     <li><b><c>%d</c></b> - integer (whole number).</li>
353	///     <li><b><c>%s</c></b> - string</li>
354	///     <li><b><c>%f</c></b> - floating-point number (Float: tag)</li>
355	///     <li><b><c>%c</c></b> - ASCII character</li>
356	///     <li><b><c>%x</c></b> - hexadecimal number</li>
357	///     <li><b><c>%b</c></b> - binary number</li>
358	///     <li><b><c>%%</c></b> - literal <b><c>%</c></b></li>
359	///     <li><b><c>%q</c></b> - escape a text for SQLite. (Added in <b>0.3.7 R2</b>)</li>
360	///   </ul>
361	/// </remarks>
362	/// <remarks>The values for the placeholders follow in the exact same order as parameters in the call. For example, <b><c>"I am %i years old"</c></b> - the <b><c>%i</c></b> will be replaced with an Integer variable, which is the person's age.</remarks>
363	/// <remarks>You may optionally put a number between the <b><c>%</c></b> and the letter of the placeholder code. This number indicates the field width; if the size of the parameter to print at the position of the placeholder is smaller than the field width, the field is expanded with spaces. To cut the number of decimal places beeing shown of a float, you can add <b><c>.&lt;max number&gt;</c></b> between the <b><c>%</c></b> and the <b><c>f</c></b>. (example: <b><c>%.2f</c></b>)</remarks>
364	native printf(const format[], {Float,_}:...);
365#endif
366
367/// <summary>Formats a string to include variables and other strings inside it.</summary>
368/// <param name="output">The string to output the result to</param>
369/// <param name="len">The maximum length output can contain</param>
370/// <param name="format">The format string</param>
371/// <param name="">Indefinite number of arguments of any tag</param>
372/// <seealso name="print"/>
373/// <seealso name="printf"/>
374/// <remarks>This function doesn't support <a href="#strpack">packed strings</a>.</remarks>
375/// <remarks>
376///   <b>Format Specifiers:</b><p/>
377///   <ul>
378///     <li><b><c>%i</c></b> - integer (whole number)</li>
379///     <li><b><c>%d</c></b> - integer (whole number).</li>
380///     <li><b><c>%s</c></b> - string</li>
381///     <li><b><c>%f</c></b> - floating-point number (Float: tag)</li>
382///     <li><b><c>%c</c></b> - ASCII character</li>
383///     <li><b><c>%x</c></b> - hexadecimal number</li>
384///     <li><b><c>%b</c></b> - binary number</li>
385///     <li><b><c>%%</c></b> - literal <b><c>%</c></b></li>
386///     <li><b><c>%q</c></b> - escape a text for SQLite. (Added in <b>0.3.7 R2</b>)</li>
387///   </ul>
388/// </remarks>
389/// <remarks>The values for the placeholders follow in the exact same order as parameters in the call. For example, <b><c>"I am %i years old"</c></b> - the <b><c>%i</c></b> will be replaced with an Integer variable, which is the person's age.</remarks>
390/// <remarks>You may optionally put a number between the <b><c>%</c></b> and the letter of the placeholder code. This number indicates the field width; if the size of the parameter to print at the position of the placeholder is smaller than the field width, the field is expanded with spaces. To cut the number of decimal places beeing shown of a float, you can add <b><c>.&lt;max number&gt;</c></b> between the <b><c>%</c></b> and the <b><c>f</c></b>. (example: <b><c>%.2f</c></b>)</remarks>
391native format(output[], len = sizeof output, const format[], {Float,_}:...);
392
393/// <summary>This function sends a message to a specific player with a chosen color in the chat. The whole line in the chatbox will be in the set color unless color embedding is used (since <b><c>0.3c</c></b>).</summary>
394/// <param name="playerid">The ID of the player to display the message to</param>
395/// <param name="color">The color of the message (<b>RGBA</b>)</param>
396/// <param name="message">The text that will be displayed <b>(max 144 characters)</b></param>
397/// <seealso name="SendClientMessageToAll"/>
398/// <seealso name="SendPlayerMessageToPlayer"/>
399/// <seealso name="SendPlayerMessageToAll"/>
400/// <remarks>If a message is longer than 144 characters, it will not be sent. Truncation can be used to prevent this. Displaying a message on multiple lines will also solve this issue. </remarks>
401/// <remarks>Avoid using the percent sign (or format specifiers) in the actual message text without properly escaping it (like <b><c>%%</c></b>). It will result in crashes otherwise. </remarks>
402/// <remarks>You can use color embedding for multiple colors in the message. </remarks>
403/// <returns>
404///   <b><c>1</c></b>: The function executed successfully. Success is reported when the string is over 144 characters, but the message won't be sent.<p/>
405///   <b><c>0</c></b>: The function failed to execute. The player is not connected.
406/// </returns>
407native SendClientMessage(playerid, color, const message[]);
408
409/// <summary>Displays a message in chat to all players. This is a multi-player equivalent of <a href="#SendClientMessage">SendClientMessage</a>.</summary>
410/// <param name="color">The color of the message (<b>RGBA</b>)</param>
411/// <param name="message">The message to show (<b>max 144 characters</b>)</param>
412/// <seealso name="SendClientMessage"/>
413/// <seealso name="SendPlayerMessageToAll"/>
414/// <remarks>Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise.</remarks>
415/// <returns>This function always returns <b><c>1</c></b>.</returns>
416native SendClientMessageToAll(color, const message[]);
417
418/// <summary>Sends a message in the name of a player to another player on the server. The message will appear in the chat box but can only be seen by the user specified with <paramref name="playerid"/>. The line will start with the sender's name in their color, followed by the message in white.</summary>
419/// <param name="playerid">The ID of the player who will receive the message</param>
420/// <param name="senderid">The sender's ID. If invalid, the message will not be sent</param>
421/// <param name="message">The message that will be sent</param>
422/// <seealso name="SendPlayerMessageToAll"/>
423/// <seealso name="SendClientMessage"/>
424/// <seealso name="SendClientMessageToAll"/>
425/// <seealso name="OnPlayerText"/>
426/// <remarks>Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise.</remarks>
427native SendPlayerMessageToPlayer(playerid, senderid, const message[]);
428
429/// <summary>Sends a message in the name of a player to all other players on the server. The line will start with the sender's name in their color, followed by the message in white.</summary>
430/// <param name="senderid">The ID of the sender. If invalid, the message will not be sent</param>
431/// <param name="message">The message that will be sent</param>
432/// <seealso name="SendPlayerMessageToPlayer"/>
433/// <seealso name="SendClientMessageToAll"/>
434/// <seealso name="OnPlayerText"/>
435/// <remarks>Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise.</remarks>
436native SendPlayerMessageToAll(senderid, const message[]);
437
438/// <summary>Adds a death to the 'killfeed' on the right-hand side of the screen for all players.</summary>
439/// <param name="killer">The ID of the killer (can be <b><c>INVALID_PLAYER_ID</c></b>)</param>
440/// <param name="killee">The ID of the player that died</param>
441/// <param name="weapon">The <a href="http://wiki.sa-mp.com/wiki/Weapons">reason</a> (not always a weapon) for the victim's death. Special icons can also be used (<b><c>ICON_CONNECT</c></b> and <b><c>ICON_DISCONNECT</c></b>)</param>
442/// <seealso name="SendDeathMessageToPlayer"/>
443/// <seealso name="OnPlayerDeath"/>
444/// <remarks>Death messages can be cleared by using a valid player ID for <paramref name="killee"/> that is not connected.</remarks>
445/// <remarks>To show a death message for just a single player, use <a href="#SendDeathMessageToPlayer">SendDeathMessageToPlayer</a>. </remarks>
446/// <remarks>You can use NPCs to create your own custom death reasons. </remarks>
447/// <returns>This function always returns <b><c>1</c></b>, even if the function fails to execute. The function fails to execute (no death message shown) if <paramref name="killee"/> is invalid. If <paramref name="reason"/> is invalid, a generic skull-and-crossbones icon is shown. <paramref name="killer"/> being invalid (<b><c>INVALID_PLAYER_ID</c></b>) is valid.</returns>
448native SendDeathMessage(killer, killee, weapon);
449
450/// <summary>Adds a death to the 'killfeed' on the right-hand side of the screen for a single player.</summary>
451/// <param name="playerid">The ID of the player to send the death message to</param>
452/// <param name="killer">The ID of the killer (can be <b><c>INVALID_PLAYER_ID</c></b>)</param>
453/// <param name="killee">The ID of the player that died</param>
454/// <param name="weapon">The <a href="http://wiki.sa-mp.com/wiki/Weapons">reason</a> (not always a weapon) for the victim's death. Special icons can also be used (<b><c>ICON_CONNECT</c></b> and <b><c>ICON_DISCONNECT</c></b>)</param>
455/// <seealso name="SendDeathMessage"/>
456/// <seealso name="OnPlayerDeath"/>
457/// <remarks>This Function was added in <b>SA-MP 0.3z R2-2</b> and will not work in earlier versions!</remarks>
458/// <returns>
459///   <b><c>1</c></b>: The function executed successfully.<p/>
460///   <b><c>0</c></b>: The function failed to execute.
461/// </returns>
462native SendDeathMessageToPlayer(playerid, killer, killee, weapon);
463
464/// <summary>Shows 'game text' (on-screen text) for a certain length of time for all players.</summary>
465/// <param name="string">The text to be displayed</param>
466/// <param name="time">The duration of the text being shown in milliseconds</param>
467/// <param name="style">The style of text to be displayed</param>
468/// <seealso name="GameTextForPlayer"/>
469/// <seealso name="TextDrawShowForAll"/>
470/// <returns>This function always returns <b><c>1</c></b>.</returns>
471native GameTextForAll(const string[], time, style);
472
473/// <summary>Shows 'game text' (on-screen text) for a certain length of time for a specific player.</summary>
474/// <param name="playerid">The ID of the player to show the gametext for</param>
475/// <param name="string">The text to be displayed</param>
476/// <param name="time">The duration of the text being shown in milliseconds</param>
477/// <param name="style">The style of text to be displayed</param>
478/// <seealso name="GameTextForAll"/>
479/// <seealso name="TextDrawShowForPlayer"/>
480/// <returns>
481///   <b><c>1</c></b>: The function executed successfully. Success is reported when the style and/or time is invalid. Nothing will happen though (no text displayed). May also cause game crashes.<p/>
482///   <b><c>0</c></b>: The function failed to execute. This means either the string is null or the player is not connected.
483/// </returns>
484native GameTextForPlayer(playerid, const string[], time, style);
485
486/// <summary>Sets a 'timer' to call a function after some time. Can be set to repeat.</summary>
487/// <param name="funcname">Name of the function to call as a string. This must be a public function (forwarded). A null string here will crash the server</param>
488/// <param name="interval">Interval in milliseconds</param>
489/// <param name="repeating">Whether the timer should repeat or not</param>
490/// <seealso name="SetTimerEx"/>
491/// <seealso name="KillTimer"/>
492/// <remarks>Timer intervals are not accurate (roughly 25% off). There's a fix available <a href="http://forum.sa-mp.com/showthread.php?t=289675">here</a>. </remarks>
493/// <remarks>Timer IDs are never used twice. You can use <a href="#KillTimer">KillTimer</a> on a timer ID and it won't matter if it's running or not. </remarks>
494/// <remarks>The function that should be called must be public. </remarks>
495/// <remarks>The use of many timers will result in increased memory/cpu usage. </remarks>
496/// <returns>The ID of the timer that was started. Timer IDs start at <b><c>1</c></b>.</returns>
497native SetTimer(const funcname[], interval, repeating);
498
499/// <summary>Sets a timer to call a function after the specified interval. This variant ('Ex') can pass parameters (such as a player ID) to the function.</summary>
500/// <param name="funcname">The name of a public function to call when the timer expires</param>
501/// <param name="interval">Interval in milliseconds</param>
502/// <param name="repeating">Whether the timer should be called repeatedly (can only be stopped with <a href="#KillTimer">KillTimer</a>) or only once</param>
503/// <param name="format">Special format indicating the types of values the timer will pass</param>
504/// <param name="">Indefinite number of arguments to pass (must follow format specified in previous parameter)</param>
505/// <seealso name="SetTimer"/>
506/// <seealso name="KillTimer"/>
507/// <seealso name="CallLocalFunction"/>
508/// <seealso name="CallRemoteFunction"/>
509/// <remarks>Timer intervals are not accurate (roughly 25% off). There's a fix available <a href="http://forum.sa-mp.com/showthread.php?t=289675">here</a>. </remarks>
510/// <remarks>Timer IDs are never used twice. You can use KillTimer() on a timer ID and it won't matter if it's running or not. </remarks>
511/// <remarks>The function that should be called must be public. </remarks>
512/// <remarks>The use of many timers will result in increased memory/cpu usage. </remarks>
513/// <remarks>
514///   <b>Format syntax:</b><p/>
515///   <ul>
516///     <li><b><c>i</c></b> - integer</li>
517///     <li><b><c>d</c></b> - integer</li>
518///     <li><b><c>a</c></b> - array The next parameter must be an integer (<b><c>"i"</c></b>) with the array's size <b>[CURRENTLY UNUSABLE]</b></li>
519///     <li><b><c>s</c></b> - string <b>[CURRENTLY UNUSABLE]</b></li>
520///     <li><b><c>f</c></b> - float</li>
521///     <li><b><c>b</c></b> - boolean</li>
522///   </ul>
523/// </remarks>
524/// <returns>The ID of the timer that was started. Timer IDs start at <b><c>1</c></b> and are never reused. There are no internal checks to verify that the parameters passed are valid (e.g. duration not a minus value).</returns>
525native SetTimerEx(const funcname[], interval, repeating, const format[], {Float,_}:...);
526
527/// <summary>Kills (stops) a running timer.</summary>
528/// <param name="timerid">The ID of the timer to kill (returned by <a href="#SetTimer">SetTimer</a> or <a href="#SetTimerEx">SetTimerEx</a>)</param>
529/// <seealso name="SetTimer"/>
530/// <seealso name="SetTimerEx"/>
531/// <returns>This function always returns <b><c>0</c></b>.</returns>
532native KillTimer(timerid);
533
534/// <summary>Returns the uptime of the actual server (not the SA-MP server) in milliseconds.</summary>
535/// <seealso name="tickcount"/>
536/// <remarks>GetTickCount will cause problems on servers with uptime of over 24 days as GetTickCount will eventually warp past the integer size constraints. However using <a href="https://gist.github.com/ziggi/5d7d8dc42f54531feba7ae924c608e73">this</a> function fixes the problem.</remarks>
537/// <remarks>One common use for GetTickCount is for benchmarking. It can be used to calculate how much time some code takes to execute.</remarks>
538/// <returns>Uptime of the actual server (not the SA-MP server).</returns>
539native GetTickCount();
540
541/// <summary>Returns the maximum number of players that can join the server, as set by the server variable 'maxplayers' in server.cfg.</summary>
542/// <seealso name="GetPlayerPoolSize"/>
543/// <seealso name="IsPlayerConnected"/>
544/// <remarks>This function can not be used in place of <b><c>MAX_PLAYERS</c></b>. It can not be used at compile time (e.g. for array sizes). <b><c>MAX_PLAYERS</c></b> should always be re-defined to what the 'maxplayers' var will be, or higher.</remarks>
545/// <returns>The maximum number of players that can join the server.</returns>
546native GetMaxPlayers();
547
548/// <summary>Calls a public function in any script that is loaded.</summary>
549/// <param name="function">Public function's name</param>
550/// <param name="format">Tag/format of each variable</param>
551/// <param name="">'Indefinite' number of arguments of any tag</param>
552/// <seealso name="CallLocalFunction"/>
553/// <returns>The value that the last public function returned.</returns>
554/// <remarks>CallRemoteFunction crashes the server if it's passing an empty string.</remarks>
555/// <remarks>
556///   Format string placeholders:<p/>
557///   <ul>
558///     <li><b><c>c</c></b> - a single character</li>
559///     <li><b><c>d</c></b> - an integer (whole) number</li>
560///     <li><b><c>i</c></b> - an integer (whole) number</li>
561///     <li><b><c>x</c></b> - a number in hexadecimal notation</li>
562///     <li><b><c>f</c></b> - a floating point number</li>
563///     <li><b><c>s</c></b> - a string</li>
564///   </ul>
565/// </remarks>
566native CallRemoteFunction(const function[], const format[], {Float,_}:...);
567
568/// <summary>Calls a public function from the script in which it is used.</summary>
569/// <param name="function">Public function's name</param>
570/// <param name="format">Tag/format of each variable</param>
571/// <param name="">'Indefinite' number of arguments of any tag</param>
572/// <seealso name="CallRemoteFunction"/>
573/// <returns>The value that the <b>only</b> public function returned.</returns>
574/// <remarks>CallLocalFunction crashes the server if it's passing an empty string.</remarks>
575/// <remarks>
576///   Format string placeholders:<p/>
577///   <ul>
578///     <li><b><c>c</c></b> - a single character</li>
579///     <li><b><c>d</c></b> - an integer (whole) number</li>
580///     <li><b><c>i</c></b> - an integer (whole) number</li>
581///     <li><b><c>x</c></b> - a number in hexadecimal notation</li>
582///     <li><b><c>f</c></b> - a floating point number</li>
583///     <li><b><c>s</c></b> - a string</li>
584///   </ul>
585/// </remarks>
586native CallLocalFunction(const function[], const format[], {Float,_}:...);
587
588
589/// <summary>Returns the norm (length) of the provided vector.</summary>
590/// <param name="x">The vector's magnitude on the X axis</param>
591/// <param name="y">The vector's magnitude on the Y axis</param>
592/// <param name="z">The vector's magnitude on the Z axis</param>
593/// <seealso name="GetPlayerDistanceFromPoint"/>
594/// <seealso name="GetVehicleDistanceFromPoint"/>
595/// <seealso name="floatsqroot"/>
596/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
597/// <returns>The norm (length) of the provided vector as a float.</returns>
598native Float:VectorSize(Float:x, Float:y, Float:z);
599
600/// <summary>Get the inversed value of a sine in degrees.</summary>
601/// <param name="value">The sine for which to find the angle for</param>
602/// <seealso name="floatsin"/>
603/// <returns>The angle in degrees.</returns>
604native Float:asin(Float:value);
605
606/// <summary>Get the inversed value of a cosine in degrees.</summary>
607/// <param name="value">The cosine for which to find the angle for</param>
608/// <seealso name="floatcos"/>
609/// <returns>The angle in degrees.</returns>
610native Float:acos(Float:value);
611
612/// <summary>Get the inversed value of a tangent in degrees.</summary>
613/// <param name="value">The tangent for which to find the angle for</param>
614/// <seealso name="atan2"/>
615/// <seealso name="floattan"/>
616/// <returns>The angle in degrees.</returns>
617native Float:atan(Float:value);
618
619/// <summary>Get the multi-valued inversed value of a tangent in degrees.</summary>
620/// <param name="y">y size</param>
621/// <param name="x">x size</param>
622/// <seealso name="atan"/>
623/// <seealso name="floattan"/>
624/// <returns>The angle in degrees.</returns>
625native Float:atan2(Float:y, Float:x);
626
627
628/// <summary>Gets the highest playerid currently in use on the server.</summary>
629/// <seealso name="GetVehiclePoolSize"/>
630/// <seealso name="GetMaxPlayers"/>
631/// <remarks>This function was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
632/// <returns>The highest playerid currently in use on the server or <b><c>0</c></b> if there are no connected players.</returns>
633native GetPlayerPoolSize();
634
635/// <summary>Gets the highest vehicleid currently in use on the server.</summary>
636/// <seealso name="GetPlayerPoolSize"/>
637/// <remarks>This function was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
638/// <returns>The highest vehicleid currently in use on the server or <b><c>0</c></b> if there are no created vehicles.</returns>
639native GetVehiclePoolSize();
640
641/// <summary>Gets the highest actorid created on the server.</summary>
642/// <seealso name="CreateActor"/>
643/// <seealso name="IsValidActor"/>
644/// <seealso name="SetActorHealth"/>
645/// <remarks>This function was added in <b><b>SA-MP 0.3.7</b></b> and will not work in earlier versions!</remarks>
646/// <returns>The highest actorid created on the server or <b><c>0</c></b> if there are no created actors.</returns>
647native GetActorPoolSize();
648
649// Hash
650
651/// <summary>Hashes a password using the SHA-256 hashing algorithm. Includes a salt. The output is always 256 bytes in length, or the equivalent of 64 Pawn cells.</summary>
652/// <param name="password">The password to hash</param>
653/// <param name="salt">The salt to use in the hash</param>
654/// <param name="ret_hash">The returned hash</param>
655/// <param name="ret_hash_len">The returned hash maximum length</param>
656/// <remarks>This function was added in <b>SA-MP 0.3.7-R1</b> and will not work in earlier versions!</remarks>
657/// <remarks>The salt is appended to the end of the password, meaning password 'foo' and salt 'bar' would form 'foobar'. </remarks>
658/// <remarks>The salt should be random, unique for each player and at least as long as the hashed password. It is to be stored alongside the actual hash in the player's account. </remarks>
659native SHA256_PassHash(const password[], const salt[], ret_hash[], ret_hash_len = sizeof ret_hash); // SHA256 for password hashing
660
661// Server wide persistent variable system (SVars)
662
663/// <summary>Set an integer server variable.</summary>
664/// <param name="varname">The name of the server variable</param>
665/// <param name="int_value">The integer to be set</param>
666/// <seealso name="GetSVarInt"/>
667/// <seealso name="SetSVarString"/>
668/// <seealso name="GetSVarString"/>
669/// <seealso name="SetSVarFloat"/>
670/// <seealso name="GetSVarFloat"/>
671/// <seealso name="DeleteSVar"/>
672/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
673/// <returns>
674///   <b><c>1</c></b>: The function executed successfully.<p/>
675///   <b><c>0</c></b>: The function failed to execute. The variable name is null or over 40 characters.
676/// </returns>
677native SetSVarInt(const varname[], int_value);
678
679/// <summary>Gets an integer server variable's value.</summary>
680/// <param name="varname">The name of the server variable (case-insensitive). Assigned in SetSVarInt</param>
681/// <seealso name="SetSVarInt"/>
682/// <seealso name="SetSVarString"/>
683/// <seealso name="GetSVarString"/>
684/// <seealso name="SetSVarFloat"/>
685/// <seealso name="GetSVarFloat"/>
686/// <seealso name="DeleteSVar"/>
687/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
688/// <returns>The integer value of the specified server variable. It will still return <b><c>0</c></b> if the variable is not set.</returns>
689native GetSVarInt(const varname[]);
690
691/// <summary>Set a string server variable.</summary>
692/// <param name="varname">The name of the server variable</param>
693/// <param name="string_value">The string to be set</param>
694/// <seealso name="SetSVarInt"/>
695/// <seealso name="GetSVarInt"/>
696/// <seealso name="GetSVarString"/>
697/// <seealso name="SetSVarFloat"/>
698/// <seealso name="GetSVarFloat"/>
699/// <seealso name="DeleteSVar"/>
700/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
701/// <returns>
702///   <b><c>1</c></b>: The function executed successfully.<p/>
703///   <b><c>0</c></b>: The function failed to execute. The variable name is null or over 40 characters.
704/// </returns>
705native SetSVarString(const varname[], const string_value[]);
706
707/// <summary>Gets a string server variable's value.</summary>
708/// <param name="varname">The name of the server variable (case-insensitive). Assigned in <a href="#SetSVarString">SetSVarString</a></param>
709/// <param name="string_return">The array in which to store the string value in, passed by reference</param>
710/// <param name="len">The maximum length of the returned string</param>
711/// <seealso name="SetSVarInt"/>
712/// <seealso name="GetSVarInt"/>
713/// <seealso name="SetSVarString"/>
714/// <seealso name="SetSVarFloat"/>
715/// <seealso name="GetSVarFloat"/>
716/// <seealso name="DeleteSVar"/>
717/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
718/// <returns>The length of the string.</returns>
719native GetSVarString(const varname[], string_return[], len = sizeof string_return);
720
721/// <summary>Set a float server variable.</summary>
722/// <param name="varname">The name of the server variable</param>
723/// <param name="float_value">The float to be set</param>
724/// <seealso name="SetSVarInt"/>
725/// <seealso name="GetSVarInt"/>
726/// <seealso name="SetSVarString"/>
727/// <seealso name="GetSVarString"/>
728/// <seealso name="GetSVarFloat"/>
729/// <seealso name="DeleteSVar"/>
730/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
731/// <returns>
732///   <b><c>1</c></b>: The function executed successfully.<p/>
733///   <b><c>0</c></b>: The function failed to execute. The variable name is null or over 40 characters.
734/// </returns>
735native SetSVarFloat(const varname[], Float:float_value);
736
737/// <summary>Gets a float server variable's value.</summary>
738/// <param name="varname">The name of the server variable (case-insensitive). Assigned in <a href="#SetSVarFloat">SetSVarFloat</a></param>
739/// <seealso name="SetSVarInt"/>
740/// <seealso name="GetSVarInt"/>
741/// <seealso name="SetSVarString"/>
742/// <seealso name="GetSVarString"/>
743/// <seealso name="SetSVarFloat"/>
744/// <seealso name="DeleteSVar"/>
745/// <remarks>This function was added in <b>SA-MP 0.3.7 R2</b> and will not work in earlier versions!</remarks>
746/// <returns>The float value of the specified server variable. It will still return <b><c>0</c></b> if the variable is not set.</returns>
747native Float:GetSVarFloat(const varname[]);
748
749/// <summary>Deletes a previously set server variable.</summary>
750/// <param name="varname">The name of the server variable to delete</param>
751/// <seealso name="SetSVarInt"/>
752/// <seealso name="GetSVarInt"/>
753/// <seealso name="SetSVarString"/>
754/// <seealso name="GetSVarString"/>
755/// <seealso name="SetSVarFloat"/>
756/// <seealso name="GetSVarFloat"/>
757/// <remarks>Once a variable is deleted, attempts to retrieve the value will return <b><c>0</c></b> (for integers and floats and <b><c>NULL</c></b> for strings.</remarks>
758/// <returns>
759///   <b><c>1</c></b>: The function executed successfully.<p/>
760///   <b><c>0</c></b>: The function failed to execute. There is no variable set with the given name.
761/// </returns>
762native DeleteSVar(const varname[]);
763
764/// <summary>Each SVar (server-variable) has its own unique identification number for lookup, this function returns the highest ID.</summary>
765/// <seealso name="GetSVarNameAtIndex"/>
766/// <seealso name="GetSVarType"/>
767/// <returns>The highest set SVar ID.</returns>
768native GetSVarsUpperIndex();
769
770/// <summary>Retrieve the name of a sVar via the index.</summary>
771/// <param name="index">The index of the sVar</param>
772/// <param name="ret_varname">A string to store the sVar's name in, passed by reference</param>
773/// <param name="ret_len">The max length of the returned string</param>
774/// <seealso name="GetSVarType"/>
775/// <seealso name="GetSVarInt"/>
776/// <seealso name="GetSVarFloat"/>
777/// <seealso name="GetSVarString"/>
778native GetSVarNameAtIndex(index, ret_varname[], ret_len = sizeof ret_varname);
779
780/// <summary>Gets the type (integer, float or string) of a server variable.</summary>
781/// <param name="varname">The name of the server variable to get the type of</param>
782/// <seealso name="SetSVarInt"/>
783/// <seealso name="GetSVarInt"/>
784/// <seealso name="SetSVarString"/>
785/// <seealso name="GetSVarString"/>
786/// <seealso name="SetSVarFloat"/>
787/// <seealso name="GetSVarFloat"/>
788/// <seealso name="DeleteSVar"/>
789/// <remarks>
790///   <b>Variable types:</b><p/>
791///   <ul>
792///     <li><b><c>SERVER_VARTYPE_NONE</c></b> (sVar with name given does not exist)</li>
793///     <li><b><c>SERVER_VARTYPE_INT</c></b></li>
794///     <li><b><c>SERVER_VARTYPE_STRING</c></b></li>
795///     <li><b><c>SERVER_VARTYPE_FLOAT</c></b></li>
796///   </ul>
797/// </remarks>
798/// <returns>Returns the type of the SVar. See table below.</returns>
799native GetSVarType(const varname[]);
800
801// Game
802
803/// <summary>Set the name of the game mode, which appears in the server browser.</summary>
804/// <param name="string">The gamemode name to display</param>
805native SetGameModeText(const string[]);
806
807
808/// <summary>This function is used to change the amount of teams used in the gamemode. It has no obvious way of being used, but can help to indicate the number of teams used for better (more effective) internal handling. This function should only be used in the <a href="#OnGameModeInit">OnGameModeInit</a> callback. Important: You can pass 2 billion here if you like, this function has no effect at all.</summary>
809/// <param name="count">Number of teams the gamemode knows</param>
810/// <seealso name="GetPlayerTeam"/>
811/// <seealso name="SetPlayerTeam"/>
812native SetTeamCount(count);
813
814/// <summary>Adds a class to class selection. Classes are used so players may spawn with a skin of their choice.</summary>
815/// <param name="modelid">The <a href="http://wiki.sa-mp.com/wiki/Skins">skin</a> which the player will spawn with</param>
816/// <param name="spawn_x">The X coordinate of the spawnpoint of this class</param>
817/// <param name="spawn_y">The Y coordinate of the spawnpoint of this class</param>
818/// <param name="spawn_z">The Z coordinate of the spawnpoint of this class</param>
819/// <param name="z_angle">The direction in which the player should face after spawning</param>
820/// <param name="weapon1">The first spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
821/// <param name="weapon1_ammo">The amount of ammunition for the primary spawn weapon</param>
822/// <param name="weapon2">The second spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
823/// <param name="weapon2_ammo">The amount of ammunition for the second spawn weapon</param>
824/// <param name="weapon3">The third spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
825/// <param name="weapon3_ammo">The amount of ammunition for the third spawn weapon</param>
826/// <returns>
827///   <ul>
828///     <li>The <b>ID of the class</b> which was just added.</li>
829///     <li><b><c>319</c></b> if the class limit (<b><c>320</c></b>) was reached. The highest possible class ID is <b><c>319</c></b>.</li>
830///   </ul>
831/// </returns>
832/// <remarks>
833///    The maximum class ID is <b><c>319</c></b> (starting from <b><c>0</c></b>, so a total of <b><c>320</c></b> classes).
834///    When this limit is reached, any more classes that are added will replace ID <b><c>319</c></b>.
835/// </remarks>
836/// <seealso name="AddPlayerClassEx"/>
837/// <seealso name="SetSpawnInfo"/>
838/// <seealso name="SetPlayerSkin"/>
839native AddPlayerClass(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, weapon1, weapon1_ammo, weapon2, weapon2_ammo, weapon3, weapon3_ammo);
840
841/// <summary>This function is exactly the same as the <a href="#AddPlayerClass">AddPlayerClass</a> function, with the addition of a team parameter.</summary>
842/// <param name="teamid">The team you want the player to spawn in</param>
843/// <param name="modelid">The <a href="http://wiki.sa-mp.com/wiki/Skins">skin</a> which the player will spawn with</param>
844/// <param name="spawn_x">The X coordinate of the class' spawn position</param>
845/// <param name="spawn_y">The Y coordinate of the class' spawn position</param>
846/// <param name="spawn_z">The Z coordinate of the class' spawn position</param>
847/// <param name="z_angle">The direction in which the player will face after spawning</param>
848/// <param name="weapon1">The first spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
849/// <param name="weapon1_ammo">The amount of ammunition for the first spawn weapon</param>
850/// <param name="weapon2">The second spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
851/// <param name="weapon2_ammo">The amount of ammunition for the second spawn weapon</param>
852/// <param name="weapon3">The third spawn-<a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> for the player</param>
853/// <param name="weapon3_ammo">The amount of ammunition for the third spawn weapon</param>
854/// <returns>
855///   <ul>
856///     <li>The <b>ID of the class</b> which was just added.</li>
857///     <li><b><c>319</c></b> if the class limit (<b><c>320</c></b>) was reached. The highest possible class ID is <b><c>319</c></b>.</li>
858///   </ul>
859/// </returns>
860/// <remarks>The maximum class ID is <b><c>319</c></b> (starting from <b><c>0</c></b>, so a total of <b><c>320</c></b> classes). When this limit is reached, any more classes that are added will replace ID <b><c>319</c></b>.</remarks>
861/// <seealso name="AddPlayerClass"/>
862/// <seealso name="SetSpawnInfo"/>
863/// <seealso name="SetPlayerTeam"/>
864/// <seealso name="SetPlayerSkin"/>
865native AddPlayerClassEx(teamid, modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, weapon1, weapon1_ammo, weapon2, weapon2_ammo, weapon3, weapon3_ammo);
866
867/// <summary>Adds a 'static' vehicle (models are pre-loaded for players) to the gamemode.</summary>
868/// <param name="modelid">The <a href="http://wiki.sa-mp.com/wiki/Vehicle_Models">Model ID</a> for the vehicle</param>
869/// <param name="spawn_x">The X-coordinate for the vehicle</param>
870/// <param name="spawn_y">The Y-coordinate for the vehicle</param>
871/// <param name="spawn_z">The Z-coordinate for the vehicle</param>
872/// <param name="z_angle">Direction of vehicle - angle</param>
873/// <param name="color1">The primary <a href="http://wiki.sa-mp.com/wiki/Color_ID">color ID</a>. <b><c>-1</c></b> for random (random color chosen by client)</param>
874/// <param name="color2">The secondary <a href="http://wiki.sa-mp.com/wiki/Color_ID">color ID</a>. <b><c>-1</c></b> for random (random color chosen by client)</param>
875/// <returns>
876///   <ul>
877///     <li>The vehicle ID of the vehicle created (between <b><c>1</c></b> and <b><c>MAX_VEHICLES</c></b>).</li>
878///     <li><b><c>INVALID_VEHICLE_ID</c></b> (<b><c>65535</c></b>) if vehicle was not created (vehicle limit reached or invalid vehicle model ID passed).</li>
879///   </ul>
880/// </returns>
881/// <remarks>Can only be used when the server first starts (under <a href="#OnGameModeInit">OnGameModeInit</a>).</remarks>
882/// <seealso name="AddStaticVehicleEx"/>
883/// <seealso name="CreateVehicle"/>
884/// <seealso name="DestroyVehicle"/>
885native AddStaticVehicle(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, color1, color2);
886
887/// <summary>Adds a 'static' vehicle (models are pre-loaded for players)to the gamemode. Differs from <a href="#AddStaticVehicle">AddStaticVehicle</a> in only one way: allows a respawn time to be set for when the vehicle is left unoccupied by the driver.</summary>
888/// <param name="modelid">The <a href="http://wiki.sa-mp.com/wiki/Vehicle_Models">Model ID</a> for the vehicle</param>
889/// <param name="spawn_x">The X-coordinate for the vehicle</param>
890/// <param name="spawn_y">The Y-coordinate for the vehicle</param>
891/// <param name="spawn_z">The Z-coordinate for the vehicle</param>
892/// <param name="z_angle">The facing - angle for the vehicle</param>
893/// <param name="color1">The primary <a href="http://wiki.sa-mp.com/wiki/Color_ID">color ID</a>. <b><c>-1</c></b> for random (random color chosen by client)</param>
894/// <param name="color2">The secondary <a href="http://wiki.sa-mp.com/wiki/Color_ID">color ID</a>. <b><c>-1</c></b> for random (random color chosen by client)</param>
895/// <param name="respawn_delay">The delay until the car is respawned without a driver, in seconds</param>
896/// <param name="addsiren"><b>Added in 0.3.7; will not work in earlier versions.</b> Enables the vehicle to have a siren, providing the vehicle has a horn (optional=<b><c>0</c></b>)</param>
897/// <returns>
898///   <ul>
899///     <li>The vehicle ID of the vehicle created (between <b><c>1</c></b> and <b><c>MAX_VEHICLES</c></b>).</li>
900///     <li><b><c>INVALID_VEHICLE_ID</c></b> (<b><c>65535</c></b>) if vehicle was not created (vehicle limit reached or invalid vehicle model ID passed).</li>
901///   </ul>
902/// </returns>
903/// <remarks>Can only be used when the server first starts (under <a href="#OnGameModeInit">OnGameModeInit</a>).</remarks>
904/// <seealso name="AddStaticVehicle"/>
905/// <seealso name="CreateVehicle"/>
906/// <seealso name="DestroyVehicle"/>
907native AddStaticVehicleEx(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, color1, color2, respawn_delay, addsiren=0);
908
909/// <summary>This function adds a 'static' pickup to the game. These pickups support weapons, health, armor etc., with the ability to function without scripting them (weapons/health/armor will be given automatically).</summary>
910/// <param name="model">The model of the pickup</param>
911/// <param name="type">The pickup type. Determines how the pickup responds when picked up</param>
912/// <param name="X">The X coordinate to create the pickup at</param>
913/// <param name="Y">The Y coordinate to create the pickup at</param>
914/// <param name="Z">The Z coordinate to create the pickup at</param>
915/// <param name="virtualworld">The virtual world ID to put the pickup in. Use -1 to show the pickup in all worlds</param>
916/// <returns>
917///   <b><c>1</c></b> if the pickup is successfully created.
918///   <p/>
919///   <b><c>0</c></b> if failed to create.
920/// </returns>
921/// <remarks>This function doesn't return a pickup ID that you can use in, for example, <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a>. Use <a href="#CreatePickup">CreatePickup</a> if you'd like to assign IDs.</remarks>
922/// <seealso name="CreatePickup"/>
923/// <seealso name="DestroyPickup"/>
924/// <seealso name="OnPlayerPickUpPickup"/>
925native AddStaticPickup(model, type, Float:X, Float:Y, Float:Z, virtualworld = 0);
926
927/// <summary>This function does exactly the same as AddStaticPickup, except it returns a pickup ID which can be used to destroy it afterwards and be tracked using <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a>.</summary>
928/// <param name="model">The <a href="http://wiki.sa-mp.com/wiki/Pickup_IDs">model</a> of the pickup</param>
929/// <param name="type">The pickup spawn type (see table under remarks)</param>
930/// <param name="X">The X coordinate to create the pickup at</param>
931/// <param name="Y">The Y coordinate to create the pickup at</param>
932/// <param name="Z">The Z coordinate to create the pickup at</param>
933/// <param name="virtualworld">The virtual world ID of the pickup. Use <b><c>-1</c></b> to make the pickup show in all worlds (optional=<b><c>0</c></b>)</param>
934/// <seealso name="AddStaticPickup"/>
935/// <seealso name="DestroyPickup"/>
936/// <seealso name="OnPlayerPickUpPickup"/>
937/// <remarks>
938///   <b>Known Bugs:</b><p/>
939///   Pickups that have a X or Y lower than <b><c>-4096.0</c></b> or bigger than <b><c>4096.0</c></b> won't show up and won't trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a> either.
940/// </remarks>
941/// <remarks>
942///   The only type of pickup that can be picked up from inside a vehicle is <b><c>14</c></b> (except for special pickups such as bribes).<p/>
943///   Pickups are shown to, and can be picked up by all players.<p/>
944///   It is possible that if <a href="#DestroyPickup">DestroyPickup</a> is used when a pickup is picked up, more than one player can pick up the pickup, due to lag. This can be circumvented through the use of variables.<p/>
945///   Certain pickup types come with 'automatic responses', for example using an M4 model in the pickup will automatically give the player the weapon and some ammo. For fully scripted pickups, type <b><c>1</c></b> should be used. <p/>
946/// </remarks>
947/// <remarks>
948///   <b>Available Pickup Types</b><p/>
949///   Most other IDs are either undocumented or are similar to type <b><c>1</c></b> (but do not use them just because they seem similar to ID <b><c>1</c></b>, they might have side-effects like ID <b><c>18</c></b> and <b><c>20</c></b>).
950///   <ul>
951///     <li><b><c>0</c></b> - The pickup does not always display. If displayed, it can't be picked up and does not trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a> and it will stay after server shutdown.</li>
952///     <li><b><c>1</c></b> - Exists always. Disables pickup scripts such as horseshoes and oysters to allow for scripted actions ONLY. Will trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a> every few seconds.</li>
953///     <li><b><c>2</c></b> - Disappears after pickup, respawns after 30 seconds if the player is at a distance of at least 15 meters.</li>
954///     <li><b><c>3</c></b> - Disappears after pickup, respawns after death.</li>
955///     <li><b><c>4</c></b> - Disappears after 15 to 20 seconds. Respawns after death.</li>
956///     <li><b><c>8</c></b> - Disappears after pickup, but has no effect.</li>
957///     <li><b><c>11</c></b> - Blows up a few seconds after being created (bombs?)</li>
958///     <li><b><c>12</c></b> - Blows up a few seconds after being created.</li>
959///     <li><b><c>13</c></b> - Invisible. Triggers checkpoint sound when picked up with a vehicle, but doesn't trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a>.</li>
960///     <li><b><c>14</c></b> - Disappears after pickup, can only be picked up with a vehicle. Triggers checkpoint sound.</li>
961///     <li><b><c>15</c></b> - Same as type <b><c>2</c></b>.</li>
962///     <li><b><c>18</c></b> - Similar to type <b><c>1</c></b>. Pressing Tab (<b><c>KEY_ACTION</c></b>) makes it disappear but the key press doesn't trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a>.</li>
963///     <li><b><c>19</c></b> - Disappears after pickup, but doesn't respawn. Makes "cash pickup" sound if picked up.</li>
964///     <li><b><c>20</c></b> - Similar to type <b><c>1</c></b>. Disappears when you take a picture of it with the Camera weapon, which triggers "Snapshot # out of 0" message. Taking a picture doesn't trigger <a href="#OnPlayerPickUpPickup">OnPlayerPickUpPickup</a>.</li>
965///     <li><b><c>22</c></b> - Same as type <b><c>3</c></b>.</li>
966///   </ul>
967/// </remarks>
968/// <returns>The ID of the created pickup, <b><c>-1</c></b> on failure (<a href="http://wiki.sa-mp.com/wiki/Limits">pickup max limit</a>).</returns>
969native CreatePickup(model, type, Float:X, Float:Y, Float:Z, virtualworld = 0);
970
971/// <summary>Destroys a pickup created with <a href="#CreatePickup">CreatePickup</a>.</summary>
972/// <param name="pickup">The ID of the pickup to destroy (returned by <a href="#CreatePickup">CreatePickup</a>)</param>
973/// <seealso name="CreatePickup"/>
974/// <seealso name="OnPlayerPickUpPickup"/>
975native DestroyPickup(pickup);
976
977/// <summary>Toggle the drawing of nametags, health bars and armor bars above players.</summary>
978/// <param name="show"><b><c>0</c></b> to disable, <b><c>1</c></b> to enable (enabled by default)</param>
979/// <seealso name="DisableNameTagLOS"/>
980/// <seealso name="ShowPlayerNameTagForPlayer"/>
981/// <seealso name="ShowPlayerMarkers"/>
982/// <remarks>This function can only be used in <a href="#OnGameModeInit">OnGameModeInit</a>. For other times, see <a href="#ShowPlayerNameTagForPlayer">ShowPlayerNameTagForPlayer</a>.</remarks>
983native ShowNameTags(show);
984
985/// <summary>Toggles player markers (blips on the radar). Must be used when the server starts (<a href="#OnGameModeInit">OnGameModeInit</a>). For other times, see <a href="#SetPlayerMarkerForPlayer">SetPlayerMarkerForPlayer</a>.</summary>
986/// <param name="mode">The mode to use for markers. They can be streamed, meaning they are only visible to nearby players. See table below</param>
987/// <seealso name="SetPlayerMarkerForPlayer"/>
988/// <seealso name="LimitPlayerMarkerRadius"/>
989/// <seealso name="ShowNameTags"/>
990/// <seealso name="SetPlayerColor"/>
991/// <remarks>
992///   <b>Marker modes:</b><p/>
993///   <ul>
994///     <li><b><c>PLAYER_MARKERS_MODE_OFF</c></b> 0</li>
995///     <li><b><c>PLAYER_MARKERS_MODE_GLOBAL</c></b> 1</li>
996///     <li><b><c>PLAYER_MARKERS_MODE_STREAMED</c></b> 2</li>
997///   </ul>
998/// </remarks>
999/// <remarks>It is also possible to set a player's color to a color that has full transparency (no alpha value). This makes it possible to show markers on a per-player basis.</remarks>
1000native ShowPlayerMarkers(mode);
1001
1002/// <summary>Ends the current gamemode.</summary>
1003/// <seealso name="OnGameModeExit"/>
1004native GameModeExit();
1005
1006/// <summary>Sets the world time (for all players) to a specific hour.</summary>
1007/// <param name="hour">The hour to set (<b><c>0</c></b>-<b><c>23</c></b>)</param>
1008/// <seealso name="SetPlayerTime"/>
1009/// <seealso name="SetWeather"/>
1010/// <seealso name="SetGravity"/>
1011/// <remarks>To set the minutes and/or to set the time for individual players, see <a href="#SetPlayerTime">SetPlayerTime</a>.</remarks>
1012/// <remarks>This function is only relevant for players that do not use a passing clock - see <a href="#TogglePlayerClock">TogglePlayerClock</a>.</remarks>
1013native SetWorldTime(hour);
1014
1015/// <summary>Get the name of a weapon.</summary>
1016/// <param name="weaponid">The ID of the weapon to get the name of</param>
1017/// <param name="weapon">An array to store the weapon's name in, passed by reference</param>
1018/// <param name="len">The maximum length of the weapon name to store.</param>
1019/// <seealso name="GetPlayerWeapon"/>
1020/// <seealso name="AllowInteriorWeapons"/>
1021/// <seealso name="GivePlayerWeapon"/>
1022/// <returns>
1023///   <b><c>1</c></b>: The function executed successfully.<p/>
1024///   <b><c>0</c></b>: The function failed to execute. The weapon specified does not exist.
1025/// </returns>
1026native GetWeaponName(weaponid, weapon[], len = sizeof weapon);
1027
1028/// <param name="enable"><b><c>1</c></b> to enable, <b><c>0</c></b> to disable tire popping</param>
1029/// <remarks>This function was removed in <b>SA-MP 0.3</b>. Tire popping is enabled by default. If you want to disable tire popping, you'll have to manually script it using <a href="#OnVehicleDamageStatusUpdate">OnVehicleDamageStatusUpdate</a>.</remarks>
1030native EnableTirePopping(enable); // deprecated function
1031
1032/// <summary>Enable friendly fire for team vehicles. Players will be unable to damage teammates' vehicles (<a href="#SetPlayerTeam">SetPlayerTeam</a> must be used!).</summary>
1033/// <seealso name="SetPlayerTeam"/>
1034/// <remarks>This function was added in <b>SA-MP 0.3x</b> and will not work in earlier versions!</remarks>
1035native EnableVehicleFriendlyFire();
1036
1037/// <summary>Toggle whether the usage of weapons in interiors is allowed or not.</summary>
1038/// <param name="allow"><b><c>1</c></b> to enable weapons in interiors (enabled by default), <b><c>0</c></b> to disable weapons in interiors</param>
1039/// <remarks>This function does not work in the current SA:MP version!</remarks>
1040/// <seealso name="SetPlayerInterior"/>
1041/// <seealso name="GetPlayerInterior"/>
1042/// <seealso name="OnPlayerInteriorChange"/>
1043native AllowInteriorWeapons(allow);
1044
1045
1046/// <summary>Set the world weather for all players.</summary>
1047/// <param name="weatherid">The <a href="http://wiki.sa-mp.com/wiki/WeatherID">weather</a> to set</param>
1048/// <seealso name="SetPlayerWeather"/>
1049/// <seealso name="SetGravity"/>
1050/// <remarks>If <a href="#TogglePlayerClock">TogglePlayerClock</a> is enabled, weather will slowly change over time, instead of changing instantly.</remarks>
1051native SetWeather(weatherid);
1052
1053/// <summary>Get the currently set gravity.</summary>
1054/// <seealso name="SetGravity"/>
1055/// <returns>The current set gravity (as a float).</returns>
1056native Float:GetGravity();
1057
1058/// <summary>Set the gravity for all players.</summary>
1059/// <param name="gravity">The value that the gravity should be set to (between -50 and 50)</param>
1060/// <seealso name="GetGravity"/>
1061/// <seealso name="SetWeather"/>
1062/// <seealso name="SetWorldTime"/>
1063/// <remarks>Default gravity is <b><c>0.008</c></b>.</remarks>
1064/// <returns>This function always returns <b><c>1</c></b>, even when it fails to execute if the gravity is out of the limits (lower than <b><c>-50.0</c></b> or higher than <b><c>+50.0</c></b>).</returns>
1065native SetGravity(Float:gravity);
1066
1067/// <summary>This function will determine whether RCON admins will be teleported to their waypoint when they set one.</summary>
1068/// <param name="allow"><b><c>0</c></b> to disable and <b><c>1</c></b> to enable</param>
1069/// <remarks><b>This function, as of 0.3d, is deprecated. Please see <a href="#OnPlayerClickMap">OnPlayerClickMap</a>.</b></remarks>
1070/// <seealso name="IsPlayerAdmin"/>
1071/// <seealso name="AllowPlayerTeleport"/>
1072native AllowAdminTeleport(allow);
1073
1074/// <summary>This function does not work in the current SA:MP version! </summary>
1075/// <seealso name="CreatePickup"/>
1076/// <seealso name="GivePlayerMoney"/>
1077/// <seealso name="OnPlayerDeath"/>
1078native SetDeathDropAmount(amount);
1079
1080/// <summary>Create an explosion at the specified coordinates.</summary>
1081/// <param name="X">The X coordinate of the explosion</param>
1082/// <param name="Y">The Y coordinate of the explosion</param>
1083/// <param name="Z">The Z coordinate of the explosion</param>
1084/// <param name="type">The type of explosion</param>
1085/// <param name="Radius">The explosion radius</param>
1086/// <seealso name="CreateExplosionForPlayer"/>
1087/// <remarks>There is a limit as to how many explosions can be seen at once by a player. This is roughly 10.</remarks>
1088/// <returns>This function always returns <b><c>1</c></b>, even when the explosion type and/or radius values are invalid.</returns>
1089native CreateExplosion(Float:X, Float:Y, Float:Z, type, Float:Radius);
1090
1091/// <summary>This function allows to turn on zone / area names such as the "Vinewood" or "Doherty" text at the bottom-right of the screen as they enter the area. This is a gamemode option and should be set in the callback <a href="#OnGameModeInit">OnGameModeInit</a>.</summary>
1092/// <param name="enable">A toggle option for whether or not you'd like zone names on or off</param>
1093/// <remarks><b>This function was removed in SA-MP 0.3. This was due to crashes it caused.</b></remarks>
1094native EnableZoneNames(enable);
1095
1096/// <summary>Uses standard player walking animation (animation of the CJ skin) instead of custom animations for every skin (e.g. skating for skater skins).</summary>
1097/// <seealso name="ApplyAnimation"/>
1098/// <seealso name="ClearAnimations"/>
1099/// <remarks>Only works when placed under <a href="#OnGameModeInit">OnGameModeInit</a>.</remarks>
1100/// <remarks>Not using this function causes two-handed weapons (not dual-handed - a single weapon that is held by both hands) to be held in only one hand.</remarks>
1101native UsePlayerPedAnims(); // Will cause the players to use CJ running/walking animations
1102
1103/// <summary>Disable all the interior entrances and exits in the game (the yellow arrows at doors).</summary>
1104/// <seealso name="AllowInteriorWeapons"/>
1105/// <remarks>If the gamemode is changed after this function has been used, and the new gamemode doesn't disable markers, the markers will NOT reappear for already-connected players (but will for newly connected players).</remarks>
1106/// <remarks>This function will only work if it has been used BEFORE a player connects (it is recommended to use it in OnGameModeInit). It will not remove a connected player's markers.</remarks>
1107/// <returns>This function always returns <b><c>1</c></b>.</returns>
1108native DisableInteriorEnterExits();  // will disable all interior enter/exits in the game.
1109
1110/// <summary>Set the maximum distance to display the names of players.</summary>
1111/// <param name="distance">The distance to set</param>
1112/// <seealso name="LimitGlobalChatRadius"/>
1113/// <seealso name="ShowNameTags"/>
1114/// <seealso name="ShowPlayerNameTagForPlayer"/>
1115/// <remarks>Default distance is <b>70</b> SA units</remarks>
1116native SetNameTagDrawDistance(Float:distance); // Distance at which nametags will start rendering on the client.
1117
1118/// <summary>Disables the nametag Line-Of-Sight checking so that players can see nametags through objects.</summary>
1119/// <seealso name="ShowNameTags"/>
1120/// <seealso name="ShowPlayerNameTagForPlayer"/>
1121/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
1122/// <remarks>This can not be reversed until the server restarts.</remarks>
1123native DisableNameTagLOS(); // Disables the nametag Line-Of-Sight checking
1124
1125/// <summary>Set a radius limitation for the chat. Only players at a certain distance from the player will see their message in the chat. Also changes the distance at which a player can see other players on the map at the same distance.</summary>
1126/// <param name="chat_radius">The range in which players will be able to see chat</param>
1127/// <seealso name="SetNameTagDrawDistance"/>
1128/// <seealso name="SendPlayerMessageToPlayer"/>
1129/// <seealso name="SendPlayerMessageToAll"/>
1130/// <seealso name="OnPlayerText"/>
1131native LimitGlobalChatRadius(Float:chat_radius);
1132
1133/// <summary>Set the player marker radius.</summary>
1134/// <param name="marker_radius">The radius that markers will show at</param>
1135/// <seealso name="ShowPlayerMarkers"/>
1136/// <seealso name="SetPlayerMarkerForPlayer"/>
1137/// <seealso name="LimitGlobalChatRadius"/>
1138/// <remarks>This Function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
1139native LimitPlayerMarkerRadius(Float:marker_radius);
1140
1141// Npc
1142
1143/// <summary>Connect an NPC to the server.</summary>
1144/// <param name="name">The name the NPC should connect as. Must follow the same rules as normal player names</param>
1145/// <param name="script">The NPC script name that is located in the <b>npcmodes</b> folder (without the .amx extension)</param>
1146/// <seealso name="IsPlayerNPC"/>
1147/// <seealso name="OnPlayerConnect"/>
1148/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
1149/// <remarks>NPCs do not have nametags. These can be scripted with <a href="#Attach3DTextLabelToPlayer">Attach3DTextLabelToPlayer</a>.</remarks>
1150/// <returns>This function always return <b><c>1</c></b>.</returns>
1151native ConnectNPC(const name[], const script[]);
1152
1153/// <summary>Check if a player is an actual player or an NPC.</summary>
1154/// <param name="playerid">The ID of the player to check</param>
1155/// <seealso name="ConnectNPC"/>
1156/// <seealso name="IsPlayerAdmin"/>
1157/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
1158/// <returns><b><c>1</c></b> if the player is an NPC, <b><c>0</c></b> if not.</returns>
1159native IsPlayerNPC(playerid);
1160
1161native AddCharModel(baseid, newid, const dffname[], const txdname[]);
1162native AddSimpleModel(virtualworld, baseid, newid, const dffname[], const txdname[]);
1163native AddSimpleModelTimed(virtualworld, baseid, newid, const dffname[], const txdname[], timeon, timeoff);
1164native FindModelFileNameFromCRC(crc, retstr[], retstr_size = sizeof retstr);
1165native FindTextureFileNameFromCRC(crc, retstr[], retstr_size = sizeof retstr);
1166native RedirectDownload(playerid, const url[]);
1167
1168// Admin
1169
1170/// <summary>Check if a player is logged in as an RCON admin.</summary>
1171/// <param name="playerid">The ID of the player to check</param>
1172/// <seealso name="SendRconCommand"/>
1173/// <seealso name="OnRconLoginAttempt"/>
1174/// <returns><b><c>1</c></b> if the player is an RCON admin, <b><c>0</c></b> if not.</returns>
1175native IsPlayerAdmin(playerid);
1176
1177/// <summary>Kicks a player from the server. They will have to quit the game and re-connect if they wish to continue playing.</summary>
1178/// <param name="playerid">The ID of the player to kick</param>
1179/// <seealso name="Ban"/>
1180/// <seealso name="BanEx"/>
1181/// <remarks>As of <b>SA-MP 0.3x</b>, any action taken directly before Kick() (such as sending a message with <a href="#SendClientMessage">SendClientMessage</a>) will not reach the player. A timer must be used to delay the kick.</remarks>
1182/// <returns>This function always returns <b><c>1</c></b>, even if the function failed to execute (player specified doesn't exist).</returns>
1183native Kick(playerid);
1184
1185/// <summary>Ban a player who is currently in the server. They will be unable to join the server ever again. The ban will be IP-based, and be saved in the samp.ban file in the server's root directory. <a href="#BanEx">BanEx</a> can be used to give a reason for the ban. IP bans can be added/removed using the RCON banip and unbanip commands (<a href="#SendRconCommand">SendRconCommand</a>).</summary>
1186/// <param name="playerid">The ID of the player to ban</param>
1187/// <seealso name="BanEx"/>
1188/// <seealso name="Kick"/>
1189/// <remarks>As of <b>SA-MP 0.3x</b>, any action taken directly before Ban() (such as sending a message with SendClientMessage) will not reach the player. A timer must be used to delay the ban.</remarks>
1190/// <remarks></remarks>
1191native Ban(playerid);
1192
1193/// <summary>Ban a player with a reason.</summary>
1194/// <param name="playerid">The ID of the player to ban</param>
1195/// <param name="reason">The reason for the ban</param>
1196/// <seealso name="Ban"/>
1197/// <seealso name="Kick"/>
1198/// <remarks>As of <b>SA-MP 0.3x</b>, any action taken directly before Ban() (such as sending a message with SendClientMessage) will not reach the player. A timer must be used to delay the ban.</remarks>
1199native BanEx(playerid, const reason[]);
1200
1201
1202/// <summary>Sends an RCON (Remote Console) command.</summary>
1203/// <param name="command">The RCON command to be executed</param>
1204/// <seealso name="IsPlayerAdmin"/>
1205/// <seealso name="OnRconCommand"/>
1206/// <seealso name="OnRconLoginAttempt"/>
1207/// <remarks>Does not support login, due to the lack of a 'playerid' parameter.</remarks>
1208/// <remarks>'password 0' will remove the server's password if one is set.</remarks>
1209/// <returns>This function always returns <b><c>1</c></b>.</returns>
1210/// <remarks>This function will result in <a href="#OnRconCommand">OnRconCommand</a> being called.</remarks>
1211native SendRconCommand(const command[]);
1212
1213/// <summary>Gets a player's network stats and saves them into a string.</summary>
1214/// <param name="playerid">The ID of the player you want to get the networkstats of</param>
1215/// <param name="retstr">The string to store the networkstats in, passed by reference</param>
1216/// <param name="retstr_size">The length of the string that should be stored</param>
1217/// <seealso name="GetNetworkStats"/>
1218/// <seealso name="NetStats_GetConnectedTime"/>
1219/// <seealso name="NetStats_MessagesReceived"/>
1220/// <seealso name="NetStats_BytesReceived"/>
1221/// <seealso name="NetStats_MessagesSent"/>
1222/// <seealso name="NetStats_BytesSent"/>
1223/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1224/// <seealso name="NetStats_PacketLossPercent"/>
1225/// <seealso name="NetStats_ConnectionStatus"/>
1226/// <seealso name="NetStats_GetIpPort"/>
1227/// <remarks>This function was added in <b>SA-MP 0.3c R4</b> and will not work in earlier versions!</remarks>
1228/// <remarks>This function may not return accurate data when used under <a href="#OnPlayerDisconnect">OnPlayerDisconnect</a> if the player has quit normally. It usually returns accurate data if the player has been kicked or has timed out.</remarks>
1229native GetPlayerNetworkStats(playerid, retstr[], retstr_size = sizeof retstr);
1230
1231/// <summary>Gets the server's network stats and stores them in a string.</summary>
1232/// <param name="retstr">The string to store the network stats in, passed by reference</param>
1233/// <param name="retstr_size">The length of the string to be stored</param>
1234/// <seealso name="GetPlayerNetworkStats"/>
1235/// <seealso name="NetStats_GetConnectedTime"/>
1236/// <seealso name="NetStats_MessagesReceived"/>
1237/// <seealso name="NetStats_BytesReceived"/>
1238/// <seealso name="NetStats_MessagesSent"/>
1239/// <seealso name="NetStats_BytesSent"/>
1240/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1241/// <seealso name="NetStats_PacketLossPercent"/>
1242/// <seealso name="NetStats_ConnectionStatus"/>
1243/// <seealso name="NetStats_GetIpPort"/>
1244/// <remarks>This function was added in <b>SA-MP 0.3c R4</b> and will not work in earlier versions!</remarks>
1245/// <remarks>
1246///   <b>Example output:</b><p/>
1247///   <c>
1248///     Server Ticks: 200<p/>
1249///     Messages in Send buffer: 0<p/>
1250///     Messages sent: 142<p/>
1251///     Bytes sent: 8203<p/>
1252///     Acks sent: 11<p/>
1253///     Acks in send buffer: 0<p/>
1254///     Messages waiting for ack: 0<p/>
1255///     Messages resent: 0<p/>
1256///     Bytes resent: 0<p/>
1257///     Packetloss: 0.0%<p/>
1258///     Messages received: 54<p/>
1259///     Bytes received: 2204<p/>
1260///     Acks received: 0<p/>
1261///     Duplicate acks received: 0<p/>
1262///     Inst. KBits per second: 28.8<p/>
1263///     KBits per second sent: 10.0<p/>
1264///     KBits per second received: 2.7<p/>
1265///   </c>
1266/// </remarks>
1267/// <returns>This function always returns <b><c>1</c></b>.</returns>
1268native GetNetworkStats(retstr[], retstr_size = sizeof retstr);
1269
1270/// <summary>Returns the SA-MP client version, as reported by the player.</summary>
1271/// <param name="playerid">The ID of the player to get the client version of</param>
1272/// <param name="version">The string to store the player's version in, passed by reference</param>
1273/// <param name="len">The maximum length of the version</param>
1274/// <seealso name="GetPlayerName"/>
1275/// <seealso name="GetPlayerPing"/>
1276/// <seealso name="GetPlayerIp"/>
1277/// <remarks>This function was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
1278/// <remarks>The string the version gets stored in will be empty if playerid is an NPC.</remarks>
1279/// <returns><b><c>1</c></b> on success and <b><c>0</c></b> on failure (if player specified doesn't exist).</returns>
1280native GetPlayerVersion(playerid, version[], len = sizeof version); // Returns the SA-MP client revision as reported by the player
1281
1282/// <summary>Blocks an IP address from further communication with the server for a set amount of time (with wildcards allowed). Players trying to connect to the server with a blocked IP address will receive the generic "You are banned from this server." message. Players that are online on the specified IP before the block will timeout after a few seconds and, upon reconnect, will receive the same message.</summary>
1283/// <param name="ip_address">The IP to block</param>
1284/// <param name="timems">The time (in milliseconds) that the connection will be blocked for. <b><c>0</c></b> can be used for an indefinite block</param>
1285/// <seealso name="UnBlockIpAddress"/>
1286/// <seealso name="OnIncomingConnection"/>
1287/// <remarks>This function was added in <b>SA-MP 0.3z R2-2</b> and will not work in earlier versions!</remarks>
1288/// <remarks>Wildcards can be used with this function, for example blocking the IP <b><c>6.9.*.*</c></b> will block all IPs where the first two octets are <b><c>6</c></b> and <b><c>9</c></b> respectively. Any number can be in place of an asterisk.</remarks>
1289native BlockIpAddress(const ip_address[], timems);
1290
1291
1292/// <summary>Unblock an IP address that was previously blocked using <a href="#BlockIpAddress">BlockIpAddress</a>.</summary>
1293/// <param name="ip_address">The IP address to unblock</param>
1294/// <seealso name="BlockIpAddress"/>
1295/// <seealso name="OnIncomingConnection"/>
1296/// <remarks>This function was added in <b>SA-MP 0.3z R2-2</b> and will not work in earlier versions!</remarks>
1297native UnBlockIpAddress(const ip_address[]);
1298
1299// Deprecated:
1300
1301/// <summary>Get the string value of a server variable.</summary>
1302/// <param name="varname">The name of the string variable to get the value of</param>
1303/// <param name="buffer">An array into which to store the value, passed by reference</param>
1304/// <param name="len">The length of the string that should be stored</param>
1305/// <seealso name="GetServerVarAsInt"/>
1306/// <seealso name="GetServerVarAsBool"/>
1307/// <remarks>This function, as of <b>0.3.7 R2</b>, is deprecated. Please see <a href="#GetConsoleVarAsString">GetConsoleVarAsString</a></remarks>
1308/// <remarks>Using this function on anything other than a <b>string</b> (int, bool or float) or a <b>nonexistent</b> server variable, will <b>crash</b> your server! This is a bug.</remarks>
1309/// <remarks>Type 'varlist' in the server console to display a list of available server variables and their types.</remarks>
1310/// <remarks>When filterscripts or plugins is specified as the varname, this function only returns the name of the first specified filterscript or plugin. This is a bug.</remarks>
1311/// <returns>The length of the returned string. <b><c>0</c></b> if the specified server variable is not a string or doesn't exist.</returns>
1312native GetServerVarAsString(const varname[], buffer[], len = sizeof buffer);
1313
1314/// <summary>Get the integer value of a server variable.</summary>
1315/// <param name="varname">The name of the integer variable to get the value of</param>
1316/// <seealso name="GetServerVarAsString"/>
1317/// <seealso name="GetServerVarAsBool"/>
1318/// <remarks>This function, as of <b>0.3.7 R2</b>, is deprecated. Please see <a href="#GetConsoleVarAsInt">GetConsoleVarAsInt</a></remarks>
1319/// <remarks>Type 'varlist' in the server console to display a list of available server variables and their types.</remarks>
1320/// <returns>The value of the specified server variable. 0 if the specified server variable is not an integer or doesn't exist.</returns>
1321native GetServerVarAsInt(const varname[]);
1322
1323/// <summary>Get the boolean value of a server variable.</summary>
1324/// <param name="varname">The name of the boolean variable to get the value of</param>
1325/// <seealso name="GetServerVarAsString"/>
1326/// <seealso name="GetServerVarAsInt"/>
1327/// <remarks>This function, as of <b>0.3.7 R2</b>, is deprecated. Please see <a href="#GetConsoleVarAsBool">GetConsoleVarAsBool</a></remarks>
1328/// <remarks>Type 'varlist' in the server console to display a list of available server variables and their types.</remarks>
1329/// <returns>The value of the specified server variable. <b><c>0</c></b> if the specified server variable is not a boolean or doesn't exist.</returns>
1330native GetServerVarAsBool(const varname[]);
1331// These are the same 3 functions as above although they avoid the name ambiguity/conflict with the SVar system.
1332
1333/// <summary>Get the string value of a console variable.</summary>
1334/// <param name="varname">The name of the string variable to get the value of</param>
1335/// <param name="buffer">An array into which to store the value, passed by reference</param>
1336/// <param name="len">The length of the string that should be stored</param>
1337/// <seealso name="GetConsoleVarAsInt"/>
1338/// <seealso name="GetConsoleVarAsBool"/>
1339/// <remarks>Type <b><c>varlist</c></b> in the server console to display a list of available console variables and their types.</remarks>
1340/// <remarks>When filterscripts or plugins are specified as the varname, this function only returns the name of the first specified filterscript or plugin.</remarks>
1341/// <remarks>Using this function with anything other than a <b>string</b> (integer, boolean or float) will cause your server to crash. Using it with a nonexistent console variable will also cause your server to crash.</remarks>
1342/// <returns>The length of the returned string. <b><c>0</c></b> if the specified console variable is not a string or doesn't exist.</returns>
1343native GetConsoleVarAsString(const varname[], buffer[], len = sizeof buffer);
1344
1345/// <summary>Get the integer value of a console variable.</summary>
1346/// <param name="varname">The name of the integer variable to get the value of</param>
1347/// <seealso name="GetConsoleVarAsString"/>
1348/// <seealso name="GetConsoleVarAsBool"/>
1349/// <remarks>Type <b><c>varlist</c></b> in the server console to display a list of available console variables and their types.</remarks>
1350/// <returns>The value of the specified console variable. <b><c>0</c></b> if the specified console variable is not an integer or doesn't exist.</returns>
1351native GetConsoleVarAsInt(const varname[]);
1352
1353/// <summary>Get the boolean value of a console variable.</summary>
1354/// <param name="varname">The name of the boolean variable to get the value of</param>
1355/// <seealso name="GetConsoleVarAsString"/>
1356/// <seealso name="GetConsoleVarAsInt"/>
1357/// <remarks>Type <b><c>varlist</c></b> in the server console to display a list of available console variables and their types.</remarks>
1358/// <returns>The value of the specified console variable. <b><c>0</c></b> if the specified console variable is not a boolean or doesn't exist.</returns>
1359native GetConsoleVarAsBool(const varname[]);
1360
1361// Extended admin network stats
1362
1363/// <summary>Gets the tick rate (like FPS) of the server.</summary>
1364/// <seealso name="GetNetworkStats"/>
1365/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1366/// <returns>The server tick rate (per second). Returns <b><c>0</c></b> when the server is just started.</returns>
1367native GetServerTickRate();
1368
1369/// <summary>Gets the amount of time (in milliseconds) that a player has been connected to the server for.</summary>
1370/// <param name="playerid">The ID of the player to get the connected time of</param>
1371/// <seealso name="GetPlayerNetworkStats"/>
1372/// <seealso name="GetNetworkStats"/>
1373/// <seealso name="NetStats_MessagesReceived"/>
1374/// <seealso name="NetStats_BytesReceived"/>
1375/// <seealso name="NetStats_MessagesSent"/>
1376/// <seealso name="NetStats_BytesSent"/>
1377/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1378/// <seealso name="NetStats_PacketLossPercent"/>
1379/// <seealso name="NetStats_ConnectionStatus"/>
1380/// <seealso name="NetStats_GetIpPort"/>
1381/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1382/// <remarks>The return value is not reset to zero after changing the game mode (using the RCON command "gmx").</remarks>
1383/// <returns>This function returns the amount of time (in milliseconds) that a player has been connected to the server for. <b><c>0</c></b> is returned if the player is not connected.</returns>
1384native NetStats_GetConnectedTime(playerid);
1385
1386/// <summary>Gets the number of messages the server has received from the player.</summary>
1387/// <param name="playerid">The ID of the player to get the data from</param>
1388/// <seealso name="GetPlayerNetworkStats"/>
1389/// <seealso name="GetNetworkStats"/>
1390/// <seealso name="NetStats_GetConnectedTime"/>
1391/// <seealso name="NetStats_BytesReceived"/>
1392/// <seealso name="NetStats_MessagesSent"/>
1393/// <seealso name="NetStats_BytesSent"/>
1394/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1395/// <seealso name="NetStats_PacketLossPercent"/>
1396/// <seealso name="NetStats_ConnectionStatus"/>
1397/// <seealso name="NetStats_GetIpPort"/>
1398/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1399/// <returns>This function returns the number of messages the server has received from the player. <b><c>0</c></b> is returned if the player is not connected.</returns>
1400native NetStats_MessagesReceived(playerid);
1401
1402/// <summary>Gets the amount of data (in bytes) that the server has received from the player.</summary>
1403/// <param name="playerid">The ID of the player to get the data from</param>
1404/// <seealso name="GetPlayerNetworkStats"/>
1405/// <seealso name="GetNetworkStats"/>
1406/// <seealso name="NetStats_GetConnectedTime"/>
1407/// <seealso name="NetStats_MessagesReceived"/>
1408/// <seealso name="NetStats_MessagesSent"/>
1409/// <seealso name="NetStats_BytesSent"/>
1410/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1411/// <seealso name="NetStats_PacketLossPercent"/>
1412/// <seealso name="NetStats_ConnectionStatus"/>
1413/// <seealso name="NetStats_GetIpPort"/>
1414/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1415/// <returns>This function returns the number of bytes the server has received from the player. <b><c>0</c></b> is returned if the player is not connected.</returns>
1416native NetStats_BytesReceived(playerid);
1417
1418/// <summary>Gets the number of messages the server has sent to the player.</summary>
1419/// <param name="playerid">The ID of the player to get the data from</param>
1420/// <seealso name="GetPlayerNetworkStats"/>
1421/// <seealso name="GetNetworkStats"/>
1422/// <seealso name="NetStats_GetConnectedTime"/>
1423/// <seealso name="NetStats_MessagesReceived"/>
1424/// <seealso name="NetStats_BytesReceived"/>
1425/// <seealso name="NetStats_BytesSent"/>
1426/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1427/// <seealso name="NetStats_PacketLossPercent"/>
1428/// <seealso name="NetStats_ConnectionStatus"/>
1429/// <seealso name="NetStats_GetIpPort"/>
1430/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1431/// <returns>The number of messages the server has sent to the player.</returns>
1432native NetStats_MessagesSent(playerid);
1433
1434/// <summary>Gets the amount of data (in bytes) that the server has sent to the player.</summary>
1435/// <param name="playerid">The ID of the player to get the data from</param>
1436/// <seealso name="GetPlayerNetworkStats"/>
1437/// <seealso name="GetNetworkStats"/>
1438/// <seealso name="NetStats_GetConnectedTime"/>
1439/// <seealso name="NetStats_MessagesReceived"/>
1440/// <seealso name="NetStats_MessagesSent"/>
1441/// <seealso name="NetStats_BytesReceived"/>
1442/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1443/// <seealso name="NetStats_PacketLossPercent"/>
1444/// <seealso name="NetStats_ConnectionStatus"/>
1445/// <seealso name="NetStats_GetIpPort"/>
1446/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1447/// <returns>This function returns the number of bytes the server has sent to the player. <b><c>0</c></b> is returned if the player is not connected.</returns>
1448native NetStats_BytesSent(playerid);
1449
1450/// <summary>Gets the number of messages the player has received in the last second.</summary>
1451/// <param name="playerid">The ID of the player to get the data from</param>
1452/// <seealso name="GetPlayerNetworkStats"/>
1453/// <seealso name="GetNetworkStats"/>
1454/// <seealso name="NetStats_GetConnectedTime"/>
1455/// <seealso name="NetStats_MessagesReceived"/>
1456/// <seealso name="NetStats_BytesReceived"/>
1457/// <seealso name="NetStats_MessagesSent"/>
1458/// <seealso name="NetStats_BytesSent"/>
1459/// <seealso name="NetStats_PacketLossPercent"/>
1460/// <seealso name="NetStats_ConnectionStatus"/>
1461/// <seealso name="NetStats_GetIpPort"/>
1462/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1463/// <returns>the number of messages the player has received in the last second.</returns>
1464native NetStats_MessagesRecvPerSecond(playerid);
1465
1466/// <summary>Gets the packet loss percentage of a player. Packet loss means data the player is sending to the server is being lost (or vice-versa).</summary>
1467/// <param name="playerid">The ID of the player to get the data from</param>
1468/// <seealso name="GetPlayerNetworkStats"/>
1469/// <seealso name="GetNetworkStats"/>
1470/// <seealso name="NetStats_GetConnectedTime"/>
1471/// <seealso name="NetStats_MessagesReceived"/>
1472/// <seealso name="NetStats_BytesReceived"/>
1473/// <seealso name="NetStats_MessagesSent"/>
1474/// <seealso name="NetStats_BytesSent"/>
1475/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1476/// <seealso name="NetStats_ConnectionStatus"/>
1477/// <seealso name="NetStats_GetIpPort"/>
1478/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1479/// <remarks>Anything greater than 0.0% should already be a cause of concern. Anything greater than 1.0% is outright bad.</remarks>
1480/// <remarks>This function has been found to be currently unreliable the output is not as expected when compared to the client. Therefore this function should not be used as a packet loss kicker. </remarks>
1481/// <remarks>A more accurate packetloss function can be found here: <a href="http://forum.sa-mp.com/showpost.php?p=2488911&amp;postcount=984">http://forum.sa-mp.com/showpost.php?p=2488911&amp;postcount=984</a></remarks>
1482/// <returns>The percentage packet loss as a float. <b><c>0.0</c></b> if player not connected.</returns>
1483native Float:NetStats_PacketLossPercent(playerid);
1484
1485/// <summary>Gets the player's current connection status.</summary>
1486/// <param name="playerid">The ID of the player to get the connection status of</param>
1487/// <seealso name="GetPlayerNetworkStats"/>
1488/// <seealso name="GetNetworkStats"/>
1489/// <seealso name="NetStats_GetConnectedTime"/>
1490/// <seealso name="NetStats_MessagesReceived"/>
1491/// <seealso name="NetStats_BytesReceived"/>
1492/// <seealso name="NetStats_MessagesSent"/>
1493/// <seealso name="NetStats_BytesSent"/>
1494/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1495/// <seealso name="NetStats_PacketLossPercent"/>
1496/// <seealso name="NetStats_GetIpPort"/>
1497/// <seealso name="IsPlayerConnected"/>
1498/// <seealso name="OnPlayerConnect"/>
1499/// <seealso name="OnPlayerDisconnect"/>
1500/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1501/// <remarks>
1502///   <b>Status:</b><p/>
1503///   <ul>
1504///     <li><b><c>0 - NO_ACTION</c></b></li>
1505///     <li><b><c>1 - DISCONNECT_ASAP</c></b></li>
1506///     <li><b><c>2 - DISCONNECT_ASAP_SILENTLY</c></b></li>
1507///     <li><b><c>3 - DISCONNECT_ON_NO_ACK</c></b></li>
1508///     <li><b><c>4 - REQUESTED_CONNECTION</c></b></li>
1509///     <li><b><c>5 - HANDLING_CONNECTION_REQUEST</c></b></li>
1510///     <li><b><c>6 - UNVERIFIED_SENDER</c></b></li>
1511///     <li><b><c>7 - SET_ENCRYPTION_ON_MULTIPLE_16_BYTE_PACKET</c></b></li>
1512///     <li><b><c>8 - CONNECTED</c></b></li>
1513///   </ul>
1514/// </remarks>
1515/// <returns>The player's connection status, as an integer value.</returns>
1516native NetStats_ConnectionStatus(playerid);
1517
1518/// <summary>Get a player's IP and port.</summary>
1519/// <param name="playerid">The ID of the player to get the IP and port of</param>
1520/// <param name="ip_port">A string array to store the IP and port in, passed by reference</param>
1521/// <param name="ip_port_len">The maximum length of the IP/port. 22 is recommended</param>
1522/// <seealso name="GetPlayerIp"/>
1523/// <seealso name="GetPlayerNetworkStats"/>
1524/// <seealso name="GetNetworkStats"/>
1525/// <seealso name="NetStats_GetConnectedTime"/>
1526/// <seealso name="NetStats_MessagesReceived"/>
1527/// <seealso name="NetStats_BytesReceived"/>
1528/// <seealso name="NetStats_MessagesSent"/>
1529/// <seealso name="NetStats_BytesSent"/>
1530/// <seealso name="NetStats_MessagesRecvPerSecond"/>
1531/// <seealso name="NetStats_PacketLossPercent"/>
1532/// <seealso name="NetStats_ConnectionStatus"/>
1533/// <remarks>This function was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
1534native NetStats_GetIpPort(playerid, ip_port[], ip_port_len = sizeof ip_port);
1535
1536// Menu
1537
1538/// <summary>Creates a menu.</summary>
1539/// <param name="title">The title for the new menu</param>
1540/// <param name="columns">How many colums shall the new menu have</param>
1541/// <param name="x">The X position of the menu (640x460 canvas - <b><c>0</c></b> would put the menu at the far left)</param>
1542/// <param name="y">The Y position of the menu (640x460 canvas - <b><c>0</c></b> would put the menu at the far top)</param>
1543/// <param name="col1width">The width for the first column</param>
1544/// <param name="col2width">The width for the second column (optional=<b><c>0.0</c></b>)</param>
1545/// <seealso name="AddMenuItem"/>
1546/// <seealso name="SetMenuColumnHeader"/>
1547/// <seealso name="DestroyMenu"/>
1548/// <seealso name="ShowMenuForPlayer"/>
1549/// <seealso name="HideMenuForPlayer"/>
1550/// <seealso name="OnPlayerSelectedMenuRow"/>
1551/// <seealso name="OnPlayerExitedMenu"/>
1552/// <remarks>
1553///   This function merely CREATES the menu - <a href="#ShowMenuForPlayer">ShowMenuForPlayer</a> must be used to show it.<p/>
1554///   You can only create and access <b><c>2</c></b> columns (<b><c>0</c></b> and <b><c>1</c></b>).<p/>
1555///   If the title's length is equal to or greater than <b><c>32</c></b> chars the title is truncated to <b><c>30</c></b> characters.
1556/// </remarks>
1557/// <remarks>There is a limit of <b><c>12</c></b> items per menu, and a limit of <b><c>128</c></b> menus in total.</remarks>
1558/// <returns>The ID of the new menu or <b><c>-1</c></b> on failure.</returns>
1559native Menu:CreateMenu(const title[], columns, Float:x, Float:y, Float:col1width, Float:col2width = 0.0);
1560
1561/// <summary>Destroys the specified menu.</summary>
1562/// <param name="menuid">The menu ID to destroy</param>
1563/// <seealso name="CreateMenu"/>
1564/// <seealso name="SetMenuColumnHeader"/>
1565/// <seealso name="AddMenuItem"/>
1566/// <seealso name="OnPlayerSelectedMenuRow"/>
1567/// <seealso name="OnPlayerExitedMenu"/>
1568/// <returns><b><c>1</c></b> if the destroying was successful, otherwise <b><c>0</c></b>.</returns>
1569native DestroyMenu(Menu:menuid);
1570
1571/// <summary>Adds an item to a specified menu.</summary>
1572/// <param name="menuid">The menu id to add an item to</param>
1573/// <param name="column">The column to add the item to</param>
1574/// <param name="menutext">The text for the new menu item</param>
1575/// <remarks>
1576///   <ul>
1577///     <li>Crashes when passed an invalid menu ID.</li>
1578///     <li>You can only have <b><c>12</c></b> items per menu (13th goes to the right side of the header of column name (colored), 14th and higher not display at all).</li>
1579///     <li>You can only use <b><c>2</c></b> columns (<b><c>0</c></b> and <b><c>1</c></b>).</li>
1580///     <li>You can only add <b><c>8</c></b> color codes per one item (<b><c>~r~</c></b>, <b><c>~g~</c></b> etc.).</li>
1581///     <li>Maximum length of menu item is <b><c>31</c></b> symbols. </li>
1582///   </ul>
1583/// </remarks>
1584/// <returns>The index of the row this item was added to.</returns>
1585/// <seealso name="CreateMenu"/>
1586/// <seealso name="SetMenuColumnHeader"/>
1587/// <seealso name="DestroyMenu"/>
1588/// <seealso name="OnPlayerSelectedMenuRow"/>
1589/// <seealso name="OnPlayerExitedMenu"/>
1590native AddMenuItem(Menu:menuid, column, const menutext[]);
1591
1592/// <summary>Sets the caption of a column in a menu.</summary>
1593/// <param name="menuid">ID of the menu to change</param>
1594/// <param name="column">The column (<b><c>0</c></b> or <b><c>1</c></b>) to set the header of</param>
1595/// <param name="columnheader">The caption text for the column</param>
1596/// <seealso name="AddMenuItem"/>
1597/// <seealso name="CreateMenu"/>
1598/// <seealso name="OnPlayerSelectedMenuRow"/>
1599/// <remarks>Crashes when passed an invalid menu ID.</remarks>
1600/// <remarks>Note that you can add only <b><c>12</c></b> items with <a href="#AddMenuItem">AddMenuItem</a>. The 13th object of a menu would replace the header of the column which is correctly set with this function.</remarks>
1601native SetMenuColumnHeader(Menu:menuid, column, const columnheader[]);
1602
1603/// <summary>Shows a previously created menu for a player.</summary>
1604/// <param name="menuid">The ID of the menu to show. Returned by CreateMenu</param>
1605/// <param name="playerid">The ID of the player to whom the menu will be shown</param>
1606/// <seealso name="CreateMenu"/>
1607/// <seealso name="AddMenuItem"/>
1608/// <seealso name="SetMenuColumnHeader"/>
1609/// <seealso name="ShowPlayerDialog"/>
1610/// <seealso name="OnPlayerSelectedMenuRow"/>
1611/// <seealso name="OnPlayerExitedMenu"/>
1612/// <remarks>Crashes the both server and player if an invalid menu ID given.</remarks>
1613/// <returns>
1614///   <b><c>1</c></b>: The function executed successfully.<p/>
1615///   <b><c>0</c></b>: The function failed to execute. Menu and/or player doesn't exist.
1616/// </returns>
1617native ShowMenuForPlayer(Menu:menuid, playerid);
1618
1619/// <summary>Hides a menu for a player.</summary>
1620/// <param name="menuid">The ID of the menu to hide. Returned by <a href="#CreateMenu">CreateMenu</a> and passed to <a href="#OnPlayerSelectedMenuRow">OnPlayerSelectedMenuRow</a></param>
1621/// <param name="playerid">The ID of the player that the menu will be hidden for</param>
1622/// <seealso name="ShowMenuForPlayer"/>
1623/// <seealso name="AddMenuItem"/>
1624/// <seealso name="SetMenuColumnHeader"/>
1625/// <seealso name="CreateMenu"/>
1626/// <returns>
1627///   <b><c>1</c></b>: The function executed successfully.<p/>
1628///   <b><c>0</c></b>: The function failed to execute.
1629/// </returns>
1630native HideMenuForPlayer(Menu:menuid, playerid);
1631
1632/// <summary>Check if a menu ID is vliad.</summary>
1633/// <param name="menuid">The menu to check for existance</param>
1634/// <seealso name="CreateMenu"/>
1635/// <seealso name="DestroyMenu"/>
1636/// <returns><b><c>1</c></b> if the menu is valid, otherwise <b><c>0</c></b>.</returns>
1637native IsValidMenu(Menu:menuid);
1638
1639/// <summary>Disable a menu.</summary>
1640/// <param name="menuid">The ID of the menu to disable</param>
1641/// <seealso name="CreateMenu"/>
1642/// <seealso name="DestroyMenu"/>
1643/// <seealso name="AddMenuItem"/>
1644/// <remarks>Crashes when passed an invalid menu ID.</remarks>
1645native DisableMenu(Menu:menuid);
1646
1647/// <summary>Disable a specific row in a menu <b>for all players</b>. It will be greyed-out and can't be selected by players.</summary>
1648/// <param name="menuid">The ID of the menu to disable a row of. Ensure this is valid, as an invalid menu ID will crash the entire server</param>
1649/// <param name="row">The ID of the row to disable (rows start at 0)</param>
1650/// <seealso name="CreateMenu"/>
1651/// <seealso name="DestroyMenu"/>
1652/// <seealso name="AddMenuItem"/>
1653/// <remarks>
1654///   Crashes when passed an invalid menu ID.<p/>
1655///   This function disabled the specified menu row for <b>all players</b>. There is no function to disable a menu row for a specific player. You'd have to create two menus - one with a row disabled, and one without. Or one per player.
1656/// </remarks>
1657/// <returns>This function always returns <b><c>1</c></b>, even if the function fails. If an invalid row is specified, nothing will happen. If an invalid menu ID is specified, the server will crash.</returns>
1658native DisableMenuRow(Menu:menuid, row);
1659
1660/// <summary>Gets the ID of the menu the player is currently viewing (shown by <a href="#ShowMenuForPlayer">ShowMenuForPlayer</a>).</summary>
1661/// <param name="playerid">The ID of the player to get the current menu of</param>
1662/// <seealso name="ShowMenuForPlayer"/>
1663/// <seealso name="HideMenuForPlayer"/>
1664/// <seealso name="CreateMenu"/>
1665/// <seealso name="DestroyMenu"/>
1666/// <seealso name="AddMenuItem"/>
1667/// <seealso name="OnPlayerSelectedMenuRow"/>
1668/// <seealso name="OnPlayerExitedMenu"/>
1669/// <remarks>Returns previous menu when none is displayed.</remarks>
1670/// <returns>The ID of the player's currently shown menu, or <b><c>INVALID_MENU</c></b> (<b><c>255</c></b>) if no menu shown.</returns>
1671native Menu:GetPlayerMenu(playerid);
1672
1673/// <summary>Creates a textdraw. Textdraws are, as the name implies, text (mainly - there can be boxes, sprites and model previews (skins/vehicles/weapons/objects too) that is drawn on a player's screens.</summary>
1674/// <param name="x">The X (left/right) coordinate to create the textdraw at</param>
1675/// <param name="y">The Y (up/down) coordinate to create the textdraw at</param>
1676/// <param name="text">The text that will appear in the textdraw</param>
1677/// <remarks>
1678///   If you choose values for y that are less than 1, the first text row will be invisible and only the shadow is visible.<p/>
1679///   text[] must not be empty or the server will crash! If you need a textdraw that shows nothing, use a space underscore. <b>Now it's fixed</b>.<p/>
1680///   If the last character in the text is a space, the text will all be blank.<p/>
1681///   If part of the text is off-screen, the color of the text will not show, only the shadow (if enabled) will.
1682/// </remarks>
1683/// <remarks>
1684///   <em>This applies ONLY to sa-mp versions before 0.3z:</em><p/>
1685///   Maximum length of textdraw is <b>800</b> characters. Longer text will crash the client in older versions.<p/>
1686///   If you use color codes (such as <b><c>~R~ ~G~</c></b>) beyond 255th character the client will crash trying to display the textdraw.
1687/// </remarks>
1688/// <remarks>
1689///   The x,y coordinate is the top left coordinate for the text draw area based on a 640x480 "canvas" (irrespective of screen resolution). If you plan on using <a href="#TextDrawAlignment">TextDrawAlignment</a> with alignment <b><c>3</c></b> (right), the x,y coordinate is the top right coordinate for the text draw.<p/>
1690///   This function merely CREATES the textdraw, you must use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a> or <a href="#TextDrawShowForAll">TextDrawShowForAll</a> to show it.<p/>
1691///   It is recommended to use WHOLE numbers instead of decimal positions when creating textdraws to ensure resolution friendly design.
1692/// </remarks>
1693/// <remarks>Keyboard key mapping codes (such as <b><c>~k~~VEHICLE_ENTER_EXIT~</c></b> don't work beyond 255th character. </remarks>
1694/// <returns>The ID of the created textdraw. Textdraw IDs start at <b><c>0</c></b>.</returns>
1695native Text:TextDrawCreate(Float:x, Float:y, const text[]);
1696
1697/// <summary>Destroys a previously-created textdraw.</summary>
1698/// <param name="text">The ID of the textdraw to destroy. Returned by <a href="#TextDrawCreate">TextDrawCreate</a></param>
1699native TextDrawDestroy(Text:text);
1700
1701/// <summary>Sets the width and height of the letters.</summary>
1702/// <param name="text">The TextDraw to change</param>
1703/// <param name="x">Width of a char</param>
1704/// <param name="y">Height of a char</param>
1705/// <remarks>When using this function purely for the benefit of affecting the TextDraw box, multiply 'Y' by <b><c>0.135</c></b> to convert to <a href="#TextDrawTextSize">TextDrawTextSize</a>-like measurements. <b>Hint</b>: it is easier and extremely precise to use <b><c>LD_SPAC:white</c></b> sprite for box-only textdraws, <a href="#TextDrawTextSize">TextDrawTextSize</a> will have regular offsets.</remarks>
1706/// <remarks>If you want to change the letter size of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible. </remarks>
1707/// <remarks>Fonts appear to look the best with an X to Y ratio of <b><c>1</c></b> to <b><c>4</c></b> (e.g. if x is <b><c>0.5</c></b> then y should be <b><c>2</c></b>). </remarks>
1708native TextDrawLetterSize(Text:text, Float:x, Float:y);
1709
1710/// <summary>Change the size of a textdraw (box if <a href="#TextDrawUseBox">TextDrawUseBox</a> is enabled and/or clickable area for use with <a href="#TextDrawSetSelectable">TextDrawSetSelectable</a>).</summary>
1711/// <param name="text">The TextDraw to set the size of</param>
1712/// <param name="x">The size on the X axis (left/right) following the same 640x480 grid as <a href="#TextDrawCreate">TextDrawCreate</a></param>
1713/// <param name="y">The size on the Y axis (up/down) following the same 640x480 grid as <a href="#TextDrawCreate">TextDrawCreate</a></param>
1714/// <remarks>
1715///   The x and y have different meanings with different TextDrawAlignment values:<p/>
1716///   <ul>
1717///     <li><b><c>1</c></b> (left): they are the right-most corner of the box, absolute coordinates.</li>
1718///     <li><b><c>2</c></b> (center): they need to inverted (switch the two) and the x value is the overall width of the box.</li>
1719///     <li><b><c>3</c></b> (right): the x and y are the coordinates of the left-most corner of the box </li>
1720///   </ul>
1721/// </remarks>
1722/// <remarks>
1723///   Using font type <b><c>4</c></b> (sprite) and <b><c>5</c></b> (model preview) converts X and Y of this function from corner coordinates to WIDTH and HEIGHT (offsets).<p/>
1724///   The TextDraw box starts <b><c>10.0</c></b> units up and <b><c>5.0</c></b> to the left as the origin (<a href="#TextDrawCreate">TextDrawCreate</a> coordinate).<p/>
1725///   This function defines the clickable area for use with <a href="#TextDrawSetSelectable">TextDrawSetSelectable</a>, whether a box is shown or not.
1726/// </remarks>
1727/// <remarks>If you want to change the text size of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1728native TextDrawTextSize(Text:text, Float:x, Float:y);
1729
1730/// <summary>Set the alignment of text in a text draw.</summary>
1731/// <param name="text">The ID of the textdraw to set the alignment of</param>
1732/// <param name="alignment"><b><c>1</c></b>-left <b><c>2</c></b>-centered <b><c>3</c></b>-right</param>
1733/// <remarks>For alignment <b><c>2</c></b> (center) the x and y values of <a href="#TextSize">TextSize</a> need to be swapped, see notes at <a href="#TextDrawTextSize">TextDrawTextSize</a>, also position coordinate become position of center of textdraw and not left/top edges. </remarks>
1734native TextDrawAlignment(Text:text, alignment);
1735
1736/// <summary>Sets the text color of a textdraw.</summary>
1737/// <param name="text">The ID of the textdraw to change the color of.</param>
1738/// <param name="color">The color to set the textdraw to</param>
1739/// <remarks>You can also use GameText Colors in TextDraws.</remarks>
1740/// <remarks>If the TextDraw is already shown, it must be re-shown (<a href="#TextDrawShowForAll">TextDrawShowForAll</a>/<a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>) for the changes of this function to take effect.</remarks>
1741native TextDrawColor(Text:text, color);
1742
1743/// <summary>Toggle whether a textdraw uses a box or not.</summary>
1744/// <param name="text">The ID of the text textdraw to toggle the box of</param>
1745/// <param name="use"><b><c>1</c></b> to show a box or <b><c>0</c></b> to not show a box</param>
1746/// <remarks>If the textdraw is already shown, it must be re-shown (<a href="#TextDrawShowForAll">TextDrawShowForAll</a>/<a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>) to show the changes of this function.</remarks>
1747/// <returns>
1748///   <b><c>1</c></b>: The function executed successfully.<p/>
1749///   <b><c>0</c></b>: The function failed to execute. This means the textdraw specified does not exist.
1750/// </returns>
1751native TextDrawUseBox(Text:text, use);
1752
1753/// <summary>Adjusts the text box colour (only used if <a href="#TextDrawUseBox">TextDrawUseBox</a> 'use' parameter is <b><c>1</c></b>).</summary>
1754/// <param name="text">The TextDraw to change</param>
1755/// <param name="color">The colour (<b>RGBA</b>)</param>
1756/// <remarks>If you want to change the boxcolour of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1757native TextDrawBoxColor(Text:text, color);
1758
1759/// <summary>Sets the size of a textdraw's text's shadow.</summary>
1760/// <param name="text">The ID of the textdraw to set the shadow size of</param>
1761/// <param name="size">The size of the shadow. <b><c>1</c></b> is generally used for a normal shadow size. <b><c>0</c></b> disables the shadow completely</param>
1762/// <remarks>The shadow can be cut by the box area if the size is set too big for the area.</remarks>
1763/// <remarks>If you want to change the shadow of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1764/// <returns>
1765///   <b><c>1</c></b>: The function executed successfully.<p/>
1766///   <b><c>0</c></b>: The function failed to execute. The textdraw does not exist.
1767/// </returns>
1768native TextDrawSetShadow(Text:text, size);
1769
1770/// <summary>Sets the thickness of a textdraw's text's outline. <a href="#TextDrawBackgroundColor">TextDrawBackgroundColor</a> can be used to change the color.</summary>
1771/// <param name="text">The ID of the text draw to set the outline thickness of</param>
1772/// <param name="size">The thickness of the outline, as an integer. <b><c>0</c></b> for no outline</param>
1773/// <remarks>If you want to change the outline of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1774native TextDrawSetOutline(Text:text, size);
1775
1776/// <summary>Adjusts the text draw area background color (the outline/shadow - NOT the box. For box color, see <a href="#TextDrawBoxColor">TextDrawBoxColor</a>).</summary>
1777/// <param name="text">The ID of the textdraw to set the background color of</param>
1778/// <param name="color">The color that the textdraw should be set to</param>
1779/// <remarks>If <a href="#TextDrawSetOutline">TextDrawSetOutline</a> is used with size &gt; <b><c>0</c></b>, the outline color will match the color used in <a href="#TextDrawBackgroundColor">TextDrawBackgroundColor</a>. Changing the value of color seems to alter the color used in <a href="#TextDrawColor">TextDrawColor</a></remarks>
1780/// <remarks>If you want to change the background colour of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1781native TextDrawBackgroundColor(Text:text, color);
1782
1783/// <summary>Changes the text font.</summary>
1784/// <param name="text">The TextDraw to change</param>
1785/// <param name="font">There are four font styles, see <a href="http://wiki.sa-mp.com/wiki/PlayerTextDrawFont">http://wiki.sa-mp.com/wiki/PlayerTextDrawFont</a>. Font value <b><c>4</c></b> specifies that this is a txd sprite; <b><c>5</c></b> specifies that this textdraw can display preview models. A font value greater than 5 does not display, and anything greater than 16 crashes the client</param>
1786/// <remarks>If you want to change the font of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible.</remarks>
1787native TextDrawFont(Text:text, font);
1788
1789/// <summary>Appears to scale text spacing to a proportional ratio. Useful when using <a href="#TextDrawLetterSize">TextDrawLetterSize</a> to ensure the text has even character spacing.</summary>
1790/// <param name="text">The ID of the textdraw to set the proportionality of</param>
1791/// <param name="set"><b><c>1</c></b> to enable proportionality, <b><c>0</c></b> to disable</param>
1792/// <remarks>Proportionality is set to <b><c>1</c></b> by default, you might skip this function if you don't want to disable it. </remarks>
1793/// <remarks>If you want to change the proportionality of a textdraw that is already shown, you don't have to recreate it. Simply use <a href="#TextDrawShowForPlayer">TextDrawShowForPlayer</a>/<a href="#TextDrawShowForAll">TextDrawShowForAll</a> after modifying the textdraw and the change will be visible. </remarks>
1794native TextDrawSetProportional(Text:text, set);
1795
1796/// <summary>Sets whether a textdraw can be selected (clicked on) or not.</summary>
1797/// <param name="text">The ID of the textdraw to make selectable</param>
1798/// <param name="set"><b><c>1</c></b> to make it selectable, or <b><c>0</c></b> to make it not selectable</param>
1799/// <remarks>This function was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
1800/// <remarks><a href="#TextDrawSetSelectable">TextDrawSetSelectable</a> must be used BEFORE the textdraw is shown to players for it to be selectable.</remarks>
1801/// <remarks>Use <a href="#TextDrawTextSize">TextDrawTextSize</a> to define the clickable area.</remarks>
1802native TextDrawSetSelectable(Text:text, set);
1803
1804/// <summary>Shows a textdraw for a specific player.</summary>
1805/// <param name="playerid">The ID of the player to show the textdraw for</param>
1806/// <param name="text">The ID of the textdraw to show. Returned by <a href="#TextDrawCreate">TextDrawCreate</a></param>
1807/// <remarks>If only a single player will see a textdraw, it might be wise to use player-textdraws instead. This is also useful for textdraws that need to show information specific for an individual player.</remarks>
1808/// <returns>
1809///   <b><c>1</c></b>: The function executed successfully.<p/>
1810///   <b><c>0</c></b>: The function failed to execute. This means either the player and/or textdraw specified does not exist.
1811/// </returns>
1812native TextDrawShowForPlayer(playerid, Text:text);
1813
1814/// <summary>Hides a textdraw for a specific player.</summary>
1815/// <param name="playerid">The ID of the player that the textdraw should be hidden for</param>
1816/// <param name="text">The ID of the textdraw to hide</param>
1817/// <seealso name="TextDrawHideForAll"/>
1818/// <seealso name="TextDrawShowForPlayer"/>
1819/// <seealso name="TextDrawShowForAll"/>
1820native TextDrawHideForPlayer(playerid, Text:text);
1821
1822/// <summary>Shows a textdraw for all players.</summary>
1823/// <param name="text">The ID of the textdraw to show. Returned by <a href="#TextDrawCreate">TextDrawCreate</a></param>
1824/// <seealso name="TextDrawShowForPlayer"/>
1825/// <seealso name="TextDrawHideForPlayer"/>
1826/// <seealso name="TextDrawHideForAll"/>
1827/// <returns>
1828///   <b><c>1</c></b>: The function executed successfully.<p/>
1829///   <b><c>0</c></b>: The function failed to execute. This means the textdraw specified does not exist.
1830/// </returns>
1831native TextDrawShowForAll(Text:text);
1832
1833/// <summary>Hides a text draw for all players.</summary>
1834/// <param name="text">The ID of the textdraw to hide (returned by <a href="#TextDrawCreate">TextDrawCreate</a>)</param>
1835/// <seealso name="TextDrawShowForPlayer"/>
1836/// <seealso name="TextDrawHideForPlayer"/>
1837/// <seealso name="TextDrawShowForAll"/>
1838native TextDrawHideForAll(Text:text);
1839
1840/// <summary>Changes the text on a textdraw.</summary>
1841/// <param name="text">The TextDraw to change</param>
1842/// <param name="string">The new string for the TextDraw</param>
1843/// <remarks>There are limits to the length of textdraw strings - see <a href="http://wiki.sa-mp.com/wiki/Limits">here</a> for more info.</remarks>
1844native TextDrawSetString(Text:text, const string[]);
1845
1846/// <summary>Set the model for a textdraw model preview. Click <a href="http://www.sa-mp.com/stuff/03xShots/pmenu.png">here</a> to see this function's effect.</summary>
1847/// <param name="text">The textdraw id that will display the 3D preview</param>
1848/// <param name="modelindex">The GTA SA or SA:MP model ID to display</param>
1849/// <remarks>This function was added in <b>SA-MP 0.3x</b> and will not work in earlier versions!</remarks>
1850/// <remarks>The textdraw MUST use the font type <b><c>TEXT_DRAW_FONT_MODEL_PREVIEW</c></b> in order for this function to have effect.</remarks>
1851/// <remarks>Use <a href="#TextDrawBackgroundColor">TextDrawBackgroundColor</a> to set the background color behind the model.</remarks>
1852native TextDrawSetPreviewModel(Text:text, modelindex);
1853
1854/// <summary>Sets the rotation and zoom of a 3D model preview textdraw.</summary>
1855/// <param name="fRotX">The X rotation value</param>
1856/// <param name="fRotY">The Y rotation value</param>
1857/// <param name="fRotZ">The Z rotation value</param>
1858/// <param name="fZoom">The zoom value, smaller values make the camera closer and larger values make the camera further away (optional=<b><c>1.0</c></b>)</param>
1859/// <remarks>This function was added in <b>SA-MP 0.3x</b> and will not work in earlier versions!</remarks>
1860/// <remarks>The textdraw MUST use the font type <b><c>TEXT_DRAW_FONT_MODEL_PREVIEW</c></b> in order for this function to have effect.</remarks>
1861native TextDrawSetPreviewRot(Text:text, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fZoom = 1.0);
1862
1863/// <summary>If a vehicle model is used in a 3D preview textdraw, this sets the two colour values for that vehicle.</summary>
1864/// <param name="text">The textdraw id that is set to display a 3D vehicle model preview</param>
1865/// <param name="color1">The primary Color ID to set the vehicle to</param>
1866/// <param name="color2">The secondary Color ID to set the vehicle to</param>
1867/// <remarks>This function was added in <b>SA-MP 0.3x</b> and will not work in earlier versions!</remarks>
1868/// <remarks>The textdraw MUST use the font type <b><c>TEXT_DRAW_FONT_MODEL_PREVIEW</c></b> in order for this function to have effect.</remarks>
1869native TextDrawSetPreviewVehCol(Text:text, color1, color2);
1870
1871// Gang Zones
1872
1873/// <summary>Create a gangzone (colored radar area).</summary>
1874/// <param name="minx">The X coordinate for the west side of the gangzone</param>
1875/// <param name="miny">The Y coordinate for the south side of the gangzone</param>
1876/// <param name="maxx">The X coordinate for the east side of the gangzone</param>
1877/// <param name="maxy">The Y coordinate for the north side of the gangzone</param>
1878/// <seealso name="GangZoneDestroy"/>
1879/// <seealso name="GangZoneShowForPlayer"/>
1880/// <seealso name="GangZoneShowForAll"/>
1881/// <seealso name="GangZoneHideForPlayer"/>
1882/// <seealso name="GangZoneHideForAll"/>
1883/// <seealso name="GangZoneFlashForPlayer"/>
1884/// <seealso name="GangZoneFlashForAll"/>
1885/// <seealso name="GangZoneStopFlashForPlayer"/>
1886/// <seealso name="GangZoneStopFlashForAll"/>
1887/// <remarks>
1888///   There is a limit of <b><c>1024</c></b> gangzones.<p/>
1889///   Putting the parameters in the wrong order results in glitchy behavior.
1890/// </remarks>
1891/// <remarks>This function merely CREATES the gangzone, you must use <a href="#GangZoneShowForPlayer">GangZoneShowForPlayer</a> or <a href="#GangZoneShowForAll">GangZoneShowForAll</a> to show it.</remarks>
1892/// <returns>The ID of the created zone, returns <b><c>-1</c></b> if not created.</returns>
1893native GangZoneCreate(Float:minx, Float:miny, Float:maxx, Float:maxy);
1894
1895/// <summary>Destroy a gangzone.</summary>
1896/// <param name="zone">The ID of the zone to destroy</param>
1897/// <seealso name="GangZoneCreate"/>
1898/// <seealso name="GangZoneShowForPlayer"/>
1899/// <seealso name="GangZoneShowForAll"/>
1900/// <seealso name="GangZoneHideForPlayer"/>
1901/// <seealso name="GangZoneHideForAll"/>
1902/// <seealso name="GangZoneFlashForPlayer"/>
1903/// <seealso name="GangZoneFlashForAll"/>
1904/// <seealso name="GangZoneStopFlashForPlayer"/>
1905/// <seealso name="GangZoneStopFlashForAll"/>
1906native GangZoneDestroy(zone);
1907
1908/// <summary>Show a gangzone for a player. Must be created with <a href="#GangZoneCreate">GangZoneCreate</a> first.</summary>
1909/// <param name="playerid">The ID of the player you would like to show the gangzone for.</param>
1910/// <param name="zone">The ID of the gang zone to show for the player. Returned by <a href="#GangZoneCreate">GangZoneCreate</a></param>
1911/// <param name="color">The color to show the gang zone, as an integer or hex in <b>RGBA</b> color format. Alpha transparency supported</param>
1912/// <seealso name="GangZoneCreate"/>
1913/// <seealso name="GangZoneDestroy"/>
1914/// <seealso name="GangZoneShowForAll"/>
1915/// <seealso name="GangZoneHideForPlayer"/>
1916/// <seealso name="GangZoneHideForAll"/>
1917/// <seealso name="GangZoneFlashForPlayer"/>
1918/// <seealso name="GangZoneFlashForAll"/>
1919/// <seealso name="GangZoneStopFlashForPlayer"/>
1920/// <seealso name="GangZoneStopFlashForAll"/>
1921/// <returns><b><c>1</c></b> if the gangzone was shown, otherwise <b><c>0</c></b> (non-existant).</returns>
1922native GangZoneShowForPlayer(playerid, zone, color);
1923
1924/// <summary>Shows a gangzone with the desired color to all players.</summary>
1925/// <param name="zone">The ID of the gangzone to show (returned by <a href="# GangZoneCreate">GangZoneCreate</a>)</param>
1926/// <param name="color">The color to show the gang zone, as an integer or hex in <b>RGBA</b> color format. Alpha transparency supported</param>
1927/// <seealso name="GangZoneCreate"/>
1928/// <seealso name="GangZoneDestroy"/>
1929/// <seealso name="GangZoneShowForPlayer"/>
1930/// <seealso name="GangZoneHideForPlayer"/>
1931/// <seealso name="GangZoneHideForAll"/>
1932/// <seealso name="GangZoneFlashForPlayer"/>
1933/// <seealso name="GangZoneFlashForAll"/>
1934/// <seealso name="GangZoneStopFlashForPlayer"/>
1935/// <seealso name="GangZoneStopFlashForAll"/>
1936/// <returns>
1937///   <b><c>1</c></b>: The function executed successfully. The gang zone was shown for all players.<p/>
1938///   <b><c>0</c></b>: The function failed to execute. The gangzone does not exist.
1939/// </returns>
1940native GangZoneShowForAll(zone, color);
1941
1942/// <summary>Hides a gangzone for a player.</summary>
1943/// <param name="playerid">The ID of the player to hide the gangzone for</param>
1944/// <param name="zone">The ID of the zone to hide</param>
1945/// <seealso name="GangZoneCreate"/>
1946/// <seealso name="GangZoneDestroy"/>
1947/// <seealso name="GangZoneShowForPlayer"/>
1948/// <seealso name="GangZoneShowForAll"/>
1949/// <seealso name="GangZoneHideForAll"/>
1950/// <seealso name="GangZoneFlashForPlayer"/>
1951/// <seealso name="GangZoneFlashForAll"/>
1952/// <seealso name="GangZoneStopFlashForPlayer"/>
1953/// <seealso name="GangZoneStopFlashForAll"/>
1954native GangZoneHideForPlayer(playerid, zone);
1955
1956/// <summary>GangZoneHideForAll hides a gangzone from all players.</summary>
1957/// <param name="zone">The zone to hide</param>
1958/// <seealso name="GangZoneCreate"/>
1959/// <seealso name="GangZoneDestroy"/>
1960/// <seealso name="GangZoneShowForPlayer"/>
1961/// <seealso name="GangZoneShowForAll"/>
1962/// <seealso name="GangZoneHideForPlayer"/>
1963/// <seealso name="GangZoneFlashForPlayer"/>
1964/// <seealso name="GangZoneFlashForAll"/>
1965/// <seealso name="GangZoneStopFlashForPlayer"/>
1966/// <seealso name="GangZoneStopFlashForAll"/>
1967native GangZoneHideForAll(zone);
1968
1969/// <summary>Makes a gangzone flash for a player.</summary>
1970/// <param name="playerid">The ID of the player to flash the gangzone for</param>
1971/// <param name="zone">The ID of the zone to flash</param>
1972/// <param name="flashcolor">The color to flash the gang zone, as an integer or hex in <b>RGBA</b> color format. Alpha transparency supported</param>
1973/// <seealso name="GangZoneCreate"/>
1974/// <seealso name="GangZoneDestroy"/>
1975/// <seealso name="GangZoneShowForPlayer"/>
1976/// <seealso name="GangZoneShowForAll"/>
1977/// <seealso name="GangZoneHideForPlayer"/>
1978/// <seealso name="GangZoneHideForAll"/>
1979/// <seealso name="GangZoneFlashForAll"/>
1980/// <seealso name="GangZoneStopFlashForPlayer"/>
1981/// <seealso name="GangZoneStopFlashForAll"/>
1982native GangZoneFlashForPlayer(playerid, zone, flashcolor);
1983
1984/// <summary>GangZoneFlashForAll flashes a gangzone for all players.</summary>
1985/// <param name="zone">The zone to flash</param>
1986/// <param name="flashcolor">The color to flash the gang zone, as an integer or hex in <b>RGBA</b> color format. Alpha transparency supported</param>
1987/// <seealso name="GangZoneCreate"/>
1988/// <seealso name="GangZoneDestroy"/>
1989/// <seealso name="GangZoneShowForPlayer"/>
1990/// <seealso name="GangZoneShowForAll"/>
1991/// <seealso name="GangZoneHideForPlayer"/>
1992/// <seealso name="GangZoneHideForAll"/>
1993/// <seealso name="GangZoneFlashForPlayer"/>
1994/// <seealso name="GangZoneStopFlashForPlayer"/>
1995/// <seealso name="GangZoneStopFlashForAll"/>
1996native GangZoneFlashForAll(zone, flashcolor);
1997
1998/// <summary>Stops a gangzone flashing for a player.</summary>
1999/// <param name="playerid">The ID of the player to stop the gangzone flashing for</param>
2000/// <param name="zone">The ID of the gangzonezone to stop flashing</param>
2001/// <seealso name="GangZoneCreate"/>
2002/// <seealso name="GangZoneDestroy"/>
2003/// <seealso name="GangZoneShowForPlayer"/>
2004/// <seealso name="GangZoneShowForAll"/>
2005/// <seealso name="GangZoneHideForPlayer"/>
2006/// <seealso name="GangZoneHideForAll"/>
2007/// <seealso name="GangZoneFlashForPlayer"/>
2008/// <seealso name="GangZoneFlashForAll"/>
2009/// <seealso name="GangZoneStopFlashForAll"/>
2010native GangZoneStopFlashForPlayer(playerid, zone);
2011
2012/// <summary>Stops a gangzone flashing for all players.</summary>
2013/// <param name="zone">The ID of the zone to stop flashing. Returned by <a href="#GangZoneCreate">GangZoneCreate</a></param>
2014/// <seealso name="GangZoneCreate"/>
2015/// <seealso name="GangZoneDestroy"/>
2016/// <seealso name="GangZoneShowForPlayer"/>
2017/// <seealso name="GangZoneShowForAll"/>
2018/// <seealso name="GangZoneHideForPlayer"/>
2019/// <seealso name="GangZoneHideForAll"/>
2020/// <seealso name="GangZoneFlashForPlayer"/>
2021/// <seealso name="GangZoneFlashForAll"/>
2022/// <seealso name="GangZoneStopFlashForPlayer"/>
2023/// <returns>
2024///   <b><c>1</c></b>: The function executed successfully. Success is reported even if the gang zone wasn't flashing to begin with.<p/>
2025///   <b><c>0</c></b>: The function failed to execute. The gangzone specified does not exist.
2026/// </returns>
2027native GangZoneStopFlashForAll(zone);
2028
2029// Global 3D Text Labels
2030
2031/// <summary>Creates a 3D Text Label at a specific location in the world.</summary>
2032/// <param name="text">The initial text string</param>
2033/// <param name="color">The text Color, as an integer or hex in <b>RGBA</b> color format</param>
2034/// <param name="X">X-Coordinate</param>
2035/// <param name="Y">Y-Coordinate</param>
2036/// <param name="Z">Z-Coordinate</param>
2037/// <param name="DrawDistance">The distance from where you are able to see the 3D Text Label</param>
2038/// <param name="virtualworld">The virtual world in which you are able to see the 3D Text</param>
2039/// <param name="testLOS">Test the line-of-sight so this text can't be seen through objects (optional=<b><c>0</c></b>)</param>
2040/// <seealso name="Delete3DTextLabel"/>
2041/// <seealso name="Attach3DTextLabelToPlayer"/>
2042/// <seealso name="Attach3DTextLabelToVehicle"/>
2043/// <seealso name="Update3DTextLabelText"/>
2044/// <seealso name="CreatePlayer3DTextLabel"/>
2045/// <seealso name="DeletePlayer3DTextLabel"/>
2046/// <seealso name="UpdatePlayer3DTextLabelText"/>
2047/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2048/// <remarks>
2049///   If <paramref name="text"/> is empty, the server/clients next to the text might crash!<p/>
2050///   If the virtualworld is set as <b><c>-1</c></b> the text will not appear.
2051/// </remarks>
2052/// <remarks>drawdistance seems to be a lot smaller when spectating.</remarks>
2053/// <remarks>Use <a href="http://wiki.sa-mp.com/wiki/Colors_List#Inline_color_embedding">color embedding</a> for multiple colors in the text.</remarks>
2054/// <returns>The ID of the newly created 3D Text Label, or <b><c>INVALID_3DTEXT_ID</c></b> if the 3D Text Label limit (<b><c>MAX_3DTEXT_GLOBAL</c></b>) was reached.</returns>
2055native Text3D:Create3DTextLabel(const text[], color, Float:X, Float:Y, Float:Z, Float:DrawDistance, virtualworld, testLOS=0);
2056
2057/// <summary>Delete a 3D text label (created with <a href="#Create3DTextLabel">Create3DTextLabel</a>).</summary>
2058/// <param name="id">The ID of the 3D text label to delete</param>
2059/// <seealso name="Create3DTextLabel"/>
2060/// <seealso name="Attach3DTextLabelToPlayer"/>
2061/// <seealso name="Attach3DTextLabelToVehicle"/>
2062/// <seealso name="Update3DTextLabelText"/>
2063/// <seealso name="CreatePlayer3DTextLabel"/>
2064/// <seealso name="DeletePlayer3DTextLabel"/>
2065/// <seealso name="UpdatePlayer3DTextLabelText"/>
2066/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2067/// <returns><b><c>1</c></b> if the 3D text label was deleted, otherwise <b><c>0</c></b>.</returns>
2068native Delete3DTextLabel(Text3D:id);
2069
2070/// <summary>Attach a 3D text label to a player.</summary>
2071/// <param name="id">The ID of the 3D text label to attach. Returned by <a href="#Create3DTextLabel">Create3DTextLabel</a></param>
2072/// <param name="playerid">The ID of the player to attach the label to</param>
2073/// <param name="OffsetX">The X offset from the player</param>
2074/// <param name="OffsetY">The Y offset from the player</param>
2075/// <param name="OffsetZ">The Z offset from the player</param>
2076/// <seealso name="Create3DTextLabel"/>
2077/// <seealso name="Delete3DTextLabel"/>
2078/// <seealso name="Attach3DTextLabelToVehicle"/>
2079/// <seealso name="Update3DTextLabelText"/>
2080/// <seealso name="CreatePlayer3DTextLabel"/>
2081/// <seealso name="DeletePlayer3DTextLabel"/>
2082/// <seealso name="UpdatePlayer3DTextLabelText"/>
2083/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2084/// <returns>
2085/// <b><c>1</c></b>: The function executed successfully.<p/>
2086/// <b><c>0</c></b>: The function failed to execute. This means the player and/or label do not exist.
2087/// </returns>
2088native Attach3DTextLabelToPlayer(Text3D:id, playerid, Float:OffsetX, Float:OffsetY, Float:OffsetZ);
2089
2090/// <summary>Attaches a 3D Text Label to a specific vehicle.</summary>
2091/// <param name="id">The ID of the 3D text label to attach. Returned by <a href="#Create3DTextLabel">Create3DTextLabel</a></param>
2092/// <param name="vehicleid">The vehicle you want to attach the 3D Text Label to</param>
2093/// <param name="OffsetX">The Offset-X coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0).</param>
2094/// <param name="OffsetY">The Offset-Y coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0).</param>
2095/// <param name="OffsetZ">The Offset-Z coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0).</param>
2096/// <seealso name="Create3DTextLabel"/>
2097/// <seealso name="Delete3DTextLabel"/>
2098/// <seealso name="Attach3DTextLabelToPlayer"/>
2099/// <seealso name="Update3DTextLabelText"/>
2100/// <seealso name="CreatePlayer3DTextLabel"/>
2101/// <seealso name="DeletePlayer3DTextLabel"/>
2102/// <seealso name="UpdatePlayer3DTextLabelText"/>
2103/// <remarks>Attach3DTextLabelToPlayer was added in SA-MP 0.3a 	This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2104native Attach3DTextLabelToVehicle(Text3D:id, vehicleid, Float:OffsetX, Float:OffsetY, Float:OffsetZ);
2105
2106
2107/// <summary>Updates a 3D Text Label text and color.</summary>
2108/// <param name="id">The 3D Text Label you want to update</param>
2109/// <param name="color">The color the 3D Text Label should have from now on</param>
2110/// <param name="text">The new text which the 3D Text Label should have from now on</param>
2111/// <seealso name="Create3DTextLabel"/>
2112/// <seealso name="Delete3DTextLabel"/>
2113/// <seealso name="Attach3DTextLabelToPlayer"/>
2114/// <seealso name="Attach3DTextLabelToVehicle"/>
2115/// <seealso name="CreatePlayer3DTextLabel"/>
2116/// <seealso name="DeletePlayer3DTextLabel"/>
2117/// <seealso name="UpdatePlayer3DTextLabelText"/>
2118/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2119/// <remarks>If <paramref name="text"/> is empty, the server/clients next to the text might crash!</remarks>
2120native Update3DTextLabelText(Text3D:id, color, const text[]);
2121
2122// Per-player 3D Text Labels
2123
2124/// <summary>Creates a 3D Text Label only for a specific player.</summary>
2125/// <param name="playerid">The player which should see the newly created 3DText Label</param>
2126/// <param name="text">The text to display</param>
2127/// <param name="color">The text color</param>
2128/// <param name="X">X Coordinate (or offset if attached)</param>
2129/// <param name="Y">Y Coordinate (or offset if attached)</param>
2130/// <param name="Z">Z Coordinate (or offset if attached)</param>
2131/// <param name="DrawDistance">The distance where you are able to see the 3D Text Label</param>
2132/// <param name="attachedplayer">The player you want to attach the 3D Text Label to. (optional=<b><c>INVALID_PLAYER_ID</c></b>)</param>
2133/// <param name="attachedvehicle">The vehicle you want to attach the 3D Text Label to. (optional=<b><c>INVALID_VEHICLE_ID</c></b>)</param>
2134/// <param name="testLOS">Test the line-of-sight so this text can't be seen through walls (optional=<b><c>0</c></b>)</param>
2135/// <seealso name="Create3DTextLabel"/>
2136/// <seealso name="Delete3DTextLabel"/>
2137/// <seealso name="Attach3DTextLabelToPlayer"/>
2138/// <seealso name="Attach3DTextLabelToVehicle"/>
2139/// <seealso name="Update3DTextLabelText"/>
2140/// <seealso name="DeletePlayer3DTextLabel"/>
2141/// <seealso name="UpdatePlayer3DTextLabelText"/>
2142/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2143/// <remarks>If <paramref name="text"/> is empty, the server/clients next to the text might crash!</remarks>
2144/// <remarks>drawdistance seems to be a lot smaller when spectating.</remarks>
2145/// <returns>The ID of the newly created Player 3D Text Label, or <b><c>INVALID_3DTEXT_ID</c></b> if the Player 3D Text Label limit (<b><c>MAX_3DTEXT_PLAYER</c></b>) was reached.</returns>
2146native PlayerText3D:CreatePlayer3DTextLabel(playerid, const text[], color, Float:X, Float:Y, Float:Z, Float:DrawDistance, attachedplayer=INVALID_PLAYER_ID, attachedvehicle=INVALID_VEHICLE_ID, testLOS=0);
2147
2148/// <summary>Destroy a 3D text label that was created using <a href="#CreatePlayer3DTextLabel">CreatePlayer3DTextLabel</a>.</summary>
2149/// <param name="playerid">The ID of the player whose 3D text label to delete</param>
2150/// <param name="id">The ID of the player's 3D text label to delete</param>
2151/// <seealso name="Create3DTextLabel"/>
2152/// <seealso name="Attach3DTextLabelToPlayer"/>
2153/// <seealso name="Attach3DTextLabelToVehicle"/>
2154/// <seealso name="Update3DTextLabelText"/>
2155/// <seealso name="CreatePlayer3DTextLabel"/>
2156/// <seealso name="UpdatePlayer3DTextLabelText"/>
2157/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2158/// <returns>
2159///   <b><c>1</c></b>: The function executed successfully.<p/>
2160///   <b><c>0</c></b>: The function failed to execute. This means the label specified doesn't exist.
2161/// </returns>
2162native DeletePlayer3DTextLabel(playerid, PlayerText3D:id);
2163
2164/// <summary>Updates a player 3D Text Label's text and color.</summary>
2165/// <param name="playerid">The ID of the player for which the 3D Text Label was created</param>
2166/// <param name="id">The 3D Text Label you want to update</param>
2167/// <param name="color">The color the 3D Text Label should have from now on</param>
2168/// <param name="text">The new text which the 3D Text Label should have from now on</param>
2169/// <seealso name="Create3DTextLabel"/>
2170/// <seealso name="Delete3DTextLabel"/>
2171/// <seealso name="Attach3DTextLabelToPlayer"/>
2172/// <seealso name="Attach3DTextLabelToVehicle"/>
2173/// <seealso name="Update3DTextLabelText"/>
2174/// <seealso name="CreatePlayer3DTextLabel"/>
2175/// <seealso name="DeletePlayer3DTextLabel"/>
2176/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2177/// <remarks>If <paramref name="text"/> is empty, the server/clients next to the text might crash!</remarks>
2178native UpdatePlayer3DTextLabelText(playerid, PlayerText3D:id, color, const text[]);
2179
2180/// <summary>Shows the player a synchronous (only one at a time) dialog box.</summary>
2181/// <param name="playerid">The ID of the player to show the dialog to</param>
2182/// <param name="dialogid">An ID to assign this dialog to, so responses can be processed. Max dialogid is <b><c>32767</c></b>. Using negative values will close any open dialog</param>
2183/// <param name="style">The style of the dialog</param>
2184/// <param name="caption">The title at the top of the dialog. The length of the caption can not exceed more than 64 characters before it starts to cut off</param>
2185/// <param name="info">The text to display in the main dialog. Use <b><c>\n</c></b> to start a new line and <b><c>\t</c></b> to tabulate</param>
2186/// <param name="button1">The text on the left button</param>
2187/// <param name="button2">The text on the right button. Leave it blank ( "" ) to hide it</param>
2188/// <seealso name="TextDrawShowForPlayer"/>
2189/// <seealso name="OnDialogResponse"/>
2190/// <remarks>This function was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2191/// <remarks>Use color embedding for multiple colors in the text. </remarks>
2192/// <remarks>Using <b><c>-1</c></b> as dialogid closes all dialogs currently shown on the client's screen. </remarks>
2193/// <returns>
2194///   <b><c>1</c></b>: The function executed successfully.<p/>
2195///   <b><c>0</c></b>: The function failed to execute. This means the player is not connected.<p/>
2196/// </returns>
2197native ShowPlayerDialog(playerid, dialogid, style, const caption[], const info[], const button1[], const button2[]);
2198
2199/// <summary>Get a players unique ID.</summary>
2200/// <param name="playerid">The player to get the unique ID of</param>
2201/// <param name="serial">Where to save the unique ID</param>
2202/// <param name="maxlen">The size of "serial"</param>
2203native gpci(playerid, serial[], maxlen);
2204
2205// --------------------------------------------------
2206// Forwards (Callback declarations)
2207// --------------------------------------------------
2208
2209
2210/// <summary>This callback is triggered when the gamemode starts.</summary>
2211/// <seealso name="OnGameModeExit"/>
2212/// <seealso name="OnFilterScriptInit"/>
2213/// <seealso name="OnFilterScriptExit"/>
2214/// <remarks>This function can also be used in a filterscript to detect if the gamemode changes with RCON commands like changemode or gmx, as changing the gamemode does not reload a filterscript.</remarks>
2215/// <returns>
2216///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2217///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2218///   It is always called first in gamemode.
2219/// </returns>
2220forward OnGameModeInit();
2221
2222/// <summary>This callback is called when a gamemode ends, either through 'gmx', the server being shut down, or <a href="#GameModeExit">GameModeExit</a>.</summary>
2223/// <seealso name="OnGameModeInit"/>
2224/// <seealso name="OnFilterScriptExit"/>
2225/// <seealso name="OnFilterScriptInit"/>
2226/// <seealso name="GameModeExit"/>
2227/// <remarks>This function can also be used in a filterscript to detect if the gamemode changes with RCON commands like changemode or gmx, as changing the gamemode does not reload a filterscript.</remarks>
2228/// <remarks>When using OnGameModeExit in conjunction with the 'rcon gmx' console command keep in mind there is a potential for client bugs to occur an example of this is excessive <a href="#RemoveBuildingForPlayer">RemoveBuildingForPlayer</a> calls during OnGameModeInit which could result in a client crash. </remarks>
2229/// <remarks>This callback will NOT be called if the server crashes or the process is killed by other means, such as using the Linux kill command or pressing the close-button on the Windows console. </remarks>
2230/// <returns>
2231///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2232///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2233///   It is always called first in gamemode.
2234/// </returns>
2235forward OnGameModeExit();
2236
2237/// <summary>This callback is called when a filterscript is initialized (loaded). It is only called inside the filterscript which is starting.</summary>
2238/// <seealso name="OnFilterScriptExit"/>
2239/// <seealso name="OnGameModeInit"/>
2240/// <seealso name="OnGameModeExit"/>
2241/// <returns>This callback does not handle returns.</returns>
2242forward OnFilterScriptInit();
2243
2244/// <summary>This callback is called when a filterscript is unloaded. It is only called inside the filterscript which is unloaded.</summary>
2245/// <seealso name="OnFilterScriptInit"/>
2246/// <seealso name="OnGameModeInit"/>
2247/// <seealso name="OnGameModeExit"/>
2248/// <returns>This callback does not handle returns.</returns>
2249forward OnFilterScriptExit();
2250
2251/// <summary>This callback is called when a player connects to the server.</summary>
2252/// <param name="playerid">The ID of the player that connected</param>
2253/// <seealso name="OnPlayerDisconnect"/>
2254/// <seealso name="OnIncomingConnection"/>
2255/// <seealso name="OnPlayerFinishedDownloading"/>
2256/// <remarks>This callback can also be called by NPC.</remarks>
2257/// <returns>
2258///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2259///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2260///   It is always called first in filterscripts.
2261/// </returns>
2262forward OnPlayerConnect(playerid);
2263
2264/// <summary>This callback is called when a player disconnects from the server.</summary>
2265/// <param name="playerid">The ID of the player that disconnected</param>
2266/// <param name="reason">The reason for the disconnection. See table below</param>
2267/// <seealso name="OnPlayerConnect"/>
2268/// <seealso name="OnIncomingConnection"/>
2269/// <seealso name="OnPlayerFinishedDownloading"/>
2270/// <remarks>This callback can also be called by NPC.</remarks>
2271/// <remarks>Some functions might not work correctly when used in this callback because the player is already disconnected when the callback is called. This means that you can't get unambiguous information from functions like <a href="#GetPlayerIp">GetPlayerIp</a> and <a href="#GetPlayerPos">GetPlayerPos</a>.</remarks>
2272/// <remarks>
2273///   <b>Reasons:</b><p/>
2274///   <ul>
2275///     <li><b><c>0</c></b> - timeout/Crash - the player's connection was lost. Either their game crashed or their network had a fault.</li>
2276///     <li><b><c>1</c></b> - quit - the player purposefully quit, either using the <b><c>/quit (/q)</c></b> command or via the pause menu.</li>
2277///     <li><b><c>2</c></b> - kick/ban - the player was kicked or banned by the server.</li>
2278///   </ul>
2279/// </remarks>
2280/// <returns>
2281///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2282///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2283///   It is always called first in filterscripts.
2284/// </returns>
2285forward OnPlayerDisconnect(playerid, reason);
2286
2287/// <summary>This callback is called when a player spawns.(i.e. after caling <a href="#SpawnPlayer">SpawnPlayer</a> function).</summary>
2288/// <param name="playerid">The ID of the player that spawned</param>
2289/// <seealso name="OnPlayerDeath"/>
2290/// <seealso name="OnVehicleSpawn"/>
2291/// <seealso name="SpawnPlayer"/>
2292/// <seealso name="AddPlayerClass"/>
2293/// <seealso name="SetSpawnInfo"/>
2294/// <remarks>This callback can also be called by NPC.</remarks>
2295/// <remarks>The game sometimes deducts $100 from players after spawn.</remarks>
2296/// <returns>
2297///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2298///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2299///   It is always called first in filterscripts.
2300/// </returns>
2301forward OnPlayerSpawn(playerid);
2302
2303/// <summary>This callback is called when a player dies, either by suicide or by being killed by another player.</summary>
2304/// <param name="playerid">The ID of the player that died</param>
2305/// <param name="killerid">The ID of the player that killed the player who died, or <b><c>INVALID_PLAYER_ID</c></b> if there was none</param>
2306/// <param name="reason">The ID of the <a href="http://wiki.sa-mp.com/wiki/Weapons">reason</a> for the player's death</param>
2307/// <seealso name="OnPlayerSpawn"/>
2308/// <seealso name="SendDeathMessage"/>
2309/// <seealso name="SetPlayerHealth"/>
2310/// <remarks>
2311///   The reason will return 37 (flame thrower) from any fire sources (e.g. molotov, 18)<p/>
2312///   The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)<p/>
2313///   You do not need to check whether killerid is valid before using it in <a href="#SendDeathMessage">SendDeathMessage</a>. <b><c>INVALID_PLAYER_ID</c></b> is a valid killerid ID parameter in that function.<p/>
2314///   <b>playerid</b> is the only one who can call the callback. (good to know for anti fake death)
2315/// </remarks>
2316/// <returns>
2317///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2318///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2319///   It is always called first in filterscripts.
2320/// </returns>
2321forward OnPlayerDeath(playerid, killerid, reason);
2322
2323/// <summary>This callback is called when a vehicle <b>re</b>spawns.</summary>
2324/// <param name="vehicleid">The ID of the vehicle that spawned</param>
2325/// <seealso name="OnVehicleDeath"/>
2326/// <seealso name="OnPlayerSpawn"/>
2327/// <seealso name="SetVehicleToRespawn"/>
2328/// <seealso name="CreateVehicle"/>
2329/// <returns>
2330///   <b><c>0</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2331///   <b><c>1</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2332///   It is always called first in filterscripts.
2333/// </returns>
2334forward OnVehicleSpawn(vehicleid);
2335
2336/// <summary>This callback is called when a vehicle is destroyed - either by exploding or becoming submerged in water.</summary>
2337/// <param name="vehicleid">The ID of the vehicle that was destroyed</param>
2338/// <param name="killerid">The ID of the player that reported (synced) the vehicle's destruction (name is misleading). Generally the driver or a passenger (if any) or the closest player</param>
2339/// <seealso name="OnVehicleSpawn"/>
2340/// <seealso name="SetVehicleHealth"/>
2341/// <remarks>This callback can also be called by NPC.</remarks>
2342/// <remarks>This callback will also be called when a vehicle enters water, but the vehicle can be saved from destruction by teleportation or driving out (if only partially submerged). The callback won't be called a second time, and the vehicle may disappear when the driver exits, or after a short time.</remarks>
2343/// <returns>
2344///   This callback does not handle returns.<p/>
2345///   It is always called first in filterscripts.
2346/// </returns>
2347forward OnVehicleDeath(vehicleid, killerid);
2348
2349/// <summary>Called when a player sends a chat message.</summary>
2350/// <param name="playerid">The ID of the player who typed the text</param>
2351/// <param name="text">The text the player typed</param>
2352/// <seealso name="OnPlayerCommandText"/>
2353/// <seealso name="SendPlayerMessageToPlayer"/>
2354/// <seealso name="SendPlayerMessageToAll"/>
2355/// <remarks>This callback can also be called by NPC.</remarks>
2356/// <returns>
2357///   Returning <b><c>0</c></b> in this callback will stop the text from being sent to all players.<p/>
2358///   It is always called first in filterscripts so returning <b><c>0</c></b> there blocks other scripts from seeing it.
2359/// </returns>
2360forward OnPlayerText(playerid, text[]);
2361
2362/// <summary>This callback is called when a player enters a command into the client chat window. Commands are anything that start with a forward slash, e.g. <c>/help</c>.</summary>
2363/// <param name="playerid">The ID of the player that entered a command</param>
2364/// <param name="cmdtext">The command that was entered (including the forward slash)</param>
2365/// <seealso name="OnPlayerText"/>
2366/// <seealso name="OnRconCommand"/>
2367/// <seealso name="SendRconCommand"/>
2368/// <remarks>This callback can also be called by NPC.</remarks>
2369/// <returns>
2370///   Return <b><c>1</c></b> if the command was processed, otherwise <b><c>0</c></b>; If the command was not found both in filterscripts and in gamemode, the player will be received a message: <em>SERVER: Unknown command</em>.<p/>
2371///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks other scripts from seeing it.
2372/// </returns>
2373forward OnPlayerCommandText(playerid, cmdtext[]);
2374
2375/// <summary>Called when a player changes class at class selection (and when class selection first appears).</summary>
2376/// <param name="playerid">The ID of the player that changed class</param>
2377/// <param name="classid">The ID of the current class being viewed (returned by <a href="#AddPlayerClass">AddPlayerClass</a>)</param>
2378/// <seealso name="OnPlayerRequestSpawn"/>
2379/// <seealso name="AddPlayerClass"/>
2380/// <remarks>This callback can also be called by NPC.</remarks>
2381/// <remarks>This callback is also called when a player presses <b>F4</b>.</remarks>
2382/// <returns>
2383///   Returning <b><c>0</c></b> in this callback will prevent the player from spawning. The player can be forced to spawn when <a href="#SpawnPlayer">SpawnPlayer</a> is used.<p/>
2384///   It is always called first in filterscripts.
2385/// </returns>
2386forward OnPlayerRequestClass(playerid, classid);
2387
2388/// <summary>This callback is called when a player <b><c>starts</c></b> to enter a vehicle, meaning the player is not in vehicle yet at the time this callback is called.</summary>
2389/// <param name="playerid">ID of the player who attempts to enter a vehicle</param>
2390/// <param name="vehicleid">ID of the vehicle the player is attempting to enter</param>
2391/// <param name="ispassenger"><b><c>0</c></b> if entering as driver. <b><c>1</c></b> if entering as passenger</param>
2392/// <seealso name="OnPlayerExitVehicle"/>
2393/// <seealso name="OnPlayerStateChange"/>
2394/// <seealso name="PutPlayerInVehicle"/>
2395/// <seealso name="GetPlayerVehicleSeat"/>
2396/// <remarks>This callback is called when a player <b>BEGINS</b> to enter a vehicle, not when they HAVE entered it. See <a href="#OnPlayerStateChange">OnPlayerStateChange</a>. </remarks>
2397/// <remarks>This callback is still called if the player is denied entry to the vehicle (e.g. it is locked or full). </remarks>
2398/// <returns>
2399///   This callback does not handle returns.<p/>
2400///   It is always called first in filterscripts.
2401/// </returns>
2402forward OnPlayerEnterVehicle(playerid, vehicleid, ispassenger);
2403
2404/// <summary>This callback is called when a player <b>starts</b> to exit a vehicle.</summary>
2405/// <param name="playerid">The ID of the player that is exiting a vehicle</param>
2406/// <param name="vehicleid">The ID of the vehicle the player is exiting</param>
2407/// <seealso name="OnPlayerEnterVehicle"/>
2408/// <seealso name="OnPlayerStateChange"/>
2409/// <seealso name="RemovePlayerFromVehicle"/>
2410/// <seealso name="GetPlayerVehicleSeat"/>
2411/// <remarks>Not called if the player falls off a bike or is removed from a vehicle by other means such as using <a href="#SetPlayerPos">SetPlayerPos</a>.</remarks>
2412/// <remarks>You must use <a href="#OnPlayerStateChange">OnPlayerStateChange</a> and check if their old state is <b><c>PLAYER_STATE_DRIVER</c></b> or <b><c>PLAYER_STATE_PASSENGER</c></b> and their new state is <b><c>PLAYER_STATE_ONFOOT</c></b>.</remarks>
2413/// <returns>
2414///   This callback does not handle returns.<p/>
2415///   It is always called first in filterscripts.
2416/// </returns>
2417forward OnPlayerExitVehicle(playerid, vehicleid);
2418
2419/// <summary>This callback is called when a player changes state. For example, when a player changes from being the driver of a vehicle to being on-foot.</summary>
2420/// <param name="playerid">The ID of the player that changed state</param>
2421/// <param name="newstate">The player's new state</param>
2422/// <param name="oldstate">The player's previous state</param>
2423/// <seealso name="OnPlayerInteriorChange"/>
2424/// <seealso name="GetPlayerState"/>
2425/// <seealso name="GetPlayerSpecialAction"/>
2426/// <seealso name="SetPlayerSpecialAction"/>
2427/// <remarks>This callback can also be called by NPC.</remarks>
2428/// <remarks>
2429///   <b>States:</b><p/>
2430///   <ul>
2431///     <li><b><c>PLAYER_STATE_NONE</c></b> - empty (while initializing)</li>
2432///     <li><b><c>PLAYER_STATE_ONFOOT</c></b> - player is on foot</li>
2433///     <li><b><c>PLAYER_STATE_DRIVER</c></b> - player is the driver of a vehicle</li>
2434///     <li><b><c>PLAYER_STATE_PASSENGER</c></b> - player is passenger of a vehicle</li>
2435///     <li><b><c>PLAYER_STATE_WASTED</c></b> - player is dead or on class selection</li>
2436///     <li><b><c>PLAYER_STATE_SPAWNED</c></b> - player is spawned</li>
2437///     <li><b><c>PLAYER_STATE_SPECTATING</c></b> - player is spectating</li>
2438///     <li><b><c>PLAYER_STATE_EXIT_VEHICLE</c></b> - player exits a vehicle</li>
2439///     <li><b><c>PLAYER_STATE_ENTER_VEHICLE_DRIVER</c></b> - player enters a vehicle as driver</li>
2440///     <li><b><c>PLAYER_STATE_ENTER_VEHICLE_PASSENGER</c></b> - player enters a vehicle as passenger </li>
2441///   </ul>
2442/// </remarks>
2443/// <returns>
2444///   This callback does not handle returns.<p/>
2445///   It is always called first in filterscripts.
2446/// </returns>
2447forward OnPlayerStateChange(playerid, newstate, oldstate);
2448
2449/// <summary>This callback is called when a player enters the checkpoint set for that player.</summary>
2450/// <param name="playerid">The player who entered the checkpoint</param>
2451/// <seealso name="OnPlayerLeaveCheckpoint"/>
2452/// <seealso name="OnPlayerEnterRaceCheckpoint"/>
2453/// <seealso name="OnPlayerLeaveRaceCheckpoint"/>
2454/// <seealso name="SetPlayerCheckpoint"/>
2455/// <seealso name="DisablePlayerCheckpoint"/>
2456/// <seealso name="IsPlayerInCheckpoint"/>
2457/// <seealso name="SetPlayerRaceCheckpoint"/>
2458/// <seealso name="DisablePlayerRaceCheckpoint"/>
2459/// <seealso name="IsPlayerInRaceCheckpoint"/>
2460/// <remarks>This callback can also be called by NPC.</remarks>
2461/// <returns>
2462///   This callback does not handle returns.<p/>
2463///   It is always called first in filterscripts.
2464/// </returns>
2465forward OnPlayerEnterCheckpoint(playerid);
2466
2467/// <summary>This callback is called when a player leaves the checkpoint set for them by <a href="#SetPlayerCheckpoint">SetPlayerCheckpoint</a>. Only one checkpoint can be set at a time.</summary>
2468/// <param name="playerid">The ID of the player that left their checkpoint</param>
2469/// <seealso name="OnPlayerEnterCheckpoint"/>
2470/// <seealso name="OnPlayerEnterRaceCheckpoint"/>
2471/// <seealso name="OnPlayerLeaveRaceCheckpoint"/>
2472/// <seealso name="SetPlayerCheckpoint"/>
2473/// <seealso name="DisablePlayerCheckpoint"/>
2474/// <seealso name="IsPlayerInCheckpoint"/>
2475/// <seealso name="SetPlayerRaceCheckpoint"/>
2476/// <seealso name="DisablePlayerRaceCheckpoint"/>
2477/// <seealso name="IsPlayerInRaceCheckpoint"/>
2478/// <remarks>This callback can also be called by NPC.</remarks>
2479/// <returns>
2480///   This callback does not handle returns.<p/>
2481///   It is always called first in filterscripts.
2482/// </returns>
2483forward OnPlayerLeaveCheckpoint(playerid);
2484
2485/// <summary>This callback is called when a player enters a race checkpoint.</summary>
2486/// <param name="playerid">The ID of the player who entered the race checkpoint</param>
2487/// <seealso name="OnPlayerEnterCheckpoint"/>
2488/// <seealso name="OnPlayerLeaveCheckpoint"/>
2489/// <seealso name="OnPlayerLeaveRaceCheckpoint"/>
2490/// <seealso name="SetPlayerCheckpoint"/>
2491/// <seealso name="DisablePlayerCheckpoint"/>
2492/// <seealso name="IsPlayerInCheckpoint"/>
2493/// <seealso name="SetPlayerRaceCheckpoint"/>
2494/// <seealso name="DisablePlayerRaceCheckpoint"/>
2495/// <seealso name="IsPlayerInRaceCheckpoint"/>
2496/// <remarks>This callback can also be called by NPC.</remarks>
2497/// <returns>
2498///   This callback does not handle returns.<p/>
2499///   It is always called first in filterscripts.
2500/// </returns>
2501forward OnPlayerEnterRaceCheckpoint(playerid);
2502
2503/// <summary>This callback is called when a player leaves the race checkpoint.</summary>
2504/// <param name="playerid">The ID of the player that left the race checkpoint</param>
2505/// <seealso name="OnPlayerEnterCheckpoint"/>
2506/// <seealso name="OnPlayerLeaveCheckpoint"/>
2507/// <seealso name="OnPlayerEnterRaceCheckpoint"/>
2508/// <seealso name="SetPlayerCheckpoint"/>
2509/// <seealso name="DisablePlayerCheckpoint"/>
2510/// <seealso name="IsPlayerInCheckpoint"/>
2511/// <seealso name="SetPlayerRaceCheckpoint"/>
2512/// <seealso name="DisablePlayerRaceCheckpoint"/>
2513/// <seealso name="IsPlayerInRaceCheckpoint"/>
2514/// <remarks>This callback can also be called by NPC.</remarks>
2515/// <returns>
2516///   This callback does not handle returns.<p/>
2517///   It is always called first in filterscripts.
2518/// </returns>
2519forward OnPlayerLeaveRaceCheckpoint(playerid);
2520
2521/// <summary>This callback is called when a command is sent through the server console, remote RCON, or via the in-game "/rcon command".</summary>
2522/// <param name="cmd">A string containing the command that was typed, as well as any passed parameters</param>
2523/// <seealso name="IsPlayerAdmin"/>
2524/// <seealso name="OnRconLoginAttempt"/>
2525/// <remarks>You will need to include this callback in a loaded filterscript for it to work in the gamemode!</remarks>
2526/// <remarks>"/rcon" is not included in "cmd" when a player types a command. </remarks>
2527/// <remarks>If you use the <a href="#print">print</a> function here, it will send a message to the player who typed the command in-game as well as the log.</remarks>
2528/// <remarks>This callback is not called when the player is not logged in as RCON admin. </remarks>
2529/// <remarks>When the player is not logged in as RCON admin and uses <b>/rcon login</b>, this callback will not be called and <a href="#OnRconLoginAttempt">OnRconLoginAttempt</a> is called instead. However, when the player is logged in as RCON admin, the use of this command will call this callback. </remarks>
2530/// <returns>
2531///   <b><c>0</c></b> if the command was not processed, it will be passed to another script or <b><c>1</c></b> if the command was processed, will not be passed to other scripts.<p/>
2532///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks gamemode from seeing it.
2533/// </returns>
2534forward OnRconCommand(cmd[]);
2535
2536/// <summary>Called when a player attempts to spawn via class selection either by pressing SHIFT or clicking the 'Spawn' button.</summary>
2537/// <param name="playerid">The ID of the player that requested to spawn</param>
2538/// <seealso name="OnPlayerSpawn"/>
2539/// <seealso name="OnPlayerRequestClass"/>
2540/// <remarks>This callback can also be called by NPC.</remarks>
2541/// <remarks>To prevent players from spawning with certain classes, the last viewed class must be saved in a variable in <a href="#OnPlayerRequestClass">OnPlayerRequestClass</a>.</remarks>
2542/// <returns>
2543///   Returning <b><c>0</c></b> in this callback will prevent the player from spawning.<p/>
2544///   It is always called first in filterscripts so returning <b><c>0</c></b> there also blocks other scripts from seeing it.
2545/// </returns>
2546forward OnPlayerRequestSpawn(playerid);
2547
2548/// <summary>This callback is called when an object is moved after <a href="#MoveObject">MoveObject</a> (when it stops moving).</summary>
2549/// <param name="objectid">The ID of the object that was moved</param>
2550/// <seealso name="MoveObject"/>
2551/// <seealso name="IsObjectMoving"/>
2552/// <seealso name="StopObject"/>
2553/// <seealso name="OnPlayerObjectMoved"/>
2554/// <remarks><a href="#SetObjectPos">SetObjectPos</a> does not work when used in this callback. To fix it, recreate the object.</remarks>
2555/// <returns>
2556///   This callback does not handle returns.<p/>
2557///   It is always called first in filterscripts.
2558/// </returns>
2559forward OnObjectMoved(objectid);
2560
2561/// <summary>This callback is called when a player object is moved after <a href="#MovePlayerObject">MovePlayerObject</a> (when it stops moving).</summary>
2562/// <param name="playerid">The playerid the object is assigned to</param>
2563/// <param name="objectid">The ID of the player object that was moved</param>
2564/// <seealso name="OnObjectMoved"/>
2565/// <seealso name="MovePlayerObject"/>
2566/// <seealso name="IsPlayerObjectMoving"/>
2567/// <seealso name="StopPlayerObject"/>
2568/// <remarks>This callback can also be called for NPC.</remarks>
2569/// <returns>
2570///   This callback does not handle returns.<p/>
2571///   It is always called first in filterscripts.
2572/// </returns>
2573forward OnPlayerObjectMoved(playerid, objectid);
2574
2575/// <summary>Called when a player picks up a pickup created with <a href="#CreatePickup">CreatePickup</a>.</summary>
2576/// <param name="playerid">The ID of the player that picked up the pickup</param>
2577/// <param name="pickupid">The ID of the pickup, returned by CreatePickup</param>
2578/// <seealso name="CreatePickup"/>
2579/// <seealso name="DestroyPickup"/>
2580/// <returns>
2581///   This callback does not handle returns.<p/>
2582///   It is always called first in gamemode.
2583/// </returns>
2584forward OnPlayerPickUpPickup(playerid, pickupid);
2585
2586/// <summary>This callback is called when a vehicle is modded.</summary>
2587/// <param name="playerid">The ID of the driver of the vehicle</param>
2588/// <param name="vehicleid">The ID of the vehicle which is modded</param>
2589/// <param name="componentid">The ID of the component which was added to the vehicle</param>
2590/// <seealso name="AddVehicleComponent"/>
2591/// <seealso name="OnEnterExitModShop"/>
2592/// <seealso name="OnVehiclePaintjob"/>
2593/// <seealso name="OnVehicleRespray"/>
2594/// <remarks>This callback is NOT called by <a href="#AddVehicleComponent">AddVehicleComponent</a>.</remarks>
2595/// <returns>
2596///   Return <b><c>0</c></b> to desync the mod (or an invalid mod) from propagating and / or crashing players.<p/>
2597///   It is always called first in gamemode so returning <b><c>0</c></b> there also blocks other filterscripts from seeing it.
2598/// </returns>
2599forward OnVehicleMod(playerid, vehicleid, componentid);
2600
2601/// <summary>This callback is called when a player enters or exits a mod shop.</summary>
2602/// <param name="playerid">The ID of the player that entered or exited the modshop</param>
2603/// <param name="enterexit"><b><c>1</c></b> if the player entered or <b><c>0</c></b> if they exited</param>
2604/// <param name="interiorid">The interior ID of the modshop that the player is entering (or 0 if exiting)</param>
2605/// <seealso name="OnVehicleMod"/>
2606/// <seealso name="OnVehicleRespray"/>
2607/// <seealso name="OnVehiclePaintjob"/>
2608/// <seealso name="AddVehicleComponent"/>
2609/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2610/// <remarks>Players collide when they get into the same mod shop.</remarks>
2611/// <returns>
2612///   This callback does not handle returns.<p/>
2613///   It is always called first in filterscripts.
2614/// </returns>
2615forward OnEnterExitModShop(playerid, enterexit, interiorid);
2616
2617/// <summary>Called when a player previews a vehicle paintjob inside a mod shop. Watch out, this callback is not called when the player buys the paintjob.</summary>
2618/// <param name="playerid">The ID of the player that changed the paintjob of their vehicle</param>
2619/// <param name="vehicleid">The ID of the vehicle that had its paintjob changed</param>
2620/// <param name="paintjobid">The ID of the new paintjob</param>
2621/// <seealso name="ChangeVehiclePaintjob"/>
2622/// <seealso name="ChangeVehicleColor"/>
2623/// <seealso name="OnVehicleRespray"/>
2624/// <seealso name="OnVehicleMod"/>
2625/// <remarks>This callback is not called by <a href="#ChangeVehiclePaintjob">ChangeVehiclePaintjob</a>.</remarks>
2626/// <returns>
2627///   This callback does not handle returns. Returning <b><c>0</c></b> won't deny the paintjob change.<p/>
2628///   It is always called first in gamemode so returning <b><c>0</c></b> there blocks other filterscripts from seeing it.
2629/// </returns>
2630forward OnVehiclePaintjob(playerid, vehicleid, paintjobid);
2631
2632/// <summary>This callback is called when a player exits a mod shop, even if the colors weren't changed. Watch out, the name is ambiguous, Pay 'n' Spray shops don't call this callback.</summary>
2633/// <param name="playerid">The ID of the player that is driving the vehicle</param>
2634/// <param name="vehicleid">The ID of the vehicle that was resprayed</param>
2635/// <param name="color1">The color that the vehicle's primary color was changed to</param>
2636/// <param name="color2">The color that the vehicle's secondary color was changed to</param>
2637/// <seealso name="ChangeVehicleColor"/>
2638/// <seealso name="ChangeVehiclePaintjob"/>
2639/// <seealso name="OnVehiclePaintjob"/>
2640/// <seealso name="OnVehicleMod"/>
2641/// <seealso name="OnEnterExitModShop"/>
2642/// <remarks>Previewing a component inside a mod shop might call this callback.</remarks>
2643/// <remarks>This callback is not called by <a href="#ChangeVehicleColor">ChangeVehicleColor</a>.</remarks>
2644/// <returns>
2645///   Returning <b><c>0</c></b> in this callback will deny the colour change. Returning <b><c>1</c></b> will allow it. This can be used to prevent hackers from changing vehicle colours using cheats.<p/>
2646///   It is always called first in gamemode so returning <b><c>0</c></b> there also blocks other filterscripts from seeing it.
2647/// </returns>
2648forward OnVehicleRespray(playerid, vehicleid, color1, color2);
2649
2650/// <summary>This callback is called when a vehicle element such as doors, tires, panels, or lights change their damage status.</summary>
2651/// <param name="vehicleid">The ID of the vehicle that was changed its damage status</param>
2652/// <param name="playerid">The ID of the player who synced the change in the damage status (who had the car damaged or repaired)</param>
2653/// <seealso name="GetVehicleDamageStatus"/>
2654/// <seealso name="UpdateVehicleDamageStatus"/>
2655/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2656/// <remarks>This does not include vehicle health changes</remarks>
2657/// <returns>
2658///   <b><c>1</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2659///   <b><c>0</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2660///   It is always called first in filterscripts.<p/>
2661/// </returns>
2662forward OnVehicleDamageStatusUpdate(vehicleid, playerid);
2663
2664/// <summary>This callback is called when a player's client updates/syncs the position of a vehicle they're not driving. This can happen outside of the vehicle or when the player is a passenger of a vehicle that has no driver.</summary>
2665/// <param name="vehicleid">The ID of the vehicle that's position was updated</param>
2666/// <param name="playerid">The ID of the player that sent a vehicle position sync update</param>
2667/// <param name="passenger_seat">The ID of the seat if the player is a passenger. 0=not in vehicle, 1=front passenger, 2=backleft 3=backright 4+ is for coach/bus etc. with many passenger seats</param>
2668/// <param name="new_x">The new X coordinate of the vehicle. This parameter was added in <b>0.3z</b>. Leave it out if using an earlier version</param>
2669/// <param name="new_y">The new Y coordinate of the vehicle. This parameter was added in <b>0.3z</b>. Leave it out if using an earlier version</param>
2670/// <param name="new_z">The new Z coordinate of the vehicle. This parameter was added in <b>0.3z</b>. Leave it out if using an earlier version</param>
2671/// <param name="vel_x">The new X velocity of the vehicle. This parameter was added in <b>0.3z R4</b>. Leave it out if using an earlier version</param>
2672/// <param name="vel_y">The new Y velocity of the vehicle. This parameter was added in <b>0.3z R4</b>. Leave it out if using an earlier version</param>
2673/// <param name="vel_z">The new Z velocity of the vehicle. This parameter was added in <b>0.3z R4</b>. Leave it out if using an earlier version</param>
2674/// <seealso name="OnTrailerUpdate"/>
2675/// <remarks>This callback was added in <b>SA-MP 0.3c R3</b> and will not work in earlier versions!</remarks>
2676/// <remarks>This callback is called very frequently per second per unoccupied vehicle. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this callback.</remarks>
2677/// <remarks><a href="#GetVehiclePos">GetVehiclePos</a> will return the old coordinates of the vehicle before this update.</remarks>
2678/// <returns>
2679///   Returning <b><c>0</c></b> in this callback will stop the vehicle's position being synced to other players. Update is still sent to the updating player. Useful for combating vehicle teleport hacks.<p/>
2680///   It is always called first in filterscripts so returning <b><c>0</c></b> there also blocks other scripts from seeing it.
2681/// </returns>
2682forward OnUnoccupiedVehicleUpdate(vehicleid, playerid, passenger_seat, Float:new_x, Float:new_y, Float:new_z, Float:vel_x, Float:vel_y, Float:vel_z);
2683
2684/// <summary>This callback is called when a player selects an item from a menu (<a href="#ShowMenuForPlayer">ShowMenuForPlayer</a>).</summary>
2685/// <param name="playerid">The ID of the player that selected a menu item</param>
2686/// <param name="row">The ID of the row that was selected. The first row is ID <b><c>0</c></b></param>
2687/// <seealso name="OnPlayerExitedMenu"/>
2688/// <seealso name="OnDialogResponse"/>
2689/// <seealso name="CreateMenu"/>
2690/// <seealso name="DestroyMenu"/>
2691/// <seealso name="AddMenuItem"/>
2692/// <seealso name="ShowMenuForPlayer"/>
2693/// <seealso name="HideMenuForPlayer"/>
2694/// <remarks>The menu ID is not passed to this callback. <a href="#GetPlayerMenu">GetPlayerMenu</a> must be used to determine which menu the player selected an item on.</remarks>
2695/// <returns>
2696///   This callback does not handle returns.<p/>
2697///   It is always called first in gamemode.
2698/// </returns>
2699forward OnPlayerSelectedMenuRow(playerid, row);
2700
2701/// <summary>Called when a player exits a menu.</summary>
2702/// <param name="playerid">The ID of the player that exited the menu</param>
2703/// <seealso name="OnPlayerSelectedMenuRow"/>
2704/// <seealso name="CreateMenu"/>
2705/// <seealso name="DestroyMenu"/>
2706/// <returns>
2707///   This callback does not handle returns.<p/>
2708///   It is always called first in gamemode.
2709/// </returns>
2710forward OnPlayerExitedMenu(playerid);
2711
2712/// <summary>Called when a player changes interior. Can be triggered by SetPlayerInterior or when a player enter/exits a building.</summary>
2713/// <param name="playerid">The playerid who changed interior</param>
2714/// <param name="newinteriorid">The interior the player is now in</param>
2715/// <param name="oldinteriorid">The interior the player was in before</param>
2716/// <seealso name="SetPlayerInterior"/>
2717/// <seealso name="GetPlayerInterior"/>
2718/// <seealso name="LinkVehicleToInterior"/>
2719/// <seealso name="OnPlayerStateChange"/>
2720/// <returns>
2721///   This callback does not handle returns.<p/>
2722///   It is always called first in gamemode.
2723/// </returns>
2724forward OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid);
2725
2726/// <summary>This callback is called when the state of any supported key is changed (pressed/released). Directional keys do not trigger OnPlayerKeyStateChange (up/down/left/right).</summary>
2727/// <param name="playerid">The ID of the player that pressed or released a key</param>
2728/// <param name="newkeys">A map (bitmask) of the keys currently held - see <a href="http://wiki.sa-mp.com/wiki/Keys">here</a></param>
2729/// <param name="oldkeys">A map (bitmask) of the keys held prior to the current change - see <a href="http://wiki.sa-mp.com/wiki/Keys">here</a></param>
2730/// <seealso name="GetPlayerKeys"/>
2731/// <remarks>This callback can also be called by NPC.</remarks>
2732/// <remarks>
2733///   Useful macros:<p/>
2734///   <code>
2735///     // HOLDING(keys)<p/>
2736///     #define HOLDING(%0) ((newkeys &amp; (%0)) == (%0))<p/>
2737///     <p/>
2738///     // PRESSED(keys)<p/>
2739///     #define PRESSED(%0) (((newkeys &amp; (%0)) == (%0)) &amp;&amp; ((oldkeys &amp; (%0)) != (%0)))<p/>
2740///     <p/>
2741///     // PRESSING(keyVariable, keys)<p/>
2742///     #define PRESSING(%0,%1) (%0 &amp; (%1))<p/>
2743///     <p/>
2744///     // RELEASED(keys)<p/>
2745///     #define RELEASED(%0) (((newkeys &amp; (%0)) != (%0)) &amp;&amp; ((oldkeys &amp; (%0)) == (%0)))<p/>
2746///   </code>
2747/// </remarks>
2748/// <returns>
2749///   This callback does not handle returns.<p/>
2750///   It is always called first in gamemode.
2751/// </returns>
2752forward OnPlayerKeyStateChange(playerid, newkeys, oldkeys);
2753
2754/// <summary>This callback is called when someone attempts to log in to RCON in-game; successful or not.</summary>
2755/// <param name="ip">The IP of the player that tried to log in to RCON</param>
2756/// <param name="password">The password used to login with</param>
2757/// <param name="success"><b><c>0</c></b> if the password was incorrect or <b><c>1</c></b> if it was correct</param>
2758/// <seealso name="OnRconCommand"/>
2759/// <seealso name="IsPlayerAdmin"/>
2760/// <seealso name="SendRconCommand"/>
2761/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2762/// <remarks>This callback is only called when /rcon login is used in-game. </remarks>
2763/// <remarks>This callback is only called when the player is not yet logged in. When the player is logged in, <a href="#OnRconCommand">OnRconCommand</a> is called instead.</remarks>
2764/// <returns>
2765///   This callback does not handle returns.<p/>
2766///   It is always called first in filterscripts.
2767/// </returns>
2768forward OnRconLoginAttempt( ip[], password[], success );
2769
2770/// <summary>This callback is called every time a client/player updates the server with their status. It is often used to create custom callbacks for client updates that aren't actively tracked by the server, such as health or armor updates or players switching weapons.</summary>
2771/// <param name="playerid">ID of the player sending an update packet</param>
2772/// <remarks>This callback can also be called by NPC.</remarks>
2773/// <remarks>This callback is called, on average, 30 times per second, per player; only use it when you know what it's meant for (or more importantly what it's NOT meant for). </remarks>
2774/// <remarks>The frequency with which this callback is called for each player varies, depending on what the player is doing. Driving or shooting will trigger a lot more updates than idling. </remarks>
2775/// <returns>
2776///   <b><c>0</c></b> - Update from this player will not be replicated to other clients.<p/>
2777///   <b><c>1</c></b> - Indicates that this update can be processed normally and sent to other players.<p/>
2778///   It is always called first in filterscripts.
2779/// </returns>
2780forward OnPlayerUpdate(playerid);
2781
2782/// <summary>This callback is called when a player is streamed by some other player's client.</summary>
2783/// <param name="playerid">The ID of the player who has been streamed</param>
2784/// <param name="forplayerid">The ID of the player that streamed the other player in</param>
2785/// <seealso name="OnPlayerStreamOut"/>
2786/// <seealso name="OnActorStreamIn"/>
2787/// <seealso name="OnVehicleStreamIn"/>
2788/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2789/// <remarks>This callback can also be called by NPC.</remarks>
2790/// <returns>
2791///   This callback does not handle returns.<p/>
2792///   It is always called first in filterscripts.
2793/// </returns>
2794forward OnPlayerStreamIn(playerid, forplayerid);
2795
2796/// <summary>This callback is called when a player is streamed out from some other player's client.</summary>
2797/// <param name="playerid">The player who has been destreamed</param>
2798/// <param name="forplayerid">The player who has destreamed the other player</param>
2799/// <seealso name="OnPlayerStreamIn"/>
2800/// <seealso name="OnActorStreamOut"/>
2801/// <seealso name="OnVehicleStreamOut"/>
2802/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2803/// <remarks>This callback can also be called by NPC.</remarks>
2804/// <returns>
2805///   This callback does not handle returns.<p/>
2806///   It is always called first in filterscripts.
2807/// </returns>
2808forward OnPlayerStreamOut(playerid, forplayerid);
2809
2810/// <summary>Called when a vehicle is streamed to a player's client.</summary>
2811/// <param name="vehicleid">The ID of the vehicle that streamed in for the player</param>
2812/// <param name="forplayerid">The ID of the player who the vehicle streamed in for</param>
2813/// <seealso name="OnVehicleStreamOut"/>
2814/// <seealso name="OnPlayerStreamIn"/>
2815/// <seealso name="OnPlayerStreamOut"/>
2816/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2817/// <remarks>This callback can also be called by NPC.</remarks>
2818/// <returns>
2819///   This callback does not handle returns.<p/>
2820///   It is always called first in filterscripts.
2821/// </returns>
2822forward OnVehicleStreamIn(vehicleid, forplayerid);
2823
2824/// <summary>This callback is called when a vehicle is streamed out for a player's client (it's so far away that they can't see it).</summary>
2825/// <param name="vehicleid">The ID of the vehicle that streamed out</param>
2826/// <param name="forplayerid">The ID of the player who is no longer streaming the vehicle</param>
2827/// <seealso name="OnVehicleStreamIn"/>
2828/// <seealso name="OnPlayerStreamIn"/>
2829/// <seealso name="OnPlayerStreamOut"/>
2830/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2831/// <remarks>This callback can also be called by NPC.</remarks>
2832/// <returns>
2833///   This callback does not handle returns.<p/>
2834///   It is always called first in filterscripts.
2835/// </returns>
2836forward OnVehicleStreamOut(vehicleid, forplayerid);
2837
2838/// <summary>This callback is called when an actor is streamed in by a player's client.</summary>
2839/// <param name="actorid">The ID of the actor that has been streamed in for the player</param>
2840/// <param name="forplayerid">The ID of the player that streamed the actor in</param>
2841/// <seealso name="OnActorStreamOut"/>
2842/// <seealso name="OnPlayerStreamIn"/>
2843/// <remarks>This function was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
2844/// <remarks>This callback can also be called by NPC.</remarks>
2845/// <remarks>It is always called first in filterscripts.</remarks>
2846/// <returns>This callback does not handle returns.</returns>
2847forward OnActorStreamIn(actorid, forplayerid);
2848
2849/// <summary>This callback is called when an actor is streamed out by a player's client.</summary>
2850/// <param name="actorid">The ID of the actor that has been streamed out for the player</param>
2851/// <param name="forplayerid">The ID of the player that streamed the actor out</param>
2852/// <seealso name="OnActorStreamIn"/>
2853/// <seealso name="OnPlayerStreamOut"/>
2854/// <remarks>This function was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
2855/// <remarks>This callback can also be called by NPC.</remarks>
2856/// <remarks>It is always called first in filterscripts.</remarks>
2857/// <returns>This callback does not handle returns.</returns>
2858forward OnActorStreamOut(actorid, forplayerid);
2859
2860/// <summary>This callback is called when a player responds to a dialog shown using <a href="#ShowPlayerDialog">ShowPlayerDialog</a> by either clicking a button, pressing ENTER/ESC or double-clicking a list item (if using a list style dialog).</summary>
2861/// <param name="playerid">The ID of the player that responded to the dialog</param>
2862/// <param name="dialogid">The ID of the dialog the player responded to, assigned in ShowPlayerDialog</param>
2863/// <param name="response"><b><c>1</c></b> for left button and <b><c>0</c></b> for right button (if only one button shown, always <b><c>1</c></b>)</param>
2864/// <param name="listitem">The ID of the list item selected by the player (starts at <b><c>0</c></b>) (only if using a list style dialog)</param>
2865/// <param name="inputtext">The text entered into the input box by the player or the selected list item text</param>
2866/// <seealso name="ShowPlayerDialog"/>
2867/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
2868/// <remarks>A player's dialog doesn't hide when the gamemode restarts, causing the server to print <c>"Warning: PlayerDialogResponse PlayerId: 0 dialog ID doesn't match last sent dialog ID"</c> if a player responded to this dialog after restart.</remarks>
2869/// <remarks>Parameters can contain different values, based on dialog's <a href="http://wiki.sa-mp.com/wiki/Dialog_Styles">style</a>.</remarks>
2870/// <returns>
2871///   Returning <b><c>0</c></b> in this callback will pass the dialog to another script in case no matching code were found in your gamemode's callback.<p/>
2872///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks other filterscripts from seeing it.
2873/// </returns>
2874forward OnDialogResponse(playerid, dialogid, response, listitem, inputtext[]);
2875
2876/// <summary>This callback is called when a player takes damage.</summary>
2877/// <param name="playerid">The ID of the player that took damage</param>
2878/// <param name="issuerid">The ID of the player that caused the damage. <b><c>INVALID_PLAYER_ID</c></b> if self-inflicted</param>
2879/// <param name="amount">The amount of damage the player took (health and armour combined)</param>
2880/// <param name="weaponid">The ID of the <a href="http://wiki.sa-mp.com/wiki/Weapons">weapon/reason</a> for the damage</param>
2881/// <param name="bodypart">The body part that was hit. (NOTE: This parameter was added in <b>0.3z</b>. Leave it out if using an older version!)</param>
2882/// <seealso name="OnPlayerGiveDamage"/>
2883/// <seealso name="OnPlayerWeaponShot"/>
2884/// <remarks>This callback was added in <b>SA-MP 0.3d</b> and will not work in earlier versions!</remarks>
2885/// <remarks><a href="#GetPlayerHealth">GetPlayerHealth</a> and <a href="#GetPlayerArmour">GetPlayerArmour</a> will return the old amounts of the player before this callback. </remarks>
2886/// <remarks>
2887///   The weaponid will return <b><c>37</c></b> (flame thrower) from any fire sources (e.g. molotov, <b><c>18</c></b>).<p/>
2888///   The weaponid will return <b><c>51</c></b> from any weapon that creates an explosion (e.g. RPG, grenade)<p/>
2889///   <b>playerid</b> is the only one who can call the callback.<p/>
2890///   The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. So when a player has <b><c>100.0</c></b> health and gets shot with a Desert Eagle which has a damage value of <b><c>46.2</c></b>, it takes 3 shots to kill that player. All 3 shots will show an amount of <b><c>46.2</c></b>, even though when the last shot hits, the player only has <b><c>7.6</c></b> health left.
2891/// </remarks>
2892/// <returns>
2893///   <b><c>1</c></b> - Callback will not be called in other filterscripts.<p/>
2894///   <b><c>0</c></b> - Allows this callback to be called in other filterscripts.<p/>
2895///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks other filterscripts from seeing it.
2896/// </returns>
2897forward OnPlayerTakeDamage(playerid, issuerid, Float:amount, weaponid, bodypart);
2898
2899/// <summary>This callback is called when a player gives damage to another player.</summary>
2900/// <param name="playerid">The ID of the player that gave damage</param>
2901/// <param name="damagedid">The ID of the player that received damage</param>
2902/// <param name="amount">The amount of health/armour damagedid has lost (combined)</param>
2903/// <param name="weaponid">The <a href="http://wiki.sa-mp.com/wiki/Weapons">reason</a> that caused the damage</param>
2904/// <param name="bodypart">The body part that was hit. (NOTE: This parameter was added in <b>0.3z</b>. Leave it out if using an older version!)</param>
2905/// <seealso name="OnPlayerTakeDamage"/>
2906/// <remarks>This callback was added in <b>SA-MP 0.3d</b> and will not work in earlier versions!</remarks>
2907/// <remarks>
2908///   Keep in mind this function can be inaccurate in some cases.<p/>
2909///   If you want to prevent certain players from damaging eachother, use <a href="#SetPlayerTeam">SetPlayerTeam</a>.<p/>
2910///   The weaponid will return <b><c>37</c></b> (flame thrower) from any fire sources (e.g. molotov, 18)<p/>
2911///   The weaponid will return <b><c>51</c></b> from any weapon that creates an explosion (e.g. RPG, grenade)<p/>
2912///   <b>playerid</b> is the only one who can call the callback.<p/>
2913///   The amount is always the maximum damage the weaponid can do, even when the health left is less than that maximum damage. So when a player has <b><c>100.0</c></b> health and gets shot with a Desert Eagle which has a damage value of <b><c>46.2</c></b>, it takes 3 shots to kill that player. All 3 shots will show an amount of <b><c>46.2</c></b>, even though when the last shot hits, the player only has <b><c>7.6</c></b> health left.
2914/// </remarks>
2915/// <returns>
2916///   <b><c>1</c></b> - Callback will not be called in other filterscripts.<p/>
2917///   <b><c>0</c></b> - Allows this callback to be called in other filterscripts.<p/>
2918///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks other filterscripts from seeing it.
2919/// </returns>
2920forward OnPlayerGiveDamage(playerid, damagedid, Float:amount, weaponid, bodypart);
2921
2922/// <summary>This callback is called when a player gives damage to an actor.</summary>
2923/// <param name="playerid">The ID of the player that gave damage</param>
2924/// <param name="damaged_actorid">The ID of the actor that received damage</param>
2925/// <param name="amount">The amount of health/armour damaged_actorid has lost</param>
2926/// <param name="weaponid">The reason that caused the damage</param>
2927/// <param name="bodypart">The body part that was hit</param>
2928/// <seealso name="CreateActor"/>
2929/// <seealso name="SetActorInvulnerable"/>
2930/// <seealso name="SetActorHealth"/>
2931/// <seealso name="GetActorHealth"/>
2932/// <seealso name="IsActorInvulnerable"/>
2933/// <seealso name="IsValidActor"/>
2934/// <seealso name="OnActorStreamOut"/>
2935/// <seealso name="OnPlayerStreamIn"/>
2936/// <remarks>This callback was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
2937/// <remarks>This function does not get called if the actor is set invulnerable (WHICH IS BY DEFAULT). See <a href="#SetActorInvulnerable">SetActorInvulnerable</a>.</remarks>
2938/// <returns>
2939///   <b><c>1</c></b> - Callback will not be called in other filterscripts.<p/>
2940///   <b><c>0</c></b> - Allows this callback to be called in other filterscripts.<p/>
2941///   It is always called first in filterscripts so returning <b><c>1</c></b> there blocks other filterscripts from seeing it.
2942/// </returns>
2943forward OnPlayerGiveDamageActor(playerid, damaged_actorid, Float:amount, weaponid, bodypart);
2944
2945/// <summary>OnPlayerClickMap is called when a player places a target/waypoint on the pause menu map (by right-clicking).</summary>
2946/// <param name="playerid">The ID of the player that placed a target/waypoint</param>
2947/// <param name="fX">The X float coordinate where the player clicked</param>
2948/// <param name="fY">The Y float coordinate where the player clicked</param>
2949/// <param name="fZ">The Z float coordinate where the player clicked (inaccurate - see note below)</param>
2950/// <seealso name="SetPlayerPos"/>
2951/// <seealso name="SetPlayerPosFindZ"/>
2952/// <seealso name="GetPlayerPos"/>
2953/// <remarks>This callback was added in <b>SA-MP 0.3d</b> and will not work in earlier versions!</remarks>
2954/// <remarks>The Z value returned will be <b><c>0</c></b> (invalid) if it is far away from the player; use the <a href="http://forum.sa-mp.com/showthread.php?t=275492">MapAndreas plugin</a> to get a more accurate Z coordinate.</remarks>
2955/// <returns>
2956///   <b><c>1</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
2957///   <b><c>0</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
2958///   It is always called first in gamemode.
2959/// </returns>
2960forward OnPlayerClickMap(playerid, Float:fX, Float:fY, Float:fZ);
2961
2962/// <summary>This callback is called when a player clicks on a textdraw or cancels the select mode with the Escape key.</summary>
2963/// <param name="playerid">The ID of the player that clicked on the textdraw</param>
2964/// <param name="clickedid">The ID of the clicked textdraw. <b><c>INVALID_TEXT_DRAW</c></b> if selection was cancelled</param>
2965/// <seealso name="OnPlayerClickPlayerTextDraw"/>
2966/// <seealso name="OnPlayerClickPlayer"/>
2967/// <remarks>This callback was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
2968/// <remarks>The clickable area is defined by <a href="#TextDrawTextSize">TextDrawTextSize</a>. The x and y parameters passed to that function must not be zero or negative. </remarks>
2969/// <remarks>Do not use <a href="#CancelSelectTextDraw">CancelSelectTextDraw</a> unconditionally within this callback. This results in an infinite loop. </remarks>
2970/// <returns>
2971///   Returning <b><c>1</c></b> in this callback will prevent it being called in other scripts. This should be used to signal that the textdraw on which they clicked was 'found' and no further processing is needed. You should return <b><c>0</c></b> if the textdraw on which they clicked wasn't found, just like in <a href="#OnPlayerCommandText">OnPlayerCommandText</a>.<p/>
2972///   It is always called first in filterscripts so returning <b><c>1</c></b> there also blocks other scripts from seeing it.
2973/// </returns>
2974forward OnPlayerClickTextDraw(playerid, Text:clickedid);
2975
2976/// <summary>This callback is called when a player clicks on a player-textdraw. It is not called when player cancels the select mode (ESC) - however, <a href="#OnPlayerClickTextDraw">OnPlayerClickTextDraw</a> is.</summary>
2977/// <param name="playerid">The ID of the player that selected a textdraw</param>
2978/// <param name="playertextid">The ID of the player-textdraw that the player selected</param>
2979/// <seealso name="PlayerTextDrawSetSelectable"/>
2980/// <seealso name="OnPlayerClickTextDraw"/>
2981/// <seealso name="OnPlayerClickPlayer"/>
2982/// <remarks>This callback was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
2983/// <remarks>When a player presses ESC to cancel selecting a textdraw, <a href="#OnPlayerClickTextDraw">OnPlayerClickTextDraw</a> is called with a textdraw ID of <b><c>INVALID_TEXT_DRAW</c></b>. <a href="#OnPlayerClickPlayerTextDraw">OnPlayerClickPlayerTextDraw</a> won't be called also.</remarks>
2984/// <returns>
2985///   Returning <b><c>1</c></b> in this callback will prevent it being called in other scripts. This should be used to signal that the textdraw on which they clicked was 'found' and no further processing is needed. You should return <b><c>0</c></b> if the textdraw on which they clicked wasn't found, just like in <a href="#OnPlayerCommandText">OnPlayerCommandText</a>.<p/>
2986///   It is always called first in filterscripts so returning <b><c>1</c></b> there also blocks other scripts from seeing it.
2987/// </returns>
2988forward OnPlayerClickPlayerTextDraw(playerid, PlayerText:playertextid);
2989
2990/// <summary>This callback is called when an IP address attempts a connection to the server. To block incoming connections, use <a href="#BlockIpAddress">BlockIpAddress</a>.</summary>
2991/// <param name="playerid">The ID of the player attempting to connect</param>
2992/// <param name="ip_address">The IP address of the player attempting to connect</param>
2993/// <param name="port">The port of the attempted connection</param>
2994/// <seealso name="OnPlayerConnect"/>
2995/// <seealso name="OnPlayerDisconnect"/>
2996/// <seealso name="OnPlayerFinishedDownloading"/>
2997/// <seealso name="BlockIpAddress"/>
2998/// <seealso name="UnBlockIpAddress"/>
2999/// <remarks> 	This callback was added in <b>SA-MP 0.3z R2-2</b> and will not work in earlier versions!</remarks>
3000/// <returns>
3001///   <b><c>1</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
3002///   <b><c>0</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
3003///   It is always called first in filterscripts.
3004/// </returns>
3005forward OnIncomingConnection(playerid, ip_address[], port);
3006
3007/// <summary>This callback is called when a player sent a trailer update.</summary>
3008/// <param name="playerid">The ID of the player who sent a trailer update</param>
3009/// <param name="vehicleid">The Trailer being updated</param>
3010/// <seealso name="OnUnoccupiedVehicleUpdate"/>
3011/// <seealso name="GetVehicleTrailer"/>
3012/// <seealso name="IsTrailerAttachedToVehicle"/>
3013/// <seealso name="AttachTrailerToVehicle"/>
3014/// <seealso name="DetachTrailerFromVehicle"/>
3015/// <remarks>This callback was added in <b>SA-MP 0.3z R4</b> and will not work in earlier versions!</remarks>
3016/// <remarks>This callback is called very frequently per second per trailer. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this callback. </remarks>
3017/// <returns>
3018///   <b><c>0</c></b> - Cancels any trailer updates from being sent to other players. Update is still sent to the updating player.<p/>
3019///   <b><c>1</c></b> - Processes the trailer update as normal and synchronizes it between all players.<p/>
3020///   It is always called first in filterscripts.
3021/// </returns>
3022forward OnTrailerUpdate(playerid, vehicleid);
3023
3024/// <summary>This callback is called when a vehicle's siren is toggled.</summary>
3025/// <param name="playerid">The ID of the player that toggled the siren (driver)</param>
3026/// <param name="vehicleid">The ID of the vehicle of which the siren was toggled for</param>
3027/// <param name="newstate"><b><c>0</c></b> if siren was turned off, <b><c>1</c></b> if siren was turned on</param>
3028/// <seealso name="GetVehicleParamsSirenState"/>
3029/// <remarks>This callback was added in <b>SA-MP 0.3.7</b> and will not work in earlier versions!</remarks>
3030/// <remarks>This callback can also be called by NPC.</remarks>
3031/// <remarks>This callback is only called when a vehicle's siren is toggled on or off, NOT when the alternate siren is in use (holding horn).</remarks>
3032/// <returns>
3033///   <b><c>1</c></b> - Will prevent gamemode from receiving this callback.<p/>
3034///   <b><c>0</c></b> - Indicates that this callback will be passed to the gamemode.<p/>
3035///   It is always called first in filterscripts.
3036/// </returns>
3037forward OnVehicleSirenStateChange(playerid, vehicleid, newstate);
3038
3039/// <summary>This callback is called when a player finishes downloading custom models. For more information on how to add custom models to your server, see <a href="http://forum.sa-mp.com/showthread.php?t=644105">the release thread</a> and <a href="http://forum.sa-mp.com/showthread.php?t=644123">this tutorial</a>.</summary>
3040/// <param name="playerid">The ID of the player that finished downloading custom models</param>
3041/// <param name="virtualworld">The ID of the virtual world the player finished downloading custom models for</param>
3042/// <seealso name="OnPlayerConnect"/>
3043/// <seealso name="OnPlayerDisconnect"/>
3044/// <seealso name="OnIncomingConnection"/>
3045/// <remarks>This callback was added in <b>SA-MP 0.3DL</b> and will not work in earlier versions!</remarks>
3046/// <remarks>This callback is called every time a player changes virtual worlds, even if there are no custom models present in that world.</remarks>
3047/// <returns>This callback does not handle returns.</returns>
3048forward OnPlayerFinishedDownloading(playerid, virtualworld);
3049forward OnPlayerRequestDownload(playerid, type, crc);
3050
3051/// <summary>Called when a player double-clicks on a player on the scoreboard.</summary>
3052/// <param name="playerid">The ID of the player that clicked on a player on the scoreboard</param>
3053/// <param name="clickedplayerid">The ID of the player that was clicked on</param>
3054/// <param name="source">The source of the player's click</param>
3055/// <seealso name="OnPlayerClickTextDraw"/>
3056/// <remarks>This callback was added in <b>SA-MP 0.3a</b> and will not work in earlier versions!</remarks>
3057/// <remarks>There is currently only one <paramref name="source"/> (<b><c>0 - CLICK_SOURCE_SCOREBOARD</c></b>). The existence of this argument suggests that more sources may be supported in the future.</remarks>
3058/// <returns>
3059///   <b><c>1</c></b> - Will prevent other filterscripts from receiving this callback.<p/>
3060///   <b><c>0</c></b> - Indicates that this callback will be passed to the next filterscript.<p/>
3061///   It is always called first in filterscripts.
3062/// </returns>
3063forward OnPlayerClickPlayer(playerid, clickedplayerid, source);
3064
3065/// <summary>This callback is called when a player finishes editing an object (<a href="#EditObject">EditObject</a>/<a href="#EditPlayerObject">EditPlayerObject</a>).</summary>
3066/// <param name="playerid">The ID of the player that edited an object</param>
3067/// <param name="playerobject"><b><c>0</c></b> if it is a global object or <b><c>1</c></b> if it is a playerobject</param>
3068/// <param name="objectid">The ID of the edited object</param>
3069/// <param name="response">The type of response</param>
3070/// <param name="fX">The X offset for the object that was edited</param>
3071/// <param name="fY">The Y offset for the object that was edited</param>
3072/// <param name="fZ">The Z offset for the object that was edited</param>
3073/// <param name="fRotX">The X rotation for the object that was edited</param>
3074/// <param name="fRotY">The Y rotation for the object that was edited</param>
3075/// <param name="fRotZ">The Z rotation for the object that was edited</param>
3076/// <seealso name="EditObject"/>
3077/// <seealso name="CreateObject"/>
3078/// <seealso name="DestroyObject"/>
3079/// <seealso name="MoveObject"/>
3080/// <remarks>This callback was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
3081/// <remarks>When using <b><c>EDIT_RESPONSE_UPDATE</c></b> be aware that this callback will not be called when releasing an edit in progress resulting in the last update of <b><c>EDIT_RESPONSE_UPDATE</c></b> being out of sync of the objects current position.</remarks>
3082/// <returns>
3083///   <b><c>1</c></b> - Will prevent other scripts from receiving this callback.<p/>
3084///   <b><c>0</c></b> - Indicates that this callback will be passed to the next script.<p/>
3085///   It is always called first in filterscripts.
3086/// </returns>
3087forward OnPlayerEditObject( playerid, playerobject, objectid, response, 
3088Float:fX, Float:fY, Float:fZ, Float:fRotX, Float:fRotY, Float:fRotZ );
3089
3090
3091/// <summary>This callback is called when a player ends attached object edition mode.</summary>
3092/// <param name="playerid">The ID of the player that ended edition mode</param>
3093/// <param name="response"><b><c>0</c></b> if they cancelled (ESC) or <b><c>1</c></b> if they clicked the save icon</param>
3094/// <param name="index">The index of the attached object</param>
3095/// <param name="modelid">The model of the attached object that was edited</param>
3096/// <param name="boneid">The bone of the attached object that was edited</param>
3097/// <param name="fOffsetX">The X offset for the attached object that was edited</param>
3098/// <param name="fOffsetY">The Y offset for the attached object that was edited</param>
3099/// <param name="fOffsetZ">The Z offset for the attached object that was edited</param>
3100/// <param name="fRotX">The X rotation for the attached object that was edited</param>
3101/// <param name="fRotY">The Y rotation for the attached object that was edited</param>
3102/// <param name="fRotZ">The Z rotation for the attached object that was edited</param>
3103/// <param name="fScaleX">The X scale for the attached object that was edited</param>
3104/// <param name="fScaleY">The Y scale for the attached object that was edited</param>
3105/// <param name="fScaleZ">The Z scale for the attached object that was edited</param>
3106/// <seealso name="EditAttachedObject"/>
3107/// <seealso name="SetPlayerAttachedObject"/>
3108/// <remarks>This callback was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
3109/// <remarks>Editions should be discarded if response was <b><c>0</c></b> (cancelled). This must be done by storing the offsets etc. in an array BEFORE using <a href="#EditAttachedObject">EditAttachedObject</a>.</remarks>
3110/// <returns>
3111///   <b><c>1</c></b> - Will prevent other scripts from receiving this callback.<p/>
3112///   <b><c>0</c></b> - Indicates that this callback will be passed to the next script.<p/>
3113///   It is always called first in filterscripts.
3114/// </returns>
3115forward OnPlayerEditAttachedObject( playerid, response, index, modelid, boneid,
3116Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ,
3117Float:fRotX, Float:fRotY, Float:fRotZ,
3118Float:fScaleX, Float:fScaleY, Float:fScaleZ );
3119
3120/// <summary>This callback is called when a player selects an object after <a href="#SelectObject">SelectObject</a> has been used.</summary>
3121/// <param name="playerid">The ID of the player that selected an object</param>
3122/// <param name="type">The type of selection</param>
3123/// <param name="objectid">The ID of the selected object</param>
3124/// <param name="modelid">The model ID of the selected object</param>
3125/// <param name="fX">The X position of the selected object</param>
3126/// <param name="fY">The Y position of the selected object</param>
3127/// <param name="fZ">The Z position of the selected object</param>
3128/// <seealso name="SelectObject"/>
3129/// <remarks>This function was added in <b>SA-MP 0.3e</b> and will not work in earlier versions!</remarks>
3130/// <returns>
3131///   <b><c>1</c></b> - Will prevent other scripts from receiving this callback.<p/>
3132///   <b><c>0</c></b> - Indicates that this callback will be passed to the next script.<p/>
3133///   It is always called first in filterscripts.
3134/// </returns>
3135forward OnPlayerSelectObject(playerid, type, objectid, modelid, Float:fX, Float:fY, Float:fZ);
3136
3137/// <summary>This callback is called when a player fires a shot from a weapon. Only bullet weapons are supported. Only <b>passenger</b> drive-by is supported (not driver drive-by, and not sea sparrow / hunter shots).</summary>
3138/// <param name="playerid">The ID of the player that shot a weapon</param>
3139/// <param name="weaponid">The ID of the <a href="http://wiki.sa-mp.com/wiki/Weapons">weapon</a> shot by the player</param>
3140/// <param name="hittype">The type of thing the shot hit (none, player, vehicle, or (player)object)</param>
3141/// <param name="hitid">The ID of the player, vehicle or object that was hit</param>
3142/// <param name="fX">The X coordinate that the shot hit</param>
3143/// <param name="fY">The Y coordinate that the shot hit</param>
3144/// <param name="fZ">The Z coordinate that the shot hit</param>
3145/// <seealso name="OnPlayerGiveDamage"/>
3146/// <seealso name="GetPlayerLastShotVectors"/>
3147/// <remarks>This callback was added in <b>SA-MP 0.3z</b> and will not work in earlier versions!</remarks>
3148/// <remarks>
3149///     <li><b><c>BULLET_HIT_TYPE_NONE(0)</c></b></li>
3150///     <li><b><c>BULLET_HIT_TYPE_PLAYER(1)</c></b></li>
3151///     <li><b><c>BULLET_HIT_TYPE_VEHICLE(2)</c></b></li>
3152///     <li><b><c>BULLET_HIT_TYPE_OBJECT(3)</c></b></li>
3153///     <li><b><c>BULLET_HIT_TYPE_PLAYER_OBJECT(4)</c></b></li>
3154/// </remarks>
3155/// <remarks><b><c>BULLET_HIT_TYPE_PLAYER</c></b> is also called for NPCs. Actors are ignored by this callback and detects as <b><c>BULLET_HIT_TYPE_NONE</c></b>.</remarks>
3156/// <remarks>This callback is only called when lag compensation is <b>enabled</b>. </remarks>
3157/// <remarks>
3158///   If hittype is:<p/>
3159///   <ul>
3160///     <li>- <b><c>BULLET_HIT_TYPE_NONE</c></b>: the fX, fY and fZ parameters are normal coordinates, will give 0.0 for coordinates if nothing was hit (e.g. far object that the bullet can't reach);</li>
3161///     <li>- Others: the fX, fY and fZ are offsets relative to the hitid.</li>
3162///   </ul>
3163/// </remarks>
3164/// <remarks>
3165///   Isn't called if you fired in vehicle as driver or if you are looking behind with the aim enabled (shooting in air).<p/>
3166///   It is called as <b><c>BULLET_HIT_TYPE_VEHICLE</c></b> with the correct hitid (the hit player's vehicleid) if you are shooting a player which is in a vehicle. It won't be called as <b><c>BULLET_HIT_TYPE_PLAYER</c></b> at all.<p/>
3167///   <b>Partially fixed in SA-MP 0.3.7:</b> If fake weapon data is sent by a malicious user, other player clients may freeze or crash. To combat this, check if the reported weaponid can actually fire bullets.
3168/// </remarks>
3169/// <remarks>
3170/// </remarks>
3171/// <remarks><a href="#GetPlayerLastShotVectors">GetPlayerLastShotVectors</a> can be used in this callback for more detailed bullet vector information.</remarks>
3172/// <returns>
3173///   <b><c>0</c></b> - Prevent the bullet from causing damage.<p/>
3174///   <b><c>1</c></b> - Allow the bullet to cause damage.<p/>
3175///   It is always called first in filterscripts so returning <b><c>0</c></b> there also blocks other scripts from seeing it.
3176/// </returns>
3177forward OnPlayerWeaponShot(playerid, weaponid, hittype, hitid, Float:fX, Float:fY, Float:fZ);
3178
3179/// <summary>This callback is called when a SendClientCheck request comletes</summary>
3180/// <param name="playerid">The ID of the player checked</param>
3181/// <param name="actionid">The type of check performed</param>
3182/// <param name="memaddr">The address requested</param>
3183/// <param name="retndata">The result of the check</param>
3184/// <seealso name="SendClientCheck"/>
3185forward OnClientCheckResponse(playerid, actionid, memaddr, retndata);
3186
3187/// <summary>This callback is called when a SendClientCheck request comletes</summary>
3188/// <param name="playerid">The ID of the player who got cash from the game</param>
3189/// <param name="amount">The amount of cash given</param>
3190/// <param name="source">Where the money came from</param>
3191/// <remarks>Doesn't work</remarks>
3192forward OnScriptCash(playerid, amount, source);
3193
3194// --------------------------------------------------