diff --git a/README.md b/README.md index 8bb6671..225d421 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,331 @@ standard library stored here on GitHub too. This means there doesn't need to be any special-case code written for the standard library, it can just be a package like all others. +## Const-Correctness + +Some functions, like `SendRconCommand`, take strings; some functions, like `GetPlayerName`, modify strings. These are different operations with different considerations. Consider the following code: + +```pawn +GetPlayerName(playerid, "Bob"); +``` + +This code doesn't make any sense. "Bob" is a string literal, you can't store someone's name in to the word `"Bob"`, it would be like trying to do: + +```pawn +"Bob" = GetPlayerName(playerid); +``` + +`"Bob"` is a *constant*, it is a value fixed by the compiler that can't be modified at runtime. `GetPlayerName` modifies its values at runtime, so cannot take a constant only a variable. For this reason it is declared as: + +```pawn +native GetPlayerName(playerid, name[], size = sizeof (name)); +``` + +But what of `SendRconCommand`? The following *is* valid: + +```pawn +SendRconCommand("loadfs objects"); +``` + +`SendRconCommand` does not return a string, it doesn't modify the value passed in. If it were declared in the same way as `GetPlayerName` it would have to take a variable that could be modified: + +```pawn +native SendRconCommand(cmd[]); +new cmd[] = "loadfs objects"; +// `cmd` must be modifiable because `SendRconCommand` doesn't say it won't. +SendRconCommand(cmd); +``` + +This is cumbersome and pointless. Again, we know that `SendRconCommand` cannot change the data given, so we tell the compiler this as well. Anything between `""`s is a *constant*, so make `SendRconCommand` accept them with `const`: + +```pawn +native SendRconCommand(const cmd[]); +// Allowed again because we know this call won't modify the string. +SendRconCommand("loadfs objects"); +``` + +This is called *const correctness* - using `const` when data will not be modified, and not using `const` when the parameter will be modified. This is mainly only useful for strings and arrays (differentiated in the includes by the use of a `string:` tag) as they are pass-by-reference, but when in doubt use the rules on normal numbers as well. + +Functions that are `const` can also take variables which may be modified. `const` means the function promises not modify the variable (`GetPlayerName` in the SA:MP includes incorrectly used `const` and broke this promise), but that doesn't mean you can't pass varaibles that don't mind being modified - there's no such thing as a variable that *must* be modified: + +```pawn +native SendRconCommand(const string:cmd[]); +new cmd[32]; +format(cmd, _, "loadfs %s", scriptName); +// `cmd` is allowed to be modified, but `SendRconCommand` won't do so. +SendRconCommand(cmd); +``` + +As a side note, the following code is now also a warning: + +```pawn +Func(const &var) +{ + printf("%d", var); +} +``` + +`const` means a variable can't be modified, while `&` means it can. Since modifiying a normal variable is the only reason to pass it by reference adding `const` to the declaration is, as with all warnings, probably a mistake. + +## More Tags + +The latest version of the SA:MP includes introduce many more tags to functions and callbacks. These are useful in the long run, but slightly annoying to upgrade to. There are three symbols: `NO_TAGS`, `WEAK_TAGS`, and `STRONG_TAGS`; that you can define before including ``, each one enabling progressively more checks: + +```pawn +#define STRONG_TAGS +#include +``` + +To encourage some adoption, the default is `WEAK_TAGS`. Most old code uses will simply give a warning when the wrong tag is found: + +```pawn +// Gives a warning: +SetPlayerControllable(playerid, 1); + +// Should be: +SetPlayerControllable(playerid, true); +``` + +Generally parameters that only accept a limited range of values (for example, object attachment bones) are now all enumerations so that passing invalid values gives a warning: + +```pawn +TextDrawAlignment(textid, TEXT_DRAW_ALIGN_LEFT); // Fine +TextDrawFont(textid, 7); // Warning +``` + +Functions that take or return just `true`/`false` all have `bool:` tags. More functions than might be expected return booleans; most player functions return `true` when they succeed and `false` when the player is not connected, sometimes skipping the need for `IsPlayerConnected`: + +```pawn +new Float:x, Float:y, Float:z; +// If the player is connected get their position. +if (GetPlayerPos(playerid, x, y, z)) +{ + // Timer repeats are on or off, so booleans. + SetTimer("TimerFunc", 1000, false); +} +``` + +In cases where there were existing defines already for valid values (like `OBJECT_MATERIAL_SIZE_512x64`) these names have been reused for the enumerations and thus tagged. Therefore code that already made use of the defines will continue to operate correctly, and code that wishes to remain backwards-compatible can start using the names in place of (usually) bare numbers (so always put `OBJECT_MATERIAL_TEXT_ALIGN_LEFT` instead of `0`). + +For parameters the default is to make these new tags *weak*, meaning that you get warnings when passing untagged values to tagged parameters, but not the other way around. This applies to function returns so saving a tag result in an untagged variable will not give a warning. This second group can also be upgraded by specifying the use of *strong* tags instead: + +```pawn +#define STRONG_TAGS +#include +``` + +Alternatively, if you really hate help: + +```pawn +#define NO_TAGS +#include +``` + +The only breaking change introduced by these new tags are on callbacks. For some reason tag mismatch warnings in function prototypes are an error, not a warning (probably because of code generation issues related to overloaded operators). The best way to deal with these is to ensure that the `public` part of the callback will compile regardless of tag settings by falling back to `_:` when none is specified: + +```pawn +#if !defined SELECT_OBJECT + #define SELECT_OBJECT: _: +#endif +forward OnPlayerSelectObject(playerid, SELECT_OBJECT:type, objectid, modelid, Float:fX, Float:fY, Float:fZ); +``` + +See lower down for a full list of all updated callbacks. This is the main problem change, but it is important to note that the following code will work with any include, with or without the new tags: + +```pawn +#if !defined CLICK_SOURCE + #define CLICK_SOURCE: _: +#endif +public OnPlayerClickPlayer(playerid, clickedplayerid, CLICK_SOURCE:source) +{ + return 1; +} +``` + +Thus writing backwards-compatible code remains possible. Forward for ALS as normal: + +```pawn +#if !defined PLAYER_STATE + // Use the default tag (none, `_:`) when the improved includes aren't found. + #define PLAYER_STATE: _: +#endif +public OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate) +{ + return Hooked_OnPlayerStateChange(playerid, newstate, oldstate); +} + +forward Hooked_OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate); +``` + +### Tag Warning Example + +```pawn +if (GetPVarType(playerid, "MY_DATA") == 1) +{ + printf("Found an int"); +} +``` + +This code is correct, and will give the correct answer, so why add warnings? + +```pawn +switch (GetPVarType(playerid, "MY_DATA")) +{ +case 0: + printf("Unknown type"); +case 1: + printf("Found an int"); +case 2: + printf("Found a float"); +case 3: + printf("Found a string"); +case 4: + printf("Found a boolean"); +} +``` + +This code is subtly wrong, take a moment to try and work out how - the compiler will not help you. + +It could take a lot of testing and debugging to find the problem here without a lot of familiarity with the functions in question, fortunately the a_samp includes now return a `VARTYPE:` tag from `GetPVarType` and this code will give tag-mismatch warnings. Once we try and fix the warnings using the defined constants the mistakes become instantly obvious: + +```pawn +switch (GetPVarType(playerid, "MY_DATA")) +{ +case PLAYER_VARTYPE_NONE: + printf("Unknown type"); +case PLAYER_VARTYPE_INT: + printf("Found an int"); +case PLAYER_VARTYPE_STRING: + printf("Found a float"); +case PLAYER_VARTYPE_FLOAT: + printf("Found a string"); +case PLAYER_VARTYPE_BOOL: + printf("Found a boolean"); +} +``` + +The string/float mixup still needs some manual review, but it is now far more obvious that those two are the wrong way around. In fact there's a good chance that the person updating the code would have used them the correct way round without even realising that they have now fixed a prior bug. The `VARTYPE_BOOL:` line will give an error that the symbol doesn't exist because there is no type `4`. The old code quite happily compiled without issues and had an impossible branch. The effects aren't serious in this example, but they could be. But, again, the old code will still compile and run. More warnings help to highlight issues, they do not introduce new ones. + +### Complete List + +* `OnPlayerStateChange` + +```pawn +#if !defined PLAYER_STATE + #define PLAYER_STATE: _: +#endif +forward OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate); +``` + +* `OnPlayerClickPlayer` + +```pawn +#if !defined CLICK_SOURCE + #define CLICK_SOURCE: _: +#endif +forward OnPlayerClickPlayer(playerid, clickedplayerid, CLICK_SOURCE:source); +``` + +* `OnPlayerEditObject` + +```pawn +#if !defined EDIT_RESPONSE + #define EDIT_RESPONSE: _: +#endif +forward OnPlayerEditObject(playerid, playerobject, objectid, EDIT_RESPONSE:response, Float:fX, Float:fY, Float:fZ, Float:fRotX, Float:fRotY, Float:fRotZ); +``` + +* `OnPlayerEditAttachedObject` + +```pawn +#if !defined EDIT_RESPONSE + #define EDIT_RESPONSE: _: +#endif +forward OnPlayerEditAttachedObject(playerid, EDIT_RESPONSE:response, index, modelid, boneid, Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fScaleX, Float:fScaleY, Float:fScaleZ); +``` + +* `OnPlayerSelectObject` + +```pawn +#if !defined SELECT_OBJECT + #define SELECT_OBJECT: _: +#endif +forward OnPlayerSelectObject(playerid, SELECT_OBJECT:type, objectid, modelid, Float:fX, Float:fY, Float:fZ); +``` + +* `OnPlayerWeaponShot` + +```pawn +#if !defined BULLET_HIT_TYPE + #define BULLET_HIT_TYPE: _: +#endif +forward OnPlayerWeaponShot(playerid, weaponid, BULLET_HIT_TYPE:hittype, hitid, Float:fX, Float:fY, Float:fZ); +``` + +* `OnPlayerKeyStateChange` + +```pawn +#if !defined KEY + #define KEY: _: +#endif +forward OnPlayerKeyStateChange(playerid, KEY:newkeys, KEY:oldkeys); +``` + +* `OnPlayerRequestDownload` + +```pawn +#if !defined DOWNLOAD_REQUEST + #define DOWNLOAD_REQUEST: _: +#endif +forward OnPlayerRequestDownload(playerid, DOWNLOAD_REQUEST:type, crc); +``` + +### Streamer Plugin + +There is a PR to extend these improved checks to the streamer plugin as well: https://github.com/samp-incognito/samp-streamer-plugin/pull/435 This PR includes more information on the tags. + +* `Streamer_OnItemStreamIn` + +```pawn +#if !defined STREAMER_TYPE + #define STREAMER_TYPE: _: +#endif +public Streamer_OnItemStreamIn(STREAMER_TYPE:type, STREAMER_ALL_TAGS:id, forplayerid) +{ +} +``` + +* `Streamer_OnItemStreamOut` + +```pawn +#if !defined STREAMER_TYPE + #define STREAMER_TYPE: _: +#endif +public Streamer_OnItemStreamOut(STREAMER_TYPE:type, STREAMER_ALL_TAGS:id, forplayerid) +{ +} +``` + +### Upgrade Tool + +Y_Less has been working on a tool to make porting code easier, here: + +https://github.com/openmultiplayer/upgrade + +This can scan all pawn files (`.inc`, `.p`, `.pawn`, `.pwn`) in a directory and search for function calls that look like the ones in these includes with new tags. It will find hook declarations following a standard `Lib_Native` naming scheme where `Native` is one known to have been enhanced, and thus upgrade these hooks automatically. It will also find many calls to the upgraded natives using bare numbers, so for example: + +```pawn +SetTimer("MyFunction", 1000, 0); +``` + +Will be found and replaced by: + +```pawn +SetTimer("MyFunction", 1000, false); +``` + +See the readme with the tool for more information, including adding your own upgrades, and checking output before applying the changes (always make backups first). + ## How Do Versions Work? ### Versions are represented by [Git Tags](https://help.github.com/articles/working-with-tags/) diff --git a/a_actor.inc b/a_actor.inc index 2f5aae4..252b695 100644 --- a/a_actor.inc +++ b/a_actor.inc @@ -1,229 +1,382 @@ -/* SA-MP Actor Functions - * - * (c) Copyright 2015, SA-MP Team - * - */ - #if defined _INC_a_actor #endinput #endif #define _INC_a_actor #define _actor_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2015, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +///

+ +// -------------------------------------------------- +// Defines +// -------------------------------------------------- -///

Create a static 'actor' in the world. These 'actors' are like NPCs, however they have limited functionality. They do not take up server player slots. -/// The model ID (skin ID) the actor should have -/// The X coordinate to create the actor at -/// The Y coordinate to create the actor at -/// The Z coordinate to create the actor at -/// The facing angle (rotation) for the actor to have -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// Actors are completely separate from NPCs. They do NOT use player IDs/slots on the server and CANNOT be handled like NPCs.

-/// Actors are limited to 1000 (MAX_ACTORS).

-/// Actors can be pushed by vehicles, use a timer to put them back at their positions.

-/// As of 0.3.7 R2 actors default to being invulnerable. -/// -/// -/// The created Actor ID (start at 0).

-/// INVALID_ACTOR_ID (65535) If the actor limit (1000) is reached. -/// -native CreateActor(modelid, Float:X, Float:Y, Float:Z, Float:Rotation); - -///

Destroy an actor which was created with CreateActor. -/// The ID of the actor to destroy. Returned by CreateActor -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor with the ID specified does not exist. -/// -native DestroyActor(actorid); - - -///

Checks if an actor is streamed in for a player. -/// The ID of the actor -/// The ID of the player -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// 1 if the actor is streamed in for the player, or 0 if it is not. -native IsActorStreamedIn(actorid, forplayerid); - - -/// Set the virtual world of an actor. Only players in the same world will see the actor. -/// The ID of the actor (returned by CreateActor) to set the virtual world of -/// The virtual world to put the actor ID -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native SetActorVirtualWorld(actorid, vworld); - -///

Get the virtual world of an actor. -/// The ID of the actor to get the virtual world of -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The virtual world of the actor. By default this is 0. Also returns 0 if actor specified does not exist. +// Limits +/** + * a_actor + */ +#if defined MAX_ACTORS + const __MAX_ACTORS = MAX_ACTORS; + #define __MAX_ACTORS +#else + const MAX_ACTORS = 1000; + #define MAX_ACTORS 1000 +#endif + +// Invalids +/** + * a_actor + */ +const INVALID_ACTOR_ID = 0xFFFF; +#define INVALID_ACTOR_ID 0xFFFF + +// Checks +#if MAX_ACTORS < 1 || MAX_ACTORS > 1000 + #error MAX_ACTORS must be >= 1 and <= 1000 +#endif + +/** + * a_actor + * Create a static 'actor' in the world. These 'actors' are like NPCs, however they have limited + * functionality. They do not take up server player slots. + * The model ID (skin ID) the actor should have + * The x coordinate to create the actor at + * The y coordinate to create the actor at + * The z coordinate to create the actor at + * The facing angle (rotation) for the actor to have + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * Actors are completely separate from NPCs. They do NOT use player IDs/slots on the server and CANNOT + * be handled like NPCs.
+ * Actors are limited to 1000 (MAX_ACTORS).
+ * Actors can be pushed by vehicles, use a timer to put them back at their positions.
+ * As of 0.3.7 R2 actors default to being invulnerable. + * + * + * The created Actor ID (start at 0).
+ * INVALID_ACTOR_ID (65535) If the actor limit (1000) is + * reached. + * + */ +native CreateActor(modelid, Float:x, Float:y, Float:z, Float:angle); + +/** + * a_actor + * Destroy an actor which was created with CreateActor. + * The ID of the actor to destroy. Returned by CreateActor + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor with the ID specified does not exist. + * + */ +native bool:DestroyActor(actorid); + +/** + * a_actor + * Checks if an actor is streamed in for a player. + * The ID of the actor + * The ID of the player + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * 1 if the actor is streamed in for the player, or 0 if it is + * not. + */ +native bool:IsActorStreamedIn(actorid, playerid); + +/** + * a_actor + * Set the virtual world of an actor. Only players in the same world will see the actor. + * The ID of the actor (returned by CreateActor) to + * set the virtual world of + * The virtual world to put the actor ID + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:SetActorVirtualWorld(actorid, virtualWorld); + +/** + * a_actor + * Get the virtual world of an actor. + * The ID of the actor to get the virtual world of + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The virtual world of the actor. By default this is 0. Also returns 0 + * if actor specified does not exist. + */ native GetActorVirtualWorld(actorid); -/// Apply an animation to an actor. -/// The ID of the actor to apply the animation to -/// The animation library from which to apply an animation -/// The name of the animation to apply, within the specified library -/// The speed to play the animation (use 4.1) -/// If set to 1, the animation will loop. If set to 0, the animation will play once -/// If set to 0, the actor is returned to their old X coordinate once the animation is complete (for animations that move the actor such as walking). 1 will not return them to their old position -/// Same as above but for the Y axis. Should be kept the same as the previous parameter -/// Setting this to 1 will freeze an actor at the end of the animation. 0 will not -/// Timer in milliseconds. For a never-ending loop it should be 0 -/// -/// You must preload the animation library for the player the actor will be applying the animation for, and not for the actor. Otherwise, the animation won't be applied to the actor until the function is executed again. -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native ApplyActorAnimation(actorid, const animlib[], const animname[], Float:fDelta, loop, lockx, locky, freeze, time); - -///

Clear any animations applied to an actor. -/// The ID of the actor (returned by CreateActor) to clear the animations for -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native ClearActorAnimations(actorid); - - -///

Set the position of an actor. -/// The ID of the actor to set the position of. Returned by CreateActor -/// The X coordinate to position the actor at -/// The Y coordinate to position the actor at -/// The Z coordinate to position the actor at -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// When creating an actor with CreateActor, you specify it's position. You do not need to use this function unless you want to change its position later. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native SetActorPos(actorid, Float:X, Float:Y, Float:Z); - -///

Get the position of an actor. -/// The ID of the actor to get the position of. Returned by CreateActor -/// A float variable, passed by reference, in which to store the X coordinate of the actor -/// A float variable, passed by reference, in which to store the Y coordinate of the actor -/// A float variable, passed by reference, in which to store the Z coordinate of the actor -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist.

-/// -native GetActorPos(actorid, &Float:X, &Float:Y, &Float:Z); - -///

Set the facing angle of an actor. -/// The ID of the actor to set the facing angle of. Returned by CreateActor -/// The facing angle to set for the actor -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// Players will see actor's facing angle changed only when it is restreamed to them. -/// When creating an actor with CreateActor, you specify it's facing angle. You do not need to use this function unless you want to change its facing angle later. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native SetActorFacingAngle(actorid, Float:ang); - -///

Get the facing angle of an actor. -/// The ID of the actor to get the facing angle of. Returned by CreateActor -/// A float variable, passed by reference, in to which the actor's facing angle will be stored -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The actor specified does not exist. -/// -native GetActorFacingAngle(actorid, &Float:ang); - - -///

Set the health of an actor. -/// The ID of the actor to set the health of -/// The value to set the actors's health to -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1 on success.

-/// 0 on failure (i.e. actor is not created). -/// -native SetActorHealth(actorid, Float:health); - -///

Get the health of an actor. -/// The ID of the actor to get the health of -/// A float variable, passed by reference, in to which to store the actor's health -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1 - success.

-/// 0 - failure (i.e. actor is not created).

-/// -native GetActorHealth(actorid, &Float:health); - -///

Toggle an actor's invulnerability. -/// The ID of the actor to set invulnerability -/// false to make them vulnerable, true to make them invulnerable (optional=true) -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// Once set invulnerable, the actor does not call OnPlayerGiveDamageActor. -/// Players will have actor's invulnerability state changed only when it is restreamed to them. -/// -/// 1 - Success.

-/// 0 - Failure (i.e. Actor is not created). -/// -native SetActorInvulnerable(actorid, invulnerable = true); - -///

Check if an actor is invulnerable. -/// The ID of the actor to check -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// 1 if the actor is invulnerable, 0 otherwise. -native IsActorInvulnerable(actorid); - - -/// Checks if an actor ID is valid. -/// The ID of the actor to check -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// 1 if the actor is valid, 0 if not. -native IsValidActor(actorid); +/** + * a_actor + * Apply an animation to an actor. + * The ID of the actor to apply the animation to + * The animation library from which to apply an animation + * The name of the animation to apply, within the specified library + * The speed to play the animation (use 4.1) + * If set to 1, the animation will loop. If set to 0, + * the animation will play once + * If set to 0, the actor is returned to their old x coordinate once + * the animation is complete (for animations that move the actor such as walking). 1 will + * not return them to their old position + * Same as above but for the y axis. Should be kept the same as the previous parameter + * Setting this to 1 will freeze an actor at the end of the animation. + * 0 will not + * Timer in milliseconds. For a never-ending loop it should be 0 + * + * You must preload the animation library for the player the actor will be applying the animation + * for, and not for the actor. Otherwise, the animation won't be applied to the actor until the function + * is executed again. + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:ApplyActorAnimation(actorid, const animationLibrary[], const animationName[], Float:delta, bool:loop, bool:lockX, bool:lockY, bool:freeze, time); + +/** + * a_actor + * Clear any animations applied to an actor. + * The ID of the actor (returned by CreateActor) to + * clear the animations for + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:ClearActorAnimations(actorid); + +/** + * a_actor + * Set the position of an actor. + * The ID of the actor to set the position of. Returned by CreateActor + * The x coordinate to position the actor at + * The y coordinate to position the actor at + * The z coordinate to position the actor at + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * When creating an actor with CreateActor, you specify it's position. + * You do not need to use this function unless you want to change its position later. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:SetActorPos(actorid, Float:x, Float:y, Float:z); + +/** + * a_actor + * Get the position of an actor. + * The ID of the actor to get the position of. Returned by CreateActor + * A float variable, passed by reference, in which to store the x coordinate of the + * actor + * A float variable, passed by reference, in which to store the y coordinate of the + * actor + * A float variable, passed by reference, in which to store the z coordinate of the + * actor + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist.
+ * + */ +native bool:GetActorPos(actorid, &Float:x, &Float:y, &Float:z); + +/** + * a_actor + * Set the facing angle of an actor. + * The ID of the actor to set the facing angle of. Returned by CreateActor + * The facing angle to set for the actor + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * Players will see actor's facing angle changed only when it is restreamed to them. + * When creating an actor with CreateActor, you specify it's facing + * angle. You do not need to use this function unless you want to change its facing angle later. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:SetActorFacingAngle(actorid, Float:angle); + +/** + * a_actor + * Get the facing angle of an actor. + * The ID of the actor to get the facing angle of. Returned by CreateActor + * A float variable, passed by reference, in to which the actor's facing angle will + * be stored + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The actor specified does not exist. + * + */ +native bool:GetActorFacingAngle(actorid, &Float:angle); + +/** + * a_actor + * Set the health of an actor. + * The ID of the actor to set the health of + * The value to set the actors's health to + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1 on success.
+ * 0 on failure (i.e. actor is not created). + * + */ +native bool:SetActorHealth(actorid, Float:health); + +/** + * a_actor + * Get the health of an actor. + * The ID of the actor to get the health of + * A float variable, passed by reference, in to which to store the actor's health + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1 - success.
+ * 0 - failure (i.e. actor is not created).
+ * + */ +native bool:GetActorHealth(actorid, &Float:health); + +/** + * a_actor + * Toggle an actor's invulnerability. + * The ID of the actor to set invulnerability + * false to make them vulnerable, true to make + * them invulnerable (optional=true) + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * Once set invulnerable, the actor does not call OnPlayerGiveDamageActor. + * Players will have actor's invulnerability state changed only when it is restreamed to them. + * + * 1 - Success.
+ * 0 - Failure (i.e. Actor is not created). + * + */ +native bool:SetActorInvulnerable(actorid, bool:invulnerable = true); + +/** + * a_actor + * Check if an actor is invulnerable. + * The ID of the actor to check + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * 1 if the actor is invulnerable, 0 otherwise. + */ +native bool:IsActorInvulnerable(actorid); + +/** + * a_actor + * Checks if an actor ID is valid. + * The ID of the actor to check + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * 1 if the actor is valid, 0 if not. + */ +native bool:IsValidActor(actorid); + +/** + * This callback is called when a player gives damage to an actor. + * The ID of the player that gave damage + * The ID of the actor that received damage + * The amount of health/armour damaged_actorid has lost + * The reason that caused the damage + * The body part that was hit + * + * + * + * + * + * + * + * + * This callback was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function does not get called if the actor is set invulnerable (WHICH IS BY DEFAULT). + * See SetActorInvulnerable. + * + * 1 - Callback will not be called in other filterscripts.
+ * 0 - Allows this callback to be called in other filterscripts.
+ * It is always called first in filterscripts so returning 1 there blocks other filterscripts + * from seeing it. + * + */ +forward OnPlayerGiveDamageActor(playerid, damaged_actorid, Float:amount, weaponid, bodypart); + +/** + * This callback is called when an actor is streamed in by a player's client. + * The ID of the actor that has been streamed in for the player + * The ID of the player that streamed the actor in + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This callback can also be called by NPC. + * It is always called first in filterscripts. + * This callback does not handle returns. + */ +forward OnActorStreamIn(actorid, forplayerid); + +/** + * This callback is called when an actor is streamed out by a player's client. + * The ID of the actor that has been streamed out for the player + * The ID of the player that streamed the actor out + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This callback can also be called by NPC. + * It is always called first in filterscripts. + * This callback does not handle returns. + */ +forward OnActorStreamOut(actorid, forplayerid); diff --git a/a_http.inc b/a_http.inc old mode 100755 new mode 100644 index f313769..4ed1ecc --- a/a_http.inc +++ b/a_http.inc @@ -1,66 +1,115 @@ - /* SA-MP threaded HTTP/1.0 client for pawn - * - * (c) Copyright 2010, SA-MP Team - * - */ - #if defined _INC_a_http #endinput #endif #define _INC_a_http +#define _http_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2010, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +///

// -------------------------------------------------- // Defines // -------------------------------------------------- -// HTTP requests -#define HTTP_GET (1) -#define HTTP_POST (2) -#define HTTP_HEAD (3) +// Limits + +// Invalids -// HTTP error response codes -// These codes compliment ordinary HTTP response codes returned in 'response_code' -// (10x) (20x OK) (30x Moved) (40x Unauthorised) (50x Server Error) -#define HTTP_ERROR_BAD_HOST (1) -#define HTTP_ERROR_NO_SOCKET (2) -#define HTTP_ERROR_CANT_CONNECT (3) -#define HTTP_ERROR_CANT_WRITE (4) -#define HTTP_ERROR_CONTENT_TOO_BIG (5) -#define HTTP_ERROR_MALFORMED_RESPONSE (6) +// Checks -///

Sends a threaded HTTP request. -/// ID used to differentiate requests that are sent to the same callback (useful for playerids) -/// The type of request you wish to send -/// The URL you want to request. (Without 'http://') -/// Any POST data you want to send with the request -/// Name of the callback function you want to use to handle responses to this request -/// This function was added in SA-MP 0.3b and will not work in earlier versions! -/// 1 on success, 0 on failure. -/// -/// Request types:

-///

    -///
  • HTTP_GET
    • -///
  • HTTP_POST
    • -///
  • HTTP_HEAD
    • -///
-/// -/// -/// Response codes:

-///

    -///
  • HTTP_ERROR_BAD_HOST
    • -///
  • HTTP_ERROR_NO_SOCKET
    • -///
  • HTTP_ERROR_CANT_CONNECT
    • -///
  • HTTP_ERROR_CANT_WRITE
    • -///
  • HTTP_ERROR_CONTENT_TOO_BIG
    • -///
  • HTTP_ERROR_MALFORMED_RESPONSE
    • -///
  • + standard HTTP response codes
    • -///
-/// -native HTTP(index, type, const url[], const data[], const callback[]); +// Enums +/// + +/** + * a_http + * HTTP request types + */ +#define HTTP_METHOD: __TAG(HTTP_METHOD): +enum HTTP_METHOD:__HTTP_METHOD +{ + HTTP_GET = 1, + HTTP_POST, + HTTP_HEAD +} +static stock HTTP_METHOD:_@HTTP_METHOD() { return __HTTP_METHOD; } + +/// + +/** + * a_http + * HTTP error response codes + * + * These codes compliment ordinary HTTP response codes returned in 'responseCode' + * (10x) (20x OK) (30x Moved) (40x Unauthorised) (50x Server Error) + * + */ +#define HTTP_ERROR: __TAG(HTTP_ERROR): +enum HTTP_ERROR:__HTTP_ERROR +{ + HTTP_ERROR_BAD_HOST = 1, + HTTP_ERROR_NO_SOCKET, + HTTP_ERROR_CANT_CONNECT, + HTTP_ERROR_CANT_WRITE, + HTTP_ERROR_CONTENT_TOO_BIG, + HTTP_ERROR_MALFORMED_RESPONSE +} +static stock HTTP_ERROR:_@HTTP_ERROR() { return __HTTP_ERROR; } + +/** + * a_http + * Sends a threaded HTTP request. + * ID used to differentiate requests that are sent to the same callback (useful + * for playerids) + * The type of request you wish to send + * The URL you want to request. (Without 'http://') + * Any POST data you want to send with the request + * Name of the callback function you want to use to handle responses to this + * request + * This function was added in SA-MP 0.3b and will not work in earlier versions! + * 1 on success, 0 on failure. + * + * Request types:
+ *
    + *
  • HTTP_GET
    • + *
  • HTTP_POST
    • + *
  • HTTP_HEAD
    • + *
+ * + * + * Response codes:
+ *
    + *
  • HTTP_ERROR_BAD_HOST
    • + *
  • HTTP_ERROR_NO_SOCKET
    • + *
  • HTTP_ERROR_CANT_CONNECT
    • + *
  • HTTP_ERROR_CANT_WRITE
    • + *
  • HTTP_ERROR_CONTENT_TOO_BIG
    • + *
  • HTTP_ERROR_MALFORMED_RESPONSE
    • + *
  • + standard HTTP response codes
    • + *
+ * + * + * + * // HTTP callback.
+ * public MyHttpResponse(index, responseCode, const data[]) { ... } + * + * + */ +native HTTP(index, HTTP_METHOD:method, const url[], const data[], const callback[]); -// example HTTP callback: public MyHttpResponse(index, response_code, const data[]) { ... } diff --git a/a_npc.inc b/a_npc.inc old mode 100755 new mode 100644 index 06b367d..03593de --- a/a_npc.inc +++ b/a_npc.inc @@ -1,9 +1,3 @@ -/* SA-MP NPC Functions - * - * (c) Copyright 2009, SA-MP Team - * - */ - #if defined _INC_a_npc #endinput #endif @@ -13,136 +7,329 @@ #define _INC_a_npc #define _samp_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2009, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ +// Ignores warning 217 for properly indented PAWNO code +// It's tab size is 4 and often uses 4 spaces instead, PAWNCC's is 8 #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +///

+ +/** + * + * Version examples: + *

    + *
  • 0.3.DL R1 - 03D010
    • + *
    • + *
  • 0.3.7 R3 - 037030
    • + *
  • 0.3.7 R2-2 - 037022
    • + *
  • 0.3.7 R1-2 - 037012
    • + *
  • 0.3.7 - 037000
    • + *
    • + *
  • 0.3z R4 - 030700
    • + *
  • 0.3z R3 - 030700
    • + *
  • 0.3z R2-1 - 030700
    • + *
  • 0.3z R1-2 - 030700
    • + *
  • 0.3z - 030700
    • + *
  • 0.3x R2 patch 1 - 030621
    • + *
  • 0.3x R2 - 030620
    • + *
  • 0.3x R1-2 - 030612
    • + *
  • 0.3x - 030600
    • + *
  • 0.3e - 030500
    • + *
  • 0.3d - 030400
    • + *
  • 0.3c - 030300
    • + *
  • 0.3b - 030200
    • + *
  • 0.3a - 030100
    • + *
    • + *
  • 0.2X - 02A000
    • + *
  • 0.2.2 R3 - 022300
    • + *
+ * Rough rules: + * + *

+ * Uses (roughtly) BCD. Special versions are denoted outside 0-9. + * + * 0.1.2c R4-5 + * | | || | | + * 0 1 23 4 5 + * = + * 0x012345 + * + * (assuming c is the third revision) + * + *

+ * 0.2X becomes 02A000 because it is basically 0.2.3, but not, while higher than + * 0.2.2 so can't be 020400 (for example). Also, its a capital letter, so doesn't + * use the revision method. + * + *

+ * P.S. Making a consistent scheme for SA:MP versions is REALLY hard. + * + *

+ * open.mp releases can use `A` as the first digit. + * + */ + +public const __SAMP_INCLUDES_VERSION = 0x037030; +#pragma unused __SAMP_INCLUDES_VERSION + +/** + * + * If running on SA:MP this will remain 0, open.mp will set it. + * open.mp versions look like: + * + * 01.04.02.0544 + * + * Thus they are encoded here as: + * + * (major << 28) | (minor << 21) | (patch << 14) | (prerel) + * + * + */ +public const __OPEN_MP_VERSION = 0; +#pragma unused __OPEN_MP_VERSION + +// Optionally stricter tags. +#if defined NO_TAGS + #define __TAG(%0) _ +#elseif defined STRONG_TAGS + #define __TAG(%0) E_%0 +#else // if defined WEAK_TAGS + #define __TAG(%0) e_%0 + #define WEAK_TAGS +#endif +#if defined MORE_TAGS + #define __MORE(%0) __TAG(%0) +#else + #define __MORE(%0) _ + #define LESS_TAGS +#endif +#define __LESS __TAG // -------------------------------------------------- // Defines // -------------------------------------------------- // Limits -#if !defined MAX_PLAYER_NAME - #define MAX_PLAYER_NAME (24) +/** + * a_npc + */ +#if defined MAX_PLAYER_NAME + const __MAX_PLAYER_NAME = MAX_PLAYER_NAME; + #define __MAX_PLAYER_NAME +#else + const MAX_PLAYER_NAME = 24; + #define MAX_PLAYER_NAME 24 #endif -#if !defined MAX_PLAYERS - #define MAX_PLAYERS (1000) +/** + * a_npc + */ +#if defined MAX_PLAYERS + const __MAX_PLAYERS = MAX_PLAYERS; + #define __MAX_PLAYERS +#else + const MAX_PLAYERS = 1000; + #define MAX_PLAYERS 1000 #endif -#if !defined MAX_VEHICLES - #define MAX_VEHICLES (2000) +/** + * a_npc + */ +#if defined MAX_VEHICLES + const __MAX_VEHICLES = MAX_VEHICLES; + #define __MAX_VEHICLES +#else + const MAX_VEHICLES = 2000; + #define MAX_VEHICLES 2000 #endif -#if !defined MAX_OBJECTS - #define MAX_OBJECTS (2000) +/** + * a_npc + */ +#if defined MAX_ACTORS + const __MAX_ACTORS = MAX_ACTORS; + #define __MAX_ACTORS +#else + const MAX_ACTORS = 1000; + #define MAX_ACTORS 1000 #endif -#if !defined MAX_GANG_ZONES - #define MAX_GANG_ZONES (1024) +/** + * a_npc + */ +#if defined MAX_OBJECTS + const __MAX_OBJECTS = MAX_OBJECTS; + #define __MAX_OBJECTS +#else + const MAX_OBJECTS = 2000; + #define MAX_OBJECTS 2000 +#endif + +/** + * a_npc + */ +#if defined MAX_GANG_ZONES + const __MAX_GANG_ZONES = MAX_GANG_ZONES; + #define __MAX_GANG_ZONES +#else + const MAX_GANG_ZONES = 1024; + #define MAX_GANG_ZONES 1024 #endif -#if !defined MAX_TEXT_DRAWS +/** + * a_npc + */ +#if defined MAX_TEXT_DRAWS + const Text:__MAX_TEXT_DRAWS = MAX_TEXT_DRAWS; + #define __MAX_TEXT_DRAWS +#else + const Text:MAX_TEXT_DRAWS = Text:2048; #define MAX_TEXT_DRAWS (Text:2048) #endif -#if !defined MAX_MENUS +/** + * a_npc + */ +#if defined MAX_PLAYER_TEXT_DRAWS + const PlayerText:__MAX_PLAYER_TEXT_DRAWS = MAX_PLAYER_TEXT_DRAWS; + #define __MAX_PLAYER_TEXT_DRAWS +#else + const PlayerText:MAX_PLAYER_TEXT_DRAWS = PlayerText:256; + #define MAX_PLAYER_TEXT_DRAWS (PlayerText:256) +#endif + +/** + * a_npc + */ +#if defined MAX_MENUS + const Menu:__MAX_MENUS = MAX_MENUS; + #define __MAX_MENUS +#else + const Menu:MAX_MENUS = Menu:128; #define MAX_MENUS (Menu:128) #endif +/** + * a_npc + */ +#if defined MAX_3DTEXT_GLOBAL + const Text3D:__MAX_3DTEXT_GLOBAL = MAX_3DTEXT_GLOBAL; + #define __MAX_3DTEXT_GLOBAL +#else + const Text3D:MAX_3DTEXT_GLOBAL = Text3D:1024; + #define MAX_3DTEXT_GLOBAL (Text3D:1024) +#endif + +/** + * a_npc + */ +#if defined MAX_3DTEXT_PLAYER + const PlayerText3D:__MAX_3DTEXT_PLAYER = MAX_3DTEXT_PLAYER; + #define __MAX_3DTEXT_PLAYER +#else + const PlayerText3D:MAX_3DTEXT_PLAYER = PlayerText3D:1024; + #define MAX_3DTEXT_PLAYER (PlayerText3D:1024) +#endif + +/** + * a_npc + */ +#if defined MAX_PICKUPS + const __MAX_PICKUPS = MAX_PICKUPS; + #define __MAX_PICKUPS +#else + const MAX_PICKUPS = 4096; + #define MAX_PICKUPS 4096 +#endif + // Invalids -#define NO_TEAM (255) +/** + * a_npc + */ +const INVALID_TIMER = 0; +#define INVALID_TIMER 0 + +/** + * a_npc + */ +const NO_TEAM = 0xFF; +#define NO_TEAM 0xFF + +/** + * a_npc + */ +const INVALID_PLAYER_ID = 0xFFFF; +#define INVALID_PLAYER_ID 0xFFFF + +/** + * a_npc + */ +const INVALID_VEHICLE_ID = 0xFFFF; +#define INVALID_VEHICLE_ID 0xFFFF + +/** + * a_npc + */ +const INVALID_ACTOR_ID = 0xFFFF; +#define INVALID_ACTOR_ID 0xFFFF -#define INVALID_PLAYER_ID (0xFFFF) -#define INVALID_VEHICLE_ID (0xFFFF) -#define INVALID_OBJECT_ID (0xFFFF) +/** + * a_npc + */ +const INVALID_OBJECT_ID = 0xFFFF; +#define INVALID_OBJECT_ID 0xFFFF + +/** + * a_npc + */ +const Menu:INVALID_MENU = Menu:0xFF; #define INVALID_MENU (Menu:0xFF) + +/** + * a_npc + */ +const Text:INVALID_TEXT_DRAW = Text:0xFFFF; #define INVALID_TEXT_DRAW (Text:0xFFFF) -#define INVALID_GANG_ZONE (-1) - -// States -#define PLAYER_STATE_NONE (0) -#define PLAYER_STATE_ONFOOT (1) -#define PLAYER_STATE_DRIVER (2) -#define PLAYER_STATE_PASSENGER (3) -#define PLAYER_STATE_WASTED (7) -#define PLAYER_STATE_SPAWNED (8) -#define PLAYER_STATE_SPECTATING (9) - -// Weapons -#define WEAPON_BRASSKNUCKLE (1) -#define WEAPON_GOLFCLUB (2) -#define WEAPON_NITESTICK (3) -#define WEAPON_KNIFE (4) -#define WEAPON_BAT (5) -#define WEAPON_SHOVEL (6) -#define WEAPON_POOLSTICK (7) -#define WEAPON_KATANA (8) -#define WEAPON_CHAINSAW (9) -#define WEAPON_DILDO (10) -#define WEAPON_DILDO2 (11) -#define WEAPON_VIBRATOR (12) -#define WEAPON_VIBRATOR2 (13) -#define WEAPON_FLOWER (14) -#define WEAPON_CANE (15) -#define WEAPON_GRENADE (16) -#define WEAPON_TEARGAS (17) -#define WEAPON_MOLTOV (18) -#define WEAPON_COLT45 (22) -#define WEAPON_SILENCED (23) -#define WEAPON_DEAGLE (24) -#define WEAPON_SHOTGUN (25) -#define WEAPON_SAWEDOFF (26) -#define WEAPON_SHOTGSPA (27) -#define WEAPON_UZI (28) -#define WEAPON_MP5 (29) -#define WEAPON_AK47 (30) -#define WEAPON_M4 (31) -#define WEAPON_TEC9 (32) -#define WEAPON_RIFLE (33) -#define WEAPON_SNIPER (34) -#define WEAPON_ROCKETLAUNCHER (35) -#define WEAPON_HEATSEEKER (36) -#define WEAPON_FLAMETHROWER (37) -#define WEAPON_MINIGUN (38) -#define WEAPON_SATCHEL (39) -#define WEAPON_BOMB (40) -#define WEAPON_SPRAYCAN (41) -#define WEAPON_FIREEXTINGUISHER (42) -#define WEAPON_CAMERA (43) -#define WEAPON_PARACHUTE (46) -#define WEAPON_VEHICLE (49) -#define WEAPON_DROWN (53) -#define WEAPON_COLLISION (54) - -// Keys -#define KEY_ACTION (1) -#define KEY_CROUCH (2) -#define KEY_FIRE (4) -#define KEY_SPRINT (8) -#define KEY_SECONDARY_ATTACK (16) -#define KEY_JUMP (32) -#define KEY_LOOK_RIGHT (64) -#define KEY_HANDBRAKE (128) -#define KEY_LOOK_LEFT (256) -#define KEY_SUBMISSION (512) -#define KEY_LOOK_BEHIND (512) -#define KEY_WALK (1024) -#define KEY_ANALOG_UP (2048) -#define KEY_ANALOG_DOWN (4096) -#define KEY_ANALOG_RIGHT (16384) -#define KEY_ANALOG_LEFT (8192) - -#define KEY_UP (-128) -#define KEY_DOWN (128) -#define KEY_LEFT (-128) -#define KEY_RIGHT (128) - -#define PLAYER_RECORDING_TYPE_NONE (0) -#define PLAYER_RECORDING_TYPE_DRIVER (1) -#define PLAYER_RECORDING_TYPE_ONFOOT (2) -// Limits +/** + * a_npc + */ +const PlayerText:INVALID_PLAYER_TEXT_DRAW = PlayerText:0xFFFF; +#define INVALID_PLAYER_TEXT_DRAW (PlayerText:0xFFFF) + +/** + * a_npc + */ +const INVALID_GANG_ZONE = 0xFFFFFFFF; +#define INVALID_GANG_ZONE 0xFFFFFFFF + +/** + * a_npc + */ +const Text3D:INVALID_3DTEXT_ID = Text3D:0xFFFF; +#define INVALID_3DTEXT_ID (Text3D:0xFFFF) + +/** + * a_npc + */ +const PlayerText3D:INVALID_PLAYER_3DTEXT_ID = PlayerText3D:0xFFFF; +#define INVALID_PLAYER_3DTEXT_ID (PlayerText3D:0xFFFF) + +// Checks #if MAX_PLAYER_NAME < 1 || MAX_PLAYER_NAME > 24 #error MAX_PLAYER_NAME must be >= 1 and <= 24 #endif @@ -171,7 +358,192 @@ #error MAX_MENUS must be >= 1 and <= 128 #endif -public const SAMP_INCLUDES_VERSION = 0x037030; +// Enums +///

+ +/** + * a_npc + *

States + */ +#define PLAYER_STATE: __TAG(PLAYER_STATE): +enum PLAYER_STATE:__PLAYER_STATE +{ + PLAYER_STATE_NONE, + PLAYER_STATE_ONFOOT, + PLAYER_STATE_DRIVER, + PLAYER_STATE_PASSENGER, + PLAYER_STATE_WASTED = 7, + PLAYER_STATE_SPAWNED, + PLAYER_STATE_SPECTATING +} +static stock PLAYER_STATE:_@PLAYER_STATE() { return __PLAYER_STATE; } + +/** + * a_npc + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_EXIT_VEH = PLAYER_STATE:4; +#define PLAYER_STATE_EXIT_VEHICLE PLAYER_STATE_EXIT_VEH + +/** + * a_npc + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_ENTER_VEHICLE_DRV = PLAYER_STATE:5; +#define PLAYER_STATE_ENTER_VEHICLE_DRIVER PLAYER_STATE_ENTER_VEHICLE_DRV + +/** + * a_npc + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_ENTER_VEHICLE_PASS = PLAYER_STATE:6; +#define PLAYER_STATE_ENTER_VEHICLE_PASSENGER PLAYER_STATE_ENTER_VEHICLE_PASS + +///

+ +/** + * a_npc + *

Weapons + */ +#define WEAPON: __TAG(WEAPON): +enum WEAPON:__WEAPON +{ + WEAPON_UNKNOWN = -1, + WEAPON_FIST = 0, + WEAPON_BRASSKNUCKLE = 1, + WEAPON_GOLFCLUB = 2, + WEAPON_NITESTICK = 3, + WEAPON_NIGHTSTICK = WEAPON_NITESTICK, + WEAPON_KNIFE = 4, + WEAPON_BAT = 5, + WEAPON_SHOVEL = 6, + WEAPON_POOLSTICK = 7, + WEAPON_KATANA = 8, + WEAPON_CHAINSAW = 9, + WEAPON_DILDO = 10, + WEAPON_DILDO2 = 11, + WEAPON_VIBRATOR = 12, + WEAPON_VIBRATOR2 = 13, + WEAPON_FLOWER = 14, + WEAPON_CANE = 15, + WEAPON_GRENADE = 16, + WEAPON_TEARGAS = 17, + WEAPON_MOLTOV = 18, + WEAPON_MOLOTOV = WEAPON_MOLTOV, + WEAPON_COLT45 = 22, + WEAPON_SILENCED = 23, + WEAPON_DEAGLE = 24, + WEAPON_SHOTGUN = 25, + WEAPON_SAWEDOFF = 26, + WEAPON_SHOTGSPA = 27, + WEAPON_UZI = 28, + WEAPON_MP5 = 29, + WEAPON_AK47 = 30, + WEAPON_M4 = 31, + WEAPON_TEC9 = 32, + WEAPON_RIFLE = 33, + WEAPON_SNIPER = 34, + WEAPON_ROCKETLAUNCHER = 35, + WEAPON_HEATSEEKER = 36, + WEAPON_FLAMETHROWER = 37, + WEAPON_MINIGUN = 38, + WEAPON_SATCHEL = 39, + WEAPON_BOMB = 40, + WEAPON_SPRAYCAN = 41, + WEAPON_FIREEXTINGUISHER = 42, + WEAPON_CAMERA = 43, + WEAPON_NIGHT_VISION_GOGGLES = 44, + WEAPON_THERMAL_GOGGLES = 45, + WEAPON_PARACHUTE = 46, + WEAPON_VEHICLE = 49, + WEAPON_DROWN = 53, + WEAPON_COLLISION = 54, + WEAPON_SPLAT = WEAPON_COLLISION +} +static stock WEAPON:_@WEAPON() { return __WEAPON; } + +#define MAX_WEAPONS __WEAPON + +///

+ +/** + * a_npc + *

Weapon Slots + */ +#define WEAPON_SLOT: __TAG(WEAPON_SLOT): +enum WEAPON_SLOT:__WEAPON_SLOT +{ + WEAPON_SLOT_UNKNOWN = -1, + WEAPON_SLOT_UNARMED = 0, + WEAPON_SLOT_MELEE = 1, + WEAPON_SLOT_PISTOL = 2, + WEAPON_SLOT_SHOTGUN = 3, + WEAPON_SLOT_MACHINE_GUN = 4, + WEAPON_SLOT_ASSAULT_RIFLE = 5, + WEAPON_SLOT_LONG_RIFLE = 6, + WEAPON_SLOT_ARTILLERY = 7, + WEAPON_SLOT_EXPLOSIVES = 8, + WEAPON_SLOT_EQUIPMENT = 9, + WEAPON_SLOT_GIFT = 10, + WEAPON_SLOT_GADGET = 11, + WEAPON_SLOT_DETONATOR = 12 +} +static stock WEAPON_SLOT:_@WEAPON_SLOT() { return __WEAPON_SLOT; } + +#define MAX_WEAPON_SLOTS __WEAPON_SLOT + +///

+ +/** + * a_npc + *

Keys + */ +#define KEY: __TAG(KEY): +enum KEY:__KEY (<<= 1) +{ + KEY_ACTION = 1, + KEY_CROUCH, + KEY_FIRE, + KEY_SPRINT, + KEY_SECONDARY_ATTACK, + KEY_JUMP, + KEY_LOOK_RIGHT, + KEY_HANDBRAKE, + KEY_LOOK_LEFT, + KEY_SUBMISSION, + KEY_LOOK_BEHIND = KEY_SUBMISSION, + KEY_WALK, + KEY_ANALOG_UP, + KEY_ANALOG_DOWN, + KEY_ANALOG_LEFT, + KEY_ANALOG_RIGHT, + KEY_YES = 65536, + KEY_NO, + KEY_CTRL_BACK, + + KEY_UP = -128, + KEY_DOWN = 128, + KEY_LEFT = -128, + KEY_RIGHT = 128, +} +static stock KEY:_@KEY() { return __KEY; } + +///

+ +/** + * a_npc + */ +#define PLAYER_RECORDING_TYPE: __TAG(PLAYER_RECORDING_TYPE): +enum PLAYER_RECORDING_TYPE:__PLAYER_RECORDING_TYPE +{ + PLAYER_RECORDING_TYPE_NONE, + PLAYER_RECORDING_TYPE_DRIVER, + PLAYER_RECORDING_TYPE_ONFOOT +} +static stock PLAYER_RECORDING_TYPE:_@PLAYER_RECORDING_TYPE() { return __PLAYER_RECORDING_TYPE; } #include #include @@ -181,466 +553,614 @@ public const SAMP_INCLUDES_VERSION = 0x037030; #include #tryinclude -/* - -Version examples: - -0.3.DL R1 - 03D010 - -0.3.7 R3 - 037030 -0.3.7 R2-2 - 037022 -0.3.7 R1-2 - 037012 -0.3.7 - 037000 - -0.3z R4 - 030700 -0.3z R3 - 030700 -0.3z R2-1 - 030700 -0.3z R1-2 - 030700 -0.3z - 030700 -0.3x R2 patch 1 - 030621 -0.3x R2 - 030620 -0.3x R1-2 - 030612 -0.3x - 030600 -0.3e - 030500 -0.3d - 030400 -0.3c - 030300 -0.3b - 030200 -0.3a - 030100 - -0.2X - 02A000 -0.2.2 R3 - 022300 - -Rough rules: - -Uses (roughtly) BCD. Special versions are denoted outside 0-9. - -0.1.2c R4-5 -| | || | | -0 1 23 4 5 -= -0x012345 - -(assuming c is the third revision) - -0.2X becomes 02A000 because it is basically 0.2.3, but not, while higher than -0.2.2 so can't be 020400 (for example). Also, its a capital letter, so doesn't -use the revision method. - -P.S. Making a consistent scheme for SA:MP versions is REALLY hard. - -open.mp releases can use `A` as the first digit. - -*/ - // -------------------------------------------------- // Natives // -------------------------------------------------- // Util -#if !defined _console_included - #define _console_included - - ///

Prints a string to the server console (not in-game chat) and logs (server_log.txt). - /// The string to print - /// +/** + * a_npc + * Prints a string to the server console (not in-game chat) and logs (server_log.txt). + * The string to print + * + */ +#if defined _console_included + // Fixes a pawndoc bug - comments on `#ifdef`ed out functions are still put + // in the output, unattached to any function. So make a function. + native a_npc_unused_print(const string[]); + #define a_npc_unused_print +#else native print(const string[]); +#endif - /// Outputs a formatted string on the console (the server window, not the in-game chat). - /// The format string - /// Indefinite number of arguments of any tag - /// - /// - /// The format string or its output should not exceed 1024 characters. Anything beyond that length can lead to a server to crash. - /// This function doesn't support packed strings. - /// - /// Format Specifiers:

- ///

    - ///
  • %i - integer (whole number)
    • - ///
  • %d - integer (whole number).
    • - ///
  • %s - string
    • - ///
  • %f - floating-point number (Float: tag)
    • - ///
  • %c - ASCII character
    • - ///
  • %x - hexadecimal number
    • - ///
  • %b - binary number
    • - ///
  • %% - literal %
    • - ///
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • - ///
- /// - /// The values for the placeholders follow in the exact same order as parameters in the call. For example, "I am %i years old" - the %i will be replaced with an Integer variable, which is the person's age. - /// You may optionally put a number between the % 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 .<max number> between the % and the f. (example: %.2f) - native printf(const format[], {Float,_}:...); +/** + * a_npc + * Outputs a formatted string on the console (the server window, not the in-game chat). + * The format string + * Indefinite number of arguments of any tag + * + * + * The format string or its output should not exceed 1024 characters. Anything beyond that + * length can lead to a server to crash. + * This function doesn't support packed strings. + * + * Format Specifiers:
+ *
    + *
  • %i - integer (whole number)
    • + *
  • %d - integer (whole number).
    • + *
  • %s - string
    • + *
  • %f - floating-point number (Float: tag)
    • + *
  • %c - ASCII character
    • + *
  • %x - hexadecimal number
    • + *
  • %b - binary number
    • + *
  • %% - literal %
    • + *
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • + *
+ * + * The values for the placeholders follow in the exact same order as parameters in the call. + * For example, "I am %i years old" - the %i will be replaced with an Integer + * variable, which is the person's age. + * You may optionally put a number between the % 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 .<max number> between + * the % and the f. (example: %.2f) + */ +#if defined _console_included + // Fixes a pawndoc bug - comments on `#ifdef`ed out functions are still put + // in the output, unattached to any function. So make a function. + native a_npc_unused_printf(const format[], {Float, _}:...); + #define a_npc_unused_printf +#else + native printf(const format[], {Float, _}:...); +#endif + +#if !defined _console_included + #define _console_included #endif -/// Formats a string to include variables and other strings inside it. -/// The string to output the result to -/// The maximum length output can contain -/// The format string -/// Indefinite number of arguments of any tag -/// -/// -/// This function doesn't support packed strings. -/// -/// Format Specifiers:

-///

    -///
  • %i - integer (whole number)
    • -///
  • %d - integer (whole number).
    • -///
  • %s - string
    • -///
  • %f - floating-point number (Float: tag)
    • -///
  • %c - ASCII character
    • -///
  • %x - hexadecimal number
    • -///
  • %b - binary number
    • -///
  • %% - literal %
    • -///
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • -///
-/// -/// The values for the placeholders follow in the exact same order as parameters in the call. For example, "I am %i years old" - the %i will be replaced with an Integer variable, which is the person's age. -/// You may optionally put a number between the % 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 .<max number> between the % and the f. (example: %.2f) -native format(output[], len = sizeof output, const format[], {Float,_}:...); - -/// Sets a 'timer' to call a function after some time. Can be set to repeat. -/// Name of the function to call as a string. This must be a public function (forwarded). A null string here will crash the server -/// Interval in milliseconds -/// Whether the timer should repeat or not -/// -/// -/// Timer intervals are not accurate (roughly 25% off). There's a fix available here. -/// 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. -/// The function that should be called must be public. -/// The use of many timers will result in increased memory/cpu usage. -/// The ID of the timer that was started. Timer IDs start at 1. -native SetTimer(const funcname[], interval, repeating); - -/// Kills (stops) a running timer. -/// The ID of the timer to kill (returned by SetTimer or SetTimerEx) -/// -/// -/// This function always returns 0. +/** + * a_npc + * Formats a string to include variables and other strings inside it. + * The string to output the result to + * The maximum length output can contain + * The format string + * Indefinite number of arguments of any tag + * + * + * This function doesn't support packed strings. + * + * Format Specifiers:
+ *
    + *
  • %i - integer (whole number)
    • + *
  • %d - integer (whole number).
    • + *
  • %s - string
    • + *
  • %f - floating-point number (Float: tag)
    • + *
  • %c - ASCII character
    • + *
  • %x - hexadecimal number
    • + *
  • %b - binary number
    • + *
  • %% - literal %
    • + *
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • + *
+ * + * The values for the placeholders follow in the exact same order as parameters in the call. + * For example, "I am %i years old" - the %i will be replaced with an Integer + * variable, which is the person's age. + * You may optionally put a number between the % 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 .<max number> between + * the % and the f. (example: %.2f) + */ +native format(output[], len = sizeof (output), const format[], {Float, _}:...); + +/** + * a_npc + * Sets a 'timer' to call a function after some time. Can be set to repeat. + * Name of the function to call as a string. This must be a public function + * (forwarded). A null string here will crash the server + * Interval in milliseconds + * Whether the timer should repeat or not + * + * + * Timer intervals are not accurate (roughly 25% off). There's a fix available + * here. + * + * 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. + * The function that should be called must be public. + * The use of many timers will result in increased memory/cpu usage. + * The ID of the timer that was started. Timer IDs start at 1. + */ +native SetTimer(const functionName[], interval, bool:repeating); + +/** + * a_npc + * Kills (stops) a running timer. + * The ID of the timer to kill (returned by SetTimer or + * SetTimerEx) + * + * + * This function always returns 0. + */ native KillTimer(timerid); -/// Returns the uptime of the actual server (not the SA-MP server) in milliseconds. -/// -/// GetTickCount will cause problems on servers with uptime of over 24 days as GetTickCount will eventually warp past the integer size constraints. However using this function fixes the problem. -/// One common use for GetTickCount is for benchmarking. It can be used to calculate how much time some code takes to execute. -/// Uptime of the actual server (not the SA-MP server). +/** + * a_npc + * Returns the uptime of the actual server (not the SA-MP server) in milliseconds. + * + * GetTickCount will cause problems on servers with uptime of over 24 days as GetTickCount + * will eventually warp past the integer size constraints. However using + * this + * function fixes the problem. + * One common use for GetTickCount is for benchmarking. It can be used to calculate how much + * time some code takes to execute. + * Uptime of the actual server (not the SA-MP server). + */ native GetTickCount(); -/// Get the inversed value of a sine in degrees. -/// The sine for which to find the angle for -/// -/// The angle in degrees. +/** + * a_npc + * Get the inversed value of a sine in degrees. + * The sine for which to find the angle for + * + * The angle in degrees. + */ native Float:asin(Float:value); -/// Get the inversed value of a cosine in degrees. -/// The cosine for which to find the angle for -/// -/// The angle in degrees. +/** + * a_npc + * Get the inversed value of a cosine in degrees. + * The cosine for which to find the angle for + * + * The angle in degrees. + */ native Float:acos(Float:value); -/// Get the inversed value of a tangent in degrees. -/// The tangent for which to find the angle for -/// -/// -/// The angle in degrees. +/** + * a_npc + * Get the inversed value of a tangent in degrees. + * The tangent for which to find the angle for + * + * + * The angle in degrees. + */ native Float:atan(Float:value); -/// Get the multi-valued inversed value of a tangent in degrees. -/// y size -/// x size -/// -/// -/// The angle in degrees. +/** + * a_npc + * Get the multi-valued inversed value of a tangent in degrees. + * y size + * x size + * + * + * The angle in degrees. + */ native Float:atan2(Float:y, Float:x); - -/// This will send a player text by the bot, just like using SendPlayerMessageToAll, but this function is to be used inside the NPC scripts. -/// The text to be sent by the NPC -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! -native SendChat(const msg[]); - -/// This will force the NPC to write a desired command, and this way, getting the effects it would produce. -/// The command text to be sent by the NPC -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! -native SendCommand(const commandtext[]); - -/// Get a player's current state. -/// The ID of the player to get the current state of -/// -/// -/// -/// -/// States:

-///

    -///
  • PLAYER_STATE_NONE - empty (while initializing)
    • -///
  • PLAYER_STATE_ONFOOT - player is on foot
    • -///
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • -///
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • -///
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • -///
  • PLAYER_STATE_SPAWNED - player is spawned
    • -///
  • PLAYER_STATE_SPECTATING - player is spectating
    • -///
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger
    • -///
-/// -/// The player's current state as an integer. -native GetPlayerState(playerid); - -/// Get the position of a player, represented by X, Y and Z coordinates. -/// The ID of the player to get the position of -/// A float variable in which to store the X coordinate in, passed by reference -/// A float variable in which to store the Y coordinate in, passed by reference -/// A float variable in which to store the Z coordinate in, passed by reference -/// -/// -/// -/// -/// This function is known to return unreliable values when used in OnPlayerDisconnect and OnPlayerRequestClass. This is because the player is not spawned. -/// true on success, false on failure (i.e. player not connected). +/** + * a_npc + * This will send a player text by the bot, just like using SendPlayerMessageToAll, + * but this function is to be used inside the NPC scripts. + * The text to be sent by the NPC + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native SendChat(const message[]); + +/** + * a_npc + * This will force the NPC to write a desired command, and this way, getting the effects it + * would produce. + * The command text to be sent by the NPC + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native SendCommand(const command[]); + +/** + * a_npc + * Get a player's current state. + * The ID of the player to get the current state of + * + * + * + * + * States:
+ *
    + *
  • PLAYER_STATE_NONE - empty (while initializing)
    • + *
  • PLAYER_STATE_ONFOOT - player is on foot
    • + *
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • + *
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • + *
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • + *
  • PLAYER_STATE_SPAWNED - player is spawned
    • + *
  • PLAYER_STATE_SPECTATING - player is spectating
    • + *
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger + *
    • + *
+ * + * The player's current state as an integer. + */ +native PLAYER_STATE:GetPlayerState(playerid); + +/** + * a_npc + * Get the position of a player, represented by x, y and z coordinates. + * The ID of the player to get the position of + * A float variable in which to store the x coordinate in, passed by reference + * A float variable in which to store the y coordinate in, passed by reference + * A float variable in which to store the z coordinate in, passed by reference + * + * + * + * + * This function is known to return unreliable values when used in OnPlayerDisconnect + * and OnPlayerRequestClass. This is because the player is not + * spawned. + * true on success, false on failure (i.e. player not connected). + */ native GetPlayerPos(playerid, &Float:x, &Float:y, &Float:z); -/// This function gets the ID of the vehicle the player is currently in. Note: NOT the model id of the vehicle. See GetVehicleModel for that. -/// The ID of the player in the vehicle that you want to get the ID of -/// -/// -/// -/// -/// ID of the vehicle or 0 if not in a vehicle. +/** + * a_npc + * This function gets the ID of the vehicle the player is currently in. Note: NOT the + * model ID of the vehicle. See GetVehicleModel for that. + * The ID of the player in the vehicle that you want to get the ID of + * + * + * + * + * ID of the vehicle or 0 if not in a vehicle. + */ native GetPlayerVehicleID(playerid); -native GetPlayerArmedWeapon(playerid); +/** + * a_npc + */ +native WEAPON:GetPlayerArmedWeapon(playerid); + +/** + * a_npc + */ native GetPlayerHealth(playerid); + +/** + * a_npc + */ native GetPlayerArmour(playerid); -/// Retrieves a player's current special action. -/// The ID of the player to get the special action of -/// -/// -/// The special action of the player. -native GetPlayerSpecialAction(playerid); - -/// Checks if a player is streamed in for an NPC. Only nearby players are streamed in. -/// The ID of the player to check -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the player is streamed in, 0 if not. -native IsPlayerStreamedIn(playerid); - -/// Checks if a vehicle is streamed in for an NPC. Only nearby vehicles are streamed in. -/// The ID of the vehicle to check -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the vehicle is streamed in, 0 if not. -native IsVehicleStreamedIn(vehicleid); - -/// Check which keys a player is pressing. -/// The ID of the player to get the keys of -/// Bitmask containing the player's key states. List of keys -/// Up/down state -/// Left/right state -/// -/// Only the FUNCTION of keys can be detected; not actual keys. For example, it is not possible to detect if a player presses SPACE, but you can detect if they press SPRINT (which can be mapped (assigned/binded) to ANY key (but is space by default)). -/// As of update 0.3.7, the keys "A" and "D" are not recognized when in a vehicle. However, keys "W" and "S" can be detected with the "keys" parameter. -/// The keys are stored in the specified variables. -native GetPlayerKeys(playerid, &keys, &updown, &leftright); - -/// Gets the angle a player is facing. -/// The player you want to get the angle of -/// The Float to store the angle in, passed by reference -/// Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do 360 - angle. -/// Angles returned when inside a vehicle is rarely correct. To get the correct facing angle while inside a vehicle, use GetVehicleZAngle. +/** + * a_npc + * Retrieves a player's current special + * action. + * The ID of the player to get the special + * action of + * + * + * The special action of the player. + */ +native SPECIAL_ACTION:GetPlayerSpecialAction(playerid); + +/** + * a_npc + * Checks if a player is streamed in for an NPC. Only nearby players are streamed in. + * The ID of the player to check + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the player is streamed in, 0 if not. + */ +native bool:IsPlayerStreamedIn(playerid); + +/** + * a_npc + * Checks if a vehicle is streamed in for an NPC. Only nearby vehicles are streamed in. + * The ID of the vehicle to check + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the vehicle is streamed in, 0 if not. + */ +native bool:IsVehicleStreamedIn(vehicleid); + +/** + * a_npc + * Check which keys a player is pressing. + * The ID of the player to get the keys of + * Bitmask containing the player's key states. List + * of keys + * Up/down state + * Left/right state + * + * Only the FUNCTION of keys can be detected; not actual keys. For example, it is not possible + * to detect if a player presses SPACE, but you can detect if they press SPRINT (which + * can be mapped (assigned/binded) to ANY key (but is space by default)). + * As of update 0.3.7, the keys "A" and "D" are not recognized when in a vehicle. However, + * keys "W" and "S" can be detected with the "keys" parameter. + * The keys are stored in the specified variables. + */ +native GetPlayerKeys(playerid, &KEY:keys, &KEY:updown, &KEY:leftright); + +/** + * a_npc + * Gets the angle a player is facing. + * The player you want to get the angle of + * The Float to store the angle in, passed by reference + * Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA + * 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do + * 360 - angle. + * Angles returned when inside a vehicle is rarely correct. To get the correct facing angle + * while inside a vehicle, use GetVehicleZAngle. + */ native GetPlayerFacingAngle(playerid, &Float:ang); -/// Get the current location of the NPC. -/// A float to save the X coordinate, passed by reference -/// A float to save the Y coordinate, passed by reference -/// A float to save the Z coordinate, passed by reference -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_npc + * Get the current location of the NPC. + * A float to save the x coordinate, passed by reference + * A float to save the y coordinate, passed by reference + * A float to save the z coordinate, passed by reference + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + */ native GetMyPos(&Float:x, &Float:y, &Float:z); -/// Set the position of the NPC. -/// The X coordinate to put the NPC at -/// The Y coordinate to put the NPC at -/// The Z coordinate to put the NPC at -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_npc + * Set the position of the NPC. + * The x coordinate to put the NPC at + * The y coordinate to put the NPC at + * The z coordinate to put the NPC at + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + */ native SetMyPos(Float:x, Float:y, Float:z); -/// Get the current facing angle of the NPC. -/// A float to save the angle in, passed by reference -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// The facing angle is stored in the specified variable. +/** + * a_npc + * Get the current facing angle of the NPC. + * A float to save the angle in, passed by reference + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * The facing angle is stored in the specified variable. + */ native GetMyFacingAngle(&Float:ang); -/// Set the NPC's facing angle. -/// The new NPC's facing angle -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This function does not return any specific values. +/** + * a_npc + * Set the NPC's facing angle. + * The new NPC's facing angle + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This function does not return any specific values. + */ native SetMyFacingAngle(Float:ang); - -/// Get the distance between the NPC and a point. -/// The X coordinate of the point -/// The Y coordinate of the point -/// The Z coordinate of the point -/// A float to save the distance in, passed by reference -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This function does not return any specific values. -native GetDistanceFromMeToPoint(Float:X, Float:Y, Float:Z, &Float:Distance); - -/// Checks if a player is in range of a point. This native function is faster than the PAWN implementation using distance formula. -/// The ID of the player -/// The furthest distance the player can be from the point to be in range -/// The X coordinate of the point to check the range to -/// The Y coordinate of the point to check the range to -/// The Z coordinate of the point to check the range to -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the player is in range, 0 if not. -native IsPlayerInRangeOfPoint(playerid, Float:range, Float:X, Float:Y, Float:Z); - -/// Get a player's name. -/// The ID of the player to get the name of -/// An array into which to store the name, passed by reference -/// The length of the string that should be stored. Recommended to be MAX_PLAYER_NAME -/// -/// -/// -/// -/// -/// A player's name can be up to 24 characters long (as of 0.3d R2) by using SetPlayerName. This is defined in a_samp.inc as MAX_PLAYER_NAME. However, the client can only join with a nickname between 3 and 20 characters, otherwise the connection will be rejected and the player has to quit to choose a valid name. -/// The length of the player's name. 0 if player specified doesn't exist. -native GetPlayerName(playerid, name[], len = sizeof name); - -/// Checks if a player is connected (if an ID is taken by a connected player). -/// The ID of the player to check -/// -/// -/// -/// This function can be omitted in a lot of cases. Many other functions already have some sort of connection check built in. -/// 1 if the player is connected, 0 if not. -native IsPlayerConnected(playerid); - -/// This will run a .rec file which has to be saved in the npcmodes/recordings folder. These files allow the NPC to follow certain actions. Their actions can be recorded manually. For more information, check the related functions. -/// The type of recording to be loaded -/// The filename to be loaded, without the .rec extension -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! -native StartRecordingPlayback(playbacktype, const recordname[]); - -/// This will stop the current .rec file which is being ran by the NPC, making it stay idle until some other order is given. -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_npc + * Get the distance between the NPC and a point. + * The x coordinate of the point + * The y coordinate of the point + * The z coordinate of the point + * A float to save the distance in, passed by reference + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This function does not return any specific values. + */ +native GetDistanceFromMeToPoint(Float:x, Float:y, Float:z, &Float:distance); + +/** + * a_npc + * Checks if a player is in range of a point. This native function is faster than the PAWN + * implementation using distance formula. + * The ID of the player + * The furthest distance the player can be from the point to be in range + * The x coordinate of the point to check the range to + * The y coordinate of the point to check the range to + * The z coordinate of the point to check the range to + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the player is in range, 0 if not. + */ +native bool:IsPlayerInRangeOfPoint(playerid, Float:range, Float:x, Float:y, Float:z); + +/** + * a_npc + * Get a player's name. + * The ID of the player to get the name of + * An array into which to store the name, passed by reference + * The length of the string that should be stored. Recommended to be MAX_PLAYER_NAME + * + * + * + * + * + * A player's name can be up to 24 characters long (as of 0.3d R2) by using SetPlayerName. + * This is defined in a_npc.inc as MAX_PLAYER_NAME. However, the client can + * only join with a nickname between 3 and 20 characters, otherwise the connection will be rejected + * and the player has to quit to choose a valid name. + * The length of the player's name. 0 if player specified doesn't exist. + */ +native GetPlayerName(playerid, name[], len = sizeof (name)); + +/** + * a_npc + * Checks if a player is connected (if an ID is taken by a connected player). + * The ID of the player to check + * + * + * + * This function can be omitted in a lot of cases. Many other functions already have some + * sort of connection check built in. + * 1 if the player is connected, 0 if not. + */ +native bool:IsPlayerConnected(playerid); + +/** + * a_npc + * This will run a .rec file which has to be saved in the npcmodes/recordings folder. These + * files allow the NPC to follow certain actions. Their actions can be recorded manually. For more + * information, check the related functions. + * The type of recording to be loaded + * The filename to be loaded, without the .rec extension + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native StartRecordingPlayback(PLAYER_RECORDING_TYPE:playbackType, const recordFile[]); + +/** + * a_npc + * This will stop the current .rec file which is being ran by the NPC, making it stay idle + * until some other order is given. + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ native StopRecordingPlayback(); -/// This will pause playing back the recording. -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_npc + * This will pause playing back the recording. + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ native PauseRecordingPlayback(); -/// This will resume the paused recording. -/// -/// This NPC function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_npc + * This will resume the paused recording. + * + * This NPC function was added in SA-MP 0.3a and will not work in earlier versions! + */ native ResumeRecordingPlayback(); // -------------------------------------------------- // Forwards (Callback declarations) // -------------------------------------------------- - -/// Gets called when a NPC script is loaded. -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC script is loaded. + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCModeInit(); -/// Gets called when a NPC-script unloaded. -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC-script unloaded. + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCModeExit(); -/// Gets called when a NPC successfully connects to the server. -/// The playerid the NPC has been given -/// -/// -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC successfully connects to the server. + * The playerid the NPC has been given + * + * + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCConnect(myplayerid); -/// Gets called when the NPC gets disconnected from the server. -/// The reason why the bot has disconnected from the server -/// -/// -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when the NPC gets disconnected from the server. + * The reason why the bot has disconnected from the server + * + * + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCDisconnect(reason[]); -/// Gets called when a NPC spawned. -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC spawned. + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCSpawn(); -/// Gets called when a NPC enters a vehicle. -/// The vehicleid from the Vehicle the NPC enters -/// The seatid the NPC uses -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC enters a vehicle. + * The vehicleid from the Vehicle the NPC enters + * The seatid the NPC uses + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCEnterVehicle(vehicleid, seatid); -/// Gets called when a NPC leaves a vehicle. -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Gets called when a NPC leaves a vehicle. + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnNPCExitVehicle(); -/// This callback gets called whenever the NPC sees a ClientMessage. This will be everytime a SendClientMessageToAll function is used and everytime a SendClientMessage function is sent towards the NPC. This callback won't be called when someone says something. For a version of this with player text, see OnPlayerText. -/// The color the ClientMessage is -/// The actual message -/// -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback gets called whenever the NPC sees a ClientMessage. This will be everytime + * a SendClientMessageToAll function is used and everytime a SendClientMessage function is sent towards the NPC. This callback + * won't be called when someone says something. For a version of this with player text, see + * OnPlayerText. + * The colour the ClientMessage is + * The actual message + * + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnClientMessage(color, text[]); -/// Just as the player version of the callback, this callback is called when any player dies. -/// The player who has died -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Just as the player version of the callback, this callback is called when any player dies. + * The player who has died + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnPlayerDeath(playerid); -/// Opposed to the player version of this callback, this callback is called everytime anyone says anything in the chat. This includes any player, any other NPC, or the same NPC himself. -/// The player who has written something in the chat -/// The text written by playerid -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * Opposed to the player version of this callback, this callback is called everytime anyone + * says anything in the chat. This includes any player, any other NPC, or the same NPC himself. + * The player who has written something in the chat + * The text written by playerid + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnPlayerText(playerid, text[]); -/// This callback is called when a player is streamed in for an NPC. Only nearby players are streamed in. -/// The ID of the player that is now streamed in for the NPC -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback is called when a player is streamed in for an NPC. Only nearby players are + * streamed in. + * The ID of the player that is now streamed in for the NPC + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnPlayerStreamIn(playerid); -/// This callback is called when a player is streamed out the NPC. -/// The player who has been destreamed -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback is called when a player is streamed out the NPC. + * The player who has been destreamed + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnPlayerStreamOut(playerid); -/// This callback is called when a vehicle is streamed by the NPC. A simpler definition would be when the NPC sees the grey vehicle icon appear on his map. -/// The vehicle that has been streamed -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback is called when a vehicle is streamed by the NPC. A simpler definition would + * be when the NPC sees the grey vehicle icon appear on his map. + * The vehicle that has been streamed + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnVehicleStreamIn(vehicleid); -/// This callback is called when a vehicle is streamed out for an NPC. -/// The vehicle that was streamed out -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback is called when a vehicle is streamed out for an NPC. + * The vehicle that was streamed out + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnVehicleStreamOut(vehicleid); -/// This callback is called when a recorded file being reproduced with StartRecordingPlayback has reached to its end. -/// This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! +/** + * This callback is called when a recorded file being reproduced with StartRecordingPlayback + * has reached to its end. + * This NPC callback was added in SA-MP 0.3a and will not work in earlier versions! + */ forward OnRecordingPlaybackEnd(); -// -------------------------------------------------- - diff --git a/a_objects.inc b/a_objects.inc old mode 100755 new mode 100644 index 7e1e529..df1bf62 --- a/a_objects.inc +++ b/a_objects.inc @@ -1,643 +1,1003 @@ -/* SA-MP Object Functions - * - * (c) Copyright 2005-2015, SA-MP Team - * - */ - #if defined _INC_a_objects #endinput #endif #define _INC_a_objects #define _objects_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2005-2015, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +///

// -------------------------------------------------- // Defines // -------------------------------------------------- -#define OBJECT_MATERIAL_SIZE_32x32 (10) -#define OBJECT_MATERIAL_SIZE_64x32 (20) -#define OBJECT_MATERIAL_SIZE_64x64 (30) -#define OBJECT_MATERIAL_SIZE_128x32 (40) -#define OBJECT_MATERIAL_SIZE_128x64 (50) -#define OBJECT_MATERIAL_SIZE_128x128 (60) -#define OBJECT_MATERIAL_SIZE_256x32 (70) -#define OBJECT_MATERIAL_SIZE_256x64 (80) -#define OBJECT_MATERIAL_SIZE_256x128 (90) -#define OBJECT_MATERIAL_SIZE_256x256 (100) -#define OBJECT_MATERIAL_SIZE_512x64 (110) -#define OBJECT_MATERIAL_SIZE_512x128 (120) -#define OBJECT_MATERIAL_SIZE_512x256 (130) -#define OBJECT_MATERIAL_SIZE_512x512 (140) - -#define OBJECT_MATERIAL_TEXT_ALIGN_LEFT (0) -#define OBJECT_MATERIAL_TEXT_ALIGN_CENTER (1) -#define OBJECT_MATERIAL_TEXT_ALIGN_RIGHT (2) +// Limits +/** + * a_objects + */ +#if defined MAX_OBJECTS + const __MAX_OBJECTS = MAX_OBJECTS; + #define __MAX_OBJECTS +#else + const MAX_OBJECTS = 2000; + #define MAX_OBJECTS 2000 +#endif + +// Invalids +/** + * a_objects + */ +const INVALID_OBJECT_ID = 0xFFFF; +#define INVALID_OBJECT_ID 0xFFFF + +// Checks +#if MAX_OBJECTS < 1 || MAX_OBJECTS > 2000 + #error MAX_OBJECTS must be >= 1 and <= 2000 +#endif + +// Enums +///

+ +/** + * a_objects + */ +#define SELECT_OBJECT: __TAG(SELECT_OBJECT): +enum SELECT_OBJECT:__SELECT_OBJECT +{ + SELECT_OBJECT_GLOBAL_OBJECT = 1, + SELECT_OBJECT_PLAYER_OBJECT +} +static stock SELECT_OBJECT:_@SELECT_OBJECT() { return __SELECT_OBJECT; } + +///

+ +/** + * a_objects + */ +#define OBJECT_MATERIAL_SIZE: __TAG(OBJECT_MATERIAL_SIZE): +enum OBJECT_MATERIAL_SIZE:__OBJECT_MATERIAL_SIZE (+= 10) +{ + OBJECT_MATERIAL_SIZE_32x32 = 10, + OBJECT_MATERIAL_SIZE_64x32, + OBJECT_MATERIAL_SIZE_64x64, + OBJECT_MATERIAL_SIZE_128x32, + OBJECT_MATERIAL_SIZE_128x64, + OBJECT_MATERIAL_SIZE_128x128, + OBJECT_MATERIAL_SIZE_256x32, + OBJECT_MATERIAL_SIZE_256x64, + OBJECT_MATERIAL_SIZE_256x128, + OBJECT_MATERIAL_SIZE_256x256, + OBJECT_MATERIAL_SIZE_512x64, + OBJECT_MATERIAL_SIZE_512x128, + OBJECT_MATERIAL_SIZE_512x256, + OBJECT_MATERIAL_SIZE_512x512 +} +static stock OBJECT_MATERIAL_SIZE:_@OBJECT_MATERIAL_SIZE() { return __OBJECT_MATERIAL_SIZE; } + +///

+ +/** + * a_objects + */ +#define OBJECT_MATERIAL_TEXT_ALIGN: __TAG(OBJECT_MATERIAL_TEXT_ALIGN): +enum OBJECT_MATERIAL_TEXT_ALIGN:__OBJECT_MATERIAL_TEXT_ALIGN +{ + OBJECT_MATERIAL_TEXT_ALIGN_LEFT, + OBJECT_MATERIAL_TEXT_ALIGN_CENT, + OBJECT_MATERIAL_TEXT_ALIGN_RIGT +} +static stock OBJECT_MATERIAL_TEXT_ALIGN:_@OBJECT_MATERIAL_TEXT_ALIGN() { return __OBJECT_MATERIAL_TEXT_ALIGN; } + +#define OBJECT_MATERIAL_TEXT_ALIGN_CENTER OBJECT_MATERIAL_TEXT_ALIGN_CENT +#define OBJECT_MATERIAL_TEXT_ALIGN_RIGHT OBJECT_MATERIAL_TEXT_ALIGN_RIGT // Objects -///

Creates an object at specified coordinates in the game world. -/// The model to create -/// The X coordinate to create the object at -/// The Y coordinate to create the object at -/// The Z coordinate to create the object at -/// The X rotation of the object -/// The Y rotation of the object -/// The Z rotation of the object -/// The distance that San Andreas renders objects at. 0.0 will cause objects to render at their default distances. Usable since 0.3b, limited to 300 prior to 0.3x (optional=0.0) -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// Objects that emit light (lampposts, police lights, bollard lights, neons etc.) that have a greater rotation than 16.26 degrees (or -16.26) on either the X or Y axis will stop shining. This effect also applies to light objects attached to other objects, players and vehicles. -/// If a light object is attached to a car and the car is rotated over 16.26 degrees (like in a rollover), the object will also stop emitting light. This is a GTA:SA issue and is not caused by a bug in SA-MP. -/// -/// In case the light is attached to another object, one fix for this is to set SyncRotation to false in AttachObjectToObject. This will ensure the light stays at 0 rotation. This would only really work for objects that consist ONLY of light, so wouldn't work for the police light for example. -/// There is a limit of 1000 objects (MAX_OBJECTS). To circumvent this limit, you can use a streamer -/// The ID of the object that was created, or INVALID_OBJECT_ID if the object limit (MAX_OBJECTS) was reached. -native CreateObject(modelid, Float:X, Float:Y, Float:Z, Float:rX, Float:rY, Float:rZ, Float:DrawDistance = 0.0); - -/// Attach an object to a vehicle. -/// The ID of the object to attach to the vehicle. Note that this is an object ID, not a model ID. The object must be CreateObject created first -/// The ID of the vehicle to attach the object to -/// The X axis offset from the vehicle to attach the object to -/// The Y axis offset from the vehicle to attach the object to -/// The Z axis offset from the vehicle to attach the object to -/// The X rotation offset for the object -/// The Y rotation offset for the object -/// The Z rotation offset for the object -/// -/// -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// The object must be created first. -/// When the vehicle is destroyed or respawned, the attached objects won't be destroyed with it; they will remain stationary at the position the vehicle disappeared and be reattached to the next vehicle to claim the vehicle ID that the objects were attached to. -native AttachObjectToVehicle(objectid, vehicleid, Float:OffsetX, Float:OffsetY, Float:OffsetZ, Float:RotX, Float:RotY, Float:RotZ); - -/// You can use this function to attach objects to other objects. The objects will folow the main object. -/// The object to attach to another object -/// The object to attach the object to -/// The distance between the main object and the object in the X direction -/// The distance between the main object and the object in the Y direction -/// The distance between the main object and the object in the Z direction -/// The X rotation between the object and the main object -/// The Y rotation between the object and the main object -/// The Z rotation between the object and the main object -/// If set to 0, objectid's rotation will not change with 's (optional=1) -/// -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// -///
    -///
  • Both objects need to be created before attempting to attach them.
    • -///
  • There is no player-object version of this function (AttachPlayerObjectToObject), meaning it will not be supported by streamers.
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the first object () does not exist. There are no internal checks to verify that the second object () exists. -/// -native AttachObjectToObject(objectid, attachtoid, Float:OffsetX, Float:OffsetY, Float:OffsetZ, Float:RotX, Float:RotY, Float:RotZ, SyncRotation = 1); - -///

Attach an object to a player. -/// The ID of the object to attach to the player -/// The ID of the player to attach the object to -/// The distance between the player and the object in the X direction -/// The distance between the player and the object in the Y direction -/// The distance between the player and the object in the Z direction -/// The X rotation between the object and the player -/// The Y rotation between the object and the player -/// The Z rotation between the object and the player -/// -/// -/// -/// -/// -/// This function always returns 0. -native AttachObjectToPlayer(objectid, playerid, Float:OffsetX, Float:OffsetY, Float:OffsetZ, Float:RotX, Float:RotY, Float:RotZ); - - -/// Change the position of an object. -/// The ID of the object to set the position of. Returned by CreateObject -/// The X coordinate to position the object at -/// The Y coordinate to position the object at -/// The Z coordinate to position the object at -/// -/// -/// -/// -/// This function always returns 1, even if the object specified does not exist. -native SetObjectPos(objectid, Float:X, Float:Y, Float:Z); - -/// Get the position of an object. -/// The ID of the object to get the position of. -/// A variable in which to store the X coordinate, passed by reference -/// A variable in which to store the Y coordinate, passed by reference -/// A variable in which to store the Z coordinate, passed by reference -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The specified object does not exist. -/// -native GetObjectPos(objectid, &Float:X, &Float:Y, &Float:Z); - -///

Set the rotation of an object on the three axes (X, Y and Z). -/// The ID of the object to set the rotation of -/// The X rotation -/// The Y rotation -/// The Z rotation -/// -/// -/// -/// -/// This function always returns 1, even if the object doesn't exist. -native SetObjectRot(objectid, Float:RotX, Float:RotY, Float:RotZ); - -/// Use this function to get the objects current rotation. The rotation is saved by reference in three RotX/RotY/RotZ variables. -/// The objectid of the object you want to get the rotation from -/// The variable to store the X rotation, passed by reference -/// The variable to store the Y rotation, passed by reference -/// The variable to store the Z rotation, passed by reference -/// -/// -/// -/// -/// The object's rotation is stored in the referenced variables, not in the return value. -native GetObjectRot(objectid, &Float:RotX, &Float:RotY, &Float:RotZ); - -/// Get the model ID of an object. -/// The ID of the object to get the model of -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The model ID of the object. -1 if does not exist. +/** + * a_objects + * Creates an object at specified coordinates in the game world. + * The model to create + * The x coordinate to create the object at + * The y coordinate to create the object at + * The z coordinate to create the object at + * The x rotation of the object + * The y rotation of the object + * The z rotation of the object + * The distance that San Andreas renders objects at. 0.0 will + * cause objects to render at their default distances. Usable since 0.3b, limited to 300 prior + * to 0.3x (optional=0.0) + * + * + * + * + * + * + * + * + * + * + * + * + * Objects that emit light (lampposts, police lights, bollard lights, neons etc.) that have a greater + * rotation than 16.26 degrees (or -16.26) on either the x or y axis will + * stop shining. This effect also applies to light objects attached to other objects, players and vehicles. + * If a light object is attached to a car and the car is rotated over 16.26 degrees + * (like in a rollover), the object will also stop emitting light. This is a GTA:SA issue and is not + * caused by a bug in SA-MP. + * + * In case the light is attached to another object, one fix for this is to set SyncRotation + * to false in AttachObjectToObject. This will ensure the light + * stays at 0 rotation. This would only really work for objects that consist ONLY of + * light, so wouldn't work for the police light for example. + * There is a limit of 1000 objects + * (MAX_OBJECTS). To circumvent this limit, you can use a + * streamer + * The ID of the object that was created, or INVALID_OBJECT_ID if the object + * limit (MAX_OBJECTS) was reached. + */ +native CreateObject(modelid, Float:x, Float:y, Float:z, Float:rotX, Float:rotY, Float:rotZ, Float:drawDistance = 0.0); + +/** + * a_objects + * Attach an object to a vehicle. + * The ID of the object to attach to the vehicle. Note that this is an object + * ID, not a model ID. The object must be CreateObject created first + * The ID of the vehicle to attach the object to + * The x axis offset from the vehicle to attach the object to + * The y axis offset from the vehicle to attach the object to + * The z axis offset from the vehicle to attach the object to + * The x rotation offset for the object + * The y rotation offset for the object + * The z rotation offset for the object + * + * + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * The object must be created first. + * When the vehicle is destroyed or respawned, the attached objects won't be destroyed with + * it; they will remain stationary at the position the vehicle disappeared and be reattached to the + * next vehicle to claim the vehicle ID that the objects were attached to. + */ +native bool:AttachObjectToVehicle(objectid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * You can use this function to attach objects to other objects. The objects will folow the + * main object. + * The object to attach to another object + * The object to attach the object to + * The distance between the main object and the object in the x direction + * The distance between the main object and the object in the y direction + * The distance between the main object and the object in the z direction + * The x rotation between the object and the main object + * The y rotation between the object and the main object + * The z rotation between the object and the main object + * If set to 0, objectid's rotation will not change with 's (optional=1) + * + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * + *
    + *
  • Both objects need to be created before attempting to attach them.
    • + *
  • There is no player-object version of this function (AttachPlayerObjectToObject), meaning + * it will not be supported by streamers.
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the first object () does not exist. There are no internal checks to verify that the second object () exists. + * + */ +native bool:AttachObjectToObject(objectid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ, Float:rotX, Float:rotY, Float:rotZ, bool:syncRotation = true); + +/** + * a_objects + * Attach an object to a player. + * The ID of the object to attach to the player + * The ID of the player to attach the object to + * The distance between the player and the object in the x direction + * The distance between the player and the object in the y direction + * The distance between the player and the object in the z direction + * The x rotation between the object and the player + * The y rotation between the object and the player + * The z rotation between the object and the player + * + * + * + * + * + * This function always returns 0. + */ +native void:AttachObjectToPlayer(objectid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * Change the position of an object. + * The ID of the object to set the position of. Returned by CreateObject + * The x coordinate to position the object at + * The y coordinate to position the object at + * The z coordinate to position the object at + * + * + * + * + * This function always returns 1, even if the object specified does not exist. + */ +native SetObjectPos(objectid, Float:x, Float:y, Float:z); + +/** + * a_objects + * Get the position of an object. + * The ID of the object to get the position of. + * A variable in which to store the x coordinate, passed by reference + * A variable in which to store the y coordinate, passed by reference + * A variable in which to store the z coordinate, passed by reference + * + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The specified object does not exist. + * + */ +native GetObjectPos(objectid, &Float:x, &Float:y, &Float:z); + +/** + * a_objects + * Set the rotation of an object on the three axes (x, y and z). + * The ID of the object to set the rotation of + * The x rotation + * The y rotation + * The z rotation + * + * + * + * + * This function always returns 1, even if the object doesn't exist. + */ +native SetObjectRot(objectid, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * Use this function to get the objects current rotation. The rotation is saved by reference + * in three rotX/rotY/rotZ variables. + * The objectid of the object you want to get the rotation from + * The variable to store the x rotation, passed by reference + * The variable to store the y rotation, passed by reference + * The variable to store the z rotation, passed by reference + * + * + * + * + * The object's rotation is stored in the referenced variables, not in the return value. + */ +native GetObjectRot(objectid, &Float:rotX, &Float:rotY, &Float:rotZ); + +/** + * a_objects + * Get the model ID of an object. + * The ID of the object to get the model of + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The model ID of the object. -1 if does not exist. + */ native GetObjectModel(objectid); -/// Disable collisions between players' cameras and the specified object. -/// The ID of the object to disable camera collisions on -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This only works outside the map boundaries (past -3000/3000 units on the x and/or y axis). -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The object specified does not exist. -/// +/** + * a_objects + *

Disable collisions between players' cameras and the specified object. + * The ID of the object to disable camera collisions on + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This only works outside the map boundaries (past -3000/3000 + * units on the x and/or y axis). + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The object specified does not exist. + * + */ native SetObjectNoCameraCol(objectid); -/// Checks if an object with the ID provided exists. -/// The ID of the object to check the existence of -/// -/// -/// -/// This is to check if an object exists, not if a model is valid. -/// 1 if the object exists, 0 if not. -native IsValidObject(objectid); - -/// Destroys (removes) an object that was created using CreateObject. -/// The ID of the object to destroy. Returned by CreateObject -/// -/// -/// +/** + * a_objects + * Checks if an object with the ID provided exists. + * The ID of the object to check the existence of + * + * + * + * This is to check if an object exists, not if a model is valid. + * 1 if the object exists, 0 if not. + */ +native bool:IsValidObject(objectid); + +/** + * a_objects + * Destroys (removes) an object that was created using CreateObject. + * The ID of the object to destroy. Returned by CreateObject + * + * + * + */ native DestroyObject(objectid); -/// Move an object to a new position with a set speed. Players/vehicles will 'surf' the object as it moves. -/// The ID of the object to move -/// The X coordinate to move the object to -/// The Y coordinate to move the object to -/// The Z coordinate to move the object to -/// The speed at which to move the object (units per second) -/// The FINAL X rotation (optional=-1000.0) -/// The FINAL Y rotation (optional=-1000.0) -/// The FINAL Z rotation (optional=-1000.0) -/// -/// -/// -/// -/// -/// -/// -/// This function can be used to make objects rotate smoothly. In order to achieve this however, the object must also be moved. The specified rotation is the rotation the object will have after the movement. Hence the object will not rotate when no movement is applied. For a script example take a look at the ferriswheel.pwn filterscript made by Kye included in the server package (SA-MP 0.3d and above). -/// To fully understand the above note, you can (but not limited to) increase the z position by (+0.001) and then (-0.001) after moving it again, as not changing the X, Y or Z will not rotate the object. -/// The time it will take for the object to move in milliseconds. -native MoveObject(objectid, Float:X, Float:Y, Float:Z, Float:Speed, Float:RotX = -1000.0, Float:RotY = -1000.0, Float:RotZ = -1000.0); - -/// Stop a moving object after MoveObject has been used. -/// The ID of the object to stop moving -/// -/// -/// -/// +/** + * a_objects + * Move an object to a new position with a set speed. Players/vehicles will 'surf' the object + * as it moves. + * The ID of the object to move + * The x coordinate to move the object to + * The y coordinate to move the object to + * The z coordinate to move the object to + * The speed at which to move the object (units per second) + * The FINAL x rotation (optional=-1000.0) + * The FINAL y rotation (optional=-1000.0) + * The FINAL z rotation (optional=-1000.0) + * + * + * + * + * + * + * + * This function can be used to make objects rotate smoothly. In order to achieve this however, + * the object must also be moved. The specified rotation is the rotation the object will have + * after the movement. Hence the object will not rotate when no movement is applied. For a script + * example take a look at the ferriswheel.pwn filterscript made by Kye included in the server package + * (SA-MP 0.3d and above). + * To fully understand the above note, you can (but not limited to) increase the z position + * by (+0.001) and then (-0.001) after moving it again, as not changing + * the x, y or z will not rotate the object. + * The time it will take for the object to move in milliseconds. + */ +native MoveObject(objectid, Float:x, Float:y, Float:z, Float:speed, Float:rotX = -1000.0, Float:rotY = -1000.0, Float:rotZ = -1000.0); + +/** + * a_objects + * Stop a moving object after MoveObject has been used. + * The ID of the object to stop moving + * + * + * + * + */ native StopObject(objectid); -/// Checks if the given objectid is moving. -/// The objectid you want to check if is moving -/// -/// -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// 1 if the object is moving, 0 if not. -native IsObjectMoving(objectid); - -/// Allows a player to edit an object (position and rotation) using their mouse on a GUI (Graphical User Interface). -/// The ID of the player that should edit the object -/// The ID of the object to be edited by the player -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// You can move the camera while editing by pressing and holding the spacebar (or W in vehicle) and moving your mouse. -/// -/// 1: The function executed successfully. Success is reported when a non-existent object is specified, but nothing will happen.

-/// 0: The function failed to execute. The player is not connected. -/// +/** + * a_objects + *

Checks if the given objectid is moving. + * The objectid you want to check if is moving + * + * + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * 1 if the object is moving, 0 if not. + */ +native bool:IsObjectMoving(objectid); + +/** + * a_objects + * Allows a player to edit an object (position and rotation) using their mouse on a GUI (Graphical + * User Interface). + * The ID of the player that should edit the object + * The ID of the object to be edited by the player + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * You can move the camera while editing by pressing and holding the spacebar (or W + * in vehicle) and moving your mouse. + * + * 1: The function executed successfully. Success is reported when a non-existent object + * is specified, but nothing will happen.
+ * 0: The function failed to execute. The player is not connected. + * + */ native EditObject(playerid, objectid); -/// Allows players to edit a player-object (position and rotation) with a GUI and their mouse. -/// The ID of the player that should edit the object -/// The object to be edited by the player -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// You can move the camera while editing by pressing and holding the spacebar (or W in vehicle) and moving your mouse. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Player or object not valid. -/// +/** + * a_objects + *

Allows players to edit a player-object (position and rotation) with a GUI and their mouse. + * The ID of the player that should edit the object + * The object to be edited by the player + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * You can move the camera while editing by pressing and holding the spacebar (or W + * in vehicle) and moving your mouse. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Player or object not valid. + * + */ native EditPlayerObject(playerid, objectid); -/// Display the cursor and allow the player to select an object. OnPlayerSelectObject is called when the player selects an object. -/// The ID of the player that should be able to select the object -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_objects + * Display the cursor and allow the player to select an object. OnPlayerSelectObject + * is called when the player selects an object. + * The ID of the player that should be able to select the object + * + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + */ native SelectObject(playerid); -/// Cancel object edition mode for a player. -/// The ID of the player to cancel edition for -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_objects + * Cancel object edition mode for a player. + * The ID of the player to cancel edition for + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + */ native CancelEdit(playerid); -/// Creates an object which will be visible to only one player. -/// The ID of the player to create the object for -/// The model to create -/// The X coordinate to create the object at -/// The Y coordinate to create the object at -/// The Z coordinate to create the object at -/// The X rotation of the object -/// The Y rotation of the object -/// The Z rotation of the object -/// The distance from which objects will appear to players. 0.0 will cause an object to render at its default distance. Leaving this parameter out will cause objects to be rendered at their default distance. The maximum usable distance is 300 in versions prior to 0.3x, in which drawdistance can be unlimited (optional=0.0) -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// The 'DrawDistance' parameter was added in 0.3b. It must be left out in scripts for older versions of SA:MP. -/// The ID of the object that was created, or INVALID_OBJECT_ID if the object limit (MAX_OBJECTS) was reached. -native CreatePlayerObject(playerid, modelid, Float:X, Float:Y, Float:Z, Float:rX, Float:rY, Float:rZ, Float:DrawDistance = 0.0); - -/// Attach a player object to a vehicle. -/// The ID of the player the object was created for -/// The ID of the object to attach to the vehicle -/// The ID of the vehicle to attach the object to -/// The X position offset for attachment -/// The Y position offset for attachment -/// The Z position offset for attachment -/// The X rotation offset for attachment -/// The Y rotation offset for attachment -/// The Z rotation offset for attachment -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// You need to create the object before attempting to attach it to a vehicle. -native AttachPlayerObjectToVehicle(playerid, objectid, vehicleid, Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ, Float:fRotX, Float:fRotY, Float:RotZ); - - -/// Sets the position of a player-object to the specified coordinates. -/// The ID of the player whose player-object to set the position of -/// The ID of the player-object to set the position of. Returned by CreatePlayerObject -/// The X coordinate to put the object at -/// The Y coordinate to put the object at -/// The Z coordinate to put the object at -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Player and/or object do not exist. -/// -native SetPlayerObjectPos(playerid, objectid, Float:X, Float:Y, Float:Z); - -///

Get the position of a player object (CreatePlayerObject). -/// The ID of the player whose player object to get the position of -/// The object's id of which you want the current location -/// A float variable in which to store the X coordinate, passed by reference -/// A float variable in which to store the Y coordinate, passed by reference -/// A float variable in which to store the Z coordinate, passed by reference -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player and/or the object don't exist.

-/// The object's position is stored in the specified variables. -/// -native GetPlayerObjectPos(playerid, objectid, &Float:X, &Float:Y, &Float:Z); - -///

Set the rotation of an object on the X, Y and Z axis. -/// The ID of the player whose player-object to rotate -/// The ID of the player-object to rotate -/// The X rotation to set -/// The Y rotation to set -/// The Z rotation to set -/// -/// -/// -/// -/// To smoothly rotate an object, see MovePlayerObject. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// -native SetPlayerObjectRot(playerid, objectid, Float:RotX, Float:RotY, Float:RotZ); - -///

Use this function to get the object's current rotation. The rotation is saved by reference in three RotX/RotY/RotZ variables. -/// The player you associated this object to -/// The objectid of the object you want to get the rotation from -/// The variable to store the X rotation, passed by reference -/// The variable to store the Y rotation, passed by reference -/// The variable to store the Z rotation, passed by reference -/// -/// -/// -/// -/// The object's rotation is stored in the specified variables. -native GetPlayerObjectRot(playerid, objectid, &Float:RotX, &Float:RotY, &Float:RotZ); - -/// Retrieve the model ID of a player-object. -/// The ID of the player whose player-object to get the model of -/// The ID of the player-object of which to retrieve the model ID -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The model ID of the player object. If the player or object don't exist, it will return -1 or 0 if the player or object does not exist. +/** + * a_objects + * Creates an object which will be visible to only one player. + * The ID of the player to create the object for + * The model to create + * The x coordinate to create the object at + * The y coordinate to create the object at + * The z coordinate to create the object at + * The x rotation of the object + * The y rotation of the object + * The z rotation of the object + * The distance from which objects will appear to players. 0.0 + * will cause an object to render at its default distance. Leaving this parameter out will cause objects + * to be rendered at their default distance. The maximum usable distance is 300 in versions + * prior to 0.3x, in which drawdistance can be unlimited (optional=0.0) + * + * + * + * + * + * + * + * + * + * + * + * The 'DrawDistance' parameter was added in 0.3b. It must be left out in scripts for + * older versions of SA:MP. + * The ID of the object that was created, or INVALID_OBJECT_ID if the object + * limit (MAX_OBJECTS) was reached. + */ +native CreatePlayerObject(playerid, modelid, Float:x, Float:y, Float:z, Float:rotX, Float:rotY, Float:rotZ, Float:drawDistance = 0.0); + +/** + * a_objects + * Attach a player object to a vehicle. + * The ID of the player the object was created for + * The ID of the object to attach to the vehicle + * The ID of the vehicle to attach the object to + * The x position offset for attachment + * The y position offset for attachment + * The z position offset for attachment + * The x rotation offset for attachment + * The y rotation offset for attachment + * The z rotation offset for attachment + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * You need to create the object before attempting to attach it to a vehicle. + */ +native AttachPlayerObjectToVehicle(playerid, objectid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * Sets the position of a player-object to the specified coordinates. + * The ID of the player whose player-object to set the position of + * The ID of the player-object to set the position of. Returned by + * CreatePlayerObject + * The x coordinate to put the object at + * The y coordinate to put the object at + * The z coordinate to put the object at + * + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Player and/or object do not exist. + * + */ +native SetPlayerObjectPos(playerid, objectid, Float:x, Float:y, Float:z); + +/** + * a_objects + * Get the position of a player object (CreatePlayerObject). + * The ID of the player whose player object to get the position of + * The object's ID of which you want the current location + * A float variable in which to store the x coordinate, passed by reference + * A float variable in which to store the y coordinate, passed by reference + * A float variable in which to store the z coordinate, passed by reference + * + * + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player and/or the object don't exist.
+ * The object's position is stored in the specified variables. + * + */ +native GetPlayerObjectPos(playerid, objectid, &Float:x, &Float:y, &Float:z); + +/** + * a_objects + * Set the rotation of an object on the x, y and z axis. + * The ID of the player whose player-object to rotate + * The ID of the player-object to rotate + * The x rotation to set + * The y rotation to set + * The z rotation to set + * + * + * + * + * To smoothly rotate an object, see MovePlayerObject. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ +native SetPlayerObjectRot(playerid, objectid, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * Use this function to get the object's current rotation. The rotation is saved by reference + * in three rotX/rotY/rotZ variables. + * The player you associated this object to + * The objectid of the object you want to get the rotation from + * The variable to store the x rotation, passed by reference + * The variable to store the y rotation, passed by reference + * The variable to store the z rotation, passed by reference + * + * + * + * + * The object's rotation is stored in the specified variables. + */ +native GetPlayerObjectRot(playerid, objectid, &Float:rotX, &Float:rotY, &Float:rotZ); + +/** + * a_objects + * Retrieve the model ID of a player-object. + * The ID of the player whose player-object to get the model of + * The ID of the player-object of which to retrieve the model ID + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The model ID of the player object. If the player or object don't exist, it will return + * -1 or 0 if the player or object does not exist. + */ native GetPlayerObjectModel(playerid, objectid); -/// Toggles a player object camera collision. -/// The playerID the object belongs to -/// The ID of the object you want to toggle -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This only works outside the map boundaries (past -3000/3000 units on the x and/or y axis). -/// 1 regardless of if the object exists or not. +/** + * a_objects + * Toggles a player object camera collision. + * The playerid the object belongs to + * The ID of the object you want to toggle + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This only works outside the map boundaries (past -3000/3000 + * units on the x and/or y axis). + * 1 regardless of if the object exists or not. + */ native SetPlayerObjectNoCameraCol(playerid, objectid); -/// Checks if the given object ID is valid for the given player. -/// The ID of the player whose player-object to validate -/// The ID of the object to validate -/// -/// -/// -/// 1 if the object exists, 0 if not. -native IsValidPlayerObject(playerid, objectid); - -/// Destroy a player-object created using CreatePlayerObject. -/// The ID of the player whose player-object to destroy -/// The ID of the player-object to destroy. Returned by CreatePlayerObject -/// -/// -/// +/** + * a_objects + * Checks if the given object ID is valid for the given player. + * The ID of the player whose player-object to validate + * The ID of the object to validate + * + * + * + * 1 if the object exists, 0 if not. + */ +native bool:IsValidPlayerObject(playerid, objectid); + +/** + * a_objects + * Destroy a player-object created using CreatePlayerObject. + * The ID of the player whose player-object to destroy + * The ID of the player-object to destroy. Returned by CreatePlayerObject + * + * + * + */ native DestroyPlayerObject(playerid, objectid); -/// Move a player object with a set speed. Also supports rotation. Players/vehicles will surf moving objects. -/// The ID of the player whose player-object to move -/// The ID of the object to move -/// The X coordinate to move the object to -/// The Y coordinate to move the object to -/// The Z coordinate to move the object to -/// The speed at which to move the object -/// The final X rotation (optional=-1000.0) -/// The final Y rotation (optional=-1000.0) -/// The final Z rotation (optional=-1000.0) -/// -/// -/// -/// -/// -/// -/// -/// 0.3d R2 and older versions do not have the rotational parameters. -/// The time it will take for the object to move in milliseconds. -native MovePlayerObject(playerid, objectid, Float:X, Float:Y, Float:Z, Float:Speed, Float:RotX = -1000.0, Float:RotY = -1000.0, Float:RotZ = -1000.0); - -/// Stop a moving player-object after MovePlayerObject has been used. -/// The ID of the player whose player-object to stop -/// The ID of the player-object to stop -/// -/// -/// -/// +/** + * a_objects + * Move a player object with a set speed. Also supports rotation. Players/vehicles will surf + * moving objects. + * The ID of the player whose player-object to move + * The ID of the object to move + * The x coordinate to move the object to + * The y coordinate to move the object to + * The z coordinate to move the object to + * The speed at which to move the object + * The final x rotation (optional=-1000.0) + * The final y rotation (optional=-1000.0) + * The final z rotation (optional=-1000.0) + * + * + * + * + * + * + * + * 0.3d R2 and older versions do not have the rotational parameters. + * The time it will take for the object to move in milliseconds. + */ +native MovePlayerObject(playerid, objectid, Float:x, Float:y, Float:z, Float:speed, Float:rotX = -1000.0, Float:rotY = -1000.0, Float:rotZ = -1000.0); + +/** + * a_objects + * Stop a moving player-object after MovePlayerObject has been + * used. + * The ID of the player whose player-object to stop + * The ID of the player-object to stop + * + * + * + * + */ native StopPlayerObject(playerid, objectid); -/// Checks if the given player objectid is moving. -/// The ID of the player whose player-object is checked -/// The player objectid you want to check if is moving -/// -/// -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// 1 if the player object is moving, 0 if not. -native IsPlayerObjectMoving(playerid, objectid); - -/// The same as AttachObjectToPlayer but for objects which were created for player. -/// The id of the player which is linked with the object -/// The objectid you want to attach to the player -/// The id of the player you want to attach to the object -/// The distance between the player and the object in the X direction -/// The distance between the player and the object in the Y direction -/// The distance between the player and the object in the Z direction -/// The X rotation -/// The Y rotation -/// The Z rotation -/// -/// -/// -/// -/// This function was removed in SA-MP 0.3. -native AttachPlayerObjectToPlayer(objectplayer, objectid, attachplayer, Float:OffsetX, Float:OffsetY, Float:OffsetZ, Float:rX, Float:rY, Float:rZ); - -/// Replace the texture of an object with the texture from another model in the game. -/// The ID of the object to change the texture of -/// The material index on the object to change (0 to 15) -/// The modelid on which the replacement texture is located. Use 0 for alpha. Use -1 to change the material color without altering the texture -/// The name of the txd file which contains the replacement texture (use "none" if not required) -/// The name of the texture to use as the replacement (use "none" if not required) -/// The object color to set, as an integer or hex in ARGB color format. Using 0 keeps the existing material color (optional=0) -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Vertex lightning of the object will disappear if material color is changed. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// -native SetObjectMaterial(objectid, materialindex, modelid, const txdname[], const texturename[], materialcolor=0); - -///

Replace the texture of a player-object with the texture from another model in the game. -/// The ID of the player the object is associated to -/// The ID of the object to replace the texture of -/// The material index on the object to change (0 to 15) -/// The modelid on which replacement texture is located. Use 0 for alpha. Use -1 to change the material color without altering the existing texture -/// The name of the txd file which contains the replacement texture (use "none" if not required) -/// The name of the texture to use as the replacement (use "none" if not required) -/// The object color to set (ARGB). Using 0 keeps the existing material color (optional=0) -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Vertex lightning of the object will disappear if material color is changed. -native SetPlayerObjectMaterial(playerid, objectid, materialindex, modelid, const txdname[], const texturename[], materialcolor=0); - - -/// Replace the texture of an object with text. -/// The ID of the object to replace the texture of with text -/// The text to show on the object. (MAX 2048 characters) -/// The object's material index to replace with text (optional=0) -/// The size of the material (optional=OBJECT_MATERIAL_SIZE_256x128) -/// The font to use (optional="Arial") -/// The size of the text (MAX 255) (optional=24) -/// Bold text. Set to 1 for bold, 0 for not (optional=1) -/// The color of the text, in ARGB format (optional=-1) -/// The background color, in ARGB format (optional=0) -/// The alignment of the text (optional=OBJECT_MATERIAL_TEXT_ALIGN_LEFT) -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Color embedding can be used for multiple colors in the text. -/// -/// Alignment:

-///

    -///
  • OBJECT_MATERIAL_TEXT_ALIGN_LEFT 0
    • -///
  • OBJECT_MATERIAL_TEXT_ALIGN_CENTER 1
    • -///
  • OBJECT_MATERIAL_TEXT_ALIGN_RIGHT 2
    • -///
-/// -/// -/// Sizes:

-///

    -///
  • OBJECT_MATERIAL_SIZE_32x32 10
    • -///
  • OBJECT_MATERIAL_SIZE_64x32 20
    • -///
  • OBJECT_MATERIAL_SIZE_64x64 30
    • -///
  • OBJECT_MATERIAL_SIZE_128x32 40
    • -///
  • OBJECT_MATERIAL_SIZE_128x64 50
    • -///
  • OBJECT_MATERIAL_SIZE_128x128 60
    • -///
  • OBJECT_MATERIAL_SIZE_256x32 70
    • -///
  • OBJECT_MATERIAL_SIZE_256x64 80
    • -///
  • OBJECT_MATERIAL_SIZE_256x128 90
    • -///
  • OBJECT_MATERIAL_SIZE_256x256 100
    • -///
  • OBJECT_MATERIAL_SIZE_512x64 110
    • -///
  • OBJECT_MATERIAL_SIZE_512x128 120
    • -///
  • OBJECT_MATERIAL_SIZE_512x256 130
    • -///
  • OBJECT_MATERIAL_SIZE_512x512 140
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// -native SetObjectMaterialText(objectid, const text[], materialindex = 0, materialsize = OBJECT_MATERIAL_SIZE_256x128, const fontface[] = "Arial", fontsize = 24, bold = 1, fontcolor = 0xFFFFFFFF, backcolor = 0, textalignment = 0); - -///

Replace the texture of a player object with text. -/// The ID of the player whose player object to set the text of -/// The ID of the object on which to place the text -/// The text to set -/// The material index to replace with text (optional=0) -/// The size of the material (optional=OBJECT_MATERIAL_SIZE_256x128) -/// The font to use (optional="Arial") -/// The size of the text (MAX 255) (optional=24) -/// Bold text. Set to 1 for bold, 0 for not (optional=1) -/// The color of the text (optional=-1) -/// The background color (optional=0) -/// The alignment of the text (optional=OBJECT_MATERIAL_TEXT_ALIGN_LEFT) -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Color embedding can be used for multiple colors in the text. -/// -/// Alignment:

-///

    -///
  • OBJECT_MATERIAL_TEXT_ALIGN_LEFT 0
    • -///
  • OBJECT_MATERIAL_TEXT_ALIGN_CENTER 1
    • -///
  • OBJECT_MATERIAL_TEXT_ALIGN_RIGHT 2
    • -///
-/// -/// -/// Sizes:

-///

    -///
  • OBJECT_MATERIAL_SIZE_32x32 10
    • -///
  • OBJECT_MATERIAL_SIZE_64x32 20
    • -///
  • OBJECT_MATERIAL_SIZE_64x64 30
    • -///
  • OBJECT_MATERIAL_SIZE_128x32 40
    • -///
  • OBJECT_MATERIAL_SIZE_128x64 50
    • -///
  • OBJECT_MATERIAL_SIZE_128x128 60
    • -///
  • OBJECT_MATERIAL_SIZE_256x32 70
    • -///
  • OBJECT_MATERIAL_SIZE_256x64 80
    • -///
  • OBJECT_MATERIAL_SIZE_256x128 90
    • -///
  • OBJECT_MATERIAL_SIZE_256x256 100
    • -///
  • OBJECT_MATERIAL_SIZE_512x64 110
    • -///
  • OBJECT_MATERIAL_SIZE_512x128 120
    • -///
  • OBJECT_MATERIAL_SIZE_512x256 130
    • -///
  • OBJECT_MATERIAL_SIZE_512x512 140
    • -///
-/// -native SetPlayerObjectMaterialText(playerid, objectid, const text[], materialindex = 0, materialsize = OBJECT_MATERIAL_SIZE_256x128, const fontface[] = "Arial", fontsize = 24, bold = 1, fontcolor = 0xFFFFFFFF, backcolor = 0, textalignment = 0); - - -/// Allows camera collisions with newly created objects to be disabled by default. -/// 1 to disable camera collisions for newly created objects and 0 to enable them (enabled by default) -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function only affects the camera collision of objects created AFTER its use - it does not toggle existing objects' camera collisions. -/// This only works outside the map boundaries (past -3000/3000 units on the x and/or y axis). -native SetObjectsDefaultCameraCol(disable); +/** + * a_objects + * Checks if the given player objectid is moving. + * The ID of the player whose player-object is checked + * The player objectid you want to check if is moving + * + * + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * 1 if the player object is moving, 0 if not. + */ +native bool:IsPlayerObjectMoving(playerid, objectid); + +/** + * a_objects + * The same as AttachObjectToPlayer but for objects which were created for player. + * The ID of the player which is linked with the object + * The objectid you want to attach to the player + * The ID of the player you want to attach to the object + * The distance between the player and the object in the x direction + * The distance between the player and the object in the y direction + * The distance between the player and the object in the z direction + * The x rotation + * The y rotation + * The z rotation + * + * + * + * + * This function was removed in SA-MP 0.3. + */ +native AttachPlayerObjectToPlayer(playerid, objectid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ, Float:rotX, Float:rotY, Float:rotZ); + +/** + * a_objects + * Replace the texture of an object with the texture from another model in the game. + * The ID of the object to change the texture of + * The material index on the object to change (0 to 15) + * The modelid on which the replacement texture is located. Use 0 + * for alpha. Use -1 to change the material colour without altering the texture + * The name of the txd file which contains the replacement texture (use + * "none" if not required) + * The name of the texture to use as the replacement (use "none" + * if not required) + * The object colour to set, as an integer or hex in ARGB colour + * format. Using 0 keeps the existing material colour (optional=0) + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Vertex lightning of the object will disappear if material colour is changed. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ +native SetObjectMaterial(objectid, materialIndex, modelid, const textureLibrary[], const textureName[], materialColour = 0); + +/** + * a_objects + * Replace the texture of a player-object with the texture from another model in the game. + * The ID of the player the object is associated to + * The ID of the object to replace the texture of + * The material index on the object to change (0 to 15) + * The modelid on which replacement texture is located. Use 0 for + * alpha. Use -1 to change the material colour without altering the existing texture + * The name of the txd file which contains the replacement texture (use + * "none" if not required) + * The name of the texture to use as the replacement (use "none" + * if not required) + * The object colour to set (ARGB). Using 0 keeps + * the existing material colour (optional=0) + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Vertex lightning of the object will disappear if material colour is changed. + */ +native SetPlayerObjectMaterial(playerid, objectid, materialIndex, modelid, const textureLibrary[], const textureName[], materialColour = 0); + +/** + * a_objects + * Replace the texture of an object with text. + * The ID of the object to replace the texture of with text + * The text to show on the object. (MAX 2048 characters) + * The object's material index to replace with text (optional=0) + * The size of the material (optional=OBJECT_MATERIAL_SIZE_256x128) + * The font to use (optional="Arial") + * The size of the text (MAX 255) (optional=24) + * Bold text. Set to 1 for bold, 0 for not (optional=1) + * The colour of the text, in ARGB format (optional=-1) + * The background colour, in ARGB format (optional=0) + * The alignment of the text (optional=OBJECT_MATERIAL_TEXT_ALIGN_LEFT) + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Color embedding can be used for multiple colours in the text. + * + * Alignment:
+ *
    + *
  • OBJECT_MATERIAL_TEXT_ALIGN_LEFT 0
    • + *
  • OBJECT_MATERIAL_TEXT_ALIGN_CENTER 1
    • + *
  • OBJECT_MATERIAL_TEXT_ALIGN_RIGHT 2
    • + *
+ * + * + * Sizes:
+ *
    + *
  • OBJECT_MATERIAL_SIZE_32x32 10
    • + *
  • OBJECT_MATERIAL_SIZE_64x32 20
    • + *
  • OBJECT_MATERIAL_SIZE_64x64 30
    • + *
  • OBJECT_MATERIAL_SIZE_128x32 40
    • + *
  • OBJECT_MATERIAL_SIZE_128x64 50
    • + *
  • OBJECT_MATERIAL_SIZE_128x128 60
    • + *
  • OBJECT_MATERIAL_SIZE_256x32 70
    • + *
  • OBJECT_MATERIAL_SIZE_256x64 80
    • + *
  • OBJECT_MATERIAL_SIZE_256x128 90
    • + *
  • OBJECT_MATERIAL_SIZE_256x256 100
    • + *
  • OBJECT_MATERIAL_SIZE_512x64 110
    • + *
  • OBJECT_MATERIAL_SIZE_512x128 120
    • + *
  • OBJECT_MATERIAL_SIZE_512x256 130
    • + *
  • OBJECT_MATERIAL_SIZE_512x512 140
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ +native SetObjectMaterialText(objectid, const text[], materialIndex = 0, OBJECT_MATERIAL_SIZE:materialSize = OBJECT_MATERIAL_SIZE_256x128, const fontFace[] = "Arial", fontSize = 24, bool:bold = true, fontColour = 0xFFFFFFFF, backgroundColour = 0, OBJECT_MATERIAL_TEXT_ALIGN:textalignment = OBJECT_MATERIAL_TEXT_ALIGN_LEFT); + +/** + * a_objects + * Replace the texture of a player object with text. + * The ID of the player whose player object to set the text of + * The ID of the object on which to place the text + * The text to set + * The material index to replace with text (optional=0) + * The size of the material (optional=OBJECT_MATERIAL_SIZE_256x128) + * The font to use (optional="Arial") + * The size of the text (MAX 255) (optional=24) + * Bold text. Set to 1 for bold, 0 for not (optional=1) + * The colour of the text (optional=-1) + * The background colour (optional=0) + * The alignment of the text (optional=OBJECT_MATERIAL_TEXT_ALIGN_LEFT) + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Color embedding can be used for multiple colours in the text. + * + * Alignment:
+ *
    + *
  • OBJECT_MATERIAL_TEXT_ALIGN_LEFT 0
    • + *
  • OBJECT_MATERIAL_TEXT_ALIGN_CENTER 1
    • + *
  • OBJECT_MATERIAL_TEXT_ALIGN_RIGHT 2
    • + *
+ * + * + * Sizes:
+ *
    + *
  • OBJECT_MATERIAL_SIZE_32x32 10
    • + *
  • OBJECT_MATERIAL_SIZE_64x32 20
    • + *
  • OBJECT_MATERIAL_SIZE_64x64 30
    • + *
  • OBJECT_MATERIAL_SIZE_128x32 40
    • + *
  • OBJECT_MATERIAL_SIZE_128x64 50
    • + *
  • OBJECT_MATERIAL_SIZE_128x128 60
    • + *
  • OBJECT_MATERIAL_SIZE_256x32 70
    • + *
  • OBJECT_MATERIAL_SIZE_256x64 80
    • + *
  • OBJECT_MATERIAL_SIZE_256x128 90
    • + *
  • OBJECT_MATERIAL_SIZE_256x256 100
    • + *
  • OBJECT_MATERIAL_SIZE_512x64 110
    • + *
  • OBJECT_MATERIAL_SIZE_512x128 120
    • + *
  • OBJECT_MATERIAL_SIZE_512x256 130
    • + *
  • OBJECT_MATERIAL_SIZE_512x512 140
    • + *
+ * + */ +native SetPlayerObjectMaterialText(playerid, objectid, const text[], materialIndex = 0, OBJECT_MATERIAL_SIZE:materialSize = OBJECT_MATERIAL_SIZE_256x128, const fontFace[] = "Arial", fontSize = 24, bool:bold = true, fontColour = 0xFFFFFFFF, backgroundColour = 0, OBJECT_MATERIAL_TEXT_ALIGN:textalignment = OBJECT_MATERIAL_TEXT_ALIGN_LEFT); + +/** + * a_objects + * Allows camera collisions with newly created objects to be disabled by default. + * 1 to disable camera collisions for newly created objects and + * 0 to enable them (enabled by default) + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function only affects the camera collision of objects created AFTER its use - it does + * not toggle existing objects' camera collisions. + * This only works outside the map boundaries (past -3000/3000 + * units on the x and/or y axis). + */ +native SetObjectsDefaultCameraCol(bool:disable); + +/** + * This callback is called when a player selects an object after SelectObject + * has been used. + * The ID of the player that selected an object + * The type of selection + * The ID of the selected object + * The model ID of the selected object + * The X position of the selected object + * The Y position of the selected object + * The Z position of the selected object + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * + * 1 - Will prevent other scripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next script.
+ * It is always called first in filterscripts. + * + */ +#if !defined SELECT_OBJECT + #define SELECT_OBJECT: _: +#endif +forward OnPlayerSelectObject(playerid, SELECT_OBJECT:type, objectid, modelid, Float:fX, Float:fY, Float:fZ); + +/** + * This callback is called when a player finishes editing an object (EditObject/EditPlayerObject). + * The ID of the player that edited an object + * 0 if it is a global object or 1 if it is a + * playerobject + * The ID of the edited object + * The type of response + * The X offset for the object that was edited + * The Y offset for the object that was edited + * The Z offset for the object that was edited + * The X rotation for the object that was edited + * The Y rotation for the object that was edited + * The Z rotation for the object that was edited + * + * + * + * + * This callback was added in SA-MP 0.3e and will not work in earlier versions! + * When using EDIT_RESPONSE_UPDATE be aware that this callback will not be called + * when releasing an edit in progress resulting in the last update of EDIT_RESPONSE_UPDATE + * being out of sync of the objects current position. + * + * 1 - Will prevent other scripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next script.
+ * It is always called first in filterscripts. + * + */ +#if !defined EDIT_RESPONSE + #define EDIT_RESPONSE: _: +#endif +forward OnPlayerEditObject(playerid, playerobject, objectid, EDIT_RESPONSE:response, Float:fX, Float:fY, Float:fZ, Float:fRotX, Float:fRotY, Float:fRotZ); + +/** + * This callback is called when a player ends attached object edition mode. + * The ID of the player that ended edition mode + * 0 if they cancelled (ESC) or 1 if they clicked + * the save icon + * The index of the attached object + * The model of the attached object that was edited + * The bone of the attached object that was edited + * The X offset for the attached object that was edited + * The Y offset for the attached object that was edited + * The Z offset for the attached object that was edited + * The X rotation for the attached object that was edited + * The Y rotation for the attached object that was edited + * The Z rotation for the attached object that was edited + * The X scale for the attached object that was edited + * The Y scale for the attached object that was edited + * The Z scale for the attached object that was edited + * + * + * This callback was added in SA-MP 0.3e and will not work in earlier versions! + * Editions should be discarded if response was 0 (cancelled). This must be + * done by storing the offsets etc. in an array BEFORE using EditAttachedObject. + * + * 1 - Will prevent other scripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next script.
+ * It is always called first in filterscripts. + * + */ +#if !defined EDIT_RESPONSE + #define EDIT_RESPONSE: _: +#endif +forward OnPlayerEditAttachedObject(playerid, EDIT_RESPONSE:response, index, modelid, boneid, Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fScaleX, Float:fScaleY, Float:fScaleZ); + +/** + * This callback is called when an object is moved after MoveObject + * (when it stops moving). + * The ID of the object that was moved + * + * + * + * + * SetObjectPos does not work when used in this callback. To fix + * it, recreate the object. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +forward OnObjectMoved(objectid); + +/** + * This callback is called when a player object is moved after MovePlayerObject + * (when it stops moving). + * The playerid the object is assigned to + * The ID of the player object that was moved + * + * + * + * + * This callback can also be called for NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +forward OnPlayerObjectMoved(playerid, objectid); diff --git a/a_players.inc b/a_players.inc old mode 100755 new mode 100644 index ce97c3b..784f805 --- a/a_players.inc +++ b/a_players.inc @@ -1,2448 +1,3835 @@ -/* SA-MP Player Functions - * - * (c) Copyright 2005-2017, SA-MP Team - * - */ - #if defined _INC_a_players #endinput #endif #define _INC_a_players #define _players_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2005-2017, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +///

+ +// -------------------------------------------------- +// Defines +// -------------------------------------------------- // Limits -#if !defined MAX_PLAYER_ATTACHED_OBJECTS - #define MAX_PLAYER_ATTACHED_OBJECTS (10) +/** + * a_players + */ +#if defined MAX_PLAYER_NAME + const __MAX_PLAYER_NAME = MAX_PLAYER_NAME; + #define __MAX_PLAYER_NAME +#else + const MAX_PLAYER_NAME = 24; + #define MAX_PLAYER_NAME 24 +#endif + +/** + * a_players + */ +#if defined MAX_PLAYERS + const __MAX_PLAYERS = MAX_PLAYERS; + #define __MAX_PLAYERS +#else + const MAX_PLAYERS = 1000; + #define MAX_PLAYERS 1000 +#endif + +/** + * a_players + */ +#if defined MAX_PLAYER_TEXT_DRAWS + const PlayerText:__MAX_PLAYER_TEXT_DRAWS = MAX_PLAYER_TEXT_DRAWS; + #define __MAX_PLAYER_TEXT_DRAWS +#else + const PlayerText:MAX_PLAYER_TEXT_DRAWS = PlayerText:256; + #define MAX_PLAYER_TEXT_DRAWS (PlayerText:256) +#endif + +/** + * a_players + */ +#if defined MAX_3DTEXT_PLAYER + const PlayerText3D:__MAX_3DTEXT_PLAYER = MAX_3DTEXT_PLAYER; + #define __MAX_3DTEXT_PLAYER +#else + const PlayerText3D:MAX_3DTEXT_PLAYER = PlayerText3D:1024; + #define MAX_3DTEXT_PLAYER (PlayerText3D:1024) +#endif + +/** + * a_players + */ +#if defined MAX_PLAYER_ATTACHED_OBJECTS + const __MAX_PLAYER_ATTACHED_OBJECTS = MAX_PLAYER_ATTACHED_OBJECTS; + #define __MAX_PLAYER_ATTACHED_OBJECTS +#else + const MAX_PLAYER_ATTACHED_OBJECTS = 10; + #define MAX_PLAYER_ATTACHED_OBJECTS 10 #endif -#if !defined MAX_CHATBUBBLE_LENGTH - #define MAX_CHATBUBBLE_LENGTH (144) +/** + * a_players + */ +#if defined MAX_CHATBUBBLE_LENGTH + const __MAX_CHATBUBBLE_LENGTH = MAX_CHATBUBBLE_LENGTH; + #define __MAX_CHATBUBBLE_LENGTH +#else + const MAX_CHATBUBBLE_LENGTH = 144; + #define MAX_CHATBUBBLE_LENGTH 144 #endif -#define SPECIAL_ACTION_NONE (0) -#define SPECIAL_ACTION_DUCK (1) -#define SPECIAL_ACTION_USEJETPACK (2) -#define SPECIAL_ACTION_ENTER_VEHICLE (3) -#define SPECIAL_ACTION_EXIT_VEHICLE (4) -#define SPECIAL_ACTION_DANCE1 (5) -#define SPECIAL_ACTION_DANCE2 (6) -#define SPECIAL_ACTION_DANCE3 (7) -#define SPECIAL_ACTION_DANCE4 (8) -#define SPECIAL_ACTION_HANDSUP (10) -#define SPECIAL_ACTION_USECELLPHONE (11) -#define SPECIAL_ACTION_SITTING (12) -#define SPECIAL_ACTION_STOPUSECELLPHONE (13) -#define SPECIAL_ACTION_DRINK_BEER (20) -#define SPECIAL_ACTION_SMOKE_CIGGY (21) -#define SPECIAL_ACTION_DRINK_WINE (22) -#define SPECIAL_ACTION_DRINK_SPRUNK (23) -#define SPECIAL_ACTION_PISSING (68) -#define SPECIAL_ACTION_CUFFED (24) -#define SPECIAL_ACTION_CARRY (25) - -#define FIGHT_STYLE_NORMAL (4) -#define FIGHT_STYLE_BOXING (5) -#define FIGHT_STYLE_KUNGFU (6) -#define FIGHT_STYLE_KNEEHEAD (7) -#define FIGHT_STYLE_GRABKICK (15) -#define FIGHT_STYLE_ELBOW (16) - -#define WEAPONSKILL_PISTOL (0) -#define WEAPONSKILL_PISTOL_SILENCED (1) -#define WEAPONSKILL_DESERT_EAGLE (2) -#define WEAPONSKILL_SHOTGUN (3) -#define WEAPONSKILL_SAWNOFF_SHOTGUN (4) -#define WEAPONSKILL_SPAS12_SHOTGUN (5) -#define WEAPONSKILL_MICRO_UZI (6) -#define WEAPONSKILL_MP5 (7) -#define WEAPONSKILL_AK47 (8) -#define WEAPONSKILL_M4 (9) -#define WEAPONSKILL_SNIPERRIFLE (10) - -#define WEAPONSTATE_UNKNOWN (-1) -#define WEAPONSTATE_NO_BULLETS (0) -#define WEAPONSTATE_LAST_BULLET (1) -#define WEAPONSTATE_MORE_BULLETS (2) -#define WEAPONSTATE_RELOADING (3) - -// PVar enumeration -#define PLAYER_VARTYPE_NONE (0) -#define PLAYER_VARTYPE_INT (1) -#define PLAYER_VARTYPE_STRING (2) -#define PLAYER_VARTYPE_FLOAT (3) - -#define MAPICON_LOCAL (0) // displays in the player's local area -#define MAPICON_GLOBAL (1) // displays always -#define MAPICON_LOCAL_CHECKPOINT (2) // displays in the player's local area and has a checkpoint marker -#define MAPICON_GLOBAL_CHECKPOINT (3) // displays always and has a checkpoint marker - -#define CAMERA_CUT (2) -#define CAMERA_MOVE (1) - -// Spectating -#define SPECTATE_MODE_NORMAL (1) -#define SPECTATE_MODE_FIXED (2) -#define SPECTATE_MODE_SIDE (3) - -// Recording for NPC playback -#define PLAYER_RECORDING_TYPE_NONE (0) -#define PLAYER_RECORDING_TYPE_DRIVER (1) -#define PLAYER_RECORDING_TYPE_ONFOOT (2) +// Invalids +/** + * a_players + */ +const PlayerText3D:INVALID_PLAYER_3DTEXT_ID = PlayerText3D:0xFFFF; +#define INVALID_PLAYER_3DTEXT_ID (PlayerText3D:0xFFFF) + +/** + * a_players + */ +const PlayerText:INVALID_PLAYER_TEXT_DRAW = PlayerText:0xFFFF; +#define INVALID_PLAYER_TEXT_DRAW (PlayerText:0xFFFF) + +/** + * a_players + */ +const NO_TEAM = 0xFF; +#define NO_TEAM 0xFF + +/** + * a_players + */ +const INVALID_PLAYER_ID = 0xFFFF; +#define INVALID_PLAYER_ID 0xFFFF + +// Checks +#if MAX_PLAYER_NAME < 3 || MAX_PLAYER_NAME > 24 + #error MAX_PLAYER_NAME must be >= 3 and <= 24 +#endif + +#if MAX_PLAYERS < 1 || MAX_PLAYERS > 1000 + #error MAX_PLAYERS must be >= 1 and <= 1000 +#endif + +#if MAX_PLAYER_TEXT_DRAWS < PlayerText:1 || MAX_PLAYER_TEXT_DRAWS > PlayerText:256 + #error MAX_PLAYER_TEXT_DRAWS must be >= 1 and <= 256 +#endif + +#if MAX_3DTEXT_PLAYER < PlayerText3D:1 || MAX_3DTEXT_PLAYER > PlayerText3D:1024 + #error MAX_3DTEXT_PLAYER must be >= 1 and <= 1024 +#endif + +#if MAX_PLAYER_ATTACHED_OBJECTS < 0 || MAX_PLAYER_ATTACHED_OBJECTS > 10 + #error MAX_PLAYER_ATTACHED_OBJECTS must be >= 0 and <= 10 +#endif + +#if MAX_CHATBUBBLE_LENGTH < 1 || MAX_CHATBUBBLE_LENGTH > 144 + #error MAX_CHATBUBBLE_LENGTH must be >= 1 and <= 144 +#endif + +// Enums +///

+ +/** + * a_players + *

States + */ +#define PLAYER_STATE: __TAG(PLAYER_STATE): +enum PLAYER_STATE:__PLAYER_STATE +{ + PLAYER_STATE_NONE, + PLAYER_STATE_ONFOOT, + PLAYER_STATE_DRIVER, + PLAYER_STATE_PASSENGER, + PLAYER_STATE_WASTED = 7, + PLAYER_STATE_SPAWNED, + PLAYER_STATE_SPECTATING +} +static stock PLAYER_STATE:_@PLAYER_STATE() { return __PLAYER_STATE; } + +/** + * a_players + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_EXIT_VEH = PLAYER_STATE:4; +#define PLAYER_STATE_EXIT_VEHICLE PLAYER_STATE_EXIT_VEH + +/** + * a_players + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_ENTER_VEHICLE_DRV = PLAYER_STATE:5; +#define PLAYER_STATE_ENTER_VEHICLE_DRIVER PLAYER_STATE_ENTER_VEHICLE_DRV + +/** + * a_players + * Used internally + */ +#pragma deprecated Used internally. +const PLAYER_STATE:PLAYER_STATE_ENTER_VEHICLE_PASS = PLAYER_STATE:6; +#define PLAYER_STATE_ENTER_VEHICLE_PASSENGER PLAYER_STATE_ENTER_VEHICLE_PASS + +///

+ +/** + * a_players + *

Marker modes used by ShowPlayerMarkers() + */ +#define PLAYER_MARKERS_MODE: __TAG(PLAYER_MARKERS_MODE): +enum PLAYER_MARKERS_MODE:__PLAYER_MARKERS_MODE +{ + PLAYER_MARKERS_MODE_OFF, + PLAYER_MARKERS_MODE_GLOBAL, + PLAYER_MARKERS_MODE_STREAMED +} +static stock PLAYER_MARKERS_MODE:_@PLAYER_MARKERS_MODE() { return __PLAYER_MARKERS_MODE; } + +///

+ +/** + * a_players + */ +#define SPECIAL_ACTION: __TAG(SPECIAL_ACTION): +enum SPECIAL_ACTION:__SPECIAL_ACTION +{ + SPECIAL_ACTION_NONE, + SPECIAL_ACTION_DUCK, + SPECIAL_ACTION_USEJETPACK, + SPECIAL_ACTION_ENTER_VEHICLE, + SPECIAL_ACTION_EXIT_VEHICLE, + SPECIAL_ACTION_DANCE1, + SPECIAL_ACTION_DANCE2, + SPECIAL_ACTION_DANCE3, + SPECIAL_ACTION_DANCE4, + SPECIAL_ACTION_HANDSUP = 10, + SPECIAL_ACTION_USECELLPHONE, + SPECIAL_ACTION_SITTING, + SPECIAL_ACTION_STOPUSECELLPHONE, + SPECIAL_ACTION_DRINK_BEER = 20, + SPECIAL_ACTION_SMOKE_CIGGY, + SPECIAL_ACTION_DRINK_WINE, + SPECIAL_ACTION_DRINK_SPRUNK, + SPECIAL_ACTION_CUFFED, + SPECIAL_ACTION_CARRY, + SPECIAL_ACTION_PISSING = 68 +} +static stock SPECIAL_ACTION:_@SPECIAL_ACTION() { return __SPECIAL_ACTION; } + +///

+ +/** + * a_players + */ +#define FIGHT_STYLE: __TAG(FIGHT_STYLE): +enum FIGHT_STYLE:__FIGHT_STYLE +{ + FIGHT_STYLE_NORMAL = 4, + FIGHT_STYLE_BOXING, + FIGHT_STYLE_KUNGFU, + FIGHT_STYLE_KNEEHEAD, + FIGHT_STYLE_GRABKICK = 15, + FIGHT_STYLE_ELBOW +} +static stock FIGHT_STYLE:_@FIGHT_STYLE() { return __FIGHT_STYLE; } + +///

+ +/** + * a_players + */ +#define WEAPONSKILL: __TAG(WEAPONSKILL): +enum WEAPONSKILL:__WEAPONSKILL +{ + WEAPONSKILL_PISTOL, + WEAPONSKILL_PISTOL_SILENCED, + WEAPONSKILL_DESERT_EAGLE, + WEAPONSKILL_SHOTGUN, + WEAPONSKILL_SAWNOFF_SHOTGUN, + WEAPONSKILL_SPAS12_SHOTGUN, + WEAPONSKILL_MICRO_UZI, + WEAPONSKILL_MP5, + WEAPONSKILL_AK47, + WEAPONSKILL_M4, + WEAPONSKILL_SNIPERRIFLE, +} +static stock WEAPONSKILL:_@WEAPONSKILL() { return __WEAPONSKILL; } + +///

+ +/** + * a_players + */ +#define WEAPONSTATE: __TAG(WEAPONSTATE): +enum WEAPONSTATE:__WEAPONSTATE +{ + WEAPONSTATE_UNKNOWN = -1, + WEAPONSTATE_NO_BULLETS, + WEAPONSTATE_LAST_BULLET, + WEAPONSTATE_MORE_BULLETS, + WEAPONSTATE_RELOADING +} +static stock WEAPONSTATE:_@WEAPONSTATE() { return __WEAPONSTATE; } + +///

+ +/** + * a_players + *

PVar enumeration + */ +#define PLAYER_VARTYPE: __TAG(PLAYER_VARTYPE): +enum PLAYER_VARTYPE:__PLAYER_VARTYPE +{ + PLAYER_VARTYPE_NONE, + PLAYER_VARTYPE_INT, + PLAYER_VARTYPE_STRING, + PLAYER_VARTYPE_FLOAT +} +static stock PLAYER_VARTYPE:_@PLAYER_VARTYPE() { return __PLAYER_VARTYPE; } + +///

+ +/** + * a_players + */ +#define MAPICON: __TAG(MAPICON): +enum MAPICON:__MAPICON +{ + MAPICON_LOCAL, // Displays in the player's local area + MAPICON_GLOBAL, // Displays always + MAPICON_LOCAL_CHECKPOINT, // Displays in the player's local area and has a checkpoint marker + MAPICON_GLOBAL_CHECKPOINT // Displays always and has a checkpoint marker +} +static stock MAPICON:_@MAPICON() { return __MAPICON; } + +///

+ +/** + * a_players + */ +#define CAM_MOVE: __TAG(CAM_MOVE): +enum CAM_MOVE:__CAMERA +{ + CAMERA_MOVE = 1, + CAMERA_CUT +} +static stock CAMERA_MOVE:_@CAMERA_MOVE() { return __CAMERA_MOVE; } + +///

+ +/** + * a_players + */ +#define CAM_MODE: __TAG(CAM_MODE): +enum CAM_MODE:__CAM_MODE +{ + CAM_MODE_DISCONNECTED = -1, + CAM_MODE_NONE = 0, + CAM_MODE_BEHINDCAR = 3, + CAM_MODE_FOLLOWPED = 4, + CAM_MODE_SNIPER = 7, + CAM_MODE_ROCKETLAUNCHER = 8, + CAM_MODE_FIXED = 15, + CAM_MODE_1STPERSON = 16, + CAM_MODE_CAM_ON_A_STRING = 18, + CAM_MODE_BEHINDBOAT = 22, + CAM_MODE_CAMERA = 46, + CAM_MODE_ROCKETLAUNCHER_HS = 51, + CAM_MODE_AIMWEAPON = 53, + CAM_MODE_AIMWEAPON_FROMCAR = 55, + CAM_MODE_DW_HELI_CHASE = 56 +} +static stock CAM_MODE:_@CAM_MODE() { return __CAM_MODE; } + +///

+ +/** + * a_players + */ +#define CP_TYPE: __TAG(CP_TYPE): +enum CP_TYPE:__CP_TYPE +{ + CP_TYPE_GROUND_NORMAL = 0, + CP_TYPE_GROUND_FINISH = 1, + CP_TYPE_GROUND_EMPTY = 2, + CP_TYPE_AIR_NORMAL = 3, + CP_TYPE_AIR_FINISH = 4, + CP_TYPE_AIR_ROTATING = 5, + CP_TYPE_AIR_STROBING = 6, + CP_TYPE_AIR_SWINGING = 7, + CP_TYPE_AIR_BOBBING = 8 +} +static stock CP_TYPE:_@CP_TYPE() { return __CP_TYPE; } + +///

+ +/** + * a_players + *

Spectating + */ +#define SPECTATE_MODE: __TAG(SPECTATE_MODE): +enum SPECTATE_MODE:__SPECTATE_MODE +{ + SPECTATE_MODE_NORMAL = 1, + SPECTATE_MODE_FIXED, + SPECTATE_MODE_SIDE +} +static stock SPECTATE_MODE:_@SPECTATE_MODE() { return __SPECTATE_MODE; } + +///

+ +/** + * a_players + *

Recording for NPC playback + */ +#define PLAYER_RECORDING_TYPE: __TAG(PLAYER_RECORDING_TYPE): +enum PLAYER_RECORDING_TYPE:__PLAYER_RECORDING_TYPE +{ + PLAYER_RECORDING_TYPE_NONE, + PLAYER_RECORDING_TYPE_DRIVER, + PLAYER_RECORDING_TYPE_ONFOOT +} +static stock PLAYER_RECORDING_TYPE:_@PLAYER_RECORDING_TYPE() { return __PLAYER_RECORDING_TYPE; } // Player -/// This function can be used to change the spawn information of a specific player. It allows you to automatically set someone's spawn weapons, their team, skin and spawn position, normally used in case of minigames or automatic-spawn systems. This function is more crash-safe then using SetPlayerSkin in OnPlayerSpawn and/or OnPlayerRequestClass, even though this has been fixed in 0.2. -/// The PlayerID of who you want to set the spawn information -/// The Team-ID of the chosen player -/// The skin which the player will spawn with -/// The X-coordinate of the player's spawn position -/// The Y-coordinate of the player's spawn position -/// The Z-coordinate of the player's spawn position -/// The direction in which the player needs to be facing after spawning -/// The first spawn-weapon for the player -/// The amount of ammunition for the primary spawnweapon -/// The second spawn-weapon for the player -/// The amount of ammunition for the second spawnweapon -/// The third spawn-weapon for the player -/// The amount of ammunition for the third spawnweapon -/// -/// -/// -native SetSpawnInfo(playerid, team, skin, Float:x, Float:y, Float:z, Float:rotation, weapon1, weapon1_ammo, weapon2, weapon2_ammo, weapon3, weapon3_ammo); - -/// (Re)Spawns a player. -/// The ID of the player to spawn -/// -/// -/// -/// Kills the player if they are in a vehicle and then they spawn with a bottle in their hand. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

This function can be used to change the spawn information of a specific player. It allows + * you to automatically set someone's spawn weapons, their team, skin and spawn position, normally used + * in case of minigames or automatic-spawn systems. This function is more crash-safe then using SetPlayerSkin in OnPlayerSpawn and/or + * OnPlayerRequestClass, + * even though this has been fixed in 0.2. + * The Playerid of who you want to set the spawn information + * The Team-ID of the chosen player + * The skin which the player will spawn with + * The x-coordinate of the player's spawn position + * The y-coordinate of the player's spawn position + * The z-coordinate of the player's spawn position + * The direction in which the player needs to be facing after spawning + * The first spawn-weapon for + * the player + * The amount of ammunition for the primary spawnweapon + * The second spawn-weapon for + * the player + * The amount of ammunition for the second spawnweapon + * The third spawn-weapon for + * the player + * The amount of ammunition for the third spawnweapon + * + * + * + */ +native SetSpawnInfo(playerid, team, skin, Float:x, Float:y, Float:z, Float:rotation, WEAPON:weapon1, ammo1, WEAPON:weapon2, ammo2, WEAPON:weapon3, ammo3); + +/** + * a_players + * (Re)Spawns a player. + * The ID of the player to spawn + * + * + * + * Kills the player if they are in a vehicle and then they spawn with a bottle in their hand. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native SpawnPlayer(playerid); // Player info -/// Set a player's position. -/// The ID of the player to set the position of -/// The X coordinate to position the player at -/// The Y coordinate to position the player at -/// The Z coordinate to position the player at -/// -/// -/// -/// -/// -/// Using this function on a player in a vehicle will instantly remove them from the vehicle. Useful for quickly ejecting players. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Set a player's position. + * The ID of the player to set the position of + * The x coordinate to position the player at + * The y coordinate to position the player at + * The z coordinate to position the player at + * + * + * + * + * + * Using this function on a player in a vehicle will instantly remove them from the vehicle. + * Useful for quickly ejecting players. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerPos(playerid, Float:x, Float:y, Float:z); -/// This sets the players position then adjusts the players z-coordinate to the nearest solid ground under the position. -/// The ID of the player to set the position of -/// The X coordinate to position the player at -/// The X coordinate to position the player at -/// The Z coordinate to position the player at -/// -/// -/// This function does not work if the new coordinates are far away from where the player currently is. The Z height will be 0, which will likely put them underground. It is highly recommended that the MapAndreas plugin be used instead. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

This sets the players position then adjusts the players z-coordinate to the nearest solid + * ground under the position. + * The ID of the player to set the position of + * The x coordinate to position the player at + * The x coordinate to position the player at + * The z coordinate to position the player at + * + * + * This function does not work if the new coordinates are far away from where the player currently + * is. The z height will be 0, which will likely put them underground. It is highly + * recommended that the MapAndreas plugin + * be used instead. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerPosFindZ(playerid, Float:x, Float:y, Float:z); -/// Get the position of a player, represented by X, Y and Z coordinates. -/// The ID of the player to get the position of -/// A float variable in which to store the X coordinate in, passed by reference -/// A float variable in which to store the Y coordinate in, passed by reference -/// A float variable in which to store the Z coordinate in, passed by reference -/// -/// -/// -/// -/// This function is known to return unreliable values when used in OnPlayerDisconnect and OnPlayerRequestClass. This is because the player is not spawned. -/// true on success, false on failure (i.e. player not connected). +/** + * a_players + * Get the position of a player, represented by x, y and z coordinates. + * The ID of the player to get the position of + * A float variable in which to store the x coordinate in, passed by reference + * A float variable in which to store the y coordinate in, passed by reference + * A float variable in which to store the z coordinate in, passed by reference + * + * + * + * + * This function is known to return unreliable values when used in OnPlayerDisconnect + * and OnPlayerRequestClass. This is because the player is not + * spawned. + * true on success, false on failure (i.e. player not connected). + */ native GetPlayerPos(playerid, &Float:x, &Float:y, &Float:z); -/// Set a player's facing angle (Z rotation). -/// The ID of the player to set the facing angle of -/// The angle the player should face -/// -/// -/// Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do 360 - angle. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// +/** + * a_players + *

Set a player's facing angle (z rotation). + * The ID of the player to set the facing angle of + * The angle the player should face + * + * + * Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA + * 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do + * 360 - angle. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ native SetPlayerFacingAngle(playerid, Float:ang); -/// Gets the angle a player is facing. -/// The player you want to get the angle of -/// The Float to store the angle in, passed by reference -/// -/// -/// Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do 360 - angle. -/// Angles returned when inside a vehicle is rarely correct. To get the correct facing angle while inside a vehicle, use GetVehicleZAngle. +/** + * a_players + * Gets the angle a player is facing. + * The player you want to get the angle of + * The Float to store the angle in, passed by reference + * + * + * Angles are reversed in GTA:SA; 90 degrees would be East in the real world, but in GTA:SA + * 90 degrees is in fact West. North and South are still 0/360 and 180. To convert this, simply do + * 360 - angle. + * Angles returned when inside a vehicle is rarely correct. To get the correct facing angle + * while inside a vehicle, use GetVehicleZAngle. + */ native GetPlayerFacingAngle(playerid, &Float:ang); -/// Checks if a player is in range of a point. This native function is faster than the PAWN implementation using distance formula. -/// The ID of the player -/// The furthest distance the player can be from the point to be in range -/// The X coordinate of the point to check the range to -/// The Y coordinate of the point to check the range to -/// The Z coordinate of the point to check the range to -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the player is in range, 0 if not. -native IsPlayerInRangeOfPoint(playerid, Float:range, Float:x, Float:y, Float:z); - -/// Calculate the distance between a player and a map coordinate. -/// The ID of the player to calculate the distance from -/// The X map coordinate -/// The Y map coordinate -/// The Z map coordinate -/// -/// -/// -/// This function was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// The distance between the player and the point as a float. -native Float:GetPlayerDistanceFromPoint(playerid, Float:X, Float:Y, Float:Z); - -/// Checks if a player is streamed in another player's client. -/// The ID of the player to check is streamed in -/// The ID of the player to check if playerid is streamed in for -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// Players aren't streamed in on their own client, so if playerid is the same as forplayerid it will return false! -/// Players stream out if they are more than 150 meters away (see server.cfg - stream_distance) -/// 1 if the player is streamed in, 0 if not. -native IsPlayerStreamedIn(playerid, forplayerid); - -/// Set a player's interior. A list of currently known interiors and their positions can be found here. -/// The ID of the player to set the interior of -/// The interior ID to set the player in -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Checks if a player is in range of a point. This native function is faster than the PAWN + * implementation using distance formula. + * The ID of the player + * The furthest distance the player can be from the point to be in range + * The x coordinate of the point to check the range to + * The y coordinate of the point to check the range to + * The z coordinate of the point to check the range to + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the player is in range, 0 if not. + */ +native bool:IsPlayerInRangeOfPoint(playerid, Float:range, Float:x, Float:y, Float:z); + +/** + * a_players + * Calculate the distance between a player and a map coordinate. + * The ID of the player to calculate the distance from + * The x map coordinate + * The y map coordinate + * The z map coordinate + * + * + * + * This function was added in SA-MP 0.3c R3 and will not work in earlier versions! + * The distance between the player and the point as a float. + */ +native Float:GetPlayerDistanceFromPoint(playerid, Float:x, Float:y, Float:z); + +/** + * a_players + * Checks if a player is streamed in another player's client. + * The ID of the player to check is streamed in + * The ID of the player to check if playerid is streamed in for + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * Players aren't streamed in on their own client, so if playerid is the same as targetid it + * will return false! + * Players stream out if they are more than 150 meters away (see server.cfg + * - stream_distance) + * 1 if the player is streamed in, 0 if not. + */ +native bool:IsPlayerStreamedIn(targetid, playerid); + +/** + * a_players + * Set a player's interior. A list of currently known interiors and their positions can be + * found here. + * The ID of the player to set the interior of + * The interior ID to + * set the player in + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native SetPlayerInterior(playerid, interiorid); -/// Retrieves the player's current interior. A list of currently known interiors with their positions can be found on this page. -/// The player to get the interior ID of -/// -/// -/// Always returns 0 for NPCs. -/// The interior ID the player is currently in. +/** + * a_players + * Retrieves the player's current interior. A list of currently known interiors with their + * positions can be found on this page. + * The player to get the interior ID of + * + * + * Always returns 0 for NPCs. + * The interior ID the player is currently in. + */ native GetPlayerInterior(playerid); - -/// Set the health of a player. -/// The ID of the player to set the health of -/// The value to set the player's health to. Max health that can be displayed in the HUD is 100, though higher values are valid -/// -/// -/// -/// Health is obtained rounded to integers: set 50.15, but get 50.0 -/// If a player's health is set to 0 or a minus value, they will die instantly. -/// If a player's health is below 10 or above 98303, their health bar will flash. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Set the health of a player. + * The ID of the player to set the health of + * The value to set the player's health to. Max health that can be displayed in + * the HUD is 100, though higher values are valid + * + * + * + * Health is obtained rounded to integers: set 50.15, but get 50.0 + * If a player's health is set to 0 or a minus value, they will die instantly. + * If a player's health is below 10 or above 98303, their health + * bar will flash. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerHealth(playerid, Float:health); -/// The function GetPlayerHealth allows you to retrieve the health of a player. Useful for cheat detection, among other things. -/// The ID of the player -/// Float to store health, passed by reference -/// -/// -/// -/// -/// Even though the health can be set to near infinite values on the server side, the individual clients will only report values up to 255. Anything higher will wrap around; 256 becomes 0, 257 becomes 1, etc.

-/// Health is obtained rounded to integers: set 50.15, but get 50.0 -/// -/// -/// 1 - success.

-/// 0 - failure (i.e. player not connected).

-/// +/** + * a_players + *

The function GetPlayerHealth allows you to retrieve the health of a player. Useful for + * cheat detection, among other things. + * The ID of the player + * Float to store health, passed by reference + * + * + * + * + * Even though the health can be set to near infinite values on the server side, the individual clients + * will only report values up to 255. Anything higher will wrap around; 256 + * becomes 0, 257 becomes 1, etc.
+ * Health is obtained rounded to integers: set 50.15, but get 50.0 + * + * + * 1 - success.
+ * 0 - failure (i.e. player not connected).
+ * + */ native GetPlayerHealth(playerid, &Float:health); -/// Set a player's armor level. -/// The ID of the player to set the armour of -/// The amount of armour to set, as a percentage (float). Values larger than 100 are valid, but won't be displayed in the HUD's armour bar -/// -/// -/// -/// Armour is obtained rounded to integers: set 50.15, but get 50.0 -/// The function's name is armour, not armor (Americanized). This is inconsistent with the rest of SA-MP, so remember that. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Set a player's armor level. + * The ID of the player to set the armour of + * The amount of armour to set, as a percentage (float). Values larger than 100 + * are valid, but won't be displayed in the HUD's armour bar + * + * + * + * Armour is obtained rounded to integers: set 50.15, but get 50.0 + * The function's name is armour, not armor (Americanized). This is inconsistent with the + * rest of SA-MP, so remember that. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerArmour(playerid, Float:armour); -/// This function stores the armour of a player into a variable. -/// The ID of the player that you want to get the armour of -/// The float to to store the armour in, passed by reference -/// -/// -/// -/// Even though the armour can be set to near infinite values on the server side, the individual clients will only report values up to 255. Anything higher will wrap around; 256 becomes 0, 257 becomes 1, etc. -/// Armour is obtained rounded to integers: set 50.15, but get 50.0 -/// The function's name is armour, not armor (Americanized). This is inconsistent with the rest of SA-MP, so remember that. -/// -/// 1 - success.

-/// 0 - failure (i.e. player not connected).

-/// +/** + * a_players + *

This function stores the armour of a player into a variable. + * The ID of the player that you want to get the armour of + * The float to to store the armour in, passed by reference + * + * + * + * Even though the armour can be set to near infinite values on the server side, the individual + * clients will only report values up to 255. Anything higher will wrap around; 256 + * becomes 0, 257 becomes 1, etc. + * Armour is obtained rounded to integers: set 50.15, but get 50.0 + * + * The function's name is armour, not armor (Americanized). This is inconsistent with the + * rest of SA-MP, so remember that. + * + * 1 - success.
+ * 0 - failure (i.e. player not connected).
+ * + */ native GetPlayerArmour(playerid, &Float:armour); -/// Set the ammo of a player's weapon. -/// The ID of the player to set the weapon ammo of -/// The ID of the weapon to set the ammo of. -/// The amount of ammo to set -/// -/// -/// -/// Set the ammo to 0 to remove a weapon from a player's inventory. Note that the weapon will still show up in GetPlayerWeaponData, albeit with 0 ammo. -/// -/// 1: The function executed successfully. Success is also returned when the weapon slot specified is invalid (not 0-12).

-/// 0: The function failed to execute. The player isn't connected.

-/// -native SetPlayerAmmo(playerid, weaponid, ammo); - -///

Gets the amount of ammo in a player's current weapon. -/// The ID of the player whose ammo to get -/// -/// -/// The ammo can hold 16-bit values, therefore values over 32767 will return erroneous values. -/// The amount of ammo in the player's current weapon. +/** + * a_players + * Set the ammo of a player's weapon. + * The ID of the player to set the weapon ammo of + * The ID of the weapon to set + * the ammo of. + * The amount of ammo to set + * + * + * + * Set the ammo to 0 to remove a weapon from a player's inventory. Note that + * the weapon will still show up in GetPlayerWeaponData, albeit with + * 0 ammo. + * + * 1: The function executed successfully. Success is also returned when the weapon + * specified is invalid.
+ * 0: The function failed to execute. The player isn't connected.
+ * + */ +native SetPlayerAmmo(playerid, WEAPON:weaponid, ammo); + +/** + * a_players + * Gets the amount of ammo in a player's current weapon. + * The ID of the player whose ammo to get + * + * + * The ammo can hold 16-bit values, therefore values over 32767 will return erroneous + * values. + * The amount of ammo in the player's current weapon. + */ native GetPlayerAmmo(playerid); -/// Check the state of a player's weapon. -/// The ID of the player to obtain the weapon state of -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Weapon states:

-///

    -///
  • WEAPONSTATE_UNKNOWN - unknown (Set when in a vehicle)
    • -///
  • WEAPONSTATE_NO_BULLETS - The weapon has no remaining ammo
    • -///
  • WEAPONSTATE_LAST_BULLET - the weapon has one remaining bullet
    • -///
  • WEAPONSTATE_MORE_BULLETS - the weapon has multiple bullets
    • -///
  • WEAPONSTATE_RELOADING - the player is reloading their weapon
    • -///
-/// -/// The state of the player's weapon. 0 if player specified does not exist. -native GetPlayerWeaponState(playerid); - -/// Check who a player is aiming at. -/// The ID of the player to get the target of -/// -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// Does not work for joypads/controllers, and after a certain distance. -/// Does not work for the sniper rifle, as it doesn't lock on to anything and as such can't and won't return a player. -/// The ID of the target player, or INVALID_PLAYER_ID if none. +/** + * a_players + * Check the state of a player's weapon. + * The ID of the player to obtain the weapon state of + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Weapon states:
+ *
    + *
  • WEAPONSTATE_UNKNOWN - unknown (Set when in a vehicle)
    • + *
  • WEAPONSTATE_NO_BULLETS - The weapon has no remaining ammo
    • + *
  • WEAPONSTATE_LAST_BULLET - the weapon has one remaining bullet
    • + *
  • WEAPONSTATE_MORE_BULLETS - the weapon has multiple bullets
    • + *
  • WEAPONSTATE_RELOADING - the player is reloading their weapon
    • + *
+ * + * The state of the player's weapon. 0 if player specified does not exist. + */ +native WEAPONSTATE:GetPlayerWeaponState(playerid); + +/** + * a_players + * Check who a player is aiming at. + * The ID of the player to get the target of + * + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * Does not work for joypads/controllers, and after a certain distance. + * Does not work for the sniper rifle, as it doesn't lock on to anything and as such can't + * and won't return a player. + * The ID of the target player, or INVALID_PLAYER_ID if none. + */ native GetPlayerTargetPlayer(playerid); -/// Gets id of an actor which is aimed by certain player. -/// The ID of the player to get the target of -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// Does not work for joypads/controllers, and after a certain distance. -/// Does not work for the sniper rifle, as it doesn't lock on to anything and as such can't and won't return a player. -/// The ID of the targeted actor, or INVALID_ACTOR_ID if none. +/** + * a_players + * Gets ID of an actor which is aimed by certain player. + * The ID of the player to get the target of + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * Does not work for joypads/controllers, and after a certain distance. + * Does not work for the sniper rifle, as it doesn't lock on to anything and as such can't + * and won't return a player. + * The ID of the targeted actor, or INVALID_ACTOR_ID if none. + */ native GetPlayerTargetActor(playerid); -/// Set the team of a player. -/// The ID of the player you want to set the team of -/// The team to put the player in. Use NO_TEAM to remove the player from any team -/// -/// -/// -/// Players can not damage/kill players on the same team unless they use a knife to slit their throat. As of SA-MP 0.3x, players are also unable to damage vehicles driven by a player from the same team. This can be enabled with EnableVehicleFriendlyFire. -/// 255 (or NO_TEAM) is the default team to be able to shoot other players, not 0. +/** + * a_players + * Set the team of a player. + * The ID of the player you want to set the team of + * The team to put the player in. Use NO_TEAM to remove the player + * from any team + * + * + * + * Players can not damage/kill players on the same team unless they use a knife to slit their + * throat. As of SA-MP 0.3x, players are also unable to damage vehicles driven by a player from + * the same team. This can be enabled with EnableVehicleFriendlyFire. + * 255 (or NO_TEAM) is the default team to be able to shoot other + * players, not 0. + */ native SetPlayerTeam(playerid, teamid); -/// Get the ID of the team the player is on. -/// The ID of the player to get the team of -/// -/// -/// -/// 0-254: The player's team. (0 is a valid team).

-/// 255: Defined as NO_TEAM. The player is not on any team.

-/// -1: The function failed to execute. Player is not connected. -/// +/** + * a_players + *

Get the ID of the team the player is on. + * The ID of the player to get the team of + * + * + * + * 0-254: The player's team. (0 is a valid team).
+ * 255: Defined as NO_TEAM. The player is not on any team.
+ * -1: The function failed to execute. Player is not connected. + * + */ native GetPlayerTeam(playerid); -/// Set a player's score. Players' scores are shown in the scoreboard (shown by holding the TAB key). -/// The ID of the player to set the score of -/// The value to set the player's score to -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Set a player's score. Players' scores are shown in the scoreboard (shown by holding the + * TAB key). + * The ID of the player to set the score of + * The value to set the player's score to + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerScore(playerid, score); -/// This function returns a player's score as it was set using SetPlayerScore. -/// The player to get the score of -/// -/// -/// The player's score. +/** + * a_players + * This function returns a player's score as it was set using SetPlayerScore. + * The player to get the score of + * + * + * The player's score. + */ native GetPlayerScore(playerid); -/// -/// Checks the player's level of drunkenness. If the level is less than 2000, the player is sober. The player's level of drunkness goes down slowly automatically (1 level per frame) but will always reach 2000 at the end (in 0.3b it will stop at 0). -/// The higher drunkenness levels affect the player's camera, and the car driving handling. The level of drunkenness increases when the player drinks from a bottle (You can use SetPlayerSpecialAction to give them bottles). -/// -/// The player you want to check the drunkenness level of -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// An integer with the level of drunkenness of the player. +/** + * a_players + * + * Checks the player's level of drunkenness. If the level is less than 2000, the player + * is sober. The player's level of drunkness goes down slowly automatically (1 level per frame) but + * will always reach 2000 at the end (in 0.3b it will stop at 0). + * The higher drunkenness levels affect the player's camera, and the car driving handling. The level + * of drunkenness increases when the player drinks from a bottle (You can use SetPlayerSpecialAction + * to give them bottles). + * + * The player you want to check the drunkenness level of + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * An integer with the level of drunkenness of the player. + */ native GetPlayerDrunkLevel(playerid); -/// Sets the drunk level of a player which makes the player's camera sway and vehicles hard to control. -/// The ID of the player to set the drunkenness of -/// The level of drunkenness to set -/// -/// -/// Players' drunk level will automatically decrease over time, based on their FPS (players with 50 FPS will lose 50 'levels' per second. This is useful for determining a player's FPS!).

-/// In 0.3a the drunk level will decrement and stop at 2000. In 0.3b+ the drunk level decrements to 0)

-/// Levels over 2000 make the player drunk (camera swaying and vehicles difficult to control).

-/// Max drunk level is 50000.

-/// While the drunk level is above 5000, the player's HUD (radar etc.) will be hidden. -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Sets the drunk level of a player which makes the player's camera sway and vehicles hard + * to control. + * The ID of the player to set the drunkenness of + * The level of drunkenness to set + * + * + * Players' drunk level will automatically decrease over time, based on their FPS (players with 50 + * FPS will lose 50 'levels' per second. This is useful for determining a player's FPS!).
+ * In 0.3a the drunk level will decrement and stop at 2000. In 0.3b+ + * the drunk level decrements to 0)
+ * Levels over 2000 make the player drunk (camera swaying and vehicles difficult to + * control).
+ * Max drunk level is 50000.
+ * While the drunk level is above 5000, the player's HUD (radar etc.) will be hidden. + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native SetPlayerDrunkLevel(playerid, level); -/// Set the colour of a player's nametag and marker (radar blip). -/// The ID of the player whose color to set -/// The color to set. Supports alpha values (RGBA) -/// -/// -/// -/// This function will change player's color for everyone, even if player's color was changed with SetPlayerMarkerForPlayer for any other player. -/// If used under OnPlayerConnect, the affecting player will not see the color in the TAB menu. -native SetPlayerColor(playerid, color); - -/// Gets the color of the player's name and radar marker. Only works after SetPlayerColor. -/// The ID of the player to get the color of -/// -/// -/// GetPlayerColor will return 0 unless SetPlayerColor has been used first. -/// The player's color. 0 if no color set or player not connected. +/** + * a_players + * Set the colour of a player's nametag and marker (radar blip). + * The ID of the player whose colour to set + * The colour to set. Supports alpha values (RGBA) + * + * + * + * This function will change player's colour for everyone, even if player's colour was changed + * with SetPlayerMarkerForPlayer for any other player. + * If used under OnPlayerConnect, the affecting player will + * not see the colour in the TAB menu. + */ +native SetPlayerColor(playerid, colour); + +/** + * a_players + * Gets the colour of the player's name and radar marker. Only works after SetPlayerColor. + * The ID of the player to get the colour of + * + * + * GetPlayerColor will return 0 unless SetPlayerColor + * has been used first. + * The player's colour. 0 if no colour set or player not connected. + */ native GetPlayerColor(playerid); -/// Set the skin of a player. A player's skin is their character model. -/// The ID of the player to set the skin of -/// The skin the player should use -/// -/// -/// If a player's skin is set when they are crouching, in a vehicle, or performing certain animations, they will become frozen or otherwise glitched. This can be fixed by using TogglePlayerControllable. Players can be detected as being crouched through GetPlayerSpecialAction (SPECIAL_ACTION_DUCK). -/// Setting a player's skin when he is dead may crash players around him. -/// Note that 'success' is reported even when skin ID is invalid (not 0-311, or 74), but the skin will be set to ID 0 (CJ). -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist.

-/// +/** + * a_players + *

Set the skin of a player. A player's skin is their character model. + * The ID of the player to set the skin of + * The skin the player should use + * + * + * If a player's skin is set when they are crouching, in a vehicle, or performing certain animations, + * they will become frozen or otherwise glitched. This can be fixed by using + * TogglePlayerControllable. + * Players can be detected as being crouched through GetPlayerSpecialAction + * (SPECIAL_ACTION_DUCK). + * Setting a player's skin when he is dead may crash players around him. + * Note that 'success' is reported even when skin ID is invalid (not 0-311, + * or 74), but the skin will be set to ID 0 (CJ). + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist.
+ * + */ native SetPlayerSkin(playerid, skinid); -/// Returns the class of the players skin. -/// The player you want to get the skin from -/// -/// Returns the new skin after SetSpawnInfo is called but before the player actually respawns to get the new skin. -/// Returns the old skin if the player was spawned through SpawnPlayer function. -/// The skin id (0 if invalid). +/** + * a_players + * Returns the class of the players skin. + * The player you want to get the skin from + * + * Returns the new skin after SetSpawnInfo is called but before + * the player actually respawns to get the new skin. + * Returns the old skin if the player was spawned through SpawnPlayer + * function. + * The skin ID (0 if invalid). + */ native GetPlayerSkin(playerid); +/** + * a_players + * Returns the class of the players skin. + * The player you want to get the skin from + * + * Returns the new skin after SetSpawnInfo is called but before + * the player actually respawns to get the new skin. + * Returns the old skin if the player was spawned through SpawnPlayer + * function. + * The skin id (0 if invalid). + */ native GetPlayerCustomSkin(playerid); -/// Give a player a weapon with a specified amount of ammo. -/// The ID of the player to give a weapon to -/// The ID of the weapon to give to the player -/// The amount of ammo to give to the player -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected.

-/// -native GivePlayerWeapon(playerid, weaponid, ammo); - -///

Removes all weapons from a player. -/// The ID of the player whose weapons to remove -/// -/// -/// To remove individual weapons from a player, set their ammo to 0 using SetPlayerAmmo. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Give a player a weapon with a specified amount of ammo. + * The ID of the player to give a weapon to + * The ID of the weapon to give to the player + * The amount of ammo to give to the player + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected.
+ * + */ +native GivePlayerWeapon(playerid, WEAPON:weaponid, ammo); + +/** + * a_players + * Removes all weapons from a player. + * The ID of the player whose weapons to remove + * + * + * To remove individual weapons from a player, set their ammo to 0 using + * SetPlayerAmmo. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native ResetPlayerWeapons(playerid); -/// Sets which weapon (that a player already has) the player is holding. -/// The ID of the player to arm with a weapon -/// The ID of the weapon that the player should be armed with -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This function arms a player with a weapon they already have; it does not give them a new weapon. See GivePlayerWeapon. -/// -/// 1: The function executed successfully. Success is returned even when the function fails to execute (the player doesn't have the weapon specified, or it is an invalid weapon).

-/// 0: The function failed to execute. The player is not connected. -/// -native SetPlayerArmedWeapon(playerid, weaponid); - -///

Get the weapon and ammo in a specific player's weapon slot (e.g. the weapon in the 'SMG' slot). -/// The ID of the player whose weapon data to retrieve -/// The weapon slot to get data for (0-12) -/// A variable in which to store the weapon ID, passed by reference -/// A variable in which to store the ammo, passed by reference -/// -/// -/// Old weapons with no ammo left are still returned. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player isn't connected and/or the weapon slot specified is invalid (valid is 0-12). -/// -native GetPlayerWeaponData(playerid, slot, &weapons, &ammo); - -///

Give money to or take money from a player. -/// The ID of the player to give money to or take money from -/// The amount of money to give the player. Use a minus value to take money -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Sets which weapon (that a player already has) the player is holding. + * The ID of the player to arm with a weapon + * The ID of the weapon that the player should be armed with + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This function arms a player with a weapon they already have; it does not give them + * a new weapon. See GivePlayerWeapon. + * + * 1: The function executed successfully. Success is returned even when the function + * fails to execute (the player doesn't have the weapon specified, or it is an invalid weapon).
+ * 0: The function failed to execute. The player is not connected. + * + */ +native SetPlayerArmedWeapon(playerid, WEAPON:weaponid); + +/** + * a_players + * Get the weapon and ammo in a specific player's weapon slot (e.g. the weapon in the 'SMG' + * slot). + * The ID of the player whose weapon data to retrieve + * The weapon slot to get data for (0-12) + * A variable in which to store the weapon ID, passed by reference + * A variable in which to store the ammo, passed by reference + * + * + * Old weapons with no ammo left are still returned. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player isn't connected and/or the weapon + * slot specified is invalid (valid is 0-12). + * + */ +native GetPlayerWeaponData(playerid, WEAPON_SLOT:slot, &WEAPON:weapons, &ammo); + +/** + * a_players + * Give money to or take money from a player. + * The ID of the player to give money to or take money from + * The amount of money to give the player. Use a minus value to take money + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native GivePlayerMoney(playerid, money); -/// Reset a player's money to $0. -/// The ID of the player to reset the money of -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Reset a player's money to $0. + * The ID of the player to reset the money of + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native ResetPlayerMoney(playerid); -/// Sets the name of a player. -/// The ID of the player to set the name of -/// The name to set. Must be 1-24 characters long and only contain valid characters (0-9, a-z, A-Z, [], (), $, @, ., _, =) -/// -/// Changing the players' name to the same name but with different character cases (e.g. "John" to "JOHN") will not work. -/// If used in OnPlayerConnect, the new name will not be shown for the connecting player. -/// Passing a null string as the new name will crash the server. -/// Player names can be up to 24 characters when using this function, but when joining the server from the SA-MP server browser, players' names must be no more than 20 and less than 3 characters (the server will deny entry). This allows for 4 characters extra when using SetPlayerName. -/// -/// 1 The name was changed successfully.

-/// 0 The player already has that name.

-/// -1 The name can not be changed (it's already in use, too long or has invalid characters). -/// +/** + * a_players + *

Sets the name of a player. + * The ID of the player to set the name of + * The name to set. Must be 1-24 characters long and only contain valid characters + * (0-9, a-z, A-z, [], (), $, @, ., _, + * =) + * + * Changing the players' name to the same name but with different character cases (e.g. "John" + * to "JOHN") will not work. + * If used in OnPlayerConnect, the new name will not + * be shown for the connecting player. + * Passing a null string as the new name will crash the server. + * Player names can be up to 24 characters when using this function, but when joining the server + * from the SA-MP server browser, players' names must be no more than 20 and less than 3 characters + * (the server will deny entry). This allows for 4 characters extra when using SetPlayerName. + * + * + * 1 The name was changed successfully.
+ * 0 The player already has that name.
+ * -1 The name can not be changed (it's already in use, too long or has invalid characters). + * + */ native SetPlayerName(playerid, const name[]); -/// Retrieves the amount of money a player has. -/// The ID of the player to get the money of -/// -/// -/// The amount of money the player has. +/** + * a_players + * Retrieves the amount of money a player has. + * The ID of the player to get the money of + * + * + * The amount of money the player has. + */ native GetPlayerMoney(playerid); -/// Get a player's current state. -/// The ID of the player to get the current state of -/// -/// -/// -/// -/// States:

-///

    -///
  • PLAYER_STATE_NONE - empty (while initializing)
    • -///
  • PLAYER_STATE_ONFOOT - player is on foot
    • -///
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • -///
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • -///
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • -///
  • PLAYER_STATE_SPAWNED - player is spawned
    • -///
  • PLAYER_STATE_SPECTATING - player is spectating
    • -///
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger
    • -///
-/// -/// The player's current state as an integer. -native GetPlayerState(playerid); - -/// Get the specified player's IP address and store it in a string. -/// The ID of the player to get the IP address of -/// An array into which to store the player's IP address, passed by reference -/// The maximum length of the IP address (recommended 16) -/// -/// -/// -/// -/// -/// -/// -/// This function does not work when used in OnPlayerDisconnect because the player is already disconnected. It will return an invalid IP (255.255.255.255). Save players' IPs under OnPlayerConnect if they need to be used under OnPlayerDisconnect. -/// 1 on success and 0 on failure. -native GetPlayerIp(playerid, ip[], len = sizeof ip); - -/// Get the ping of a player. The ping measures the amount of time it takes for the server to 'ping' the client and for the client to send the message back. -/// The ID of the player to get the ping of -/// -/// -/// -/// Player's ping may be 65535 for a while after a player connects -/// The current ping of the player (expressed in milliseconds). +/** + * a_players + * Get a player's current state. + * The ID of the player to get the current state of + * + * + * + * + * States:
+ *
    + *
  • PLAYER_STATE_NONE - empty (while initializing)
    • + *
  • PLAYER_STATE_ONFOOT - player is on foot
    • + *
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • + *
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • + *
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • + *
  • PLAYER_STATE_SPAWNED - player is spawned
    • + *
  • PLAYER_STATE_SPECTATING - player is spectating
    • + *
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger + *
    • + *
+ * + * The player's current state as an integer. + */ +native PLAYER_STATE:GetPlayerState(playerid); + +/** + * a_players + * Get the specified player's IP address and store it in a string. + * The ID of the player to get the IP address of + * An array into which to store the player's IP address, passed by reference + * The maximum length of the IP address (recommended 16) + * + * + * + * + * + * + * + * This function does not work when used in OnPlayerDisconnect + * because the player is already disconnected. It will return an invalid IP (255.255.255.255). + * Save players' IPs under OnPlayerConnect if they need to be used under + * OnPlayerDisconnect. + * 1 on success and 0 on failure. + */ +native GetPlayerIp(playerid, ip[], len = sizeof (ip)); + +/** + * a_players + * Get the ping of a player. The ping measures the amount of time it takes for the server + * to 'ping' the client and for the client to send the message back. + * The ID of the player to get the ping of + * + * + * + * Player's ping may be 65535 for a while after a player connects + * The current ping of the player (expressed in milliseconds). + */ native GetPlayerPing(playerid); -/// Returns the ID of the weapon a player is currently holding. -/// The ID of the player to get the currently held weapon of -/// -/// -/// -/// Prior to version 0.3z R1-2, when the player state is PLAYER_STATE_PASSENGER this function returns the weapon held by the player before they entered the vehicle. If a cheat is used to spawn a weapon inside a vehicle, this function will not report it. -/// The ID of the player's current weapon. Returns -1 if the player specified does not exist. -native GetPlayerWeapon(playerid); - -/// Check which keys a player is pressing. -/// The ID of the player to get the keys of -/// Bitmask containing the player's key states. List of keys -/// Up/down state -/// Left/right state -/// -/// Only the FUNCTION of keys can be detected; not actual keys. For example, it is not possible to detect if a player presses SPACE, but you can detect if they press SPRINT (which can be mapped (assigned/binded) to ANY key (but is space by default)). -/// As of update 0.3.7, the keys "A" and "D" are not recognized when in a vehicle. However, keys "W" and "S" can be detected with the "keys" parameter. -/// The keys are stored in the specified variables. -native GetPlayerKeys(playerid, &keys, &updown, &leftright); - -/// Get a player's name. -/// The ID of the player to get the name of -/// An array into which to store the name, passed by reference -/// The length of the string that should be stored. Recommended to be MAX_PLAYER_NAME -/// -/// -/// -/// -/// -/// A player's name can be up to 24 characters long (as of 0.3d R2) by using SetPlayerName. This is defined in a_samp.inc as MAX_PLAYER_NAME. However, the client can only join with a nickname between 3 and 20 characters, otherwise the connection will be rejected and the player has to quit to choose a valid name. -/// The length of the player's name. 0 if player specified doesn't exist. -native GetPlayerName(playerid, name[], len = sizeof name); - -/// Sets the game time for a player. If a player's clock is enabled (TogglePlayerClock) the time displayed by it will update automatically. -/// The ID of the player to set the game time of -/// Hour to set (0-23) -/// Minutes to set (0-59) -/// -/// -/// -/// Using this function under OnPlayerConnect doesn't work. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// +/** + * a_players + *

Returns the ID of the weapon a player is currently holding. + * The ID of the player to get the currently held weapon of + * + * + * + * Prior to version 0.3z R1-2, when the player state is PLAYER_STATE_PASSENGER + * this function returns the weapon held by the player before they entered the vehicle. If a cheat + * is used to spawn a weapon inside a vehicle, this function will not report it. + * The ID of the player's current weapon. Returns -1 if the player specified + * does not exist. + */ +native WEAPON:GetPlayerWeapon(playerid); + +/** + * a_players + * Check which keys a player is pressing. + * The ID of the player to get the keys of + * Bitmask containing the player's key states. List + * of keys + * Up/down state + * Left/right state + * + * Only the FUNCTION of keys can be detected; not actual keys. For example, it is not possible + * to detect if a player presses SPACE, but you can detect if they press SPRINT (which + * can be mapped (assigned/binded) to ANY key (but is space by default)). + * As of update 0.3.7, the keys "A" and "D" are not recognized when in a vehicle. However, + * keys "W" and "S" can be detected with the "keys" parameter. + * The keys are stored in the specified variables. + */ +native GetPlayerKeys(playerid, &KEY:keys, &KEY:updown, &KEY:leftright); + +/** + * a_players + * Get a player's name. + * The ID of the player to get the name of + * An array into which to store the name, passed by reference + * The length of the string that should be stored. Recommended to be MAX_PLAYER_NAME + * + * + * + * + * + * A player's name can be up to 24 characters long (as of 0.3d R2) by using SetPlayerName. + * This is defined as 24 by default. However, the client can + * only join with a nickname between 3 and 20 characters, otherwise the connection will be rejected + * and the player has to quit to choose a valid name. + * The length of the player's name. 0 if player specified doesn't exist. + */ +native GetPlayerName(playerid, name[], len = sizeof (name)); + +/** + * a_players + * Sets the game time for a player. If a player's clock is enabled (TogglePlayerClock) + * the time displayed by it will update automatically. + * The ID of the player to set the game time of + * Hour to set (0-23) + * Minutes to set (0-59) + * + * + * + * Using this function under OnPlayerConnect doesn't work. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ native SetPlayerTime(playerid, hour, minute); -/// Get the player's current game time. Set by SetWorldTime or SetPlayerTime, or by the game automatically if TogglePlayerClock is used. -/// The ID of the player to get the game time of -/// A variable in which to store the hour, passed by reference -/// A variable in which to store the minutes, passed by reference -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist.

-/// +/** + * a_players + *

Get the player's current game time. Set by SetWorldTime or + * SetPlayerTime, or by the game automatically if TogglePlayerClock + * is used. + * The ID of the player to get the game time of + * A variable in which to store the hour, passed by reference + * A variable in which to store the minutes, passed by reference + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist.
+ * + */ native GetPlayerTime(playerid, &hour, &minute); -/// Toggle the in-game clock (top-right corner) for a specific player. When this is enabled, time will progress at 1 minute per second. Weather will also interpolate (slowly change over time) when set using SetWeather/SetPlayerWeather. -/// The player whose clock you want to enable/disable -/// 1 to show and 0 to hide. Hidden by default -/// Time is not synced with other players! Time can be synced using SetPlayerTime. -/// Time will automatically advance 6 hours when the player dies. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The specified player does not exist. -/// -native TogglePlayerClock(playerid, toggle); - -///

Set a player's weather. -/// The ID of the player whose weather to set -/// The weather to set -/// -/// -/// If TogglePlayerClock is enabled, weather will slowly change over time, instead of changing instantly. +/** + * a_players + * Toggle the in-game clock (top-right corner) for a specific player. When this is enabled, + * time will progress at 1 minute per second. Weather will also interpolate (slowly change over time) + * when set using SetWeather/SetPlayerWeather. + * The player whose clock you want to enable/disable + * 1 to show and 0 to hide. Hidden by default + * Time is not synced with other players! Time can be synced using SetPlayerTime. + * Time will automatically advance 6 hours when the player dies. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The specified player does not exist. + * + */ +native TogglePlayerClock(playerid, bool:toggle); + +/** + * a_players + * Set a player's weather. + * The ID of the player whose weather to set + * The weather to set + * + * + * If TogglePlayerClock is enabled, weather will slowly change + * over time, instead of changing instantly. + */ native SetPlayerWeather(playerid, weather); -/// Forces a player to go back to class selection. -/// The player to send back to class selection -/// -/// -/// -/// -/// The player will not return to class selection until they re-spawn. This can be achieved with TogglePlayerSpectating, as seen in the below example. +/** + * a_players + * Forces a player to go back to class selection. + * The player to send back to class selection + * + * + * + * + * The player will not return to class selection until they re-spawn. This can be achieved + * with TogglePlayerSpectating, as seen in the below example. + */ native ForceClassSelection(playerid); -/// Set a player's wanted level (6 brown stars under HUD). -/// The ID of the player to set the wanted level of -/// The wanted level to set for the player (0-6) -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// +/** + * a_players + *

Set a player's wanted level (6 brown stars under HUD). + * The ID of the player to set the wanted level of + * The wanted level to set for the player (0-6) + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ native SetPlayerWantedLevel(playerid, level); -/// Gets the wanted level of a player. -/// The ID of the player that you want to get the wanted level of -/// -/// -/// The player's wanted level. +/** + * a_players + * Gets the wanted level of a player. + * The ID of the player that you want to get the wanted level of + * + * + * The player's wanted level. + */ native GetPlayerWantedLevel(playerid); -/// Set a player's special fighting style. To use in-game, aim and press the 'secondary attack' key (ENTER by default). -/// The ID of player to set the fighting style of -/// The fighting style that should be set -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This does not affect normal fist attacks - only special/secondary attacks (aim + press 'secondary attack' key). -/// -/// Fighting styles:

-///

    -///
  • FIGHT_STYLE_NORMAL
    • -///
  • FIGHT_STYLE_BOXING
    • -///
  • FIGHT_STYLE_KUNGFU
    • -///
  • FIGHT_STYLE_KNEEHEAD
    • -///
  • FIGHT_STYLE_GRABKICK
    • -///
  • FIGHT_STYLE_ELBOW
    • -///
-/// -native SetPlayerFightingStyle(playerid, style); - -/// Get the fighting style the player currently using. -/// The ID of the player to get the fighting style of -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Fighting styles:

-///

    -///
  • FIGHT_STYLE_NORMAL
    • -///
  • FIGHT_STYLE_BOXING
    • -///
  • FIGHT_STYLE_KUNGFU
    • -///
  • FIGHT_STYLE_KNEEHEAD
    • -///
  • FIGHT_STYLE_GRABKICK
    • -///
  • FIGHT_STYLE_ELBOW
    • -///
-/// -/// The ID of the fighting style of the player. -native GetPlayerFightingStyle(playerid); - -/// Set a player's velocity on the X, Y and Z axes. -/// The player to apply the speed to -/// The velocity (speed) on the X axis -/// The velocity (speed) on the Y axis -/// The velocity (speed) on the Z axis -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// -native SetPlayerVelocity(playerid, Float:X, Float:Y, Float:Z); - -///

Get the velocity (speed) of a player on the X, Y and Z axes. -/// The player to get the speed from -/// A float variable in which to store the velocity on the X axis, passed by reference -/// A float variable in which to store the velocity on the Y axis, passed by reference -/// A float variable in which to store the velocity on the Z axis, passed by reference -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -native GetPlayerVelocity( playerid, &Float:X, &Float:Y, &Float:Z ); - -/// This function plays a crime report for a player - just like in single-player when CJ commits a crime. -/// The ID of the player that will hear the crime report -/// The ID of the suspect player whom will be described in the crime report -/// The crime ID, which will be reported as a 10-code (i.e. 10-16 if 16 was passed as the crime) -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Crime list:

-///

    -///
  • 3 10-71 Advise nature of fire (size, type, contents of building)
    • -///
  • 4 10-47 Emergency road repairs needed
    • -///
  • 5 10-81 Breatherlizer Report
    • -///
  • 6 10-24 Assignment Completed
    • -///
  • 7 10-21 Call () by phone
    • -///
  • 8 10-21 Call () by phone
    • -///
  • 9 10-21 Call () by phone
    • -///
  • 10 10-17 Meet Complainant
    • -///
  • 11 10-81 Breatherlizer Report
    • -///
  • 12 10-91 Pick up prisoner/subject
    • -///
  • 13 10-28 Vehicle registration information
    • -///
  • 14 10-81 Breathalyzer
    • -///
  • 15 10-28 Vehicle registration information
    • -///
  • 16 10-91 Pick up prisoner/subject
    • -///
  • 17 10-34 Riot
    • -///
  • 18 10-37 (Investigate) suspicious vehicle
    • -///
  • 19 10-81 Breathalyzer
    • -///
  • 21 10-7 Out of service
    • -///
  • 22 10-7 Out of service
    • -///
-/// +/** + * a_players + * Set a player's special fighting style. To use in-game, aim and press the 'secondary attack' + * key (ENTER by default). + * The ID of player to set the fighting style of + * The fighting style that should be set + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This does not affect normal fist attacks - only special/secondary attacks (aim + press 'secondary + * attack' key). + * + * Fighting styles:
+ *
    + *
  • FIGHT_STYLE_NORMAL
    • + *
  • FIGHT_STYLE_BOXING
    • + *
  • FIGHT_STYLE_KUNGFU
    • + *
  • FIGHT_STYLE_KNEEHEAD
    • + *
  • FIGHT_STYLE_GRABKICK
    • + *
  • FIGHT_STYLE_ELBOW
    • + *
+ * + */ +native SetPlayerFightingStyle(playerid, FIGHT_STYLE:style); + +/** + * a_players + * Get the fighting style the player currently using. + * The ID of the player to get the fighting style of + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Fighting styles:
+ *
    + *
  • FIGHT_STYLE_NORMAL
    • + *
  • FIGHT_STYLE_BOXING
    • + *
  • FIGHT_STYLE_KUNGFU
    • + *
  • FIGHT_STYLE_KNEEHEAD
    • + *
  • FIGHT_STYLE_GRABKICK
    • + *
  • FIGHT_STYLE_ELBOW
    • + *
+ * + * The ID of the fighting style of the player. + */ +native FIGHT_STYLE:GetPlayerFightingStyle(playerid); + +/** + * a_players + * Set a player's velocity on the x, y and z axes. + * The player to apply the speed to + * The velocity (speed) on the x axis + * The velocity (speed) on the y axis + * The velocity (speed) on the z axis + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ +native SetPlayerVelocity(playerid, Float:x, Float:y, Float:z); + +/** + * a_players + * Get the velocity (speed) of a player on the x, y and z axes. + * The player to get the speed from + * A float variable in which to store the velocity on the x axis, passed by reference + * A float variable in which to store the velocity on the y axis, passed by reference + * A float variable in which to store the velocity on the z axis, passed by reference + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native GetPlayerVelocity(playerid, &Float:x, &Float:y, &Float:z); + +/** + * a_players + * This function plays a crime report for a player - just like in single-player when CJ commits + * a crime. + * The ID of the player that will hear the crime report + * The ID of the suspect player whom will be described in the crime report + * The crime ID, which will be reported as a 10-code (i.e. 10-16 if 16 was passed + * as the crime) + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Crime list:
+ *
    + *
  • 3 10-71 Advise nature of fire (size, type, contents of building)
    • + *
  • 4 10-47 Emergency road repairs needed
    • + *
  • 5 10-81 Breatherlizer Report
    • + *
  • 6 10-24 Assignment Completed
    • + *
  • 7 10-21 Call () by phone
    • + *
  • 8 10-21 Call () by phone
    • + *
  • 9 10-21 Call () by phone
    • + *
  • 10 10-17 Meet Complainant
    • + *
  • 11 10-81 Breatherlizer Report
    • + *
  • 12 10-91 Pick up prisoner/subject
    • + *
  • 13 10-28 Vehicle registration information
    • + *
  • 14 10-81 Breathalyzer
    • + *
  • 15 10-28 Vehicle registration information
    • + *
  • 16 10-91 Pick up prisoner/subject
    • + *
  • 17 10-34 Riot
    • + *
  • 18 10-37 (Investigate) suspicious vehicle
    • + *
  • 19 10-81 Breathalyzer
    • + *
  • 21 10-7 Out of service
    • + *
  • 22 10-7 Out of service
    • + *
+ * + */ native PlayCrimeReportForPlayer(playerid, suspectid, crime); -/// Play an 'audio stream' for a player. Normal audio files also work (e.g. MP3). -/// The ID of the player to play the audio for -/// The url to play. Valid formats are mp3 and ogg/vorbis. A link to a .pls (playlist) file will play that playlist -/// The X position at which to play the audio. Has no effect unless usepos is set to 1 (optional=0.0) -/// The Y position at which to play the audio. Has no effect unless usepos is set to 1 (optional=0.0) -/// The Z position at which to play the audio. Has no effect unless usepos is set to 1 (optional=0.0) -/// The distance over which the audio will be heard. Has no effect unless usepos is set to 1 (optional=50.0) -/// Use the positions and distance specified. (optional=0) -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// -native PlayAudioStreamForPlayer(playerid, const url[], Float:posX = 0.0, Float:posY = 0.0, Float:posZ = 0.0, Float:distance = 50.0, usepos = 0); - -///

Stops the current audio stream for a player. -/// The player you want to stop the audio stream for -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! +/** + * a_players + * Play an 'audio stream' for a player. Normal audio files also work (e.g. MP3). + * The ID of the player to play the audio for + * The url to play. Valid formats are mp3 and ogg/vorbis. A link to a .pls (playlist) + * file will play that playlist + * The x position at which to play the audio. Has no effect unless usepos is set + * to 1 (optional=0.0) + * The y position at which to play the audio. Has no effect unless usepos is set + * to 1 (optional=0.0) + * The z position at which to play the audio. Has no effect unless usepos is set + * to 1 (optional=0.0) + * The distance over which the audio will be heard. Has no effect unless usepos + * is set to 1 (optional=50.0) + * Use the positions and distance specified. (optional=0) + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ +native PlayAudioStreamForPlayer(playerid, const url[], Float:posX = 0.0, Float:posY = 0.0, Float:posZ = 0.0, Float:distance = 50.0, bool:usepos = false); + +/** + * a_players + * Stops the current audio stream for a player. + * The player you want to stop the audio stream for + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + */ native StopAudioStreamForPlayer(playerid); -/// Loads or unloads an interior script for a player (for example the ammunation menu). -/// The ID of the player to load the interior script for -/// The shop script to load. Leave blank ("") to unload scripts -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This function does not support casino scripts. -/// -/// Shop names:

-///

    -///
  • "FDPIZA" Pizza Stack
    • -///
  • "FDBURG" Burger Shot
    • -///
  • "FDCHICK"Cluckin' Bell
    • -///
  • "AMMUN1" Ammunation 1
    • -///
  • "AMMUN2" Ammunation 2
    • -///
  • "AMMUN3" Ammunation 3
    • -///
  • "AMMUN4" Ammunation 4
    • -///
  • "AMMUN5" Ammunation 5
    • -///
-/// -native SetPlayerShopName(playerid, const shopname[]); - -/// Set the skill level of a certain weapon type for a player. -/// The ID of the player to set the weapon skill of -/// The weapon to set the skill of -/// The skill level to set for that weapon, ranging from 0 to 999. A level out of range will max it out -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Weapon skills:

-///

    -///
  • WEAPONSKILL_PISTOL(0)
    • -///
  • WEAPONSKILL_PISTOL_SILENCED(1)
    • -///
  • WEAPONSKILL_DESERT_EAGLE(2)
    • -///
  • WEAPONSKILL_SHOTGUN(3)
    • -///
  • WEAPONSKILL_SAWNOFF_SHOTGUN(4)
    • -///
  • WEAPONSKILL_SPAS12_SHOTGUN(5)
    • -///
  • WEAPONSKILL_MICRO_UZI(6)
    • -///
  • WEAPONSKILL_MP5(7)
    • -///
  • WEAPONSKILL_AK47(8)
    • -///
  • WEAPONSKILL_M4(9)
    • -///
  • WEAPONSKILL_SNIPERRIFLE(10)
    • -///
-/// -native SetPlayerSkillLevel(playerid, skill, level); - -/// Get the ID of the vehicle that the player is surfing (stuck to the roof of). -/// The ID of the player you want to know the surfing vehicle ID of -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// The ID of the vehicle that the player is surfing. If they are not surfing a vehicle or the vehicle they are surfing has no driver, INVALID_VEHICLE_ID. If the player specified is not connected, INVALID_VEHICLE_ID also. +/** + * a_players + * Loads or unloads an interior script for a player (for example the ammunation menu). + * The ID of the player to load the interior script for + * The shop script to load. Leave blank ("") to unload scripts + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This function does not support casino scripts. + * + * Shop names:
+ *
    + *
  • "FDPIZA" Pizza Stack
    • + *
  • "FDBURG" Burger Shot
    • + *
  • "FDCHICK"Cluckin' Bell
    • + *
  • "AMMUN1" Ammunation 1
    • + *
  • "AMMUN2" Ammunation 2
    • + *
  • "AMMUN3" Ammunation 3
    • + *
  • "AMMUN4" Ammunation 4
    • + *
  • "AMMUN5" Ammunation 5
    • + *
+ * + */ +native SetPlayerShopName(playerid, const shopName[]); + +/** + * a_players + * Set the skill level of a certain weapon type for a player. + * The ID of the player to set the weapon skill of + * The weapon to set the skill of + * The skill level to set for that weapon, ranging from 0 to 999. + * A level out of range will max it out + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Weapon skills:
+ *
    + *
  • WEAPONSKILL_PISTOL(0)
    • + *
  • WEAPONSKILL_PISTOL_SILENCED(1)
    • + *
  • WEAPONSKILL_DESERT_EAGLE(2)
    • + *
  • WEAPONSKILL_SHOTGUN(3)
    • + *
  • WEAPONSKILL_SAWNOFF_SHOTGUN(4)
    • + *
  • WEAPONSKILL_SPAS12_SHOTGUN(5)
    • + *
  • WEAPONSKILL_MICRO_UZI(6)
    • + *
  • WEAPONSKILL_MP5(7)
    • + *
  • WEAPONSKILL_AK47(8)
    • + *
  • WEAPONSKILL_M4(9)
    • + *
  • WEAPONSKILL_SNIPERRIFLE(10)
    • + *
+ * + */ +native SetPlayerSkillLevel(playerid, WEAPONSKILL:skill, level); + +/** + * a_players + * Get the ID of the vehicle that the player is surfing (stuck to the roof of). + * The ID of the player you want to know the surfing vehicle ID of + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * The ID of the vehicle that the player is surfing. If they are not surfing a vehicle or + * the vehicle they are surfing has no driver, INVALID_VEHICLE_ID. If the player specified + * is not connected, INVALID_VEHICLE_ID also. + */ native GetPlayerSurfingVehicleID(playerid); -/// Returns the ID of the object the player is surfing on. -/// The ID of the player surfing the object -/// This function was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// The ID of the moving object the player is surfing. If the player isn't surfing a moving object, it will return INVALID_OBJECT_ID. +/** + * a_players + * Returns the ID of the object the player is surfing on. + * The ID of the player surfing the object + * This function was added in SA-MP 0.3c R3 and will not work in earlier versions! + * The ID of the moving object the player is surfing. If the player isn't surfing a + * moving object, it will return INVALID_OBJECT_ID. + */ native GetPlayerSurfingObjectID(playerid); -/// Removes a standard San Andreas model for a single player within a specified range. -/// The ID of the player to remove the objects for -/// The model to remove -/// The X coordinate around which the objects will be removed -/// The Y coordinate around which the objects will be removed -/// The Z coordinate around which the objects will be removed -/// The radius around the specified point to remove objects with the specified model -/// -/// -/// This function was added in SA-MP 0.3d and will not work in earlier versions! -/// There appears to be a limit of around 1000 lines/objects. There is no workaround. -/// When removing the same object for a player, they will crash. Commonly, players crash when reconnecting to the server because the server removes buildings on OnPlayerConnect. -/// In SA-MP 0.3.7 you can use -1 for the modelid to remove all objects within the specified radius. -native RemoveBuildingForPlayer(playerid, modelid, Float:fX, Float:fY, Float:fZ, Float:fRadius); - -/// Retrieves the start and end (hit) position of the last bullet a player fired. -/// The ID of the player to get the last bullet shot information of -/// A float variable in which to save the X coordinate of where the bullet originated from -/// A float variable in which to save the Y coordinate of where the bullet originated from -/// A float variable in which to save the Z coordinate of where the bullet originated from -/// A float variable in which to save the X coordinate of where the bullet hit -/// A float variable in which to save the Y coordinate of where the bullet hit -/// A float variable in which to save the Z coordinate of where the bullet hit -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// This function will only work when lag compensation is enabled. -/// If the player hit nothing, the hit positions will be 0. This means you can't currently calculate how far a bullet travels through open air. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist.

-/// -native GetPlayerLastShotVectors(playerid, &Float:fOriginX, &Float:fOriginY, &Float:fOriginZ, &Float:fHitPosX, &Float:fHitPosY, &Float:fHitPosZ); +/** + * a_players + *

Removes a standard San Andreas model for a single player within a specified range. + * The ID of the player to remove the objects for + * The model to remove + * The x coordinate around which the objects will be removed + * The y coordinate around which the objects will be removed + * The z coordinate around which the objects will be removed + * The radius around the specified point to remove objects with the specified model + * + * + * This function was added in SA-MP 0.3d and will not work in earlier versions! + * There appears to be a limit of around 1000 lines/objects. There is no workaround. + * + * When removing the same object for a player, they will crash. Commonly, players crash when + * reconnecting to the server because the server removes buildings on OnPlayerConnect. + * + * In SA-MP 0.3.7 you can use -1 for the modelid to remove all objects + * within the specified radius. + */ +native RemoveBuildingForPlayer(playerid, modelid, Float:centerX, Float:centerY, Float:centerZ, Float:radius); + +/** + * a_players + * Retrieves the start and end (hit) position of the last bullet a player fired. + * The ID of the player to get the last bullet shot information of + * A float variable in which to save the x coordinate of where the bullet originated + * from + * A float variable in which to save the y coordinate of where the bullet originated + * from + * A float variable in which to save the z coordinate of where the bullet originated + * from + * A float variable in which to save the x coordinate of where the bullet hit + * A float variable in which to save the y coordinate of where the bullet hit + * A float variable in which to save the z coordinate of where the bullet hit + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * This function will only work when lag + * compensation is enabled. + * If the player hit nothing, the hit positions will be 0. This means you can't + * currently calculate how far a bullet travels through open air. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist.
+ * + */ +native GetPlayerLastShotVectors(playerid, &Float:originX, &Float:originY, &Float:originZ, &Float:hitPosX, &Float:hitPosY, &Float:hitPosZ); // Attached to bone objects #if MAX_PLAYER_ATTACHED_OBJECTS < 1 || MAX_PLAYER_ATTACHED_OBJECTS > 10 #error MAX_PLAYER_ATTACHED_OBJECTS must be >= 1 and <= 10 #endif -/// Attach an object to a specific bone on a player. -/// The ID of the player to attach the object to -/// The index (slot) to assign the object to (0-9 since 0.3d, 0-4 in previous versions) -/// The model to attach -/// The bone to attach the object to -/// X axis offset for the object position (optional=0.0) -/// Y axis offset for the object position (optional=0.0) -/// Z axis offset for the object position (optional=0.0) -/// X axis rotation of the object (optional=0.0) -/// Y axis rotation of the object (optional=0.0) -/// Z axis rotation of the object (optional=0.0) -/// X axis scale of the object (optional=1.0) -/// Y axis scale of the object (optional=1.0) -/// Z axis scale of the object (optional=1.0) -/// The first object color to set ARGB (optional=0) -/// The second object color to set ARGB (optional=0) -/// -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// In version 0.3d and onwards, 10 objects can be attached to a single player (index 0-9). In earlier versions, the limit is 5 (index 0-4). -/// This function is separate from the CreateObject / CreatePlayerObject pools. -/// -/// Bone IDs:

-///

    -///
  • 1 - spine
    • -///
  • 2 - head
    • -///
  • 3 - left upper arm
    • -///
  • 4 - right upper arm
    • -///
  • 5 - left hand
    • -///
  • 6 - right hand
    • -///
  • 7 - left thigh
    • -///
  • 8 - right thigh
    • -///
  • 9 - left foot
    • -///
  • 10 - right foot
    • -///
  • 11 - right calf
    • -///
  • 12 - left calf
    • -///
  • 13 - left forearm
    • -///
  • 14 - right forearm
    • -///
  • 15 - left clavicle (shoulder)
    • -///
  • 16 - right clavicle (shoulder)
    • -///
  • 17 - neck
    • -///
  • 18 - jaw
    • -///
-/// -/// 1 on success, 0 on failure. -native SetPlayerAttachedObject(playerid, index, modelid, bone, Float:fOffsetX = 0.0, Float:fOffsetY = 0.0, Float:fOffsetZ = 0.0, Float:fRotX = 0.0, Float:fRotY = 0.0, Float:fRotZ = 0.0, Float:fScaleX = 1.0, Float:fScaleY = 1.0, Float:fScaleZ = 1.0, materialcolor1 = 0, materialcolor2 = 0); - -/// Remove an attached object from a player. -/// The ID of the player to remove the object from -/// The index of the object to remove (set with SetPlayerAttachedObject) -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// 1 on success, 0 on failure. +/** + * a_players + * Attach an object to a specific bone on a player. + * The ID of the player to attach the object to + * The index (slot) to assign the object to (0-9 since 0.3d, 0-4 in previous versions) + * The model to attach + * The bone to attach the object to + * x axis offset for the object position (optional=0.0) + * y axis offset for the object position (optional=0.0) + * z axis offset for the object position (optional=0.0) + * x axis rotation of the object (optional=0.0) + * y axis rotation of the object (optional=0.0) + * z axis rotation of the object (optional=0.0) + * x axis scale of the object (optional=1.0) + * y axis scale of the object (optional=1.0) + * z axis scale of the object (optional=1.0) + * The first object colour to set ARGB (optional=0) + * The second object colour to set ARGB (optional=0) + * + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * In version 0.3d and onwards, 10 objects can be attached to a single + * player (index 0-9). In earlier versions, the limit is 5 + * (index 0-4). + * This function is separate from the CreateObject/ + * CreatePlayerObject + * pools. + * + * Bone IDs:
+ *
    + *
  • 1 - spine
    • + *
  • 2 - head
    • + *
  • 3 - left upper arm
    • + *
  • 4 - right upper arm
    • + *
  • 5 - left hand
    • + *
  • 6 - right hand
    • + *
  • 7 - left thigh
    • + *
  • 8 - right thigh
    • + *
  • 9 - left foot
    • + *
  • 10 - right foot
    • + *
  • 11 - right calf
    • + *
  • 12 - left calf
    • + *
  • 13 - left forearm
    • + *
  • 14 - right forearm
    • + *
  • 15 - left clavicle (shoulder)
    • + *
  • 16 - right clavicle (shoulder)
    • + *
  • 17 - neck
    • + *
  • 18 - jaw
    • + *
+ * + * 1 on success, 0 on failure. + */ +native SetPlayerAttachedObject(playerid, index, modelid, bone, Float:offsetX = 0.0, Float:offsetY = 0.0, Float:offsetZ = 0.0, Float:rotX = 0.0, Float:rotY = 0.0, Float:rotZ = 0.0, Float:scaleX = 1.0, Float:scaleY = 1.0, Float:scaleZ = 1.0, materialColour1 = 0, materialColour2 = 0); + +/** + * a_players + * Remove an attached object from a player. + * The ID of the player to remove the object from + * The index of the object to remove (set with SetPlayerAttachedObject) + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * 1 on success, 0 on failure. + */ native RemovePlayerAttachedObject(playerid, index); -/// Check if a player has an object attached in the specified index (slot). -/// The ID of the player to check -/// The index (slot) to check -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// 1 if used, 0 if not. -native IsPlayerAttachedObjectSlotUsed(playerid, index); - -/// Enter edition mode for an attached object. -/// The ID of the player to enter in to edition mode -/// The index (slot) of the attached object to edit -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// You can move the camera while editing by pressing and holding the spacebar (or W in vehicle) and moving your mouse. -/// -/// There are 7 clickable buttons in edition mode.

-/// The three single icons that have X/Y/Z on them can be dragged to edit position/rotation/scale.

-/// The four buttons in a row are to select the edition mode and save edition: [Move] [Rotate] [Scale] [Save].

-/// Clicking save will call OnPlayerEditAttachedObject. -/// -/// Players will be able to scale objects up to a very large or negative value size. Limits should be put in place using OnPlayerEditAttachedObject to abort the edit. -/// 1 on success and 0 on failure. +/** + * a_players + *

Check if a player has an object attached in the specified index (slot). + * The ID of the player to check + * The index (slot) to check + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * 1 if used, 0 if not. + */ +native bool:IsPlayerAttachedObjectSlotUsed(playerid, index); + +/** + * a_players + * Enter edition mode for an attached object. + * The ID of the player to enter in to edition mode + * The index (slot) of the attached object to edit + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * You can move the camera while editing by pressing and holding the spacebar (or W + * in vehicle) and moving your mouse. + * + * There are 7 clickable buttons in edition mode.
+ * The three single icons that have x/y/z on them can be dragged to edit position/rotation/scale.
+ * The four buttons in a row are to select the edition mode and save edition: [Move] [Rotate] [Scale] + * [Save].
+ * Clicking save will call OnPlayerEditAttachedObject. + * + * Players will be able to scale objects up to a very large or negative value size. Limits + * should be put in place using OnPlayerEditAttachedObject + * to abort the edit. + * 1 on success and 0 on failure. + */ native EditAttachedObject(playerid, index); // Per-player TextDraws -/// Creates a textdraw for a single player. This can be used as a way around the global text-draw limit. -/// The ID of the player to create the textdraw for -/// X-Coordinate -/// Y-Coordinate -/// The text in the textdraw -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// -/// If you choose values for y that are less than 1, the first text row will be invisible and only the shadow is visible.

-/// must NOT be empty or the server will crash! If you need a textdraw that shows nothing, use " " (a space) or _ (underscore)

-/// If the last character in the text is a space (" "), the text will all be blank.

-/// If part of the text is off-screen, the color of the text will not show, only the shadow (if enabled) will.

-/// -/// -/// This applies ONLY to sa-mp versions before 0.3z:

-/// Maximum length of textdraw is 800 characters. Longer text will crash the client in older versions.

-/// If you use color codes (such as ~R~ ~G~) beyond 255th character the client will crash trying to display the textdraw.

-/// -/// Keyboard key mapping codes (such as ~k~~VEHICLE_ENTER_EXIT~ Doesn't work beyond 255th character. -/// -/// 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 PlayerTextDrawAlignment with alignment 3 (right), the x,y coordinate is the top right coordinate for the text draw.

-/// This function merely CREATES the textdraw, you must use PlayerTextDrawShow to show it to a player.

-/// It is recommended to use WHOLE numbers instead of decimal positions when creating player textdraws to ensure resolution friendly design.

-/// -/// Player-textdraws are automatically destroyed when a player disconnects. -/// The ID of the created textdraw. +/** + * a_players + *

Creates a textdraw for a single player. This can be used as a way around the global + * text-draw limit. + * The ID of the player to create the textdraw for + * x-Coordinate + * y-Coordinate + * The text in the textdraw + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * + * If you choose values for y that are less than 1, the first text row will be invisible and only + * the shadow is visible.
+ * must NOT be empty or the server will crash! If you need a textdraw + * that shows nothing, use " " (a space) or _ (underscore)
+ * If the last character in the text is a space (" "), the text will all be blank.
+ * If part of the text is off-screen, the colour of the text will not show, only the shadow (if enabled) + * will.
+ * + * + * This applies ONLY to sa-mp versions before 0.3z:

+ * Maximum length of textdraw is 800 characters. Longer text will crash the client + * in older versions.
+ * If you use colour codes (such as ~R~ ~G~) beyond 255th character the client will + * crash trying to display the textdraw.
+ * + * Keyboard key mapping codes (such as ~k~~VEHICLE_ENTER_EXIT~ Doesn't work beyond + * 255th character. + * + * 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 PlayerTextDrawAlignment + * with alignment 3 (right), the x, y coordinate is the top right coordinate for the text + * draw.
+ * This function merely CREATES the textdraw, you must use PlayerTextDrawShow + * to show it to a player.
+ * It is recommended to use WHOLE numbers instead of decimal positions when creating player textdraws + * to ensure resolution friendly design.
+ * + * Player-textdraws are automatically destroyed when a player disconnects. + * The ID of the created textdraw. + */ native PlayerText:CreatePlayerTextDraw(playerid, Float:x, Float:y, const text[]); -/// Destroy a player-textdraw. -/// The ID of the player who's player-textdraw to destroy -/// The ID of the textdraw to destroy -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_players + * Destroy a player-textdraw. + * The ID of the player who's player-textdraw to destroy + * The ID of the textdraw to destroy + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ native PlayerTextDrawDestroy(playerid, PlayerText:text); -/// Sets the width and height of the letters in a player-textdraw. -/// The ID of the player whose player-textdraw to set the letter size of -/// The ID of the player-textdraw to change the letter size of -/// Width of a char -/// Height of a char -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// When using this function purely for the benefit of affecting the textdraw box, multiply 'Y' by 0.135 to convert to TextDrawTextSize-like measurements -/// Fonts appear to look the best with an X to Y ratio of 1 to 4 (e.g. if x is 0.5 then y should be 2). -native PlayerTextDrawLetterSize(playerid, PlayerText:text, Float:x, Float:y); - -/// Change the size of a player-textdraw (box if PlayerTextDrawUseBox is enabled and/or clickable area for use with PlayerTextDrawSetSelectable). -/// The ID of the player whose player-textdraw to set the size of -/// The ID of the player-textdraw to set the size of -/// The size on the X axis (left/right) following the same 640x480 grid as TextDrawCreate -/// The size on the Y axis (up/down) following the same 640x480 grid as TextDrawCreate -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// -/// The x and y have different meanings with different PlayerTextDrawAlignment values:

-///

    -///
  • 1 (left): they are the right-most corner of the box, absolute coordinates.
    • -///
  • 2 (center): they need to inverted (switch the two) and the x value is the overall width of the box.
    • -///
  • 3 (right): the x and y are the coordinates of the left-most corner of the box
    • -///
-/// -/// -/// Using font type 4 (sprite) and 5 (model preview) converts X and Y of this function from corner coordinates to WIDTH and HEIGHT (offsets).

-/// The TextDraw box starts 10.0 units up and 5.0 to the left as the origin (TextDrawCreate coordinate).

-/// This function defines the clickable area for use with PlayerTextDrawSetSelectable, whether a box is shown or not. -/// -native PlayerTextDrawTextSize(playerid, PlayerText:text, Float:x, Float:y); - -///

Set the text alignment of a player-textdraw. -/// The ID of the player whose player-textdraw to set the alignment of -/// The ID of the player-textdraw to set the alignment of -/// 1-left 2-centered 3-right -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// For alignment 2 (center) the x and y values of TextSize need to be swapped, see notes at PlayerTextDrawTextSize. -native PlayerTextDrawAlignment(playerid, PlayerText:text, alignment); - -/// Sets the text color of a player-textdraw. -/// The ID of the player who's textdraw to set the color of -/// The TextDraw to change -/// The color in hexadecimal format -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// You can also use Gametext colors in textdraws. -/// The textdraw must be re-shown to the player in order to update the color. -native PlayerTextDrawColor(playerid, PlayerText:text, color); - -/// Toggle the box on a player-textdraw. -/// The ID of the player whose textdraw to toggle the box of -/// The ID of the player-textdraw to toggle the box of -/// 1 to use a box or 0 to not use a box -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -native PlayerTextDrawUseBox(playerid, PlayerText:text, use); - -/// Sets the color of a textdraw's box (PlayerTextDrawUseBox). -/// The ID of the player whose textdraw to set the box color of -/// The ID of the player textdraw to set the box color of -/// The color to set. Alpha (transparency) is supported -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -native PlayerTextDrawBoxColor(playerid, PlayerText:text, color); - -/// Show a player-textdraw to the player it was created for. -/// The ID of the player to show the textdraw for -/// The ID of the textdraw to show -/// The size of the shadow. 0 will hide the shadow -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_players + * Sets the width and height of the letters in a player-textdraw. + * The ID of the player whose player-textdraw to set the letter size of + * The ID of the player-textdraw to change the letter size of + * Width of a char + * Height of a char + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * When using this function purely for the benefit of affecting the textdraw box, multiply + * 'y' by 0.135 to convert to TextDrawTextSize-like measurements + * Fonts appear to look the best with an x to y ratio of 1 to 4 + * (e.g. if x is 0.5 then y should be 2). + */ +native PlayerTextDrawLetterSize(playerid, PlayerText:text, Float:width, Float:height); + +/** + * a_players + * Change the size of a player-textdraw (box if PlayerTextDrawUseBox + * is enabled and/or clickable area for use with PlayerTextDrawSetSelectable). + * The ID of the player whose player-textdraw to set the size of + * The ID of the player-textdraw to set the size of + * The size on the x axis (left/right) following the same 640x480 grid as + * TextDrawCreate + * The size on the y axis (up/down) following the same 640x480 grid as + * TextDrawCreate + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * + * The x and y have different meanings with different PlayerTextDrawAlignment values:
+ *
    + *
  • 1 (left): they are the right-most corner of the box, absolute coordinates.
    • + *
  • 2 (center): they need to inverted (switch the two) and the x value is the overall + * width of the box.
    • + *
  • 3 (right): the x and y are the coordinates of the left-most corner of the box + *
    • + *
+ * + * + * Using font type 4 (sprite) and 5 (model preview) converts x and y of + * this function from corner coordinates to WIDTH and HEIGHT (offsets).
+ * The TextDraw box starts 10.0 units up and 5.0 to the left as the origin + * (TextDrawCreate coordinate).
+ * This function defines the clickable area for use with PlayerTextDrawSetSelectable, + * whether a box is shown or not. + * + */ +native PlayerTextDrawTextSize(playerid, PlayerText:text, Float:width, Float:height); + +/** + * a_players + * Set the text alignment of a player-textdraw. + * The ID of the player whose player-textdraw to set the alignment of + * The ID of the player-textdraw to set the alignment of + * 1-left 2-centered 3-right + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * For alignment 2 (center) the x and y values of TextSize need to be swapped, + * see notes at PlayerTextDrawTextSize. + */ +native PlayerTextDrawAlignment(playerid, PlayerText:text, TEXT_DRAW_ALIGN:alignment); + +/** + * a_players + * Sets the text colour of a player-textdraw. + * The ID of the player who's textdraw to set the colour of + * The TextDraw to change + * The colour in hexadecimal format + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * You can also use Gametext colours in textdraws. + * The textdraw must be re-shown to the player in order to update the colour. + */ +native PlayerTextDrawColor(playerid, PlayerText:text, colour); + +/** + * a_players + * Toggle the box on a player-textdraw. + * The ID of the player whose textdraw to toggle the box of + * The ID of the player-textdraw to toggle the box of + * 1 to use a box or 0 to not use a box + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ +native PlayerTextDrawUseBox(playerid, PlayerText:text, bool:use); + +/** + * a_players + * Sets the colour of a textdraw's box (PlayerTextDrawUseBox). + * The ID of the player whose textdraw to set the box colour of + * The ID of the player textdraw to set the box colour of + * The colour to set. Alpha (transparency) is supported + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ +native PlayerTextDrawBoxColor(playerid, PlayerText:text, colour); + +/** + * a_players + * Show a player-textdraw to the player it was created for. + * The ID of the player to show the textdraw for + * The ID of the textdraw to show + * The size of the shadow. 0 will hide the shadow + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ native PlayerTextDrawSetShadow(playerid, PlayerText:text, size); -/// Set the outline of a player-textdraw. The outline colour cannot be changed unless PlayerTextDrawBackgroundColor is used. -/// The ID of the player whose player-textdraw to set the outline of -/// The ID of the player-textdraw to set the outline of -/// The thickness of the outline -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_players + * Set the outline of a player-textdraw. The outline colour cannot be changed unless + * PlayerTextDrawBackgroundColor + * is used. + * The ID of the player whose player-textdraw to set the outline of + * The ID of the player-textdraw to set the outline of + * The thickness of the outline + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ native PlayerTextDrawSetOutline(playerid, PlayerText:text, size); -/// Adjust the background color of a player-textdraw. -/// The ID of the player whose player-textdraw to set the background color of -/// The ID of the player-textdraw to set the background color of -/// The color that the textdraw should be set to -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// If PlayerTextDrawSetOutline is used with size > 0, the outline color will match the color used in PlayerTextDrawBackgroundColor. Changing the value of color seems to alter the color used in PlayerTextDrawColor -native PlayerTextDrawBackgroundColor(playerid, PlayerText:text, color); - -/// Change the font of a player-textdraw. -/// The ID of the player whose player-textdraw to change the font of -/// The ID of the player-textdraw to change the font of -/// There are four font styles. A font value greater than 3 does not display, and anything greater than 16 crashes the client. See http://wiki.sa-mp.com/wiki/PlayerTextDrawFont -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -native PlayerTextDrawFont(playerid, PlayerText:text, font); - -/// Appears to scale text spacing to a proportional ratio. Useful when using PlayerTextDrawLetterSize to ensure the text has even character spacing. -/// The ID of the player whose player-textdraw to set the proportionality of -/// The ID of the player-textdraw to set the proportionality of -/// 1 to enable proportionality, 0 to disable -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -native PlayerTextDrawSetProportional(playerid, PlayerText:text, set); - -/// Toggles whether a player-textdraw can be selected or not. -/// The ID of the player whose player-textdraw to set the selectability of -/// The ID of the player-textdraw to set the selectability of -/// Set the player-textdraw selectable (1) or non-selectable (0). By default this is 0 -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// PlayerTextDrawSetSelectable MUST be used BEFORE the textdraw is shown to the player. -/// Use PlayerTextDrawTextSize to define the clickable area. -native PlayerTextDrawSetSelectable(playerid, PlayerText:text, set); - -/// Show a player-textdraw to the player it was created for. -/// The ID of the player to show the textdraw for -/// The ID of the textdraw to show -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_players + * Adjust the background colour of a player-textdraw. + * The ID of the player whose player-textdraw to set the background colour of + * The ID of the player-textdraw to set the background colour of + * The colour that the textdraw should be set to + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * If PlayerTextDrawSetOutline is used with size > + * 0, the outline colour will match the colour used in PlayerTextDrawBackgroundColor. + * Changing the value of colour seems to alter the colour used in PlayerTextDrawColor + */ +native PlayerTextDrawBackgroundColor(playerid, PlayerText:text, colour); + +/** + * a_players + * Change the font of a player-textdraw. + * The ID of the player whose player-textdraw to change the font of + * The ID of the player-textdraw to change the font of + * There are four font styles. A font value greater than 3 does not + * display, and anything greater than 16 crashes the client. See + * http://wiki.sa-mp.com/wiki/PlayerTextDrawFont + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ +native PlayerTextDrawFont(playerid, PlayerText:text, TEXT_DRAW_FONT:font); + +/** + * a_players + * Appears to scale text spacing to a proportional ratio. Useful when using + * PlayerTextDrawLetterSize + * to ensure the text has even character spacing. + * The ID of the player whose player-textdraw to set the proportionality of + * The ID of the player-textdraw to set the proportionality of + * 1 to enable proportionality, 0 to disable + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ +native PlayerTextDrawSetProportional(playerid, PlayerText:text, bool:set); + +/** + * a_players + * Toggles whether a player-textdraw can be selected or not. + * The ID of the player whose player-textdraw to set the selectability of + * The ID of the player-textdraw to set the selectability of + * Set the player-textdraw selectable (1) or non-selectable (0). + * By default this is 0 + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * PlayerTextDrawSetSelectable MUST be used BEFORE + * the textdraw is shown to the player. + * Use PlayerTextDrawTextSize to define the clickable + * area. + */ +native PlayerTextDrawSetSelectable(playerid, PlayerText:text, bool:set); + +/** + * a_players + * Show a player-textdraw to the player it was created for. + * The ID of the player to show the textdraw for + * The ID of the textdraw to show + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ native PlayerTextDrawShow(playerid, PlayerText:text); -/// Hide a player-textdraw from the player it was created for. -/// The ID of the player to hide the textdraw for -/// The ID of the textdraw to hide -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! +/** + * a_players + * Hide a player-textdraw from the player it was created for. + * The ID of the player to hide the textdraw for + * The ID of the textdraw to hide + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + */ native PlayerTextDrawHide(playerid, PlayerText:text); -/// Change the text of a player-textdraw. -/// The ID of the player who's textdraw string to set -/// The ID of the textdraw to change -/// The new string for the TextDraw -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier versions! -/// There are limits to the length of textdraw strings! See Limits for more info. -/// You don't have to show the TextDraw again in order to apply the changes. +/** + * a_players + * Change the text of a player-textdraw. + * The ID of the player who's textdraw string to set + * The ID of the textdraw to change + * The new string for the TextDraw + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * This feature (player-textdraws) was added in SA-MP 0.3e and will not work in earlier + * versions! + * There are limits to the length of textdraw strings! See Limits + * for more info. + * You don't have to show the TextDraw again in order to apply the changes. + */ native PlayerTextDrawSetString(playerid, PlayerText:text, const string[]); -/// Sets a player textdraw 2D preview sprite of a specified model ID. -/// The PlayerTextDraw player ID -/// The textdraw id that will display the 3D preview -/// The GTA SA or SA:MP model ID to display -/// -/// -/// -/// -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order for this function to have effect. -/// -/// 1: The function executed successfully. If an invalid model is passed 'success' is reported, but the model will appear as a yellow/black question mark.

-/// 0: The function failed to execute. Player and/or textdraw do not exist. -/// -native PlayerTextDrawSetPreviewModel(playerid, PlayerText:text, modelindex); - -///

Sets the rotation and zoom of a 3D model preview player-textdraw. -/// The ID of the player whose player-textdraw to change -/// The ID of the player-textdraw to change -/// The X rotation value -/// The Y rotation value -/// The Z rotation value -/// The zoom value, smaller values make the camera closer and larger values make the camera further away (optional=1.0) -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW and already have a model set in order for this function to have effect. -native PlayerTextDrawSetPreviewRot(playerid, PlayerText:text, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fZoom = 1.0); - -/// Set the color of a vehicle in a player-textdraw model preview (if a vehicle is shown). -/// The ID of the player whose player-textdraw to change -/// The ID of the player's player-textdraw to change -/// The color to set the vehicle's primary color to -/// The color to set the vehicle's secondary color to -/// -/// -/// -/// -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font TEXT_DRAW_FONT_MODEL_PREVIEW and be showing a vehicle in order for this function to have effect. -native PlayerTextDrawSetPreviewVehCol(playerid, PlayerText:text, color1, color2); +/** + * a_players + * Sets a player textdraw 2D preview sprite of a specified model ID. + * The PlayerTextDraw player ID + * The textdraw ID that will display the 3D preview + * The GTA SA or SA:MP model ID to display + * + * + * + * + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order + * for this function to have effect. + * + * 1: The function executed successfully. If an invalid model is passed 'success' is + * reported, but the model will appear as a yellow/black question mark.
+ * 0: The function failed to execute. Player and/or textdraw do not exist. + * + */ +native PlayerTextDrawSetPreviewModel(playerid, PlayerText:text, modelIndex); + +/** + * a_players + * Sets the rotation and zoom of a 3D model preview player-textdraw. + * The ID of the player whose player-textdraw to change + * The ID of the player-textdraw to change + * The x rotation value + * The y rotation value + * The z rotation value + * The zoom value, smaller values make the camera closer and larger values make the + * camera further away (optional=1.0) + * + * + * + * + * + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW and already + * have a model set in order for this function to have effect. + */ +native PlayerTextDrawSetPreviewRot(playerid, PlayerText:text, Float:rotX, Float:rotY, Float:rotZ, Float:zoom = 1.0); + +/** + * a_players + * Set the colour of a vehicle in a player-textdraw model preview (if a vehicle is shown). + * The ID of the player whose player-textdraw to change + * The ID of the player's player-textdraw to change + * The colour to set + * the vehicle's primary colour to + * The colour to set + * the vehicle's secondary colour to + * + * + * + * + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font TEXT_DRAW_FONT_MODEL_PREVIEW and be showing + * a vehicle in order for this function to have effect. + */ +native PlayerTextDrawSetPreviewVehCol(playerid, PlayerText:text, colour1, colour2); // Per-player variable system (PVars) -/// Set an integer player variable. -/// The ID of the player whose player variable will be set -/// The name of the player variable -/// The integer to be set -/// -/// -/// -/// -/// -/// -/// Variables aren't reset until after OnPlayerDisconnect is called, so the values are still accessible in OnPlayerDisconnect. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Either the player specified is not connected, or the variable name is null or over 40 characters. -/// -native SetPVarInt(playerid, const varname[], int_value); - -///

Gets an integer player variable's value. -/// The ID of the player whose player variable to get -/// The name of the player variable (case-insensitive). Assigned in SetPVarInt -/// -/// -/// -/// -/// -/// -/// The integer value of the specified player variable. It will still return 0 if the variable is not set, or the player does not exist. -native GetPVarInt(playerid, const varname[]); - -/// Saves a string into a player variable. -/// The ID of the player whose player variable will be set -/// The name of the player variable -/// The string you want to save in the player variable -/// -/// -/// -/// -/// -/// -native SetPVarString(playerid, const varname[], const string_value[]); - -/// Gets a player variable as a string. -/// The ID of the player whose player variable to get -/// The name of the player variable, set by SetPVarString -/// The array in which to store the string value in, passed by reference -/// The maximum length of the returned string -/// -/// -/// -/// -/// -/// -/// If length of string is zero (value not set), string_return text will not be updated or set to anything and will remain with old data, neccesying that you clear the variable to blank value if GetPVarString returns 0 if that behavior is undesired -/// The length of the string. -native GetPVarString(playerid, const varname[], string_return[], len = sizeof string_return); - -/// Set a float player variable's value. -/// The ID of the player whose player variable will be set -/// The name of the player variable -/// The float you want to save in the player variable -/// -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Either the player specified is not connected, or the variable name is null or over 40 characters. -/// -native SetPVarFloat(playerid, const varname[], Float:float_value); - -///

Gets a player variable as a float. -/// The ID of the player whose player variable you want to get -/// The name of the player variable -/// -/// -/// -/// -/// -/// -/// The float from the specified player variable. -native Float:GetPVarFloat(playerid, const varname[]); - -/// Deletes a previously set player variable. -/// The ID of the player whose player variable to delete -/// The name of the player variable to delete -/// -/// -/// -/// -/// -/// -/// Once a variable is deleted, attempts to retrieve the value will return 0 (for integers and floats and NULL for strings). -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Either the player specified isn't connected or there is no variable set with the given name. -/// -native DeletePVar(playerid, const varname[]); - -///

Each PVar (player-variable) has its own unique identification number for lookup, this function returns the highest ID set for a player. -/// The ID of the player to get the upper PVar index of -/// -/// -/// The highest set PVar ID. +/** + * a_players + * Set an integer player variable. + * The ID of the player whose player variable will be set + * The name of the player variable + * The integer to be set + * + * + * + * + * + * + * Variables aren't reset until after OnPlayerDisconnect + * is called, so the values are still accessible in OnPlayerDisconnect. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Either the player specified is not connected, + * or the variable name is null or over 40 characters. + * + */ +native SetPVarInt(playerid, const pvar[], value); + +/** + * a_players + * Gets an integer player variable's value. + * The ID of the player whose player variable to get + * The name of the player variable (case-insensitive). Assigned in SetPVarInt + * + * + * + * + * + * + * The integer value of the specified player variable. It will still return 0 + * if the variable is not set, or the player does not exist. + */ +native GetPVarInt(playerid, const pvar[]); + +/** + * a_players + * Saves a string into a player variable. + * The ID of the player whose player variable will be set + * The name of the player variable + * The string you want to save in the player variable + * + * + * + * + * + * + */ +native SetPVarString(playerid, const pvar[], const value[]); + +/** + * a_players + * Gets a player variable as a string. + * The ID of the player whose player variable to get + * The name of the player variable, set by SetPVarString + * The array in which to store the string value in, passed by reference + * The maximum length of the returned string + * + * + * + * + * + * + * If length of string is zero (value not set), output text will not be updated or set to anything + * and will remain with old data, neccesying that you clear the variable to blank value if GetPVarString + * returns 0 if that behavior is undesired + * The length of the string. + */ +native GetPVarString(playerid, const pvar[], output[], len = sizeof (output)); + +/** + * a_players + * Set a float player variable's value. + * The ID of the player whose player variable will be set + * The name of the player variable + * The float you want to save in the player variable + * + * + * + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Either the player specified is not connected, + * or the variable name is null or over 40 characters. + * + */ +native SetPVarFloat(playerid, const pvar[], Float:value); + +/** + * a_players + * Gets a player variable as a float. + * The ID of the player whose player variable you want to get + * The name of the player variable + * + * + * + * + * + * + * The float from the specified player variable. + */ +native Float:GetPVarFloat(playerid, const pvar[]); + +/** + * a_players + * Deletes a previously set player variable. + * The ID of the player whose player variable to delete + * The name of the player variable to delete + * + * + * + * + * + * + * Once a variable is deleted, attempts to retrieve the value will return 0 (for + * integers and floats and NULL for strings). + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Either the player specified isn't connected or + * there is no variable set with the given name. + * + */ +native DeletePVar(playerid, const pvar[]); + +/** + * a_players + * Each PVar (player-variable) has its own unique identification number for lookup, this function + * returns the highest ID set for a player. + * The ID of the player to get the upper PVar index of + * + * + * The highest set PVar ID. + */ native GetPVarsUpperIndex(playerid); -/// Retrieve the name of a player's pVar via the index. -/// The ID of the player whose player variable to get the name of -/// The index of the player's pVar -/// A string to store the pVar's name in, passed by reference -/// The max length of the returned string -/// -/// -/// -/// -native GetPVarNameAtIndex(playerid, index, ret_varname[], ret_len = sizeof ret_varname); - -/// Gets the type (integer, float or string) of a player variable. -/// The ID of the player whose player variable to get the type of -/// The name of the player variable to get the type of -/// -/// -/// -/// -/// -/// -/// -/// -/// Variable types:

-///

    -///
  • PLAYER_VARTYPE_NONE (pVar with name given does not exist)
    • -///
  • PLAYER_VARTYPE_INT
    • -///
  • PLAYER_VARTYPE_STRING
    • -///
  • PLAYER_VARTYPE_FLOAT
    • -///
-/// -/// Returns the type of the PVar. See table below. -native GetPVarType(playerid, const varname[]); +/** + * a_players + * Retrieve the name of a player's pVar via the index. + * The ID of the player whose player variable to get the name of + * The index of the player's pVar + * A string to store the pVar's name in, passed by reference + * The max length of the returned string + * + * + * + * + */ +native GetPVarNameAtIndex(playerid, index, output[], size = sizeof (output)); + +/** + * a_players + * Gets the type (integer, float or string) of a player variable. + * The ID of the player whose player variable to get the type of + * The name of the player variable to get the type of + * + * + * + * + * + * + * + * + * Variable types:
+ *
    + *
  • PLAYER_VARTYPE_NONE (pVar with name given does not exist)
    • + *
  • PLAYER_VARTYPE_INT
    • + *
  • PLAYER_VARTYPE_STRING
    • + *
  • PLAYER_VARTYPE_FLOAT
    • + *
+ * + * Returns the type of the PVar. See table below. + */ +native PLAYER_VARTYPE:GetPVarType(playerid, const pvar[]); #if MAX_CHATBUBBLE_LENGTH < 1 || MAX_CHATBUBBLE_LENGTH > 144 #error MAX_CHATBUBBLE_LENGTH must be >= 1 and <= 144 #endif -/// Creates a chat bubble above a player's name tag. -/// The player which should have the chat bubble -/// The text to display -/// The text color -/// The distance from where players are able to see the chat bubble -/// The time in miliseconds the bubble should be displayed for -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// You can't see your own chatbubbles. The same applies to attached 3D text labels. -/// You can use color embedding for multiple colors in the message. -native SetPlayerChatBubble(playerid, const text[], color, Float:drawdistance, expiretime); +/** + * a_players + * Creates a chat bubble above a player's name tag. + * The player which should have the chat bubble + * The text to display + * The text colour + * The distance from where players are able to see the chat bubble + * The time in miliseconds the bubble should be displayed for + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * You can't see your own chatbubbles. The same applies to attached 3D text labels. + * You can use colour embedding for multiple colours in the message. + */ +native SetPlayerChatBubble(playerid, const text[], colour, Float:drawDistance, expireTime); // Player control -/// Puts a player in a vehicle. -/// The ID of the player to put in a vehicle -/// The ID of the vehicle to put the player in -/// The ID of the seat to put the player in -/// -/// -/// -/// -/// If this function is used on a player that is already in a vehicle, other players will still see them in their previous vehicle. To fix this, first remove the player from the vehicle. -/// If the seat is invalid or is taken, will cause a crash when they EXIT the vehicle. -/// You can use GetPlayerVehicleSeat in a loop to check if a seat is occupied by any players. -/// -/// Seats:

-///

    -///
  • 0 - driver.
    • -///
  • 1 - front passenger.
    • -///
  • 2 - back-left passenger.
    • -///
  • 3 - back-right passenger.
    • -///
  • 4+ - passenger seats (coach etc.).
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player or vehicle don't exist. -/// +/** + * a_players + *

Puts a player in a vehicle. + * The ID of the player to put in a vehicle + * The ID of the vehicle to put the player in + * The ID of the seat to put the player in + * + * + * + * + * If this function is used on a player that is already in a vehicle, other players will still + * see them in their previous vehicle. To fix this, first remove the player from the vehicle. + * If the seat is invalid or is taken, will cause a crash when they EXIT the vehicle. + * You can use GetPlayerVehicleSeat in a loop to check + * if a seat is occupied by any players. + * + * Seats:
+ *
    + *
  • 0 - driver.
    • + *
  • 1 - front passenger.
    • + *
  • 2 - back-left passenger.
    • + *
  • 3 - back-right passenger.
    • + *
  • 4+ - passenger seats (coach etc.).
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player or vehicle don't exist. + * + */ native PutPlayerInVehicle(playerid, vehicleid, seatid); -/// This function gets the ID of the vehicle the player is currently in. Note: NOT the model id of the vehicle. See GetVehicleModel for that. -/// The ID of the player in the vehicle that you want to get the ID of -/// -/// -/// -/// -/// ID of the vehicle or 0 if not in a vehicle. +/** + * a_players + * This function gets the ID of the vehicle the player is currently in. Note: NOT the + * model ID of the vehicle. See GetVehicleModel for that. + * The ID of the player in the vehicle that you want to get the ID of + * + * + * + * + * ID of the vehicle or 0 if not in a vehicle. + */ native GetPlayerVehicleID(playerid); -/// Find out which seat a player is in. -/// The ID of the player you want to get the seat of -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// Sometimes the result can be 128 which is an invalid seat ID. Circumstances of this are not yet known, but it is best to discard information when returned seat number is 128. -/// The ID of the seat the player is in. -1 is not in vehicle, 0 is the driver, 1 is the front passenger, and 2 & 3 are the rear passengers. +/** + * a_players + * Find out which seat a player is in. + * The ID of the player you want to get the seat of + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * Sometimes the result can be 128 which is an invalid seat ID. Circumstances + * of this are not yet known, but it is best to discard information when returned seat number is 128. + * The ID of the seat the player is in. -1 is not in vehicle, 0 + * is the driver, 1 is the front passenger, and 2 & 3 + * are the rear passengers. + */ native GetPlayerVehicleSeat(playerid); -/// Removes/ejects a player from their vehicle. -/// The ID of the player to remove from their vehicle -/// -/// -/// The exiting animation is not synced for other players.

-/// This function will not work when used in OnPlayerEnterVehicle, because the player isn't in the vehicle when the callback is called. Use OnPlayerStateChange instead.

-/// The player isn't removed if he is in a RC Vehicle. -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Removes/ejects a player from their vehicle. + * The ID of the player to remove from their vehicle + * + * + * The exiting animation is not synced for other players.
+ * This function will not work when used in OnPlayerEnterVehicle, + * because the player isn't in the vehicle when the callback is called. Use OnPlayerStateChange + * instead.
+ * The player isn't removed if he is in a RC Vehicle. + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native RemovePlayerFromVehicle(playerid); -/// Toggles whether a player can control their character or not. The player will also be unable to move their camera. -/// The ID of the player to toggle the controllability of -/// 0 to make them uncontrollable, 1 to make them controllable -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// -native TogglePlayerControllable(playerid, toggle); - -///

Plays the specified sound for a player. -/// The ID of the player for whom to play the sound -/// The sound to play -/// X coordinate for the sound to play at. (0 for no position) -/// Y coordinate for the sound to play at. (0 for no position) -/// Z coordinate for the sound to play at. (0 for no position) -/// -/// -/// -/// Only use the coordinates if you want the sound to be played at a certain position. Set coordinates all to 0 to just play the sound. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Toggles whether a player can control their character or not. The player will also be unable + * to move their camera. + * The ID of the player to toggle the controllability of + * 0 to make them uncontrollable, 1 to make them controllable + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ +native TogglePlayerControllable(playerid, bool:toggle); + +/** + * a_players + * Plays the specified sound for a player. + * The ID of the player for whom to play the sound + * The sound to play + * x coordinate for the sound to play at. (0 for no position) + * y coordinate for the sound to play at. (0 for no position) + * z coordinate for the sound to play at. (0 for no position) + * + * + * + * Only use the coordinates if you want the sound to be played at a certain position. Set + * coordinates all to 0 to just play the sound. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native PlayerPlaySound(playerid, soundid, Float:x, Float:y, Float:z); -/// Apply an animation to a player. -/// The ID of the player to apply the animation to -/// The animation library from which to apply an animation -/// The name of the animation to apply, within the specified library -/// The speed to play the animation (use 4.1) -/// If set to 1, the animation will loop. If set to 0, the animation will play once -/// If set to 0, the player is returned to their old X coordinate once the animation is complete (for animations that move the player such as walking). 1 will not return them to their old position -/// Same as above but for the Y axis. Should be kept the same as the previous parameter -/// Setting this to 1 will freeze the player at the end of the animation. 0 will not -/// Timer in milliseconds. For a never-ending loop it should be 0 -/// Set to 1 to make server sync the animation with all other players in streaming radius. 2 works same as 1, but will ONLY apply the animation to streamed-in players, but NOT the actual player being animated (useful for npc animations and persistent animations when players are being streamed) (optional=0) -/// -/// -/// The optional parameter, which defaults to 0, in most cases is not needed since players sync animations themselves. The parameter can force all players who can see to play the animation regardless of whether the player is performing that animation. This is useful in circumstances where the player can't sync the animation themselves. For example, they may be paused. -/// An invalid animation library will crash the player's game. -/// This function always returns 1, even if the player specified does not exist, or any of the parameters are invalid (e.g. invalid library). -native ApplyAnimation(playerid, const animlib[], const animname[], Float:fDelta, loop, lockx, locky, freeze, time, forcesync = 0); - -/// Clears all animations for the given player (it also cancels all current tasks such as jetpacking,parachuting,entering vehicles, driving (removes player out of vehicle), swimming, etc.. ). -/// The ID of the player to clear the animations of -/// Set to 1 to force playerid to sync the animation with other players in streaming radius (optional=0) -/// -/// ClearAnimations doesn't do anything when the animation ends if we pass 1 for the freeze parameter in ApplyAnimation. -/// Unlike some other ways to remove player from a vehicle, this will also reset the vehicle's velocity to zero, instantly stopping the car. Player will appear on top of the vehicle with the same location as he was in his car seat. -/// This function always returns 1, even when the player specified is not connected. -native ClearAnimations(playerid, forcesync = 0); - -/// Returns the index of any running applied animations. -/// ID of the player of whom you want to get the animation index of -/// -/// This function was added in SA-MP 0.3b and will not work in earlier versions! -/// 0 if there is no animation applied. +/** + * a_players + * Apply an animation to a player. + * The ID of the player to apply the animation to + * The animation library from which to apply an animation + * The name of the animation to apply, within the specified library + * The speed to play the animation (use 4.1) + * If set to 1, the animation will loop. If set to 0, + * the animation will play once + * If set to 0, the player is returned to their old x coordinate once + * the animation is complete (for animations that move the player such as walking). 1 + * will not return them to their old position + * Same as above but for the y axis. Should be kept the same as the previous parameter + * Setting this to 1 will freeze the player at the end of the animation. + * 0 will not + * Timer in milliseconds. For a never-ending loop it should be 0 + * Set to 1 to make server sync the animation with all other players + * in streaming radius. 2 works same as 1, but will ONLY apply the animation + * to streamed-in players, but NOT the actual player being animated (useful for npc animations and persistent + * animations when players are being streamed) (optional=0) + * + * + * The optional parameter, which defaults to 0, + * in most cases is not needed since players sync animations themselves. The parameter can force all players who can see to play the animation + * regardless of whether the player is performing that animation. This is useful in circumstances where + * the player can't sync the animation themselves. For example, they may be paused. + * An invalid animation library will crash the player's game. + * This function always returns 1, even if the player specified does not exist, + * or any of the parameters are invalid (e.g. invalid library). + */ +native ApplyAnimation(playerid, const animationLibrary[], const animationName[], Float:delta, bool:loop, bool:lockX, bool:lockY, bool:freeze, time, FORCE_SYNC:forceSync = SYNC_NONE); + +/** + * a_players + * Clears all animations for the given player (it also cancels all current tasks such as jetpacking,parachuting,entering + * vehicles, driving (removes player out of vehicle), swimming, etc.. ). + * The ID of the player to clear the animations of + * Set to 1 to force playerid to sync the animation with other + * players in streaming radius (optional=0) + * + * ClearAnimations doesn't do anything when the animation ends if we pass 1 for the freeze + * parameter in ApplyAnimation. + * Unlike some other ways to remove player from a vehicle, this will also reset the vehicle's + * velocity to zero, instantly stopping the car. Player will appear on top of the vehicle with the + * same location as he was in his car seat. + * This function always returns 1, even when the player specified is not connected. + */ +native ClearAnimations(playerid, FORCE_SYNC:forceSync = SYNC_NONE); + +/** + * a_players + * Returns the index of any running applied animations. + * ID of the player of whom you want to get the animation index of + * + * This function was added in SA-MP 0.3b and will not work in earlier versions! + * 0 if there is no animation applied. + */ native GetPlayerAnimationIndex(playerid); // return the index of any running applied animations (0 if none are running) -/// Get the animation library/name for the index. -/// The animation index, returned by GetPlayerAnimationIndex -/// String variable that stores the animation library -/// Size of the string that stores the animation library -/// String variable that stores the animation name -/// Size of the string that stores the animation name -/// -/// This function was added in SA-MP 0.3b and will not work in earlier versions! -/// 1 on success, 0 on failure. -native GetAnimationName(index, animlib[], len1 = sizeof animlib, animname[], len2 = sizeof animname); // get the animation lib/name for the index - -/// Retrieves a player's current special action. -/// The ID of the player to get the special action of -/// -/// -/// -/// Special actions: (marked with * cannot be set)

-///

    -///
  • 0 - SPECIAL_ACTION_NONE
    • -///
  • 2 - SPECIAL_ACTION_USEJETPACK
    • -///
  • 5 - SPECIAL_ACTION_DANCE1
    • -///
  • 6 - SPECIAL_ACTION_DANCE2
    • -///
  • 7 - SPECIAL_ACTION_DANCE3
    • -///
  • 8 - SPECIAL_ACTION_DANCE4
    • -///
  • 10 - SPECIAL_ACTION_HANDSUP
    • -///
  • 11 - SPECIAL_ACTION_USECELLPHONE
    • -///
  • 12 - SPECIAL_ACTION_SITTING *
    • -///
  • 13 - SPECIAL_ACTION_STOPUSECELLPHONE
    • -///
-/// added in SA-MP 0.3:

-///

    -///
  • 1 - SPECIAL_ACTION_DUCK * - Detect if the player is crouching.
    • -///
  • 3 - SPECIAL_ACTION_ENTER_VEHICLE * - Detect if the player is entering a vehicle via an animation.
    • -///
  • 4 - SPECIAL_ACTION_EXIT_VEHICLE * - Detect if the player is exiting a vehicle via an animation.
    • -///
  • 20 - SPECIAL_ACTION_DRINK_BEER - Will increase the player's drunk level when used
    • -///
  • 21 - SPECIAL_ACTION_SMOKE_CIGGY - Will give the player a cigar
    • -///
  • 22 - SPECIAL_ACTION_DRINK_WINE - Will give the player a wine bottle to get drunk from
    • -///
  • 23 - SPECIAL_ACTION_DRINK_SPRUNK - Will give the player a sprunk bottle to drink from
    • -///
  • 68 - SPECIAL_ACTION_PISSING - Will make make the player perform the pissing animation with visible pee.
    • -///
-/// added in SA-MP 0.3e:

-///

    -///
  • 24 - SPECIAL_ACTION_CUFFED - Will force the player in to cuffs (hands are behind their back) (does not work on CJ skin)
    • -///
-/// added in SA-MP 0.3x:

-///

    -///
  • 25 - SPECIAL_ACTION_CARRY - Will apply a 'carrying' animation to the player and make them unable to sprint, jump or punch (does not work on CJ skin)
    • -///
-/// -/// The special action of the player. -native GetPlayerSpecialAction(playerid); - -/// This function allows to set players special action. -/// The player that should perform the action -/// The action that should be performed -/// -/// -/// Removing jetpacks from players by setting their special action to 0 causes the sound to stay until death. -/// -/// Special actions: (marked with * cannot be set)

-///

    -///
  • 0 - SPECIAL_ACTION_NONE
    • -///
  • 2 - SPECIAL_ACTION_USEJETPACK
    • -///
  • 5 - SPECIAL_ACTION_DANCE1
    • -///
  • 6 - SPECIAL_ACTION_DANCE2
    • -///
  • 7 - SPECIAL_ACTION_DANCE3
    • -///
  • 8 - SPECIAL_ACTION_DANCE4
    • -///
  • 10 - SPECIAL_ACTION_HANDSUP
    • -///
  • 11 - SPECIAL_ACTION_USECELLPHONE
    • -///
  • 12 - SPECIAL_ACTION_SITTING *
    • -///
  • 13 - SPECIAL_ACTION_STOPUSECELLPHONE
    • -///
-/// added in SA-MP 0.3:

-///

    -///
  • 1 - SPECIAL_ACTION_DUCK * - Detect if the player is crouching.
    • -///
  • 3 - SPECIAL_ACTION_ENTER_VEHICLE * - Detect if the player is entering a vehicle via an animation.
    • -///
  • 4 - SPECIAL_ACTION_EXIT_VEHICLE * - Detect if the player is exiting a vehicle via an animation.
    • -///
  • 20 - SPECIAL_ACTION_DRINK_BEER - Will increase the player's drunk level when used
    • -///
  • 21 - SPECIAL_ACTION_SMOKE_CIGGY - Will give the player a cigar
    • -///
  • 22 - SPECIAL_ACTION_DRINK_WINE - Will give the player a wine bottle to get drunk from
    • -///
  • 23 - SPECIAL_ACTION_DRINK_SPRUNK - Will give the player a sprunk bottle to drink from
    • -///
  • 68 - SPECIAL_ACTION_PISSING - Will make make the player perform the pissing animation with visible pee.
    • -///
-/// added in SA-MP 0.3e:

-///

    -///
  • 24 - SPECIAL_ACTION_CUFFED - Will force the player in to cuffs (hands are behind their back) (does not work on CJ skin)
    • -///
-/// added in SA-MP 0.3x:

-///

    -///
  • 25 - SPECIAL_ACTION_CARRY - Will apply a 'carrying' animation to the player and make them unable to sprint, jump or punch (does not work on CJ skin)
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// -native SetPlayerSpecialAction(playerid, actionid); - -///

Disables collisions between occupied vehicles for a player. -/// The ID of the player for whom you want to disable collisions -/// 1 to disable collisions, 0 to enable collisions -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// -native DisableRemoteVehicleCollisions(playerid, disable); +/** + * a_players + *

Get the animation library/name for the index. + * The animation index, returned by GetPlayerAnimationIndex + * String variable that stores the animation library + * Size of the string that stores the animation library + * String variable that stores the animation name + * Size of the string that stores the animation name + * + * This function was added in SA-MP 0.3b and will not work in earlier versions! + * 1 on success, 0 on failure. + */ +native GetAnimationName(index, animationLibrary[], len1 = sizeof (animationLibrary), animationName[], len2 = sizeof (animationName)); // get the animation lib/name for the index + +/** + * a_players + * Retrieves a player's current special + * action. + * The ID of the player to get the special + * action of + * + * + * + * Special actions: (marked with * cannot be set)
+ *
    + *
  • 0 - SPECIAL_ACTION_NONE
    • + *
  • 2 - SPECIAL_ACTION_USEJETPACK
    • + *
  • 5 - SPECIAL_ACTION_DANCE1
    • + *
  • 6 - SPECIAL_ACTION_DANCE2
    • + *
  • 7 - SPECIAL_ACTION_DANCE3
    • + *
  • 8 - SPECIAL_ACTION_DANCE4
    • + *
  • 10 - SPECIAL_ACTION_HANDSUP
    • + *
  • 11 - SPECIAL_ACTION_USECELLPHONE
    • + *
  • 12 - SPECIAL_ACTION_SITTING *
    • + *
  • 13 - SPECIAL_ACTION_STOPUSECELLPHONE
    • + *
+ * added in SA-MP 0.3:
+ *
    + *
  • 1 - SPECIAL_ACTION_DUCK * - Detect if the player is crouching.
    • + *
  • 3 - SPECIAL_ACTION_ENTER_VEHICLE * - Detect if the player is entering a vehicle + * via an animation.
    • + *
  • 4 - SPECIAL_ACTION_EXIT_VEHICLE * - Detect if the player is exiting a vehicle + * via an animation.
    • + *
  • 20 - SPECIAL_ACTION_DRINK_BEER - Will increase the player's drunk level when + * used
    • + *
  • 21 - SPECIAL_ACTION_SMOKE_CIGGY - Will give the player a cigar
    • + *
  • 22 - SPECIAL_ACTION_DRINK_WINE - Will give the player a wine bottle to get + * drunk from
    • + *
  • 23 - SPECIAL_ACTION_DRINK_SPRUNK - Will give the player a sprunk bottle to + * drink from
    • + *
  • 68 - SPECIAL_ACTION_PISSING - Will make make the player perform the pissing + * animation with visible pee.
    • + *
+ * added in SA-MP 0.3e:
+ *
    + *
  • 24 - SPECIAL_ACTION_CUFFED - Will force the player in to cuffs (hands are behind + * their back) (does not work on CJ skin)
    • + *
+ * added in SA-MP 0.3x:
+ *
    + *
  • 25 - SPECIAL_ACTION_CARRY - Will apply a 'carrying' animation to the + * player and make them unable to sprint, jump or punch (does not work on CJ skin)
    • + *
+ * + * The special action of the player. + */ +native SPECIAL_ACTION:GetPlayerSpecialAction(playerid); + +/** + * a_players + * This function allows to set players special action. + * The player that should perform the action + * The action that should be performed + * + * + * Removing jetpacks from players by setting their special action to 0 causes + * the sound to stay until death. + * + * Special actions: (marked with * cannot be set)
+ *
    + *
  • 0 - SPECIAL_ACTION_NONE
    • + *
  • 2 - SPECIAL_ACTION_USEJETPACK
    • + *
  • 5 - SPECIAL_ACTION_DANCE1
    • + *
  • 6 - SPECIAL_ACTION_DANCE2
    • + *
  • 7 - SPECIAL_ACTION_DANCE3
    • + *
  • 8 - SPECIAL_ACTION_DANCE4
    • + *
  • 10 - SPECIAL_ACTION_HANDSUP
    • + *
  • 11 - SPECIAL_ACTION_USECELLPHONE
    • + *
  • 12 - SPECIAL_ACTION_SITTING *
    • + *
  • 13 - SPECIAL_ACTION_STOPUSECELLPHONE
    • + *
+ * added in SA-MP 0.3:
+ *
    + *
  • 1 - SPECIAL_ACTION_DUCK * - Detect if the player is crouching.
    • + *
  • 3 - SPECIAL_ACTION_ENTER_VEHICLE * - Detect if the player is entering a vehicle + * via an animation.
    • + *
  • 4 - SPECIAL_ACTION_EXIT_VEHICLE * - Detect if the player is exiting a vehicle + * via an animation.
    • + *
  • 20 - SPECIAL_ACTION_DRINK_BEER - Will increase the player's drunk level when + * used
    • + *
  • 21 - SPECIAL_ACTION_SMOKE_CIGGY - Will give the player a cigar
    • + *
  • 22 - SPECIAL_ACTION_DRINK_WINE - Will give the player a wine bottle to get + * drunk from
    • + *
  • 23 - SPECIAL_ACTION_DRINK_SPRUNK - Will give the player a sprunk bottle to + * drink from
    • + *
  • 68 - SPECIAL_ACTION_PISSING - Will make make the player perform the pissing + * animation with visible pee.
    • + *
+ * added in SA-MP 0.3e:
+ *
    + *
  • 24 - SPECIAL_ACTION_CUFFED - Will force the player in to cuffs (hands are behind + * their back) (does not work on CJ skin)
    • + *
+ * added in SA-MP 0.3x:
+ *
    + *
  • 25 - SPECIAL_ACTION_CARRY - Will apply a 'carrying' animation to the + * player and make them unable to sprint, jump or punch (does not work on CJ skin)
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ +native SetPlayerSpecialAction(playerid, SPECIAL_ACTION:actionid); + +/** + * a_players + * Disables collisions between occupied vehicles for a player. + * The ID of the player for whom you want to disable collisions + * 1 to disable collisions, 0 to enable collisions + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ +native DisableRemoteVehicleCollisions(playerid, bool:disable); // Player world/map related -/// Sets a checkpoint (red cylinder) for a player. Also shows a red blip on the radar. When players enter a checkpoint, OnPlayerEnterCheckpoint is called and actions can be performed. -/// The ID of the player for whom to set a checkpoint -/// The X coordinate to set the checkpoint at -/// The Y coordinate to set the checkpoint at -/// The Z coordinate to set the checkpoint at -/// The size of the checkpoint -/// -/// If a checkpoint is already set it will use the size of that checkpoint instead of the new one.

-/// Checkpoints created on server-created objects (CreateObject/CreatePlayerObject) will appear down on the 'real' ground, but will still function correctly. A pickup can be used instead. -/// -/// Checkpoints are asynchronous, meaning only one can be shown at a time. To 'stream' checkpoints (only show them when players are close enough), use a checkpoint streamer. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// +/** + * a_players + *

Sets a checkpoint (red cylinder) for a player. Also shows a red blip on the radar. When + * players enter a checkpoint, OnPlayerEnterCheckpoint is called + * and actions can be performed. + * The ID of the player for whom to set a checkpoint + * The x coordinate to set the checkpoint at + * The y coordinate to set the checkpoint at + * The z coordinate to set the checkpoint at + * The size of the checkpoint + * + * If a checkpoint is already set it will use the size of that checkpoint instead of the new one.
+ * Checkpoints created on server-created objects (CreateObject/ + * CreatePlayerObject) + * will appear down on the 'real' ground, but will still function correctly. A pickup can be used instead. + * + * Checkpoints are asynchronous, meaning only one can be shown at a time. To 'stream' checkpoints + * (only show them when players are close enough), use a checkpoint streamer. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ native SetPlayerCheckpoint(playerid, Float:x, Float:y, Float:z, Float:size); -/// Disables (hides/destroys) a player's set checkpoint. Players can only have a single checkpoint set at a time. Checkpoints don't need to be disabled before setting another one. -/// The ID of the player whose checkpoint to disable -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully. Success is also returned if the player doesn't have a checkpoint shown already.

-/// 0: The function failed to execute. This means the player is not connected. -/// +/** + * a_players + *

Disables (hides/destroys) a player's set checkpoint. Players can only have a single checkpoint + * set at a time. Checkpoints don't need to be disabled before setting another one. + * The ID of the player whose checkpoint to disable + * + * + * + * + * + * + * + * + * + * + * 1: The function executed successfully. Success is also returned if the player doesn't + * have a checkpoint shown already.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ native DisablePlayerCheckpoint(playerid); -/// Creates a race checkpoint. When the player enters it, the OnPlayerEnterRaceCheckpoint callback is called. -/// The ID of the player to set the checkpoint for -/// Type of checkpoint. 0-Normal, 1-Finish, 2-Nothing(Only the checkpoint without anything on it), 3-Air normal, 4-Air finish, 5-Air (rotates and stops), 6-Air (increases, decreases and disappears), 7-Air (swings down and up), 8-Air (swings up and down) -/// X-Coordinate -/// Y-Coordinate -/// Z-Coordinate -/// X-Coordinate of the next point, for the arrow facing direction -/// Y-Coordinate of the next point, for the arrow facing direction -/// Z-Coordinate of the next point, for the arrow facing direction -/// Size (diameter) of the checkpoint -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// If a race checkpoint is already set it will use the size of that checkpoint instead of the new one. -/// -/// Race checkpoints created on server-created objects (CreateObject/CreatePlayerObject) will appear down on the 'real' ground, but will still function correctly.

-/// Race checkpoints are asynchronous, meaning only one can be shown at a time. To 'stream' race checkpoints (only show them when players are close enough), use a race checkpoint streamer. -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player specified does not exist. -/// -native SetPlayerRaceCheckpoint(playerid, type, Float:x, Float:y, Float:z, Float:nextx, Float:nexty, Float:nextz, Float:size); - -///

Disable any initialized race checkpoints for a specific player, since you can only have one at any given time. -/// The player to disable the current checkpoint for -/// -/// -/// -/// -/// -/// -/// -/// -/// +/** + * a_players + * Creates a race checkpoint. When the player enters it, the OnPlayerEnterRaceCheckpoint + * callback is called. + * The ID of the player to set the checkpoint for + * Type of checkpoint. 0-Normal, 1-Finish, 2-Nothing(Only + * the checkpoint without anything on it), 3-Air normal, 4-Air finish, 5-Air + * (rotates and stops), 6-Air (increases, decreases and disappears), 7-Air + * (swings down and up), 8-Air (swings up and down) + * x-Coordinate + * y-Coordinate + * z-Coordinate + * x-Coordinate of the next point, for the arrow facing direction + * y-Coordinate of the next point, for the arrow facing direction + * z-Coordinate of the next point, for the arrow facing direction + * Size (diameter) of the checkpoint + * + * + * + * + * + * + * + * + * + * If a race checkpoint is already set it will use the size of that checkpoint instead of the + * new one. + * + * Race checkpoints created on server-created objects (CreateObject/CreatePlayerObject) will appear down on the 'real' ground, but will + * still function correctly.
+ * Race checkpoints are asynchronous, meaning only one can be shown at a time. To 'stream' race checkpoints + * (only show them when players are close enough), use a race checkpoint streamer. + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player specified does not exist. + * + */ +native SetPlayerRaceCheckpoint(playerid, CP_TYPE:type, Float:centerX, Float:centerY, Float:centerZ, Float:nextX, Float:nextY, Float:nextZ, Float:size); + +/** + * a_players + * Disable any initialized race checkpoints for a specific player, since you can only have + * one at any given time. + * The player to disable the current checkpoint for + * + * + * + * + * + * + * + * + * + */ native DisablePlayerRaceCheckpoint(playerid); -/// Set the world boundaries for a player. Players can not go out of the boundaries (they will be pushed back in). -/// The ID of the player to set the world boundaries of -/// The maximum X coordinate the player can go to -/// The minimum X coordinate the player can go to -/// The maximum Y coordinate the player can go to -/// The minimum Y coordinate the player can go to -/// -/// This function does not work if used in OnPlayerConnect -/// A player's world boundaries can be reset by setting them to 20000.0, -20000.0, 20000.0, -20000.0. These are the default values. -/// This function doesn't work in interiors! -native SetPlayerWorldBounds(playerid, Float:x_max,Float:x_min,Float:y_max,Float:y_min); - -/// Change the colour of a player's nametag and radar blip for another player. -/// The player that will see the player's changed blip/nametag color -/// The player whose color will be changed -/// New color. (RGBA) -/// -/// -/// -/// -native SetPlayerMarkerForPlayer(playerid, showplayerid, color); - -/// This functions allows you to toggle the drawing of player nametags, healthbars and armor bars which display above their head. For use of a similar function like this on a global level, ShowNameTags function. -/// Player who will see the results of this function -/// Player whose name tag will be shown or hidden -/// 1-show name tag, 0-hide name tag -/// -/// -/// -/// ShowNameTags must be set to 1 to be able to show name tags with ShowPlayerNameTagForPlayer, that means that in order to be effective you need to ShowPlayerNameTagForPlayer(forplayerid, playerid, 0) ahead of time(OnPlayerStreamIn is a good spot). -native ShowPlayerNameTagForPlayer(playerid, showplayerid, show); - -/// Place an icon/marker on a player's map. Can be used to mark locations such as banks and hospitals to players. -/// The ID of the player to set the map icon for -/// The player's icon ID, ranging from 0 to 99. This means there is a maximum of 100 map icons. ID can be used in RemovePlayerMapIcon -/// The X coordinate to place the map icon at -/// The Y coordinate to place the map icon at -/// The Z coordinate to place the map icon at -/// The icon to set -/// The color of the icon (RGBA). This should only be used with the square icon (ID: 0) -/// The style of icon (optional=MAPICON_LOCAL) -/// -/// -/// If you use an invalid marker type, it will create ID 1 (White Square). -/// If you use an icon ID that is already in use, it will replace the current map icon using that ID. -/// Marker type 1 (square), 2 (player blip), 4 (north), and 56 (single airstrip blip) will cause your game to crash if you have map legends enabled while viewing the map. -/// -/// Map icon styles:

-///

    -///
  • 0 MAPICON_LOCAL - close proximity only
    • -///
  • 1 MAPICON_GLOBAL - show on radar edge as long as in range
    • -///
  • 2 MAPICON_LOCAL_CHECKPOINT - Close proximity only (with checkpoint)
    • -///
  • 3 MAPICON_GLOBAL_CHECKPOINT - Show on radar edge as long as in range (with checkpoint)
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Player is not connected. -/// -native SetPlayerMapIcon(playerid, iconid, Float:x, Float:y, Float:z, markertype, color, style = MAPICON_LOCAL); - -///

Removes a map icon that was set earlier for a player using SetPlayerMapIcon. -/// The ID of the player whose icon to remove -/// The ID of the icon to remove. This is the second parameter of SetPlayerMapIcon -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// +/** + * a_players + *

Set the world boundaries for a player. Players can not go out of the boundaries (they will + * be pushed back in). + * The ID of the player to set the world boundaries of + * The maximum x coordinate the player can go to + * The minimum x coordinate the player can go to + * The maximum y coordinate the player can go to + * The minimum y coordinate the player can go to + * + * This function does not work if used in OnPlayerConnect + * A player's world boundaries can be reset by setting them to 20000.0, -20000.0, + * 20000.0, -20000.0. These are the default values. + * This function doesn't work in interiors! + */ +native SetPlayerWorldBounds(playerid, Float:maxX, Float:minX, Float:maxY, Float:minY); + +/** + * a_players + * Change the colour of a player's nametag and radar blip for another player. + * The player that will see the player's changed blip/nametag colour + * The player whose colour will be changed + * New colour. (RGBA) + * + * + * + * + */ +native SetPlayerMarkerForPlayer(playerid, targetid, colour); + +/** + * a_players + * This functions allows you to toggle the drawing of player nametags, healthbars and armor + * bars which display above their head. For use of a similar function like this on a global level, + * ShowNameTags function. + * Player who will see the results of this function + * Player whose name tag will be shown or hidden + * 1-show name tag, 0-hide name tag + * + * + * + * ShowNameTags must be set to 1 to be able to show + * name tags with ShowPlayerNameTagForPlayer, that means that in order to be effective you need to ShowPlayerNameTagForPlayer(forplayerid, + * playerid, 0) ahead of time(OnPlayerStreamIn is a good spot). + */ +native ShowPlayerNameTagForPlayer(playerid, targetid, bool:show); + +/** + * a_players + * Place an icon/marker on a player's map. Can be used to mark locations such as banks and + * hospitals to players. + * The ID of the player to set the map icon for + * The player's icon ID, ranging from 0 to 99. This + * means there is a maximum of 100 map icons. ID can be used in RemovePlayerMapIcon + * The x coordinate to place the map icon at + * The y coordinate to place the map icon at + * The z coordinate to place the map icon at + * The icon to set + * The colour of the icon (RGBA). This should only be used with the square + * icon (ID: 0) + * The style of icon (optional=MAPICON_LOCAL) + * + * + * If you use an invalid marker type, it will create ID 1 (White Square). + * If you use an icon ID that is already in use, it will replace the current map icon using + * that ID. + * Marker type 1 (square), 2 (player blip), 4 (north), + * and 56 (single airstrip blip) will cause your game to crash if you have map legends + * enabled while viewing the map. + * + * Map icon styles:
+ *
    + *
  • 0 MAPICON_LOCAL - close proximity only
    • + *
  • 1 MAPICON_GLOBAL - show on radar edge as long as in range
    • + *
  • 2 MAPICON_LOCAL_CHECKPOINT - Close proximity only (with checkpoint)
    • + *
  • 3 MAPICON_GLOBAL_CHECKPOINT - Show on radar edge as long as in range (with + * checkpoint)
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Player is not connected. + * + */ +native SetPlayerMapIcon(playerid, iconid, Float:x, Float:y, Float:z, markerType, colour, MAPICON:style = MAPICON_LOCAL); + +/** + * a_players + * Removes a map icon that was set earlier for a player using SetPlayerMapIcon. + * The ID of the player whose icon to remove + * The ID of the icon to remove. This is the second parameter of + * SetPlayerMapIcon + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ native RemovePlayerMapIcon(playerid, iconid); -/// Enable/Disable the teleporting ability for a player by right-clicking on the map. -/// The ID of the player to allow teleport -/// 1 to allow, 0 to disallow -/// This function, as of 0.3d, is deprecated. Check OnPlayerClickMap. -/// This function will work only if AllowAdminTeleport is enabled, and you have to be an admin. -/// -native AllowPlayerTeleport(playerid, allow); +/** + * a_players + * Enable/Disable the teleporting ability for a player by right-clicking on the map. + * The ID of the player to allow teleport + * 1 to allow, 0 to disallow + * This function, as of 0.3d, is deprecated. Check OnPlayerClickMap. + * This function will work only if AllowAdminTeleport is + * enabled, and you have to be an admin. + * + */ +#pragma deprecated Use `OnPlayerClickMap`. +native AllowPlayerTeleport(playerid, bool:allow); // Player camera -/// Sets the camera to a specific position for a player. -/// ID of the player -/// The X coordinate to place the camera at -/// The Y coordinate to place the camera at -/// The Z coordinate to place the camera at -/// -/// -/// You may also have to use SetPlayerCameraLookAt with this function in order to work properly. -/// Use SetCameraBehindPlayer to reset the camera to behind the player. -/// Using the camera functions directly after enabling spectator mode doesn't work. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified doesn't exist. -/// +/** + * a_players + *

Sets the camera to a specific position for a player. + * ID of the player + * The x coordinate to place the camera at + * The y coordinate to place the camera at + * The z coordinate to place the camera at + * + * + * You may also have to use SetPlayerCameraLookAt with + * this function in order to work properly. + * Use SetCameraBehindPlayer to reset the camera to behind + * the player. + * Using the camera functions directly after enabling spectator mode doesn't work. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified doesn't exist. + * + */ native SetPlayerCameraPos(playerid, Float:x, Float:y, Float:z); -/// Set the direction a player's camera looks at. Generally meant to be used in combination with SetPlayerCameraPos. -/// The ID of the player whose camera to set -/// The X coordinate for the player's camera to look at -/// The Y coordinate for the player's camera to look at -/// The Z coordinate for the player's camera to look at -/// The style of the change. Can be used to interpolate (change slowly) from old pos to new pos using CAMERA_MOVE. Added in 0.3e. Leave out for older versions (optional=CAMERA_CUT) -/// -/// -/// -/// -/// Using the camera functions directly after enabling spectator mode doesn't work. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player specified does not exist. -/// -native SetPlayerCameraLookAt(playerid, Float:x, Float:y, Float:z, cut = CAMERA_CUT); - -///

Restore the camera to a place behind the player, after using a function like SetPlayerCameraPos. -/// The player you want to restore the camera for -/// -/// +/** + * a_players + * Set the direction a player's camera looks at. Generally meant to be used in combination + * with SetPlayerCameraPos. + * The ID of the player whose camera to set + * The x coordinate for the player's camera to look at + * The y coordinate for the player's camera to look at + * The z coordinate for the player's camera to look at + * The style of the change. Can be used to interpolate (change slowly) from old pos + * to new pos using CAMERA_MOVE. Added in 0.3e. Leave out for older versions + * (optional=CAMERA_CUT) + * + * + * + * + * Using the camera functions directly after enabling spectator mode doesn't work. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player specified does not exist. + * + */ +native SetPlayerCameraLookAt(playerid, Float:x, Float:y, Float:z, CAM_MOVE:cut = CAMERA_CUT); + +/** + * a_players + * Restore the camera to a place behind the player, after using a function like + * SetPlayerCameraPos. + * The player you want to restore the camera for + * + * + */ native SetCameraBehindPlayer(playerid); -/// Get the position of the player's camera. -/// The ID of the player to get the camera position of -/// A float variable to store the X coordinate in, passed by reference -/// A float variable to store the Y coordinate in, passed by reference -/// A float variable to store the Z coordinate in, passed by reference -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// Player's camera positions are only updated once a second, unless aiming. -/// It is recommended to set a 1 second timer if you wish to take action that relies on a player's camera position. +/** + * a_players + * Get the position of the player's camera. + * The ID of the player to get the camera position of + * A float variable to store the x coordinate in, passed by reference + * A float variable to store the y coordinate in, passed by reference + * A float variable to store the z coordinate in, passed by reference + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * Player's camera positions are only updated once a second, unless aiming. + * It is recommended to set a 1 second timer if you wish to take action that relies on a player's + * camera position. + */ native GetPlayerCameraPos(playerid, &Float:x, &Float:y, &Float:z); -/// This function will return the current direction of player's aiming in 3-D space, the coords are relative to the camera position, see GetPlayerCameraPos. -/// The ID of the player you want to obtain the camera front vector of -/// A float to store the X coordinate, passed by reference -/// A float to store the Y coordinate, passed by reference -/// A float to store the Z coordinate, passed by reference -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// In 0.3a the camera front vector is only obtainable when player is inside a rhino, S.W.A.T tank, fire truck, or on foot. -/// Since 0.3b the camera data can be obtained when the player is in any vehicle or on foot. -/// The position is stored in the specified variables. +/** + * a_players + * This function will return the current direction of player's aiming in 3-D space, the coords + * are relative to the camera position, see GetPlayerCameraPos. + * The ID of the player you want to obtain the camera front vector of + * A float to store the x coordinate, passed by reference + * A float to store the y coordinate, passed by reference + * A float to store the z coordinate, passed by reference + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * In 0.3a the camera front vector is only obtainable when player is inside a rhino, + * S.W.A.T tank, fire truck, or on foot. + * Since 0.3b the camera data can be obtained when the player is in any vehicle or on + * foot. + * The position is stored in the specified variables. + */ native GetPlayerCameraFrontVector(playerid, &Float:x, &Float:y, &Float:z); -/// Returns the current GTA camera mode for the requested player. The camera modes are useful in determining whether a player is aiming, doing a passenger driveby etc. -/// The ID of the player whose camera mode to retrieve -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// The camera mode as an integer (or -1 if player is not connected). -native GetPlayerCameraMode(playerid); - -/// Toggle camera targeting functions for a player. Disabled by default to save bandwidth. -/// The ID of the player to toggle camera targeting functions for -/// 1 to enable camera targeting functions and 0 to disable them -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player is not connected. -/// -native EnablePlayerCameraTarget(playerid, enable); - -///

Allows you to retrieve the ID of the object the player is looking at. -/// The ID of the player to check -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget to enable it for each player. -/// The ID of the object playerid is looking at. If INVALID_OBJECT_ID (65535) is returned, playerid isn't looking at any object. +/** + * a_players + * Returns the current GTA camera mode for the requested player. The camera modes are useful + * in determining whether a player is aiming, doing a passenger driveby etc. + * The ID of the player whose camera mode to retrieve + * + * + * + * + * + * This function was added in SA-MP 0.3c R3 and will not work in earlier versions! + * The camera mode as an integer (or -1 if player is not connected). + */ +native CAM_MODE:GetPlayerCameraMode(playerid); + +/** + * a_players + * Toggle camera targeting functions for a player. Disabled by default to save bandwidth. + * The ID of the player to toggle camera targeting functions for + * 1 to enable camera targeting functions and 0 to + * disable them + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player is not connected. + * + */ +native EnablePlayerCameraTarget(playerid, bool:enable); + +/** + * a_players + * Allows you to retrieve the ID of the object the player is looking at. + * The ID of the player to check + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget + * to enable it for each player. + * The ID of the object playerid is looking at. If INVALID_OBJECT_ID (65535) + * is returned, playerid isn't looking at any object. + */ native GetPlayerCameraTargetObject(playerid); -/// Get the ID of the vehicle the player is looking at. -/// The ID of the player to check -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget to enable it for each player. -/// This function can (obviously) only return one vehicle ID at a time, while the player may be looking at multiple. It generally seems to detect the closest vehicle first. -/// The vehicle ID of the vehicle the player is looking at. INVALID_VEHICLE_ID if none. +/** + * a_players + * Get the ID of the vehicle the player is looking at. + * The ID of the player to check + * + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget + * to enable it for each player. + * This function can (obviously) only return one vehicle ID at a time, while the player may + * be looking at multiple. It generally seems to detect the closest vehicle first. + * The vehicle ID of the vehicle the player is looking at. INVALID_VEHICLE_ID + * if none. + */ native GetPlayerCameraTargetVehicle(playerid); -/// Allows you to retrieve the ID of the player the playerid is looking at. -/// The ID of the player to check -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget to enable it for each player. -/// Do not confuse this function with GetPlayerTargetPlayer. GetPlayerTargetPlayer returns the ID of the player playerid is aming at (with a weapon). GetPlayerCameraTargetPlayer returns the ID of the player playerid is looking at (reference point is the center of the screen). -/// The ID of the player the playerid is looking at. +/** + * a_players + * Allows you to retrieve the ID of the player the playerid is looking at. + * The ID of the player to check + * + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget + * to enable it for each player. + * Do not confuse this function with GetPlayerTargetPlayer. + * GetPlayerTargetPlayer returns the ID of the player playerid + * is aming at (with a weapon). GetPlayerCameraTargetPlayer + * returns the ID of the player playerid is looking at (reference point is the center of the screen). + * The ID of the player the playerid is looking at. + */ native GetPlayerCameraTargetPlayer(playerid); -/// Allows you to retrieve the ID of the actor the player is looking at (if any). -/// The ID of the player to get the target actor of -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget to enable it for each player. -/// This function only tells you which actor (if any) the player is looking at. To find out if they are aiming at them, you need to use GetPlayerTargetActor. -/// The ID of the actor the player is looking at. +/** + * a_players + * Allows you to retrieve the ID of the actor the player is looking at (if any). + * The ID of the player to get the target actor of + * + * + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * This function is disabled by default to save bandwidth. Use EnablePlayerCameraTarget + * to enable it for each player. + * This function only tells you which actor (if any) the player is looking at. To find + * out if they are aiming at them, you need to use GetPlayerTargetActor. + * The ID of the actor the player is looking at. + */ native GetPlayerCameraTargetActor(playerid); -/// Retrieves the aspect ratio of a player's camera. -/// The ID of the player to get the camera aspect ratio of -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// The return value of this function represents the value of the "widescreen" option in the game's display settings, not the actual aspect ratio of the player's display. -/// The aspect ratio of the player's camera, as a float. The aspect ratio can be one of three values: 4:3 (1.3333334, Float:0x3FAAAAAB) when widescreen is turned off, 5:4 (1.2470589, Float:0x3F9F9FA0) when letterbox mode is turned on, and 16:9 (1.7764707, Float:0x3FE36364) when widescreen is turned on regardless of the letterbox mode. +/** + * a_players + * Retrieves the aspect ratio of a player's camera. + * The ID of the player to get the camera aspect ratio of + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * The return value of this function represents the value of the "widescreen" option in the + * game's display settings, not the actual aspect ratio of the player's display. + * The aspect ratio of the player's camera, as a float. The aspect ratio can be one of three + * values: 4:3 (1.3333334, Float:0x3FAAAAAB) when widescreen is turned off, + * 5:4 (1.2470589, Float:0x3F9F9FA0) when letterbox mode is turned on, and + * 16:9 (1.7764707, Float:0x3FE36364) when widescreen is turned on regardless + * of the letterbox mode. + */ native Float:GetPlayerCameraAspectRatio(playerid); -/// Retrieves the game camera zoom level for a given player. -/// The ID of the player to get the camera zoom level of -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// This retrieves the zoom level of the GAME camera, not the camera WEAPON. -/// The player's camera zoom level (camera, sniper etc.), a float. +/** + * a_players + * Retrieves the game camera zoom level for a given player. + * The ID of the player to get the camera zoom level of + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * This retrieves the zoom level of the GAME camera, not the camera WEAPON. + * The player's camera zoom level (camera, sniper etc.), a float. + */ native Float:GetPlayerCameraZoom(playerid); -/// You can use this function to attach the player camera to objects. -/// The ID of the player which will have your camera attached on object -/// The object id which you want to attach the player camera -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// You need to create the object first, before attempting to attach a player camera for that. +/** + * a_players + * You can use this function to attach the player camera to objects. + * The ID of the player which will have your camera attached on object + * The object ID which you want to attach the player camera + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * You need to create the object first, before attempting to attach a player camera for that. + */ native AttachCameraToObject(playerid, objectid); -/// Attaches a player's camera to a player-object. The player is able to move their camera while it is attached to an object. Can be used with MovePlayerObject and AttachPlayerObjectToVehicle. -/// The ID of the player which will have their camera attached to a player-object -/// The ID of the player-object to which the player's camera will be attached -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// The player-object must be created before attempting to attach the player's camera to it. -native AttachCameraToPlayerObject(playerid, playerobjectid); - - -/// Move a player's camera from one position to another, within the set time. Useful for scripted cut scenes. -/// The ID of the player the camera should be moved for -/// The X position the camera should start to move from -/// The Y position the camera should start to move from -/// The Z position the camera should start to move from -/// The X position the camera should move to -/// The Y position the camera should move to -/// The Z position the camera should move to -/// Time in milliseconds -/// The jumpcut to use. Set to CAMERA_MOVE for a smooth movement (optional=CAMERA_CUT) -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Use TogglePlayerSpectating to make objects stream in for the player while the camera is moving. You can reset the camera behind the player with SetCameraBehindPlayer. -native InterpolateCameraPos(playerid, Float:FromX, Float:FromY, Float:FromZ, Float:ToX, Float:ToY, Float:ToZ, time, cut = CAMERA_CUT); - -/// Interpolate a player's camera's 'look at' point between two coordinates with a set speed. Can be be used with InterpolateCameraPos. -/// The ID of the player the camera should be moved for -/// The X position the camera should start to move from -/// The Y position the camera should start to move from -/// The Z position the camera should start to move from -/// The X position the camera should move to -/// The Y position the camera should move to -/// The Z position the camera should move to -/// Time in milliseconds to complete interpolation -/// The 'jumpcut' to use. Set to CAMERA_MOVE for interpolation (optional=CAMERA_CUT) -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// Use TogglePlayerSpectating to make objects stream in for the player while the camera is moving. You can reset the camera behind the player with SetCameraBehindPlayer. -native InterpolateCameraLookAt(playerid, Float:FromX, Float:FromY, Float:FromZ, Float:ToX, Float:ToY, Float:ToZ, time, cut = CAMERA_CUT); +/** + * a_players + * Attaches a player's camera to a player-object. The player is able to move their camera + * while it is attached to an object. Can be used with MovePlayerObject and AttachPlayerObjectToVehicle. + * The ID of the player which will have their camera attached to a player-object + * The ID of the player-object to which the player's camera will be attached + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * The player-object must be created before attempting to attach the player's camera to it. + */ +native AttachCameraToPlayerObject(playerid, objectid); + +/** + * a_players + * Move a player's camera from one position to another, within the set time. Useful for scripted + * cut scenes. + * The ID of the player the camera should be moved for + * The x position the camera should start to move from + * The y position the camera should start to move from + * The z position the camera should start to move from + * The x position the camera should move to + * The y position the camera should move to + * The z position the camera should move to + * Time in milliseconds + * The jumpcut to use. Set to CAMERA_MOVE for a smooth movement (optional=CAMERA_CUT) + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Use TogglePlayerSpectating to make objects stream in for the player while + * the camera is moving. You can reset the camera behind the player with SetCameraBehindPlayer. + */ +native InterpolateCameraPos(playerid, Float:fromX, Float:fromY, Float:fromZ, Float:toX, Float:toY, Float:toZ, time, CAM_MOVE:cut = CAMERA_CUT); + +/** + * a_players + * Interpolate a player's camera's 'look at' point between two coordinates with a set speed. + * Can be be used with InterpolateCameraPos. + * The ID of the player the camera should be moved for + * The x position the camera should start to move from + * The y position the camera should start to move from + * The z position the camera should start to move from + * The x position the camera should move to + * The y position the camera should move to + * The z position the camera should move to + * Time in milliseconds to complete interpolation + * The 'jumpcut' to use. Set to CAMERA_MOVE for interpolation (optional=CAMERA_CUT) + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * Use TogglePlayerSpectating to make objects stream in for the player while + * the camera is moving. You can reset the camera behind the player with SetCameraBehindPlayer. + */ +native InterpolateCameraLookAt(playerid, Float:fromX, Float:fromY, Float:fromZ, Float:toX, Float:toY, Float:toZ, time, CAM_MOVE:cut = CAMERA_CUT); // Player conditionals -/// Checks if a player is connected (if an ID is taken by a connected player). -/// The ID of the player to check -/// -/// -/// -/// This function can be omitted in a lot of cases. Many other functions already have some sort of connection check built in. -/// 1 if the player is connected, 0 if not. -native IsPlayerConnected(playerid); - -/// Checks if a player is in a specific vehicle. -/// ID of the player -/// ID of the vehicle -/// -/// -/// 1 if the player is in the vehicle, 0 if not. -native IsPlayerInVehicle(playerid, vehicleid); - -/// Check if a player is inside any vehicle (as a driver or passenger). -/// The ID of the player to check -/// -/// -/// 1 if the player is in a vehicle, 0 if not. -native IsPlayerInAnyVehicle(playerid); - -/// Check if the player is currently inside a checkpoint, this could be used for properties or teleport points for example. -/// The player you want to know the status of -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 0 if player isn't in his checkpoint else 1. -native IsPlayerInCheckpoint(playerid); - -/// Check if the player is inside their current set race checkpoint (SetPlayerRaceCheckpoint). -/// The ID of the player to check -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 1 is the player is in a race checkpoint, 0 if not. -native IsPlayerInRaceCheckpoint(playerid); +/** + * a_players + * Checks if a player is connected (if an ID is taken by a connected player). + * The ID of the player to check + * + * + * + * This function can be omitted in a lot of cases. Many other functions already have some + * sort of connection check built in. + * 1 if the player is connected, 0 if not. + */ +native bool:IsPlayerConnected(playerid); + +/** + * a_players + * Checks if a player is in a specific vehicle. + * ID of the player + * ID of the vehicle + * + * + * 1 if the player is in the vehicle, 0 if not. + */ +native bool:IsPlayerInVehicle(playerid, vehicleid); + +/** + * a_players + * Check if a player is inside any vehicle (as a driver or passenger). + * The ID of the player to check + * + * + * 1 if the player is in a vehicle, 0 if not. + */ +native bool:IsPlayerInAnyVehicle(playerid); + +/** + * a_players + * Check if the player is currently inside a checkpoint, this could be used for properties + * or teleport points for example. + * The player you want to know the status of + * + * + * + * + * + * + * + * + * + * 0 if player isn't in his checkpoint else 1. + */ +native bool:IsPlayerInCheckpoint(playerid); + +/** + * a_players + * Check if the player is inside their current set race checkpoint + * (SetPlayerRaceCheckpoint). + * The ID of the player to check + * + * + * + * + * + * + * + * + * + * 1 is the player is in a race checkpoint, 0 if not. + */ +native bool:IsPlayerInRaceCheckpoint(playerid); // Virtual Worlds -/// Set the virtual world of a player. They can only see other players or vehicles that are in that same world. -/// The ID of the player you want to set the virtual world of -/// The virtual world ID to put the player in -/// -/// -/// The default virtual world is 0 -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected. -/// -native SetPlayerVirtualWorld(playerid, worldid); - -///

Retrieves the current virtual world the player is in. -/// The ID of the player to get the virtual world of -/// -/// -/// -/// The ID of the virtual world the player is currently in. +/** + * a_players + * Set the virtual world of a player. They can only see other players or vehicles that are + * in that same world. + * The ID of the player you want to set the virtual world of + * The virtual world ID to put the player in + * + * + * The default virtual world is 0 + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected. + * + */ +native SetPlayerVirtualWorld(playerid, virtualWorld); + +/** + * a_players + * Retrieves the current virtual world the player is in. + * The ID of the player to get the virtual world of + * + * + * + * The ID of the virtual world the player is currently in. + */ native GetPlayerVirtualWorld(playerid); // Insane Stunts -/// Toggle stunt bonuses for a player. Enabled by default. -/// The ID of the player to toggle stunt bonuses for -/// 1 to enable stunt bonuses and 0 to disable them -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player is not connected. -/// -native EnableStuntBonusForPlayer(playerid, enable); - -///

Enables or disables stunt bonuses for all players. If enabled, players will receive monetary rewards when performing a stunt in a vehicle (e.g. a wheelie). -/// 1 to enable stunt bonuses or 0 to disable them -/// -native EnableStuntBonusForAll(enable); - -/// Toggle whether a player is in spectator mode or not. While in spectator mode a player can spectate (watch) other players and vehicles. After using this function, either PlayerSpectatePlayer or PlayerSpectateVehicle needs to be used. -/// The ID of the player who should spectate -/// 1 to enable spectating and 0 to disable -/// -/// -/// If the player is not loaded in before setting the spectate status to false, the connection can be closed unexpectedly. -/// When spectator mode is disabled, OnPlayerSpawn will automatically be called, if you wish to restore player to state before spectating, you will have to handle that in OnPlayerSpawn. Note also, that player can also go to class selection before if they used F4 during spectate, a player also CAN die in spectate mode due to various glitches. -/// When a player is in spectate mode their HUD is hidden, making it useful for setting a player's camera without the HUD. Also, objects near the player's camera will be streamed in, making this useful for interpolating cameras. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The player does not exist. -/// -native TogglePlayerSpectating(playerid, toggle); - -///

Makes a player spectate (watch) another player. -/// The ID of the player that will spectate -/// The ID of the player that should be spectated -/// The mode to spectate with (optional=SPECTATE_MODE_NORMAL) -/// -/// -/// Order is CRITICAL! Ensure that you use TogglePlayerSpectating before PlayerSpectatePlayer. -/// playerid and targetplayerid's virtual world and interior must be the same for this function to work properly. -/// -/// Spectate modes:

-///

    -///
  • SPECTATE_MODE_NORMAL - normal spectate mode (third person point of view). Camera can not be changed.
    • -///
  • SPECTATE_MODE_FIXED - use SetPlayerCameraPos after this to position the player's camera, and it will track the player/vehicle set with PlayerSpectatePlayer/PlayerSpectateVehicle.
    • -///
  • SPECTATE_MODE_SIDE - the camera will be attached to the side of the player/vehicle (like when you're in first-person camera on a bike and you do a wheelie).
    • -///
-/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. One of the players specified does not exist. -/// -native PlayerSpectatePlayer(playerid, targetplayerid, mode = SPECTATE_MODE_NORMAL); - -///

Sets a player to spectate another vehicle. Their camera will be attached to the vehicle as if they are driving it. -/// The ID of the player who should spectate a vehicle -/// The ID of the vehicle the player should spectate -/// The spectate mode. Can generally be left blank as it defaults to 'normal' -/// -/// -/// Order is CRITICAL! Ensure that you use TogglePlayerSpectating before PlayerSpectatePlayer. -/// playerid and targetvehicleid have to be in the same interior for this function to work properly. -/// -/// 1: The function executed successfully. Note that success is reported if the player is not in spectator mode (TogglePlayerSpectating), but nothing will happen. TogglePlayerSpectating MUST be used first.

-/// 0: The function failed to execute. The player, vehicle, or both don't exist. -/// -native PlayerSpectateVehicle(playerid, targetvehicleid, mode = SPECTATE_MODE_NORMAL); - -///

Starts recording a player's movements to a file, which can then be reproduced by an NPC. -/// The ID of the player to record -/// The type of recording -/// The name of the file which will hold the recorded data. It will be saved in the scriptfiles directory, with an automatically added .rec extension, you will need to move the file to npcmodes/recordings to use for playback -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -native StartRecordingPlayerData(playerid, recordtype, const recordname[]); - -/// Stops all the recordings that had been started with StartRecordingPlayerData for a specific player. -/// The player you want to stop the recordings of -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! +/** + * a_players + * Toggle stunt bonuses for a player. Enabled by default. + * The ID of the player to toggle stunt bonuses for + * 1 to enable stunt bonuses and 0 to disable them + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player is not connected. + * + */ +native EnableStuntBonusForPlayer(playerid, bool:enable); + +/** + * a_players + * Enables or disables stunt bonuses for all players. If enabled, players will receive monetary + * rewards when performing a stunt in a vehicle (e.g. a wheelie). + * 1 to enable stunt bonuses or 0 to disable them + * + */ +native EnableStuntBonusForAll(bool:enable); + +/** + * a_players + * Toggle whether a player is in spectator mode or not. While in spectator mode a player can + * spectate (watch) other players and vehicles. After using this function, either PlayerSpectatePlayer + * or PlayerSpectateVehicle needs to be used. + * The ID of the player who should spectate + * 1 to enable spectating and 0 to disable + * + * + * If the player is not loaded in before setting the spectate status to false, the connection + * can be closed unexpectedly. + * When spectator mode is disabled, OnPlayerSpawn will automatically + * be called, if you wish to restore player to state before spectating, you will have to handle that + * in OnPlayerSpawn. Note also, that player can also go to class selection + * before if they used F4 during spectate, a player also CAN die in spectate mode due to various glitches. + * When a player is in spectate mode their HUD is hidden, making it useful for setting a player's + * camera without the HUD. Also, objects near the player's camera will be streamed in, making this + * useful for interpolating cameras. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The player does not exist. + * + */ +native TogglePlayerSpectating(playerid, bool:toggle); + +/** + * a_players + * Makes a player spectate (watch) another player. + * The ID of the player that will spectate + * The ID of the player that should be spectated + * The mode to spectate with (optional=SPECTATE_MODE_NORMAL) + * + * + * Order is CRITICAL! Ensure that you use TogglePlayerSpectating + * before PlayerSpectatePlayer. + * playerid and targetid's virtual world and interior must be the same for this function to + * work properly. + * + * Spectate modes:
+ *
    + *
  • SPECTATE_MODE_NORMAL - normal spectate mode (third person point of view). + * Camera can not be changed.
    • + *
  • SPECTATE_MODE_FIXED - use SetPlayerCameraPos after this to position the player's + * camera, and it will track the player/vehicle set with PlayerSpectatePlayer/PlayerSpectateVehicle.
    • + *
  • SPECTATE_MODE_SIDE - the camera will be attached to the side of the player/vehicle + * (like when you're in first-person camera on a bike and you do a wheelie).
    • + *
+ * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. One of the players specified does not exist. + * + */ +native PlayerSpectatePlayer(playerid, targetid, SPECTATE_MODE:mode = SPECTATE_MODE_NORMAL); + +/** + * a_players + * Sets a player to spectate another vehicle. Their camera will be attached to the vehicle + * as if they are driving it. + * The ID of the player who should spectate a vehicle + * The ID of the vehicle the player should spectate + * The spectate mode. Can generally be left blank as it defaults to 'normal' + * + * + * Order is CRITICAL! Ensure that you use TogglePlayerSpectating + * before PlayerSpectatePlayer. + * playerid and targetid have to be in the same interior for this function to work properly. + * + * + * 1: The function executed successfully. Note that success is reported if the player + * is not in spectator mode (TogglePlayerSpectating), but nothing + * will happen. TogglePlayerSpectating MUST be used first.
+ * 0: The function failed to execute. The player, vehicle, or both don't exist. + * + */ +native PlayerSpectateVehicle(playerid, targetid, SPECTATE_MODE:mode = SPECTATE_MODE_NORMAL); + +/** + * a_players + * Starts recording a player's movements to a file, which can then be reproduced by an NPC. + * The ID of the player to record + * The type of recording + * The name of the file which will hold the recorded data. It will be saved + * in the scriptfiles directory, with an automatically added .rec extension, you will need to move the + * file to npcmodes/recordings to use for playback + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native StartRecordingPlayerData(playerid, PLAYER_RECORDING_TYPE:recordType, const recordFile[]); + +/** + * a_players + * Stops all the recordings that had been started with StartRecordingPlayerData + * for a specific player. + * The player you want to stop the recordings of + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + */ native StopRecordingPlayerData(playerid); -/// Display the cursor and allow the player to select a textdraw. -/// The ID of the player that should be able to select a textdraw -/// The color of the textdraw when hovering over with mouse (RGBA) -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// TextDrawSetSelectable or PlayerTextDrawSetSelectable MUST be used first, to allow a textdraw to be selectable. -/// It is the TEXT which will be highlighted when hovered over, NOT the box (if one is shown). -native SelectTextDraw(playerid, hovercolor); // enables the mouse so the player can select a textdraw - -/// Cancel textdraw selection with the mouse. -/// The ID of the player that should be the textdraw selection disabled -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// This function calls OnPlayerClickTextDraw with INVALID_TEXT_DRAW (65535). Using this function inside OnPlayerClickTextDraw without catching this case will cause clients to go into an infinite loop. +/** + * a_players + * Display the cursor and allow the player to select a textdraw. + * The ID of the player that should be able to select a textdraw + * The colour of the textdraw when hovering over with mouse (RGBA) + * + * + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * TextDrawSetSelectable or + * PlayerTextDrawSetSelectable + * MUST be used first, to allow a textdraw to be selectable. + * It is the TEXT which will be highlighted when hovered over, NOT the box (if one is shown). + */ +native SelectTextDraw(playerid, hoverColour); // enables the mouse so the player can select a textdraw + +/** + * a_players + * Cancel textdraw selection with the mouse. + * The ID of the player that should be the textdraw selection disabled + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * This function calls OnPlayerClickTextDraw with INVALID_TEXT_DRAW + * (65535). Using this function inside OnPlayerClickTextDraw + * without catching this case will cause clients to go into an infinite loop. + */ native CancelSelectTextDraw(playerid); // cancel textdraw selection with the mouse // Explosion -/// Creates an explosion that is only visible to a single player. This can be used to isolate explosions from other players or to make them only appear in specific virtual worlds. -/// The ID of the player to create the explosion for -/// The X coordinate of the explosion -/// The Y coordinate of the explosion -/// The Z coordinate of the explosion -/// The explosion type -/// The radius of the explosion -/// -/// This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! -/// There is a limit as to how many explosions can be seen at once by a player. This is roughly 10. -/// This function always returns 1, even if the function failed to excute (player doesn't exist, invalid radius, or invalid explosion type). -native CreateExplosionForPlayer(playerid, Float:X, Float:Y, Float:Z, type, Float:Radius); - -/// Perform a memory check on the client. -/// The ID of the player to check -/// The type of check to perform -/// The base address to check -/// The offset from the base address -/// The number of bytes to check -native SendClientCheck(playerid, type, memAddr, memOffset, byteCount); +/** + * a_players + * Creates an explosion that is only visible to a single player. This can be used to isolate + * explosions from other players or to make them only appear in specific virtual + * worlds. + * The ID of the player to create the explosion for + * The x coordinate of the explosion + * The y coordinate of the explosion + * The z coordinate of the explosion + * The explosion type + * The radius of the explosion + * + * This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! + * There is a limit as to how many explosions can be seen at once by a player. This is roughly + * 10. + * This function always returns 1, even if the function failed to excute (player + * doesn't exist, invalid radius, or invalid explosion type). + */ +native CreateExplosionForPlayer(playerid, Float:x, Float:y, Float:z, type, Float:radius); + +/** + * a_players + * Perform a memory check on the client. + * The ID of the player to check + * The type of check to perform + * The base address to check + * The offset from the base address + * The number of bytes to check + */ +native SendClientCheck(playerid, type, memoryAddress, memoryOffset, byteCount); + +/** + * a_players + * Creates a 3D Text Label only for a specific player. + * The player which should see the newly created 3DText Label + * The text to display + * The text colour + * x Coordinate (or offset if attached) + * y Coordinate (or offset if attached) + * z Coordinate (or offset if attached) + * The distance where you are able to see the 3D Text Label + * The player you want to attach the 3D Text Label to. (optional=INVALID_PLAYER_ID) + * The vehicle you want to attach the 3D Text Label to. (optional=INVALID_VEHICLE_ID) + * Test the line-of-sight so this text can't be seen through walls (optional=0) + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * If is empty, the server/clients next to the text might crash! + * drawdistance seems to be a lot smaller when spectating. + * The ID of the newly created Player 3D Text Label, or INVALID_3DTEXT_ID if + * the Player 3D Text Label limit (MAX_3DTEXT_PLAYER) was reached. + */ +native PlayerText3D:CreatePlayer3DTextLabel(playerid, const text[], colour, Float:x, Float:y, Float:z, Float:drawDistance, parentPlayerid = INVALID_PLAYER_ID, parentVehicleid = INVALID_VEHICLE_ID, bool:testLOS = false); + +/** + * a_players + * Destroy a 3D text label that was created using CreatePlayer3DTextLabel. + * The ID of the player whose 3D text label to delete + * The ID of the player's 3D text label to delete + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the label specified doesn't exist. + * + */ +native DeletePlayer3DTextLabel(playerid, PlayerText3D:textid); + +/** + * a_players + * Updates a player 3D Text Label's text and colour. + * The ID of the player for which the 3D Text Label was created + * The 3D Text Label you want to update + * The colour the 3D Text Label should have from now on + * The new text which the 3D Text Label should have from now on + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * If is empty, the server/clients next to the text might crash! + */ +native UpdatePlayer3DTextLabelText(playerid, PlayerText3D:textid, colour, const text[]); + +/** + * This callback is called when a player clicks on a player-textdraw. It is not called when + * player cancels the select mode (ESC) - however, OnPlayerClickTextDraw + * is. + * The ID of the player that selected a textdraw + * The ID of the player-textdraw that the player selected + * + * + * + * This callback was added in SA-MP 0.3e and will not work in earlier versions! + * When a player presses ESC to cancel selecting a textdraw, OnPlayerClickTextDraw + * is called with a textdraw ID of INVALID_TEXT_DRAW. OnPlayerClickPlayerTextDraw + * won't be called also. + * + * Returning 1 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 0 if the textdraw on which they clicked wasn't found, + * just like in OnPlayerCommandText.
+ * It is always called first in filterscripts so returning 1 there also blocks other + * scripts from seeing it. + * + */ +forward OnPlayerClickPlayerTextDraw(playerid, PlayerText:playertextid); + +/** + * This callback is called when a player is streamed by some other player's client. + * The ID of the player who has been streamed + * The ID of the player that streamed the other player in + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +forward OnPlayerStreamIn(playerid, forplayerid); + +/** + * This callback is called when a player is streamed out from some other player's client. + * The player who has been destreamed + * The player who has destreamed the other player + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +forward OnPlayerStreamOut(playerid, forplayerid); + +/** + * This callback is called when a player takes damage. + * The ID of the player that took damage + * The ID of the player that caused the damage. INVALID_PLAYER_ID + * if self-inflicted + * The amount of damage the player took (health and armour combined) + * The ID of the weapon/reason + * for the damage + * The body part that was hit. (NOTE: This parameter was added in 0.3z. + * Leave it out if using an older version!) + * + * + * This callback was added in SA-MP 0.3d and will not work in earlier versions! + * GetPlayerHealth and GetPlayerArmour + * will return the old amounts of the player before this callback. + * + * The weaponid will return 37 (flame thrower) from any fire sources (e.g. molotov, + * 18).
+ * The weaponid will return 51 from any weapon that creates an explosion (e.g. RPG, + * grenade)
+ * playerid is the only one who can call the callback.
+ * 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 100.0 health and gets shot with a Desert + * Eagle which has a damage value of 46.2, it takes 3 shots to kill that player. All + * 3 shots will show an amount of 46.2, even though when the last shot hits, the player + * only has 7.6 health left. + * + * + * 1 - Callback will not be called in other filterscripts.
+ * 0 - Allows this callback to be called in other filterscripts.
+ * It is always called first in filterscripts so returning 1 there blocks other filterscripts + * from seeing it. + * + */ +forward OnPlayerTakeDamage(playerid, issuerid, Float:amount, weaponid, bodypart); + +/** + * This callback is called when a player gives damage to another player. + * The ID of the player that gave damage + * The ID of the player that received damage + * The amount of health/armour damagedid has lost (combined) + * The reason that caused the + * damage + * The body part that was hit. (NOTE: This parameter was added in 0.3z. + * Leave it out if using an older version!) + * + * This callback was added in SA-MP 0.3d and will not work in earlier versions! + * + * Keep in mind this function can be inaccurate in some cases.
+ * If you want to prevent certain players from damaging eachother, use SetPlayerTeam.
+ * The weaponid will return 37 (flame thrower) from any fire sources (e.g. molotov, + * 18)
+ * The weaponid will return 51 from any weapon that creates an explosion (e.g. RPG, + * grenade)
+ * playerid is the only one who can call the callback.
+ * 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 100.0 health and gets shot with a Desert + * Eagle which has a damage value of 46.2, it takes 3 shots to kill that player. All + * 3 shots will show an amount of 46.2, even though when the last shot hits, the player + * only has 7.6 health left. + * + * + * 1 - Callback will not be called in other filterscripts.
+ * 0 - Allows this callback to be called in other filterscripts.
+ * It is always called first in filterscripts so returning 1 there blocks other filterscripts + * from seeing it. + * + */ +forward OnPlayerGiveDamage(playerid, damagedid, Float:amount, weaponid, bodypart); + +/** + * Called when a player double-clicks on a player on the scoreboard. + * The ID of the player that clicked on a player on the scoreboard + * The ID of the player that was clicked on + * The source of the player's click + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * There is currently only one (0 - CLICK_SOURCE_SCOREBOARD). + * The existence of this argument suggests that more sources may be supported in the future. + * + * 1 - Will prevent other filterscripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ +#if !defined CLICK_SOURCE + #define CLICK_SOURCE: _: +#endif +forward OnPlayerClickPlayer(playerid, clickedplayerid, CLICK_SOURCE:source); + +/** + * This callback is called when a player dies, either by suicide or by being killed by another + * player. + * The ID of the player that died + * The ID of the player that killed the player who died, or INVALID_PLAYER_ID + * if there was none + * The ID of the reason for the + * player's death + * + * + * + * + * The reason will return 37 (flame thrower) from any fire sources (e.g. molotov, 18)
+ * The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)
+ * You do not need to check whether killerid is valid before using it in SendDeathMessage. + * INVALID_PLAYER_ID is a valid killerid ID parameter in that function.
+ * playerid is the only one who can call the callback. (good to know for anti fake death) + * + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ +forward OnPlayerDeath(playerid, killerid, reason); diff --git a/a_samp.inc b/a_samp.inc old mode 100755 new mode 100644 index 7bba236..9369622 --- a/a_samp.inc +++ b/a_samp.inc @@ -1,9 +1,3 @@ -/* SA-MP Functions - * - * (c) Copyright 2005-2017, SA-MP Team - * - */ - #if defined _INC_a_samp #endinput #endif @@ -13,227 +7,210 @@ #define _INC_a_samp #define _samp_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2005-2017, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ + +///

-#pragma tabsize 4 // Ignores warning 217 for properly indented PAWNO code // It's tab size is 4 and often uses 4 spaces instead, PAWNCC's is 8 +#pragma tabsize 4 +#define SAMP_CONST_CORRECT -// -------------------------------------------------- -// Defines -// -------------------------------------------------- - -// Limits -#if !defined MAX_PLAYER_NAME - #define MAX_PLAYER_NAME (24) -#endif - -#if !defined MAX_PLAYERS - #define MAX_PLAYERS (1000) -#endif +/** + * + * Version examples: + *

    + *
  • 0.3.DL R1 - 03D010
    • + *
    • + *
  • 0.3.7 R3 - 037030
    • + *
  • 0.3.7 R2-2 - 037022
    • + *
  • 0.3.7 R1-2 - 037012
    • + *
  • 0.3.7 - 037000
    • + *
    • + *
  • 0.3z R4 - 030700
    • + *
  • 0.3z R3 - 030700
    • + *
  • 0.3z R2-1 - 030700
    • + *
  • 0.3z R1-2 - 030700
    • + *
  • 0.3z - 030700
    • + *
  • 0.3x R2 patch 1 - 030621
    • + *
  • 0.3x R2 - 030620
    • + *
  • 0.3x R1-2 - 030612
    • + *
  • 0.3x - 030600
    • + *
  • 0.3e - 030500
    • + *
  • 0.3d - 030400
    • + *
  • 0.3c - 030300
    • + *
  • 0.3b - 030200
    • + *
  • 0.3a - 030100
    • + *
    • + *
  • 0.2X - 02A000
    • + *
  • 0.2.2 R3 - 022300
    • + *
+ * Rough rules: + * + *

+ * Uses (roughtly) BCD. Special versions are denoted outside 0-9. + * + * 0.1.2c R4-5 + * | | || | | + * 0 1 23 4 5 + * = + * 0x012345 + * + * (assuming c is the third revision) + * + *

+ * 0.2X becomes 02A000 because it is basically 0.2.3, but not, while higher than + * 0.2.2 so can't be 020400 (for example). Also, its a capital letter, so doesn't + * use the revision method. + * + *

+ * P.S. Making a consistent scheme for SA:MP versions is REALLY hard. + * + *

+ * open.mp releases can use `A` as the first digit. + * + */ -#if !defined MAX_VEHICLES - #define MAX_VEHICLES (2000) +public const __SAMP_INCLUDES_VERSION = 0x037030; +#pragma unused __SAMP_INCLUDES_VERSION + +/** + * + * If running on SA:MP this will remain 0, open.mp will set it. + * open.mp versions look like: + * + * 01.04.02.0544 + * + * Thus they are encoded here as: + * + * (major << 28) | (minor << 21) | (patch << 14) | (prerel) + * + * + */ +public const __OPEN_MP_VERSION = 0; +#pragma unused __OPEN_MP_VERSION + +// Optionally stricter tags. +#if defined NO_TAGS + #define __TAG(%0) _ +#elseif defined STRONG_TAGS + #define __TAG(%0) T_%0 +#else // if defined WEAK_TAGS + #define __TAG(%0) t_%0 + #define WEAK_TAGS #endif - -#if !defined MAX_ACTORS - #define MAX_ACTORS (1000) +#if defined MORE_TAGS + #define __MORE(%0) __TAG(%0) +#else + #define __MORE(%0) _ + #define LESS_TAGS #endif +#define __LESS __TAG -#if !defined MAX_OBJECTS - #define MAX_OBJECTS (2000) -#endif +// -------------------------------------------------- +// Defines +// -------------------------------------------------- -#if !defined MAX_GANG_ZONES - #define MAX_GANG_ZONES (1024) +// Limits +/** + * a_samp + */ +#if defined MAX_GANG_ZONES + const __MAX_GANG_ZONES = MAX_GANG_ZONES; + #define __MAX_GANG_ZONES +#else + const MAX_GANG_ZONES = 1024; + #define MAX_GANG_ZONES 1024 #endif -#if !defined MAX_TEXT_DRAWS +/** + * a_samp + */ +#if defined MAX_TEXT_DRAWS + const Text:__MAX_TEXT_DRAWS = MAX_TEXT_DRAWS; + #define __MAX_TEXT_DRAWS +#else + const Text:MAX_TEXT_DRAWS = Text:2048; #define MAX_TEXT_DRAWS (Text:2048) #endif -#if !defined MAX_PLAYER_TEXT_DRAWS - #define MAX_PLAYER_TEXT_DRAWS (PlayerText:256) -#endif - -#if !defined MAX_MENUS +/** + * a_samp + */ +#if defined MAX_MENUS + const Menu:__MAX_MENUS = MAX_MENUS; + #define __MAX_MENUS +#else + const Menu:MAX_MENUS = Menu:128; #define MAX_MENUS (Menu:128) #endif -#if !defined MAX_3DTEXT_GLOBAL +/** + * a_samp + */ +#if defined MAX_3DTEXT_GLOBAL + const Text3D:__MAX_3DTEXT_GLOBAL = MAX_3DTEXT_GLOBAL; + #define __MAX_3DTEXT_GLOBAL +#else + const Text3D:MAX_3DTEXT_GLOBAL = Text3D:1024; #define MAX_3DTEXT_GLOBAL (Text3D:1024) #endif -#if !defined MAX_3DTEXT_PLAYER - #define MAX_3DTEXT_PLAYER (PlayerText3D:1024) -#endif - -#if !defined MAX_PICKUPS - #define MAX_PICKUPS (4096) +/** + * a_samp + */ +#if defined MAX_PICKUPS + const __MAX_PICKUPS = MAX_PICKUPS; + #define __MAX_PICKUPS +#else + const MAX_PICKUPS = 4096; + #define MAX_PICKUPS 4096 #endif // Invalids -#define NO_TEAM (255) +/** + * a_samp + */ +const INVALID_TIMER = 0; +#define INVALID_TIMER 0 -#define INVALID_PLAYER_ID (0xFFFF) -#define INVALID_VEHICLE_ID (0xFFFF) -#define INVALID_ACTOR_ID (0xFFFF) -#define INVALID_OBJECT_ID (0xFFFF) +/** + * a_samp + */ +const Menu:INVALID_MENU = Menu:0xFF; #define INVALID_MENU (Menu:0xFF) -#define INVALID_TEXT_DRAW (Text:0xFFFF) -#define INVALID_PLAYER_TEXT_DRAW (PlayerText:0xFFFF) -#define INVALID_GANG_ZONE (-1) -#define INVALID_3DTEXT_ID (Text3D:0xFFFF) -#define INVALID_PLAYER_3DTEXT_ID (PlayerText3D:0xFFFF) - -// States -#define PLAYER_STATE_NONE (0) -#define PLAYER_STATE_ONFOOT (1) -#define PLAYER_STATE_DRIVER (2) -#define PLAYER_STATE_PASSENGER (3) -#define PLAYER_STATE_EXIT_VEHICLE (4) // (used internally) -#define PLAYER_STATE_ENTER_VEHICLE_DRIVER (5) // (used internally) -#define PLAYER_STATE_ENTER_VEHICLE_PASSENGER (6) // (used internally) -#define PLAYER_STATE_WASTED (7) -#define PLAYER_STATE_SPAWNED (8) -#define PLAYER_STATE_SPECTATING (9) - -// Marker modes used by ShowPlayerMarkers() -#define PLAYER_MARKERS_MODE_OFF (0) -#define PLAYER_MARKERS_MODE_GLOBAL (1) -#define PLAYER_MARKERS_MODE_STREAMED (2) - -// Weapons -#define WEAPON_BRASSKNUCKLE (1) -#define WEAPON_GOLFCLUB (2) -#define WEAPON_NITESTICK (3) -#define WEAPON_KNIFE (4) -#define WEAPON_BAT (5) -#define WEAPON_SHOVEL (6) -#define WEAPON_POOLSTICK (7) -#define WEAPON_KATANA (8) -#define WEAPON_CHAINSAW (9) -#define WEAPON_DILDO (10) -#define WEAPON_DILDO2 (11) -#define WEAPON_VIBRATOR (12) -#define WEAPON_VIBRATOR2 (13) -#define WEAPON_FLOWER (14) -#define WEAPON_CANE (15) -#define WEAPON_GRENADE (16) -#define WEAPON_TEARGAS (17) -#define WEAPON_MOLTOV (18) -#define WEAPON_COLT45 (22) -#define WEAPON_SILENCED (23) -#define WEAPON_DEAGLE (24) -#define WEAPON_SHOTGUN (25) -#define WEAPON_SAWEDOFF (26) -#define WEAPON_SHOTGSPA (27) -#define WEAPON_UZI (28) -#define WEAPON_MP5 (29) -#define WEAPON_AK47 (30) -#define WEAPON_M4 (31) -#define WEAPON_TEC9 (32) -#define WEAPON_RIFLE (33) -#define WEAPON_SNIPER (34) -#define WEAPON_ROCKETLAUNCHER (35) -#define WEAPON_HEATSEEKER (36) -#define WEAPON_FLAMETHROWER (37) -#define WEAPON_MINIGUN (38) -#define WEAPON_SATCHEL (39) -#define WEAPON_BOMB (40) -#define WEAPON_SPRAYCAN (41) -#define WEAPON_FIREEXTINGUISHER (42) -#define WEAPON_CAMERA (43) -#define WEAPON_PARACHUTE (46) -#define WEAPON_VEHICLE (49) -#define WEAPON_DROWN (53) -#define WEAPON_COLLISION (54) - -// Keys -#define KEY_ACTION (1) -#define KEY_CROUCH (2) -#define KEY_FIRE (4) -#define KEY_SPRINT (8) -#define KEY_SECONDARY_ATTACK (16) -#define KEY_JUMP (32) -#define KEY_LOOK_RIGHT (64) -#define KEY_HANDBRAKE (128) -#define KEY_LOOK_LEFT (256) -#define KEY_SUBMISSION (512) -#define KEY_LOOK_BEHIND (512) -#define KEY_WALK (1024) -#define KEY_ANALOG_UP (2048) -#define KEY_ANALOG_DOWN (4096) -#define KEY_ANALOG_LEFT (8192) -#define KEY_ANALOG_RIGHT (16384) -#define KEY_YES (65536) -#define KEY_NO (131072) -#define KEY_CTRL_BACK (262144) - -#define KEY_UP (-128) -#define KEY_DOWN (128) -#define KEY_LEFT (-128) -#define KEY_RIGHT (128) - -// Player GUI Dialog -#define DIALOG_STYLE_MSGBOX (0) -#define DIALOG_STYLE_INPUT (1) -#define DIALOG_STYLE_LIST (2) -#define DIALOG_STYLE_PASSWORD (3) -#define DIALOG_STYLE_TABLIST (4) -#define DIALOG_STYLE_TABLIST_HEADERS (5) - -// Text Draw -#define TEXT_DRAW_FONT_SPRITE_DRAW (4) -#define TEXT_DRAW_FONT_MODEL_PREVIEW (5) - -// SVar enumeration -#define SERVER_VARTYPE_NONE (0) -#define SERVER_VARTYPE_INT (1) -#define SERVER_VARTYPE_STRING (2) -#define SERVER_VARTYPE_FLOAT (3) - -// Artwork/NetModels -#define DOWNLOAD_REQUEST_EMPTY (0) -#define DOWNLOAD_REQUEST_MODEL_FILE (1) -#define DOWNLOAD_REQUEST_TEXTURE_FILE (2) - -#define CLICK_SOURCE_SCOREBOARD (0) - -#define EDIT_RESPONSE_CANCEL (0) -#define EDIT_RESPONSE_FINAL (1) -#define EDIT_RESPONSE_UPDATE (2) - -#define SELECT_OBJECT_GLOBAL_OBJECT (1) -#define SELECT_OBJECT_PLAYER_OBJECT (2) - -#define BULLET_HIT_TYPE_NONE (0) -#define BULLET_HIT_TYPE_PLAYER (1) -#define BULLET_HIT_TYPE_VEHICLE (2) -#define BULLET_HIT_TYPE_OBJECT (3) -#define BULLET_HIT_TYPE_PLAYER_OBJECT (4) -// Limits -#if MAX_PLAYER_NAME < 3 || MAX_PLAYER_NAME > 24 - #error MAX_PLAYER_NAME must be >= 3 and <= 24 -#endif - -#if MAX_PLAYERS < 1 || MAX_PLAYERS > 1000 - #error MAX_PLAYERS must be >= 1 and <= 1000 -#endif - -#if MAX_VEHICLES < 1 || MAX_VEHICLES > 2000 - #error MAX_VEHICLES must be >= 1 and <= 2000 -#endif +/** + * a_samp + */ +const Text:INVALID_TEXT_DRAW = Text:0xFFFF; +#define INVALID_TEXT_DRAW (Text:0xFFFF) -#if MAX_ACTORS < 1 || MAX_ACTORS > 1000 - #error MAX_ACTORS must be >= 1 and <= 1000 -#endif +/** + * a_samp + */ +const INVALID_GANG_ZONE = 0xFFFFFFFF; +#define INVALID_GANG_ZONE 0xFFFFFFFF -#if MAX_OBJECTS < 1 || MAX_OBJECTS > 2000 - #error MAX_OBJECTS must be >= 1 and <= 2000 -#endif +/** + * a_samp + */ +const Text3D:INVALID_3DTEXT_ID = Text3D:0xFFFF; +#define INVALID_3DTEXT_ID (Text3D:0xFFFF) +// Checks #if MAX_GANG_ZONES < 1 || MAX_GANG_ZONES > 1024 #error MAX_GANG_ZONES must be >= 1 and <= 1024 #endif @@ -242,10 +219,6 @@ #error MAX_TEXT_DRAWS must be >= 1 and <= 2048 #endif -#if MAX_PLAYER_TEXT_DRAWS < PlayerText:1 || MAX_PLAYER_TEXT_DRAWS > PlayerText:256 - #error MAX_PLAYER_TEXT_DRAWS must be >= 1 and <= 256 -#endif - #if MAX_MENUS < Menu:1 || MAX_MENUS > Menu:128 #error MAX_MENUS must be >= 1 and <= 128 #endif @@ -254,81 +227,377 @@ #error MAX_3DTEXT_GLOBAL must be >= 1 and <= 1024 #endif -#if MAX_3DTEXT_PLAYER < PlayerText3D:1 || MAX_3DTEXT_PLAYER > PlayerText3D:1024 - #error MAX_3DTEXT_PLAYER must be >= 1 and <= 1024 -#endif - #if MAX_PICKUPS < 1 || MAX_PICKUPS > 4096 #error MAX_PICKUPS must be >= 1 and <= 4096 #endif -public const SAMP_INCLUDES_VERSION = 0x037030; -#pragma unused SAMP_INCLUDES_VERSION +// Enums +///

-#include -#include -#include -#include -#include

Weapons + */ +#define WEAPON: __TAG(WEAPON): +enum WEAPON:__WEAPON +{ + WEAPON_UNKNOWN = -1, + WEAPON_FIST = 0, + WEAPON_BRASSKNUCKLE = 1, + WEAPON_GOLFCLUB = 2, + WEAPON_NITESTICK = 3, + WEAPON_NIGHTSTICK = WEAPON_NITESTICK, + WEAPON_KNIFE = 4, + WEAPON_BAT = 5, + WEAPON_SHOVEL = 6, + WEAPON_POOLSTICK = 7, + WEAPON_KATANA = 8, + WEAPON_CHAINSAW = 9, + WEAPON_DILDO = 10, + WEAPON_DILDO2 = 11, + WEAPON_VIBRATOR = 12, + WEAPON_VIBRATOR2 = 13, + WEAPON_FLOWER = 14, + WEAPON_CANE = 15, + WEAPON_GRENADE = 16, + WEAPON_TEARGAS = 17, + WEAPON_MOLTOV = 18, + WEAPON_MOLOTOV = WEAPON_MOLTOV, + WEAPON_COLT45 = 22, + WEAPON_SILENCED = 23, + WEAPON_DEAGLE = 24, + WEAPON_SHOTGUN = 25, + WEAPON_SAWEDOFF = 26, + WEAPON_SHOTGSPA = 27, + WEAPON_UZI = 28, + WEAPON_MP5 = 29, + WEAPON_AK47 = 30, + WEAPON_M4 = 31, + WEAPON_TEC9 = 32, + WEAPON_RIFLE = 33, + WEAPON_SNIPER = 34, + WEAPON_ROCKETLAUNCHER = 35, + WEAPON_HEATSEEKER = 36, + WEAPON_FLAMETHROWER = 37, + WEAPON_MINIGUN = 38, + WEAPON_SATCHEL = 39, + WEAPON_BOMB = 40, + WEAPON_SPRAYCAN = 41, + WEAPON_FIREEXTINGUISHER = 42, + WEAPON_CAMERA = 43, + WEAPON_NIGHT_VISION_GOGGLES = 44, + WEAPON_THERMAL_GOGGLES = 45, + WEAPON_PARACHUTE = 46, + WEAPON_VEHICLE = 49, + WEAPON_DROWN = 53, + WEAPON_COLLISION = 54, + WEAPON_SPLAT = WEAPON_COLLISION +} +static stock WEAPON:_@WEAPON() { return __WEAPON; } + +#define MAX_WEAPONS __WEAPON + +///

+ +/** + * a_npc + *

Weapon Slots + */ +#define WEAPON_SLOT: __TAG(WEAPON_SLOT): +enum WEAPON_SLOT:__WEAPON_SLOT +{ + WEAPON_SLOT_UNKNOWN = -1, + WEAPON_SLOT_UNARMED = 0, + WEAPON_SLOT_MELEE = 1, + WEAPON_SLOT_PISTOL = 2, + WEAPON_SLOT_SHOTGUN = 3, + WEAPON_SLOT_MACHINE_GUN = 4, + WEAPON_SLOT_ASSAULT_RIFLE = 5, + WEAPON_SLOT_LONG_RIFLE = 6, + WEAPON_SLOT_ARTILLERY = 7, + WEAPON_SLOT_EXPLOSIVES = 8, + WEAPON_SLOT_EQUIPMENT = 9, + WEAPON_SLOT_GIFT = 10, + WEAPON_SLOT_GADGET = 11, + WEAPON_SLOT_DETONATOR = 12 +} +static stock WEAPON_SLOT:_@WEAPON_SLOT() { return __WEAPON_SLOT; } + +#define MAX_WEAPON_SLOTS __WEAPON_SLOT + +///

+ +/** + * a_samp + *

Keys + */ +#define KEY: __TAG(KEY): +enum KEY:__KEY (<<= 1) +{ + KEY_ACTION = 1, + KEY_CROUCH, + KEY_FIRE, + KEY_SPRINT, + KEY_SECONDARY_ATTACK, + KEY_JUMP, + KEY_LOOK_RIGHT, + KEY_HANDBRAKE, + KEY_LOOK_LEFT, + KEY_SUBMISSION, + KEY_LOOK_BEHIND = KEY_SUBMISSION, + KEY_WALK, + KEY_ANALOG_UP, + KEY_ANALOG_DOWN, + KEY_ANALOG_LEFT, + KEY_ANALOG_RIGHT, + KEY_YES = 65536, + KEY_NO, + KEY_CTRL_BACK, + + KEY_UP = -128, + KEY_DOWN = 128, + KEY_LEFT = -128, + KEY_RIGHT = 128, +} +static stock KEY:_@KEY() { return __KEY; } + +///

+ +/** + * a_samp + *

Player GUI dialog + */ +#define DIALOG_STYLE: __TAG(DIALOG_STYLE): +enum DIALOG_STYLE:__DIALOG_STYLE +{ + DIALOG_STYLE_MSGBOX, + DIALOG_STYLE_INPUT, + DIALOG_STYLE_LIST, + DIALOG_STYLE_PASSWORD, + DIALOG_STYLE_TABLIST, + DIALOG_STYLE_TABLIST_HEADERS +} +static stock DIALOG_STYLE:_@DIALOG_STYLE() { return __DIALOG_STYLE; } + +///

+ +/** + * a_samp + *

Text draw font + */ +#define TEXT_DRAW_FONT: __TAG(TEXT_DRAW_FONT): +enum TEXT_DRAW_FONT:__TEXT_DRAW_FONT +{ + TEXT_DRAW_FONT_0, + TEXT_DRAW_FONT_1, + TEXT_DRAW_FONT_2, + TEXT_DRAW_FONT_3, + TEXT_DRAW_FONT_SPRITE_DRAW, + TEXT_DRAW_FONT_MODEL_PREVIEW, +} +static stock TEXT_DRAW_FONT:_@TEXT_DRAW_FONT() { return __TEXT_DRAW_FONT; } + +///

+ +/** + * a_samp + *

Text draw alignment + */ +#define TEXT_DRAW_ALIGN: __TAG(TEXT_DRAW_ALIGN): +enum TEXT_DRAW_ALIGN:__TEXT_DRAW_ALIGN +{ + TEXT_DRAW_ALIGN_LEFT = 1, + TEXT_DRAW_ALIGN_CENTRE, + TEXT_DRAW_ALIGN_CENTER = TEXT_DRAW_ALIGN_CENTRE, + TEXT_DRAW_ALIGN_RIGHT +} +static stock TEXT_DRAW_ALIGN:_@TEXT_DRAW_ALIGN() { return __TEXT_DRAW_ALIGN; } + +///

+ +/** + * a_samp + *

SVar enumeration + */ +#define SERVER_VARTYPE: __TAG(SERVER_VARTYPE): +enum SERVER_VARTYPE:__SERVER_VARTYPE +{ + SERVER_VARTYPE_NONE, + SERVER_VARTYPE_INT, + SERVER_VARTYPE_STRING, + SERVER_VARTYPE_FLOAT +} +static stock SERVER_VARTYPE:_@SERVER_VARTYPE() { return __SERVER_VARTYPE; } + +///

+ +/** + * a_samp + *

Artwork/NetModels + */ +#define DOWNLOAD_REQUEST: __TAG(DOWNLOAD_REQUEST): +enum DOWNLOAD_REQUEST:__DOWNLOAD_REQUEST +{ + DOWNLOAD_REQUEST_EMPTY, + DOWNLOAD_REQUEST_MODEL_FILE, + DOWNLOAD_REQUEST_TEXTURE_FILE +} +static stock DOWNLOAD_REQUEST:_@DOWNLOAD_REQUEST() { return __DOWNLOAD_REQUEST; } + +///

+ +/** + * a_samp + */ +#define CLICK_SOURCE: __TAG(CLICK_SOURCE): +enum CLICK_SOURCE:__CLICK_SOURCE +{ + CLICK_SOURCE_SCOREBOARD +} +static stock CLICK_SOURCE:_@CLICK_SOURCE() { return __CLICK_SOURCE; } -/* +///

-Version examples: +/** + * a_samp + */ +#define EDIT_RESPONSE: __TAG(EDIT_RESPONSE): +enum EDIT_RESPONSE:__EDIT_RESPONSE +{ + EDIT_RESPONSE_CANCEL, + EDIT_RESPONSE_FINAL, + EDIT_RESPONSE_UPDATE +} +static stock EDIT_RESPONSE:_@EDIT_RESPONSE() { return __EDIT_RESPONSE; } + +///

+ +/** + * a_samp + */ +#define BULLET_HIT_TYPE: __TAG(BULLET_HIT_TYPE): +enum BULLET_HIT_TYPE:__BULLET_HIT_TYPE +{ + BULLET_HIT_TYPE_NONE, + BULLET_HIT_TYPE_PLAYER, + BULLET_HIT_TYPE_VEHICLE, + BULLET_HIT_TYPE_OBJECT, + BULLET_HIT_TYPE_PLAYER_OBJECT +} +static stock BULLET_HIT_TYPE:_@BULLET_HIT_TYPE() { return __BULLET_HIT_TYPE; } + +///

+ +/** + * a_samp + */ +#define FORCE_SYNC: __TAG(FORCE_SYNC): +enum FORCE_SYNC:__FORCE_SYNC +{ + SYNC_NONE, // Don't force sync to anyone else. + SYNC_ALL, // Sync to all streamed-in players. + SYNC_OTHER // Sync to all streamed-in players, except the player with the animation. +} +static stock FORCE_SYNC:_@FORCE_SYNC() { return __FORCE_SYNC; } + +// Try many places to get the latest version. + +#tryinclude "..\pawn-stdlib\console" +#tryinclude "..\pawn-stdlib\core" +#tryinclude "..\pawn-stdlib\file" +#tryinclude "..\pawn-stdlib\float" +#tryinclude "..\pawn-stdlib\string" +#tryinclude "..\pawn-stdlib\time" + +#tryinclude +#tryinclude +#tryinclude +#tryinclude +#tryinclude +#tryinclude + +#tryinclude "console" +#tryinclude "core" +#tryinclude "file" +#tryinclude "float" +#tryinclude "string" +#tryinclude "time" -0.3.DL R1 - 03D010 +#tryinclude +#tryinclude +#tryinclude +#tryinclude +#tryinclude +#tryinclude

Prints a string to the server console (not in-game chat) and logs (server_log.txt). - /// The string to print - /// +/** + * a_samp + * Prints a string to the server console (not in-game chat) and logs (server_log.txt). + * The string to print + * + */ +#if defined _console_included + // Fixes a pawndoc bug - comments on `#ifdef`ed out functions are still put + // in the output, unattached to any function. So make a function. + native a_samp_unused_print(const string[]); + #define a_samp_unused_print +#else native print(const string[]); +#endif - /// Outputs a formatted string on the console (the server window, not the in-game chat). - /// The format string - /// Indefinite number of arguments of any tag - /// - /// - /// The format string or its output should not exceed 1024 characters. Anything beyond that length can lead to a server to crash. - /// This function doesn't support packed strings. - /// - /// Format Specifiers:

- ///

    - ///
  • %i - integer (whole number)
    • - ///
  • %d - integer (whole number).
    • - ///
  • %s - string
    • - ///
  • %f - floating-point number (Float: tag)
    • - ///
  • %c - ASCII character
    • - ///
  • %x - hexadecimal number
    • - ///
  • %b - binary number
    • - ///
  • %% - literal %
    • - ///
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • - ///
- /// - /// The values for the placeholders follow in the exact same order as parameters in the call. For example, "I am %i years old" - the %i will be replaced with an Integer variable, which is the person's age. - /// You may optionally put a number between the % 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 .<max number> between the % and the f. (example: %.2f) - native printf(const format[], {Float,_}:...); +/** + * a_samp + * Outputs a formatted string on the console (the server window, not the in-game chat). + * The format string + * Indefinite number of arguments of any tag + * + * + * The format string or its output should not exceed 1024 characters. Anything beyond that + * length can lead to a server to crash. + * This function doesn't support packed strings. + * + * Format Specifiers:
+ *
    + *
  • %i - integer (whole number)
    • + *
  • %d - integer (whole number).
    • + *
  • %s - string
    • + *
  • %f - floating-point number (Float: tag)
    • + *
  • %c - ASCII character
    • + *
  • %x - hexadecimal number
    • + *
  • %b - binary number
    • + *
  • %% - literal %
    • + *
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • + *
+ * + * The values for the placeholders follow in the exact same order as parameters in the call. + * For example, "I am %i years old" - the %i will be replaced with an Integer + * variable, which is the person's age. + * You may optionally put a number between the % 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 .<max number> between + * the % and the f. (example: %.2f) + */ +#if defined _console_included + // Fixes a pawndoc bug - comments on `#ifdef`ed out functions are still put + // in the output, unattached to any function. So make a function. + native a_samp_unused_printf(const format[], {Float, _}:...); + #define a_samp_unused_printf +#else + native printf(const format[], {Float, _}:...); #endif -/// Formats a string to include variables and other strings inside it. -/// The string to output the result to -/// The maximum length output can contain -/// The format string -/// Indefinite number of arguments of any tag -/// -/// -/// This function doesn't support packed strings. -/// -/// Format Specifiers:

-///

    -///
  • %i - integer (whole number)
    • -///
  • %d - integer (whole number).
    • -///
  • %s - string
    • -///
  • %f - floating-point number (Float: tag)
    • -///
  • %c - ASCII character
    • -///
  • %x - hexadecimal number
    • -///
  • %b - binary number
    • -///
  • %% - literal %
    • -///
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • -///
-/// -/// The values for the placeholders follow in the exact same order as parameters in the call. For example, "I am %i years old" - the %i will be replaced with an Integer variable, which is the person's age. -/// You may optionally put a number between the % 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 .<max number> between the % and the f. (example: %.2f) -native format(output[], len = sizeof output, const format[], {Float,_}:...); - -/// 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 0.3c). -/// The ID of the player to display the message to -/// The color of the message (RGBA) -/// The text that will be displayed (max 144 characters) -/// -/// -/// -/// 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. -/// Avoid using the percent sign (or format specifiers) in the actual message text without properly escaping it (like %%). It will result in crashes otherwise. -/// You can use color embedding for multiple colors in the message. -/// -/// 1: The function executed successfully. Success is reported when the string is over 144 characters, but the message won't be sent.

-/// 0: The function failed to execute. The player is not connected. -/// -native SendClientMessage(playerid, color, const message[]); - -///

Displays a message in chat to all players. This is a multi-player equivalent of SendClientMessage. -/// The color of the message (RGBA) -/// The message to show (max 144 characters) -/// -/// -/// Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise. -/// This function always returns 1. -native SendClientMessageToAll(color, const message[]); - -/// 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 . The line will start with the sender's name in their color, followed by the message in white. -/// The ID of the player who will receive the message -/// The sender's ID. If invalid, the message will not be sent -/// The message that will be sent -/// -/// -/// -/// -/// Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise. -native SendPlayerMessageToPlayer(playerid, senderid, const message[]); - -/// 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. -/// The ID of the sender. If invalid, the message will not be sent -/// The message that will be sent -/// -/// -/// -/// Avoid using format specifiers in your messages without formatting the string that is sent. It will result in crashes otherwise. -native SendPlayerMessageToAll(senderid, const message[]); - -/// Adds a death to the 'killfeed' on the right-hand side of the screen for all players. -/// The ID of the killer (can be INVALID_PLAYER_ID) -/// The ID of the player that died -/// The reason (not always a weapon) for the victim's death. Special icons can also be used (ICON_CONNECT and ICON_DISCONNECT) -/// -/// -/// Death messages can be cleared by using a valid player ID for that is not connected. -/// To show a death message for just a single player, use SendDeathMessageToPlayer. -/// You can use NPCs to create your own custom death reasons. -/// This function always returns 1, even if the function fails to execute. The function fails to execute (no death message shown) if is invalid. If is invalid, a generic skull-and-crossbones icon is shown. being invalid (INVALID_PLAYER_ID) is valid. -native SendDeathMessage(killer, killee, weapon); - -/// Adds a death to the 'killfeed' on the right-hand side of the screen for a single player. -/// The ID of the player to send the death message to -/// The ID of the killer (can be INVALID_PLAYER_ID) -/// The ID of the player that died -/// The reason (not always a weapon) for the victim's death. Special icons can also be used (ICON_CONNECT and ICON_DISCONNECT) -/// -/// -/// This Function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// -native SendDeathMessageToPlayer(playerid, killer, killee, weapon); - -///

Shows 'game text' (on-screen text) for a certain length of time for all players. -/// The text to be displayed -/// The duration of the text being shown in milliseconds -/// The style of text to be displayed -/// -/// -/// This function always returns 1. -native GameTextForAll(const string[], time, style); - -/// Shows 'game text' (on-screen text) for a certain length of time for a specific player. -/// The ID of the player to show the gametext for -/// The text to be displayed -/// The duration of the text being shown in milliseconds -/// The style of text to be displayed -/// -/// -/// -/// 1: 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.

-/// 0: The function failed to execute. This means either the string is null or the player is not connected. -/// -native GameTextForPlayer(playerid, const string[], time, style); - -///

Sets a 'timer' to call a function after some time. Can be set to repeat. -/// Name of the function to call as a string. This must be a public function (forwarded). A null string here will crash the server -/// Interval in milliseconds -/// Whether the timer should repeat or not -/// -/// -/// Timer intervals are not accurate (roughly 25% off). There's a fix available here. -/// 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. -/// The function that should be called must be public. -/// The use of many timers will result in increased memory/cpu usage. -/// The ID of the timer that was started. Timer IDs start at 1. -native SetTimer(const funcname[], interval, repeating); - -/// 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. -/// The name of a public function to call when the timer expires -/// Interval in milliseconds -/// Whether the timer should be called repeatedly (can only be stopped with KillTimer) or only once -/// Special format indicating the types of values the timer will pass -/// Indefinite number of arguments to pass (must follow format specified in previous parameter) -/// -/// -/// -/// -/// Timer intervals are not accurate (roughly 25% off). There's a fix available here. -/// 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. -/// The function that should be called must be public. -/// The use of many timers will result in increased memory/cpu usage. -/// -/// Format syntax:

-///

    -///
  • i - integer
    • -///
  • d - integer
    • -///
  • a - array The next parameter must be an integer ("i") with the array's size [CURRENTLY UNUSABLE]
    • -///
  • s - string [CURRENTLY UNUSABLE]
    • -///
  • f - float
    • -///
  • b - boolean
    • -///
-/// -/// The ID of the timer that was started. Timer IDs start at 1 and are never reused. There are no internal checks to verify that the parameters passed are valid (e.g. duration not a minus value). -native SetTimerEx(const funcname[], interval, repeating, const format[], {Float,_}:...); - -/// Kills (stops) a running timer. -/// The ID of the timer to kill (returned by SetTimer or SetTimerEx) -/// -/// -/// This function always returns 0. -native KillTimer(timerid); - -/// Returns the uptime of the actual server (not the SA-MP server) in milliseconds. -/// -/// GetTickCount will cause problems on servers with uptime of over 24 days as GetTickCount will eventually warp past the integer size constraints. However using this function fixes the problem. -/// One common use for GetTickCount is for benchmarking. It can be used to calculate how much time some code takes to execute. -/// Uptime of the actual server (not the SA-MP server). +#if !defined _console_included + #define _console_included +#endif + +/** + * a_samp + * Formats a string to include variables and other strings inside it. + * The string to output the result to + * The maximum length output can contain + * The format string + * Indefinite number of arguments of any tag + * + * + * This function doesn't support packed strings. + * + * Format Specifiers:
+ *
    + *
  • %i - integer (whole number)
    • + *
  • %d - integer (whole number).
    • + *
  • %s - string
    • + *
  • %f - floating-point number (Float: tag)
    • + *
  • %c - ASCII character
    • + *
  • %x - hexadecimal number
    • + *
  • %b - binary number
    • + *
  • %% - literal %
    • + *
  • %q - escape a text for SQLite. (Added in 0.3.7 R2)
    • + *
+ * + * The values for the placeholders follow in the exact same order as parameters in the call. + * For example, "I am %i years old" - the %i will be replaced with an Integer + * variable, which is the person's age. + * You may optionally put a number between the % 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 .<max number> between + * the % and the f. (example: %.2f) + */ +native format(output[], len = sizeof (output), const format[], {Float, _}:...); + +/** + * a_samp + * This function sends a message to a specific player with a chosen colour in the chat. The + * whole line in the chatbox will be in the set colour unless colour embedding is used (since 0.3c). + * The ID of the player to display the message to + * The colour of the message (RGBA) + * The text that will be displayed (max 144 characters) + * + * + * + * 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. + * Avoid using the percent sign (or format specifiers) in the actual message text without properly + * escaping it (like %%). It will result in crashes otherwise. + * You can use colour embedding for multiple colours in the message. + * + * 1: The function executed successfully. Success is reported when the string is over + * 144 characters, but the message won't be sent.
+ * 0: The function failed to execute. The player is not connected. + * + */ +native bool:SendClientMessage(playerid, colour, const message[]); + +/** + * a_samp + * Displays a message in chat to all players. This is a multi-player equivalent of + * SendClientMessage. + * The colour of the message (RGBA) + * The message to show (max 144 characters) + * + * + * Avoid using format specifiers in your messages without formatting the string that is sent. + * It will result in crashes otherwise. + * This function always returns 1. + */ +native void:SendClientMessageToAll(colour, const message[]); + +/** + * a_samp + * 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 . The line will start with the sender's name in their colour, followed by the message in white. + * The ID of the player who will receive the message + * The sender's ID. If invalid, the message will not be sent + * The message that will be sent + * + * + * + * + * Avoid using format specifiers in your messages without formatting the string that is sent. + * It will result in crashes otherwise. + */ +native bool:SendPlayerMessageToPlayer(playerid, senderid, const message[]); + +/** + * a_samp + * 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 colour, followed by the message in white. + * The ID of the sender. If invalid, the message will not be sent + * The message that will be sent + * + * + * + * Avoid using format specifiers in your messages without formatting the string that is sent. + * It will result in crashes otherwise. + */ +native bool:SendPlayerMessageToAll(senderid, const message[]); + +/** + * a_samp + * Adds a death to the 'killfeed' on the right-hand side of the screen for all players. + * The ID of the killer (can be INVALID_PLAYER_ID) + * The ID of the player that died + * The reason (not always a weapon) + * for the victim's death. Special icons can also be used (ICON_CONNECT and ICON_DISCONNECT) + * + * + * Death messages can be cleared by using a valid player ID for + * that is not connected. + * To show a death message for just a single player, use SendDeathMessageToPlayer. + * + * You can use NPCs to create your own custom death reasons. + * This function always returns 1, even if the function fails to execute. The + * function fails to execute (no death message shown) if is invalid. If + * is invalid, a generic skull-and-crossbones icon is shown. being invalid (INVALID_PLAYER_ID) is valid. + */ +native bool:SendDeathMessage(killer, killee, weapon); + +/** + * a_samp + * Adds a death to the 'killfeed' on the right-hand side of the screen for a single player. + * The ID of the player to send the death message to + * The ID of the killer (can be INVALID_PLAYER_ID) + * The ID of the player that died + * The reason (not always a weapon) + * for the victim's death. Special icons can also be used (ICON_CONNECT and ICON_DISCONNECT) + * + * + * This Function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ +native bool:SendDeathMessageToPlayer(playerid, killer, killee, weapon); + +/** + * a_samp + * Shows 'game text' (on-screen text) for a certain length of time for all players. + * The text to be displayed + * The duration of the text being shown in milliseconds + * The style of text to be displayed + * + * + * This function always returns 1. + */ +native void:GameTextForAll(const string[], time, style); + +/** + * a_samp + * Shows 'game text' (on-screen text) for a certain length of time for a specific player. + * The ID of the player to show the gametext for + * The text to be displayed + * The duration of the text being shown in milliseconds + * The style of text to be displayed + * + * + * + * 1: 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.
+ * 0: The function failed to execute. This means either the string is null or the player + * is not connected. + * + */ +native bool:GameTextForPlayer(playerid, const string[], time, style); + +/** + * a_samp + * Sets a 'timer' to call a function after some time. Can be set to repeat. + * Name of the function to call as a string. This must be a public function + * (forwarded). A null string here will crash the server + * Interval in milliseconds + * Whether the timer should repeat or not + * + * + * Timer intervals are not accurate (roughly 25% off). There's a fix available + * here. + * + * 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. + * The function that should be called must be public. + * The use of many timers will result in increased memory/cpu usage. + * The ID of the timer that was started. Timer IDs start at 1. + */ +native SetTimer(const functionName[], interval, bool:repeating); + +/** + * a_samp + * 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. + * The name of a public function to call when the timer expires + * Interval in milliseconds + * Whether the timer should be called repeatedly (can only be stopped with KillTimer) or only once + * Special format indicating the types of values the timer will pass + * Indefinite number of arguments to pass (must follow format specified in previous parameter) + * + * + * + * + * Timer intervals are not accurate (roughly 25% off). There's a fix available + * here. + * + * 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. + * The function that should be called must be public. + * The use of many timers will result in increased memory/cpu usage. + * + * Format syntax:
+ *
    + *
  • i - integer
    • + *
  • d - integer
    • + *
  • a - array The next parameter must be an integer ("i") with the + * array's size [CURRENTLY UNUSABLE]
    • + *
  • s - string [CURRENTLY UNUSABLE]
    • + *
  • f - float
    • + *
  • b - boolean
    • + *
+ * + * The ID of the timer that was started. Timer IDs start at 1 and are never + * reused. There are no internal checks to verify that the parameters passed are valid (e.g. duration + * not a minus value). + */ +native SetTimerEx(const functionName[], interval, bool:repeating, const format[] = "", {Float, _}:...); + +/** + * a_samp + * Kills (stops) a running timer. + * The ID of the timer to kill (returned by SetTimer or + * SetTimerEx) + * + * + * This function always returns 0. + */ +native void:KillTimer(timerid); + +/** + * a_samp + * Returns the uptime of the actual server (not the SA-MP server) in milliseconds. + * + * GetTickCount will cause problems on servers with uptime of over 24 days as GetTickCount + * will eventually warp past the integer size constraints. However using + * this + * function fixes the problem. + * One common use for GetTickCount is for benchmarking. It can be used to calculate how much + * time some code takes to execute. + * Uptime of the actual server (not the SA-MP server). + */ native GetTickCount(); -/// Returns the maximum number of players that can join the server, as set by the server variable 'maxplayers' in server.cfg. -/// -/// -/// This function can not be used in place of MAX_PLAYERS. It can not be used at compile time (e.g. for array sizes). MAX_PLAYERS should always be re-defined to what the 'maxplayers' var will be, or higher. -/// The maximum number of players that can join the server. +/** + * a_samp + * Returns the maximum number of players that can join the server, as set by the server variable + * 'maxplayers' in server.cfg. + * + * + * This function can not be used in place of MAX_PLAYERS. It can not be used + * at compile time (e.g. for array sizes). MAX_PLAYERS should always be re-defined to + * what the 'maxplayers' var will be, or higher. + * The maximum number of players that can join the server. + */ native GetMaxPlayers(); -/// Calls a public function in any script that is loaded. -/// Public function's name -/// Tag/format of each variable -/// 'Indefinite' number of arguments of any tag -/// -/// The value that the last public function returned. -/// CallRemoteFunction crashes the server if it's passing an empty string. -/// -/// Format string placeholders:

-///

    -///
  • c - a single character
    • -///
  • d - an integer (whole) number
    • -///
  • i - an integer (whole) number
    • -///
  • x - a number in hexadecimal notation
    • -///
  • f - a floating point number
    • -///
  • s - a string
    • -///
-/// -native CallRemoteFunction(const function[], const format[], {Float,_}:...); - -/// Calls a public function from the script in which it is used. -/// Public function's name -/// Tag/format of each variable -/// 'Indefinite' number of arguments of any tag -/// -/// The value that the only public function returned. -/// CallLocalFunction crashes the server if it's passing an empty string. -/// -/// Format string placeholders:

-///

    -///
  • c - a single character
    • -///
  • d - an integer (whole) number
    • -///
  • i - an integer (whole) number
    • -///
  • x - a number in hexadecimal notation
    • -///
  • f - a floating point number
    • -///
  • s - a string
    • -///
-/// -native CallLocalFunction(const function[], const format[], {Float,_}:...); - - -/// Returns the norm (length) of the provided vector. -/// The vector's magnitude on the X axis -/// The vector's magnitude on the Y axis -/// The vector's magnitude on the Z axis -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// The norm (length) of the provided vector as a float. +/** + * a_samp + * Calls a public function in any script that is loaded. + * Public function's name + * Tag/format of each variable + * 'Indefinite' number of arguments of any tag + * + * The value that the last public function returned. + * CallRemoteFunction crashes the server if it's passing an empty string. + * + * Format string placeholders:
+ *
    + *
  • c - a single character
    • + *
  • d - an integer (whole) number
    • + *
  • i - an integer (whole) number
    • + *
  • x - a number in hexadecimal notation
    • + *
  • f - a floating point number
    • + *
  • s - a string
    • + *
+ * + */ +native CallRemoteFunction(const function[], const format[] = "", {Float, _}:...); + +/** + * a_samp + * Calls a public function from the script in which it is used. + * Public function's name + * Tag/format of each variable + * 'Indefinite' number of arguments of any tag + * + * The value that the only public function returned. + * CallLocalFunction crashes the server if it's passing an empty string. + * + * Format string placeholders:
+ *
    + *
  • c - a single character
    • + *
  • d - an integer (whole) number
    • + *
  • i - an integer (whole) number
    • + *
  • x - a number in hexadecimal notation
    • + *
  • f - a floating point number
    • + *
  • s - a string
    • + *
+ * + */ +native CallLocalFunction(const function[], const format[] = "", {Float, _}:...); + +/** + * a_samp + * Returns the norm (length) of the provided vector. + * The vector's magnitude on the x axis + * The vector's magnitude on the y axis + * The vector's magnitude on the z axis + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * The norm (length) of the provided vector as a float. + */ native Float:VectorSize(Float:x, Float:y, Float:z); -/// Get the inversed value of a sine in degrees. -/// The sine for which to find the angle for -/// -/// The angle in degrees. +/** + * a_samp + * Get the inversed value of a sine in degrees. + * The sine for which to find the angle for + * + * The angle in degrees. + */ native Float:asin(Float:value); -/// Get the inversed value of a cosine in degrees. -/// The cosine for which to find the angle for -/// -/// The angle in degrees. +/** + * a_samp + * Get the inversed value of a cosine in degrees. + * The cosine for which to find the angle for + * + * The angle in degrees. + */ native Float:acos(Float:value); -/// Get the inversed value of a tangent in degrees. -/// The tangent for which to find the angle for -/// -/// -/// The angle in degrees. +/** + * a_samp + * Get the inversed value of a tangent in degrees. + * The tangent for which to find the angle for + * + * + * The angle in degrees. + */ native Float:atan(Float:value); -/// Get the multi-valued inversed value of a tangent in degrees. -/// y size -/// x size -/// -/// -/// The angle in degrees. +/** + * a_samp + * Get the multi-valued inversed value of a tangent in degrees. + * y size + * x size + * + * + * The angle in degrees. + */ native Float:atan2(Float:y, Float:x); - -/// Gets the highest playerid currently in use on the server. -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The highest playerid currently in use on the server or 0 if there are no connected players. +/** + * a_samp + * Gets the highest playerid currently in use on the server. + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The highest playerid currently in use on the server or 0 if there are no connected + * players. + */ +#pragma deprecated This function is fundamentally broken. See: open.mp/docs/scripting/functions/GetPlayerPoolSize native GetPlayerPoolSize(); -/// Gets the highest vehicleid currently in use on the server. -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The highest vehicleid currently in use on the server or 0 if there are no created vehicles. +/** + * a_samp + * Gets the highest vehicleid currently in use on the server. + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The highest vehicleid currently in use on the server or 0 if there are no + * created vehicles. + */ +#pragma deprecated This function is fundamentally broken. See: open.mp/docs/scripting/functions/GetVehiclePoolSize native GetVehiclePoolSize(); -/// Gets the highest actorid created on the server. -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The highest actorid created on the server or 0 if there are no created actors. +/** + * a_samp + * Gets the highest actorid created on the server. + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The highest actorid created on the server or 0 if there are no created actors. + */ +#pragma deprecated This function is fundamentally broken. See: open.mp/docs/scripting/functions/GetActorPoolSize native GetActorPoolSize(); // Hash -/// 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. -/// The password to hash -/// The salt to use in the hash -/// The returned hash -/// The returned hash maximum length -/// This function was added in SA-MP 0.3.7-R1 and will not work in earlier versions! -/// The salt is appended to the end of the password, meaning password 'foo' and salt 'bar' would form 'foobar'. -/// 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. -native SHA256_PassHash(const password[], const salt[], ret_hash[], ret_hash_len = sizeof ret_hash); // SHA256 for password hashing +/** + * a_samp + * 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. + * The password to hash + * The salt to use in the hash + * The returned hash + * The returned hash maximum length + * This function was added in SA-MP 0.3.7-R1 and will not work in earlier versions! + * The salt is appended to the end of the password, meaning password 'foo' and salt 'bar' would + * form 'foobar'. + * 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. + */ +#pragma deprecated Use BCrypt for hashing passwords. +native SHA256_PassHash(const password[], const salt[], output[], size = sizeof (output)); // SHA256 for password hashing // Server wide persistent variable system (SVars) -/// Set an integer server variable. -/// The name of the server variable -/// The integer to be set -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The variable name is null or over 40 characters. -/// -native SetSVarInt(const varname[], int_value); - -///

Gets an integer server variable's value. -/// The name of the server variable (case-insensitive). Assigned in SetSVarInt -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// The integer value of the specified server variable. It will still return 0 if the variable is not set. -native GetSVarInt(const varname[]); - -/// Set a string server variable. -/// The name of the server variable -/// The string to be set -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The variable name is null or over 40 characters. -/// -native SetSVarString(const varname[], const string_value[]); - -///

Gets a string server variable's value. -/// The name of the server variable (case-insensitive). Assigned in SetSVarString -/// The array in which to store the string value in, passed by reference -/// The maximum length of the returned string -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// The length of the string. -native GetSVarString(const varname[], string_return[], len = sizeof string_return); - -/// Set a float server variable. -/// The name of the server variable -/// The float to be set -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The variable name is null or over 40 characters. -/// -native SetSVarFloat(const varname[], Float:float_value); - -///

Gets a float server variable's value. -/// The name of the server variable (case-insensitive). Assigned in SetSVarFloat -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! -/// The float value of the specified server variable. It will still return 0 if the variable is not set. -native Float:GetSVarFloat(const varname[]); - -/// Deletes a previously set server variable. -/// The name of the server variable to delete -/// -/// -/// -/// -/// -/// -/// Once a variable is deleted, attempts to retrieve the value will return 0 (for integers and floats and NULL for strings. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. There is no variable set with the given name. -/// -native DeleteSVar(const varname[]); - -///

Each SVar (server-variable) has its own unique identification number for lookup, this function returns the highest ID. -/// -/// -/// The highest set SVar ID. +/** + * a_samp + * Set an integer server variable. + * The name of the server variable + * The integer to be set + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The variable name is null or over 40 characters. + * + */ +native bool:SetSVarInt(const svar[], value); + +/** + * a_samp + * Gets an integer server variable's value. + * The name of the server variable (case-insensitive). Assigned in SetSVarInt + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * The integer value of the specified server variable. It will still return 0 + * if the variable is not set. + */ +native GetSVarInt(const svar[]); + +/** + * a_samp + * Set a string server variable. + * The name of the server variable + * The string to be set + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The variable name is null or over 40 characters. + * + */ +native bool:SetSVarString(const svar[], const value[]); + +/** + * a_samp + * Gets a string server variable's value. + * The name of the server variable (case-insensitive). Assigned in SetSVarString + * The array in which to store the string value in, passed by reference + * The maximum length of the returned string + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * The length of the string. + */ +native GetSVarString(const svar[], output[], len = sizeof (output)); + +/** + * a_samp + * Set a float server variable. + * The name of the server variable + * The float to be set + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The variable name is null or over 40 characters. + * + */ +native bool:SetSVarFloat(const svar[], Float:value); + +/** + * a_samp + * Gets a float server variable's value. + * The name of the server variable (case-insensitive). Assigned in SetSVarFloat + * + * + * + * + * + * + * This function was added in SA-MP 0.3.7 R2 and will not work in earlier versions! + * The float value of the specified server variable. It will still return 0 + * if the variable is not set. + */ +native Float:GetSVarFloat(const svar[]); + +/** + * a_samp + * Deletes a previously set server variable. + * The name of the server variable to delete + * + * + * + * + * + * + * Once a variable is deleted, attempts to retrieve the value will return 0 (for + * integers and floats and NULL for strings. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. There is no variable set with the given name. + * + */ +native bool:DeleteSVar(const svar[]); + +/** + * a_samp + * Each SVar (server-variable) has its own unique identification number for lookup, this function + * returns the highest ID. + * + * + * The highest set SVar ID. + */ native GetSVarsUpperIndex(); -/// Retrieve the name of a sVar via the index. -/// The index of the sVar -/// A string to store the sVar's name in, passed by reference -/// The max length of the returned string -/// -/// -/// -/// -native GetSVarNameAtIndex(index, ret_varname[], ret_len = sizeof ret_varname); - -/// Gets the type (integer, float or string) of a server variable. -/// The name of the server variable to get the type of -/// -/// -/// -/// -/// -/// -/// -/// -/// Variable types:

-///

    -///
  • SERVER_VARTYPE_NONE (sVar with name given does not exist)
    • -///
  • SERVER_VARTYPE_INT
    • -///
  • SERVER_VARTYPE_STRING
    • -///
  • SERVER_VARTYPE_FLOAT
    • -///
-/// -/// Returns the type of the SVar. See table below. -native GetSVarType(const varname[]); +/** + * a_samp + * Retrieve the name of a sVar via the index. + * The index of the sVar + * A string to store the sVar's name in, passed by reference + * The max length of the returned string + * + * + * + * + */ +native GetSVarNameAtIndex(index, output[], size = sizeof (output)); + +/** + * a_samp + * Gets the type (integer, float or string) of a server variable. + * The name of the server variable to get the type of + * + * + * + * + * + * + * + * + * Variable types:
+ *
    + *
  • SERVER_VARTYPE_NONE (sVar with name given does not exist)
    • + *
  • SERVER_VARTYPE_INT
    • + *
  • SERVER_VARTYPE_STRING
    • + *
  • SERVER_VARTYPE_FLOAT
    • + *
+ * + * Returns the type of the SVar. See table below. + */ +native SERVER_VARTYPE:GetSVarType(const svar[]); // Game -/// Set the name of the game mode, which appears in the server browser. -/// The gamemode name to display +/** + * a_samp + * Set the name of the game mode, which appears in the server browser. + * The gamemode name to display + */ native SetGameModeText(const string[]); - -/// 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 OnGameModeInit callback. Important: You can pass 2 billion here if you like, this function has no effect at all. -/// Number of teams the gamemode knows -/// -/// +/** + * a_samp + * 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 OnGameModeInit + * callback. Important: You can pass 2 billion here if you like, this function has no effect at all. + * Number of teams the gamemode knows + * + * + */ native SetTeamCount(count); -/// Adds a class to class selection. Classes are used so players may spawn with a skin of their choice. -/// The skin which the player will spawn with -/// The X coordinate of the spawnpoint of this class -/// The Y coordinate of the spawnpoint of this class -/// The Z coordinate of the spawnpoint of this class -/// The direction in which the player should face after spawning -/// The first spawn-weapon for the player -/// The amount of ammunition for the primary spawn weapon -/// The second spawn-weapon for the player -/// The amount of ammunition for the second spawn weapon -/// The third spawn-weapon for the player -/// The amount of ammunition for the third spawn weapon -/// -///
    -///
  • The ID of the class which was just added.
    • -///
  • 319 if the class limit (320) was reached. The highest possible class ID is 319.
    • -///
-/// -/// -/// The maximum class ID is 319 (starting from 0, so a total of 320 classes). -/// When this limit is reached, any more classes that are added will replace ID 319. -/// -/// -/// -/// -native AddPlayerClass(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, weapon1, weapon1_ammo, weapon2, weapon2_ammo, weapon3, weapon3_ammo); - -/// This function is exactly the same as the AddPlayerClass function, with the addition of a team parameter. -/// The team you want the player to spawn in -/// The skin which the player will spawn with -/// The X coordinate of the class' spawn position -/// The Y coordinate of the class' spawn position -/// The Z coordinate of the class' spawn position -/// The direction in which the player will face after spawning -/// The first spawn-weapon for the player -/// The amount of ammunition for the first spawn weapon -/// The second spawn-weapon for the player -/// The amount of ammunition for the second spawn weapon -/// The third spawn-weapon for the player -/// The amount of ammunition for the third spawn weapon -/// -///
    -///
  • The ID of the class which was just added.
    • -///
  • 319 if the class limit (320) was reached. The highest possible class ID is 319.
    • -///
-/// -/// The maximum class ID is 319 (starting from 0, so a total of 320 classes). When this limit is reached, any more classes that are added will replace ID 319. -/// -/// -/// -/// -native AddPlayerClassEx(teamid, modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, weapon1, weapon1_ammo, weapon2, weapon2_ammo, weapon3, weapon3_ammo); - -/// Adds a 'static' vehicle (models are pre-loaded for players) to the gamemode. -/// The Model ID for the vehicle -/// The X-coordinate for the vehicle -/// The Y-coordinate for the vehicle -/// The Z-coordinate for the vehicle -/// Direction of vehicle - angle -/// The primary color ID. -1 for random (random color chosen by client) -/// The secondary color ID. -1 for random (random color chosen by client) -/// -///
    -///
  • The vehicle ID of the vehicle created (between 1 and MAX_VEHICLES).
    • -///
  • INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle limit reached or invalid vehicle model ID passed).
    • -///
-/// -/// Can only be used when the server first starts (under OnGameModeInit). -/// -/// -/// -native AddStaticVehicle(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, color1, color2); - -/// Adds a 'static' vehicle (models are pre-loaded for players)to the gamemode. Differs from AddStaticVehicle in only one way: allows a respawn time to be set for when the vehicle is left unoccupied by the driver. -/// The Model ID for the vehicle -/// The X-coordinate for the vehicle -/// The Y-coordinate for the vehicle -/// The Z-coordinate for the vehicle -/// The facing - angle for the vehicle -/// The primary color ID. -1 for random (random color chosen by client) -/// The secondary color ID. -1 for random (random color chosen by client) -/// The delay until the car is respawned without a driver, in seconds -/// Added in 0.3.7; will not work in earlier versions. Enables the vehicle to have a siren, providing the vehicle has a horn (optional=0) -/// -///
    -///
  • The vehicle ID of the vehicle created (between 1 and MAX_VEHICLES).
    • -///
  • INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle limit reached or invalid vehicle model ID passed).
    • -///
-/// -/// Can only be used when the server first starts (under OnGameModeInit). -/// -/// -/// -native AddStaticVehicleEx(modelid, Float:spawn_x, Float:spawn_y, Float:spawn_z, Float:z_angle, color1, color2, respawn_delay, addsiren=0); - -/// 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). -/// The model of the pickup -/// The pickup type. Determines how the pickup responds when picked up -/// The X coordinate to create the pickup at -/// The Y coordinate to create the pickup at -/// The Z coordinate to create the pickup at -/// The virtual world ID to put the pickup in. Use -1 to show the pickup in all worlds -/// -/// 1 if the pickup is successfully created. -///

-/// 0 if failed to create. -/// -/// This function doesn't return a pickup ID that you can use in, for example, OnPlayerPickUpPickup. Use CreatePickup if you'd like to assign IDs. -/// -/// -/// -native AddStaticPickup(model, type, Float:X, Float:Y, Float:Z, virtualworld = 0); - -///

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 OnPlayerPickUpPickup. -/// The model of the pickup -/// The pickup spawn type (see table under remarks) -/// The X coordinate to create the pickup at -/// The Y coordinate to create the pickup at -/// The Z coordinate to create the pickup at -/// The virtual world ID of the pickup. Use -1 to make the pickup show in all worlds (optional=0) -/// -/// -/// -/// -/// Known Bugs:

-/// Pickups that have a X or Y lower than -4096.0 or bigger than 4096.0 won't show up and won't trigger OnPlayerPickUpPickup either. -/// -/// -/// The only type of pickup that can be picked up from inside a vehicle is 14 (except for special pickups such as bribes).

-/// Pickups are shown to, and can be picked up by all players.

-/// It is possible that if DestroyPickup 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.

-/// 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 1 should be used.

-/// -/// -/// Available Pickup Types

-/// Most other IDs are either undocumented or are similar to type 1 (but do not use them just because they seem similar to ID 1, they might have side-effects like ID 18 and 20). -///

    -///
  • 0 - The pickup does not always display. If displayed, it can't be picked up and does not trigger OnPlayerPickUpPickup and it will stay after server shutdown.
    • -///
  • 1 - Exists always. Disables pickup scripts such as horseshoes and oysters to allow for scripted actions ONLY. Will trigger OnPlayerPickUpPickup every few seconds.
    • -///
  • 2 - Disappears after pickup, respawns after 30 seconds if the player is at a distance of at least 15 meters.
    • -///
  • 3 - Disappears after pickup, respawns after death.
    • -///
  • 4 - Disappears after 15 to 20 seconds. Respawns after death.
    • -///
  • 8 - Disappears after pickup, but has no effect.
    • -///
  • 11 - Blows up a few seconds after being created (bombs?)
    • -///
  • 12 - Blows up a few seconds after being created.
    • -///
  • 13 - Invisible. Triggers checkpoint sound when picked up with a vehicle, but doesn't trigger OnPlayerPickUpPickup.
    • -///
  • 14 - Disappears after pickup, can only be picked up with a vehicle. Triggers checkpoint sound.
    • -///
  • 15 - Same as type 2.
    • -///
  • 18 - Similar to type 1. Pressing Tab (KEY_ACTION) makes it disappear but the key press doesn't trigger OnPlayerPickUpPickup.
    • -///
  • 19 - Disappears after pickup, but doesn't respawn. Makes "cash pickup" sound if picked up.
    • -///
  • 20 - Similar to type 1. 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 OnPlayerPickUpPickup.
    • -///
  • 22 - Same as type 3.
    • -///
-/// -/// The ID of the created pickup, -1 on failure (pickup max limit). -native CreatePickup(model, type, Float:X, Float:Y, Float:Z, virtualworld = 0); - -/// Destroys a pickup created with CreatePickup. -/// The ID of the pickup to destroy (returned by CreatePickup) -/// -/// -native DestroyPickup(pickup); - -/// Toggle the drawing of nametags, health bars and armor bars above players. -/// 0 to disable, 1 to enable (enabled by default) -/// -/// -/// -/// This function can only be used in OnGameModeInit. For other times, see ShowPlayerNameTagForPlayer. -native ShowNameTags(show); - -/// Toggles player markers (blips on the radar). Must be used when the server starts (OnGameModeInit). For other times, see SetPlayerMarkerForPlayer. -/// The mode to use for markers. They can be streamed, meaning they are only visible to nearby players. See table below -/// -/// -/// -/// -/// -/// Marker modes:

-///

    -///
  • PLAYER_MARKERS_MODE_OFF 0
    • -///
  • PLAYER_MARKERS_MODE_GLOBAL 1
    • -///
  • PLAYER_MARKERS_MODE_STREAMED 2
    • -///
-/// -/// 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. -native ShowPlayerMarkers(mode); - -/// Ends the current gamemode. -/// -native GameModeExit(); - -/// Sets the world time (for all players) to a specific hour. -/// The hour to set (0-23) -/// -/// -/// -/// To set the minutes and/or to set the time for individual players, see SetPlayerTime. -/// This function is only relevant for players that do not use a passing clock - see TogglePlayerClock. -native SetWorldTime(hour); - -/// Get the name of a weapon. -/// The ID of the weapon to get the name of -/// An array to store the weapon's name in, passed by reference -/// The maximum length of the weapon name to store. -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The weapon specified does not exist. -/// -native GetWeaponName(weaponid, weapon[], len = sizeof weapon); - -/// 1 to enable, 0 to disable tire popping -/// This function was removed in SA-MP 0.3. Tire popping is enabled by default. If you want to disable tire popping, you'll have to manually script it using OnVehicleDamageStatusUpdate. -native EnableTirePopping(enable); // deprecated function - -///

Enable friendly fire for team vehicles. Players will be unable to damage teammates' vehicles (SetPlayerTeam must be used!). -/// -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -native EnableVehicleFriendlyFire(); - -/// Toggle whether the usage of weapons in interiors is allowed or not. -/// 1 to enable weapons in interiors (enabled by default), 0 to disable weapons in interiors -/// This function does not work in the current SA:MP version! -/// -/// -/// -native AllowInteriorWeapons(allow); - - -/// Set the world weather for all players. -/// The weather to set -/// -/// -/// If TogglePlayerClock is enabled, weather will slowly change over time, instead of changing instantly. -native SetWeather(weatherid); - -/// Get the currently set gravity. -/// -/// The current set gravity (as a float). +/** + * a_samp + * Adds a class to class selection. Classes are used so players may spawn with a skin of their + * choice. + * The skin which the player will + * spawn with + * The x coordinate of the spawnpoint of this class + * The y coordinate of the spawnpoint of this class + * The z coordinate of the spawnpoint of this class + * The direction in which the player should face after spawning + * The first spawn-weapon for + * the player + * The amount of ammunition for the primary spawn weapon + * The second spawn-weapon for + * the player + * The amount of ammunition for the second spawn weapon + * The third spawn-weapon for + * the player + * The amount of ammunition for the third spawn weapon + * + *
    + *
  • The ID of the class which was just added.
    • + *
  • 319 if the class limit (320) was reached. The highest possible + * class ID is 319.
    • + *
+ * + * + * The maximum class ID is 319 (starting from 0, so a total of 320 + * classes). + * When this limit is reached, any more classes that are added will replace ID 319. + * + * + * + * + */ +native AddPlayerClass(modelid, Float:spawnX, Float:spawnY, Float:spawnZ, Float:angle, WEAPON:weapon1, ammo1, WEAPON:weapon2, ammo2, WEAPON:weapon3, ammo3); + +/** + * a_samp + * This function is exactly the same as the AddPlayerClass function, + * with the addition of a team parameter. + * The team you want the player to spawn in + * The skin which the player will + * spawn with + * The x coordinate of the spawnpoint of this class + * The y coordinate of the spawnpoint of this class + * The z coordinate of the spawnpoint of this class + * The direction in which the player should face after spawning + * The first spawn-weapon for + * the player + * The amount of ammunition for the primary spawn weapon + * The second spawn-weapon for + * the player + * The amount of ammunition for the second spawn weapon + * The third spawn-weapon for + * the player + * The amount of ammunition for the third spawn weapon + * + *
    + *
  • The ID of the class which was just added.
    • + *
  • 319 if the class limit (320) was reached. The highest possible + * class ID is 319.
    • + *
+ * + * The maximum class ID is 319 (starting from 0, so a total of + * 320 classes). When this limit is reached, any more classes that are added will replace + * ID 319. + * + * + * + * + */ +native AddPlayerClassEx(teamid, modelid, Float:spawnX, Float:spawnY, Float:spawnZ, Float:angle, WEAPON:weapon1, ammo1, WEAPON:weapon2, ammo2, WEAPON:weapon3, ammo3); + +/** + * a_samp + * Adds a 'static' vehicle (models are pre-loaded for players) to the gamemode. + * The Model ID for the + * vehicle + * The x coordinate of the spawnpoint of this vehicle + * The y coordinate of the spawnpoint of this vehicle + * The z coordinate of the spawnpoint of this vehicle + * Direction of vehicle - angle + * The primary colour ID. -1 + * for random (random colour chosen by client) + * The secondary colour ID. + * -1 for random (random colour chosen by client) + * + *
    + *
  • The vehicle ID of the vehicle created (between 1 and MAX_VEHICLES).
    • + *
  • INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle + * limit reached or invalid vehicle model ID passed).
    • + *
+ * + * Can only be used when the server first starts (under OnGameModeInit). + * + * + * + */ +native AddStaticVehicle(modelid, Float:spawnX, Float:spawnY, Float:spawnZ, Float:angle, colour1, colour2); + +/** + * a_samp + * Adds a 'static' vehicle (models are pre-loaded for players)to the gamemode. Differs from + * AddStaticVehicle in only one way: allows a respawn time to be set + * for when the vehicle is left unoccupied by the driver. + * The Model ID for the + * vehicle + * The x coordinate of the spawnpoint of this vehicle + * The y coordinate of the spawnpoint of this vehicle + * The z coordinate of the spawnpoint of this vehicle + * Direction of vehicle - angle + * The primary colour ID. -1 + * for random (random colour chosen by client) + * The secondary colour ID. + * -1 for random (random colour chosen by client) + * The delay until the car is respawned without a driver, in seconds + * Added in 0.3.7; will not work in earlier versions. Enables the vehicle + * to have a siren, providing the vehicle has a horn (optional=0) + * + *
    + *
  • The vehicle ID of the vehicle created (between 1 and MAX_VEHICLES).
    • + *
  • INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle + * limit reached or invalid vehicle model ID passed).
    • + *
+ * + * Can only be used when the server first starts (under OnGameModeInit). + * + * + * + */ +native AddStaticVehicleEx(modelid, Float:spawnX, Float:spawnY, Float:spawnZ, Float:angle, colour1, colour2, respawnDelay, bool:addSiren = false); + +/** + * a_samp + * 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). + * The model of the pickup + * The pickup type. Determines how the pickup responds when picked up + * The x coordinate to create the pickup at + * The y coordinate to create the pickup at + * The z coordinate to create the pickup at + * The virtual world ID to put the pickup in. Use -1 to show the pickup + * in all worlds + * + * 1 if the pickup is successfully created. + *
+ * 0 if failed to create. + * + * This function doesn't return a pickup ID that you can use in, for example, + * OnPlayerPickUpPickup. + * Use CreatePickup if you'd like to assign IDs. + * + * + * + */ +native AddStaticPickup(model, type, Float:x, Float:y, Float:z, virtualWorld = 0); + +/** + * a_samp + * 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 OnPlayerPickUpPickup. + * The model of the pickup + * The pickup spawn type (see table under remarks) + * The x coordinate to create the pickup at + * The y coordinate to create the pickup at + * The z coordinate to create the pickup at + * The virtual world ID of the pickup. Use -1 to make the + * pickup show in all worlds (optional=0) + * + * + * + * + * Known Bugs:
+ * Pickups that have a x or y lower than -4096.0 or bigger than 4096.0 + * won't show up and won't trigger OnPlayerPickUpPickup either. + * + * + * The only type of pickup that can be picked up from inside a vehicle is 14 (except + * for special pickups such as bribes).
+ * Pickups are shown to, and can be picked up by all players.
+ * It is possible that if DestroyPickup 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.
+ * 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 1 + * should be used.
+ * + * + * Available Pickup Types
+ * Most other IDs are either undocumented or are similar to type 1 (but do not use them + * just because they seem similar to ID 1, they might have side-effects like ID 18 + * and 20). + *
    + *
  • 0 - The pickup does not always display. If displayed, it can't be picked up + * and does not trigger OnPlayerPickUpPickup and it will stay after + * server shutdown.
    • + *
  • 1 - Exists always. Disables pickup scripts such as horseshoes and oysters + * to allow for scripted actions ONLY. Will trigger OnPlayerPickUpPickup + * every few seconds.
    • + *
  • 2 - Disappears after pickup, respawns after 30 seconds if the player is at + * a distance of at least 15 meters.
    • + *
  • 3 - Disappears after pickup, respawns after death.
    • + *
  • 4 - Disappears after 15 to 20 seconds. Respawns after death.
    • + *
  • 8 - Disappears after pickup, but has no effect.
    • + *
  • 11 - Blows up a few seconds after being created (bombs?)
    • + *
  • 12 - Blows up a few seconds after being created.
    • + *
  • 13 - Invisible. Triggers checkpoint sound when picked up with a vehicle, but + * doesn't trigger OnPlayerPickUpPickup.
    • + *
  • 14 - Disappears after pickup, can only be picked up with a vehicle. Triggers + * checkpoint sound.
    • + *
  • 15 - Same as type 2.
    • + *
  • 18 - Similar to type 1. Pressing Tab (KEY_ACTION) + * makes it disappear but the key press doesn't trigger OnPlayerPickUpPickup.
    • + *
  • 19 - Disappears after pickup, but doesn't respawn. Makes "cash pickup" sound + * if picked up.
    • + *
  • 20 - Similar to type 1. 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 OnPlayerPickUpPickup.
    • + *
  • 22 - Same as type 3.
    • + *
+ * + * The ID of the created pickup, -1 on failure (pickup + * max limit). + */ +native CreatePickup(model, type, Float:x, Float:y, Float:z, virtualWorld = 0); + +/** + * a_samp + * Destroys a pickup created with CreatePickup. + * The ID of the pickup to destroy (returned by CreatePickup) + * + * + */ +native bool:DestroyPickup(pickup); + +/** + * a_samp + * Toggle the drawing of nametags, health bars and armor bars above players. + * 0 to disable, 1 to enable (enabled by default) + * + * + * + * This function can only be used in OnGameModeInit. For other + * times, see ShowPlayerNameTagForPlayer. + */ +native void:ShowNameTags(bool:show); + +/** + * a_samp + * Toggles player markers (blips on the radar). Must be used when the server starts (OnGameModeInit). + * For other times, see SetPlayerMarkerForPlayer. + * The mode to use for markers. They can be streamed, meaning they are only visible + * to nearby players. See table below + * + * + * + * + * + * Marker modes:
+ *
    + *
  • PLAYER_MARKERS_MODE_OFF 0
    • + *
  • PLAYER_MARKERS_MODE_GLOBAL 1
    • + *
  • PLAYER_MARKERS_MODE_STREAMED 2
    • + *
+ * + * It is also possible to set a player's colour to a colour that has full transparency (no + * alpha value). This makes it possible to show markers on a per-player basis. + */ +native void:ShowPlayerMarkers(PLAYER_MARKERS_MODE:mode); + +/** + * a_samp + * Ends the current gamemode. + * + */ +native void:GameModeExit(); + +/** + * a_samp + * Sets the world time (for all players) to a specific hour. + * The hour to set (0-23) + * + * + * + * To set the minutes and/or to set the time for individual players, see SetPlayerTime. + * This function is only relevant for players that do not use a passing clock - see + * TogglePlayerClock. + */ +native void:SetWorldTime(hour); + +/** + * a_samp + * Get the name of a weapon. + * The ID of the weapon to get the name of + * An array to store the weapon's name in, passed by reference + * The maximum length of the weapon name to store. + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The weapon specified does not exist. + * + */ +native bool:GetWeaponName(WEAPON:weaponid, weapon[], len = sizeof (weapon)); + +/** + * a_samp + * 1 to enable, 0 to disable tire popping + * This function was removed in SA-MP 0.3. Tire popping is enabled by default. If + * you want to disable tire popping, you'll have to manually script it using + * OnVehicleDamageStatusUpdate. + */ +#pragma deprecated Use `OnVehicleDamageStatusUpdate`. +native void:EnableTirePopping(bool:enable); // deprecated function + +/** + * a_samp + * Enable friendly fire for team vehicles. Players will be unable to damage teammates' vehicles + * (SetPlayerTeam must be used!). + * + * This function was added in SA-MP 0.3x and will not work in earlier versions! + */ +native void:EnableVehicleFriendlyFire(); + +/** + * a_samp + * Toggle whether the usage of weapons in interiors is allowed or not. + * 1 to enable weapons in interiors (enabled by default), 0 + * to disable weapons in interiors + * This function does not work in the current SA:MP version! + * + * + * + */ +#pragma deprecated Use `OnPlayerInteriorChange`. +native void:AllowInteriorWeapons(bool:allow); + +/** + * a_samp + * Set the world weather for all players. + * The weather to set + * + * + * If TogglePlayerClock is enabled, weather will slowly change + * over time, instead of changing instantly. + */ +native void:SetWeather(weatherid); + +/** + * a_samp + * Get the currently set gravity. + * + * The current set gravity (as a float). + */ native Float:GetGravity(); -/// Set the gravity for all players. -/// The value that the gravity should be set to (between -50 and 50) -/// -/// -/// -/// Default gravity is 0.008. -/// This function always returns 1, even when it fails to execute if the gravity is out of the limits (lower than -50.0 or higher than +50.0). -native SetGravity(Float:gravity); - -/// This function will determine whether RCON admins will be teleported to their waypoint when they set one. -/// 0 to disable and 1 to enable -/// This function, as of 0.3d, is deprecated. Please see OnPlayerClickMap. -/// -/// -native AllowAdminTeleport(allow); - -/// This function does not work in the current SA:MP version! -/// -/// -/// -native SetDeathDropAmount(amount); - -/// Create an explosion at the specified coordinates. -/// The X coordinate of the explosion -/// The Y coordinate of the explosion -/// The Z coordinate of the explosion -/// The type of explosion -/// The explosion radius -/// -/// There is a limit as to how many explosions can be seen at once by a player. This is roughly 10. -/// This function always returns 1, even when the explosion type and/or radius values are invalid. -native CreateExplosion(Float:X, Float:Y, Float:Z, type, Float:Radius); - -/// 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 OnGameModeInit. -/// A toggle option for whether or not you'd like zone names on or off -/// This function was removed in SA-MP 0.3. This was due to crashes it caused. -native EnableZoneNames(enable); - -/// Uses standard player walking animation (animation of the CJ skin) instead of custom animations for every skin (e.g. skating for skater skins). -/// -/// -/// Only works when placed under OnGameModeInit. -/// 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. +/** + * a_samp + * Set the gravity for all players. + * The value that the gravity should be set to (between -50 and 50) + * + * + * + * Default gravity is 0.008. + * This function always returns 1, even when it fails to execute if the gravity + * is out of the limits (lower than -50.0 or higher than +50.0). + */ +native void:SetGravity(Float:gravity); + +/** + * a_samp + * This function will determine whether RCON admins will be teleported to their waypoint when + * they set one. + * 0 to disable and 1 to enable + * This function, as of 0.3d, is deprecated. Please see OnPlayerClickMap. + * + * + */ +#pragma deprecated Use `OnPlayerClickMap`. +native void:AllowAdminTeleport(bool:allow); + +/** + * a_samp + * This function does not work in the current SA:MP version! + * + * + * + */ +#pragma deprecated Use `CreatePickup`. +native void:SetDeathDropAmount(amount); + +/** + * a_samp + * Create an explosion at the specified coordinates. + * The x coordinate of the explosion + * The y coordinate of the explosion + * The z coordinate of the explosion + * The type of explosion + * The explosion radius + * + * There is a limit as to how many explosions can be seen at once by a player. This is roughly + * 10. + * This function always returns 1, even when the explosion type and/or radius + * values are invalid. + */ +native void:CreateExplosion(Float:x, Float:y, Float:z, type, Float:radius); + +/** + * a_samp + * 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 OnGameModeInit. + * A toggle option for whether or not you'd like zone names on or off + * This function was removed in SA-MP 0.3. This was due to crashes it caused. + */ +#pragma deprecated Show names manually. +native EnableZoneNames(bool:enable); + +/** + * a_samp + * Uses standard player walking animation (animation of the CJ skin) instead of custom animations + * for every skin (e.g. skating for skater skins). + * + * + * Only works when placed under OnGameModeInit. + * 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. + */ native UsePlayerPedAnims(); // Will cause the players to use CJ running/walking animations -/// Disable all the interior entrances and exits in the game (the yellow arrows at doors). -/// -/// 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). -/// 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. -/// This function always returns 1. +/** + * a_samp + * Disable all the interior entrances and exits in the game (the yellow arrows at doors). + * + * 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). + * 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. + * This function always returns 1. + */ native DisableInteriorEnterExits(); // will disable all interior enter/exits in the game. -/// Set the maximum distance to display the names of players. -/// The distance to set -/// -/// -/// -/// Default distance is 70 SA units +/** + * a_samp + * Set the maximum distance to display the names of players. + * The distance to set + * + * + * + * Default distance is 70 SA units + */ native SetNameTagDrawDistance(Float:distance); // Distance at which nametags will start rendering on the client. -/// Disables the nametag Line-Of-Sight checking so that players can see nametags through objects. -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This can not be reversed until the server restarts. +/** + * a_samp + * Disables the nametag Line-Of-Sight checking so that players can see nametags through objects. + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This can not be reversed until the server restarts. + */ native DisableNameTagLOS(); // Disables the nametag Line-Of-Sight checking -/// 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. -/// The range in which players will be able to see chat -/// -/// -/// -/// -native LimitGlobalChatRadius(Float:chat_radius); - -/// Set the player marker radius. -/// The radius that markers will show at -/// -/// -/// -/// This Function was added in SA-MP 0.3a and will not work in earlier versions! -native LimitPlayerMarkerRadius(Float:marker_radius); +/** + * a_samp + * 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. + * The range in which players will be able to see chat + * + * + * + * + */ +native LimitGlobalChatRadius(Float:chatRadius); + +/** + * a_samp + * Set the player marker radius. + * The radius that markers will show at + * + * + * + * This Function was added in SA-MP 0.3a and will not work in earlier versions! + */ +native LimitPlayerMarkerRadius(Float:markerRadius); // Npc -/// Connect an NPC to the server. -/// The name the NPC should connect as. Must follow the same rules as normal player names -/// The NPC script name that is located in the npcmodes folder (without the .amx extension) -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// NPCs do not have nametags. These can be scripted with Attach3DTextLabelToPlayer. -/// This function always return 1. +/** + * a_samp + * Connect an NPC to the server. + * The name the NPC should connect as. Must follow the same rules as normal player + * names + * The NPC script name that is located in the npcmodes folder (without the + * .amx extension) + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * NPCs do not have nametags. These can be scripted with + * Attach3DTextLabelToPlayer. + * This function always return 1. + */ native ConnectNPC(const name[], const script[]); -/// Check if a player is an actual player or an NPC. -/// The ID of the player to check -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the player is an NPC, 0 if not. -native IsPlayerNPC(playerid); - -native AddCharModel(baseid, newid, const dffname[], const txdname[]); -native AddSimpleModel(virtualworld, baseid, newid, const dffname[], const txdname[]); -native AddSimpleModelTimed(virtualworld, baseid, newid, const dffname[], const txdname[], timeon, timeoff); -native FindModelFileNameFromCRC(crc, retstr[], retstr_size = sizeof retstr); -native FindTextureFileNameFromCRC(crc, retstr[], retstr_size = sizeof retstr); +/** + * a_samp + * Check if a player is an actual player or an NPC. + * The ID of the player to check + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the player is an NPC, 0 if not. + */ +native bool:IsPlayerNPC(playerid); + +/** + * a_samp + */ +native AddCharModel(baseid, newid, const dff[], const textureLibrary[]); + +/** + * a_samp + */ +native AddSimpleModel(virtualWorld, baseid, newid, const dff[], const textureLibrary[]); + +/** + * a_samp + */ +native AddSimpleModelTimed(virtualWorld, baseid, newid, const dff[], const textureLibrary[], timeOn, timeOff); + +/** + * a_samp + */ +native FindModelFileNameFromCRC(crc, output[], size = sizeof (output)); + +/** + * a_samp + */ +native FindTextureFileNameFromCRC(crc, output[], size = sizeof (output)); + +/** + * a_samp + */ native RedirectDownload(playerid, const url[]); // Admin -/// Check if a player is logged in as an RCON admin. -/// The ID of the player to check -/// -/// -/// 1 if the player is an RCON admin, 0 if not. -native IsPlayerAdmin(playerid); - -/// Kicks a player from the server. They will have to quit the game and re-connect if they wish to continue playing. -/// The ID of the player to kick -/// -/// -/// As of SA-MP 0.3x, any action taken directly before Kick() (such as sending a message with SendClientMessage) will not reach the player. A timer must be used to delay the kick. -/// This function always returns 1, even if the function failed to execute (player specified doesn't exist). +/** + * a_samp + * Check if a player is logged in as an RCON admin. + * The ID of the player to check + * + * + * 1 if the player is an RCON admin, 0 if not. + */ +native bool:IsPlayerAdmin(playerid); + +/** + * a_samp + * Kicks a player from the server. They will have to quit the game and re-connect if they + * wish to continue playing. + * The ID of the player to kick + * + * + * As of SA-MP 0.3x, any action taken directly before Kick() (such as sending a message + * with SendClientMessage) will not reach the player. A timer must + * be used to delay the kick. + * This function always returns 1, even if the function failed to execute (player + * specified doesn't exist). + */ native Kick(playerid); -/// 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. BanEx can be used to give a reason for the ban. IP bans can be added/removed using the RCON banip and unbanip commands (SendRconCommand). -/// The ID of the player to ban -/// -/// -/// As of SA-MP 0.3x, 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. -/// +/** + * a_samp + * 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. + * BanEx can be used to give a reason for the ban. IP bans can be added/removed + * using the RCON banip and unbanip commands (SendRconCommand). + * The ID of the player to ban + * + * + * As of SA-MP 0.3x, 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. + * + */ native Ban(playerid); -/// Ban a player with a reason. -/// The ID of the player to ban -/// The reason for the ban -/// -/// -/// As of SA-MP 0.3x, 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. +/** + * a_samp + * Ban a player with a reason. + * The ID of the player to ban + * The reason for the ban + * + * + * As of SA-MP 0.3x, 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. + */ native BanEx(playerid, const reason[]); - -/// Sends an RCON (Remote Console) command. -/// The RCON command to be executed -/// -/// -/// -/// Does not support login, due to the lack of a 'playerid' parameter. -/// 'password 0' will remove the server's password if one is set. -/// This function always returns 1. -/// This function will result in OnRconCommand being called. +/** + * a_samp + * Sends an RCON (Remote Console) command. + * The RCON command to be executed + * + * + * + * Does not support login, due to the lack of a 'playerid' parameter. + * 'password 0' will remove the server's password if one is set. + * This function always returns 1. + * This function will result in OnRconCommand being called. + */ native SendRconCommand(const command[]); -/// Gets a player's network stats and saves them into a string. -/// The ID of the player you want to get the networkstats of -/// The string to store the networkstats in, passed by reference -/// The length of the string that should be stored -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3c R4 and will not work in earlier versions! -/// This function may not return accurate data when used under OnPlayerDisconnect if the player has quit normally. It usually returns accurate data if the player has been kicked or has timed out. -native GetPlayerNetworkStats(playerid, retstr[], retstr_size = sizeof retstr); - -/// Gets the server's network stats and stores them in a string. -/// The string to store the network stats in, passed by reference -/// The length of the string to be stored -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3c R4 and will not work in earlier versions! -/// -/// Example output:

-/// -/// Server Ticks: 200

-/// Messages in Send buffer: 0

-/// Messages sent: 142

-/// Bytes sent: 8203

-/// Acks sent: 11

-/// Acks in send buffer: 0

-/// Messages waiting for ack: 0

-/// Messages resent: 0

-/// Bytes resent: 0

-/// Packetloss: 0.0%

-/// Messages received: 54

-/// Bytes received: 2204

-/// Acks received: 0

-/// Duplicate acks received: 0

-/// Inst. KBits per second: 28.8

-/// KBits per second sent: 10.0

-/// KBits per second received: 2.7

-/// -/// -/// This function always returns 1. -native GetNetworkStats(retstr[], retstr_size = sizeof retstr); - -///

Returns the SA-MP client version, as reported by the player. -/// The ID of the player to get the client version of -/// The string to store the player's version in, passed by reference -/// The maximum length of the version -/// -/// -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// The string the version gets stored in will be empty if playerid is an NPC. -/// 1 on success and 0 on failure (if player specified doesn't exist). -native GetPlayerVersion(playerid, version[], len = sizeof version); // Returns the SA-MP client revision as reported by the player - -/// 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. -/// The IP to block -/// The time (in milliseconds) that the connection will be blocked for. 0 can be used for an indefinite block -/// -/// -/// This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! -/// Wildcards can be used with this function, for example blocking the IP 6.9.*.* will block all IPs where the first two octets are 6 and 9 respectively. Any number can be in place of an asterisk. -native BlockIpAddress(const ip_address[], timems); - - -/// Unblock an IP address that was previously blocked using BlockIpAddress. -/// The IP address to unblock -/// -/// -/// This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! -native UnBlockIpAddress(const ip_address[]); +/** + * a_samp + * Gets a player's network stats and saves them into a string. + * The ID of the player you want to get the networkstats of + * The string to store the networkstats in, passed by reference + * The length of the string that should be stored + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3c R4 and will not work in earlier versions! + * This function may not return accurate data when used under OnPlayerDisconnect + * if the player has quit normally. It usually returns accurate data if the player has been kicked + * or has timed out. + */ +native GetPlayerNetworkStats(playerid, output[], size = sizeof (output)); + +/** + * a_samp + * Gets the server's network stats and stores them in a string. + * The string to store the network stats in, passed by reference + * The length of the string to be stored + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3c R4 and will not work in earlier versions! + * + * Example output:
+ * + * Server Ticks: 200
+ * Messages in Send buffer: 0
+ * Messages sent: 142
+ * Bytes sent: 8203
+ * Acks sent: 11
+ * Acks in send buffer: 0
+ * Messages waiting for ack: 0
+ * Messages resent: 0
+ * Bytes resent: 0
+ * Packetloss: 0.0%
+ * Messages received: 54
+ * Bytes received: 2204
+ * Acks received: 0
+ * Duplicate acks received: 0
+ * Inst. KBits per second: 28.8
+ * KBits per second sent: 10.0
+ * KBits per second received: 2.7
+ * + * + * This function always returns 1. + */ +native GetNetworkStats(output[], size = sizeof (output)); + +/** + * a_samp + * Returns the SA-MP client version, as reported by the player. + * The ID of the player to get the client version of + * The string to store the player's version in, passed by reference + * The maximum length of the version + * + * + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * The string the version gets stored in will be empty if playerid is an NPC. + * 1 on success and 0 on failure (if player specified doesn't exist). + */ +native GetPlayerVersion(playerid, version[], len = sizeof (version)); // Returns the SA-MP client revision as reported by the player + +/** + * a_samp + * 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. + * The IP to block + * The time (in milliseconds) that the connection will be blocked for. 0 + * can be used for an indefinite block + * + * + * This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! + * Wildcards can be used with this function, for example blocking the IP 6.9.*.* + * will block all IPs where the first two octets are 6 and 9 respectively. + * Any number can be in place of an asterisk. + */ +native BlockIpAddress(const ipAddress[], timeMS); + +/** + * a_samp + * Unblock an IP address that was previously blocked using BlockIpAddress. + * The IP address to unblock + * + * + * This function was added in SA-MP 0.3z R2-2 and will not work in earlier versions! + */ +native UnBlockIpAddress(const ipAddress[]); // Deprecated: -/// Get the string value of a server variable. -/// The name of the string variable to get the value of -/// An array into which to store the value, passed by reference -/// The length of the string that should be stored -/// -/// -/// This function, as of 0.3.7 R2, is deprecated. Please see GetConsoleVarAsString -/// Using this function on anything other than a string (int, bool or float) or a nonexistent server variable, will crash your server! This is a bug. -/// Type 'varlist' in the server console to display a list of available server variables and their types. -/// 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. -/// The length of the returned string. 0 if the specified server variable is not a string or doesn't exist. -native GetServerVarAsString(const varname[], buffer[], len = sizeof buffer); - -/// Get the integer value of a server variable. -/// The name of the integer variable to get the value of -/// -/// -/// This function, as of 0.3.7 R2, is deprecated. Please see GetConsoleVarAsInt -/// Type 'varlist' in the server console to display a list of available server variables and their types. -/// The value of the specified server variable. 0 if the specified server variable is not an integer or doesn't exist. -native GetServerVarAsInt(const varname[]); - -/// Get the boolean value of a server variable. -/// The name of the boolean variable to get the value of -/// -/// -/// This function, as of 0.3.7 R2, is deprecated. Please see GetConsoleVarAsBool -/// Type 'varlist' in the server console to display a list of available server variables and their types. -/// The value of the specified server variable. 0 if the specified server variable is not a boolean or doesn't exist. -native GetServerVarAsBool(const varname[]); +/** + * a_samp + * Get the string value of a server variable. + * The name of the string variable to get the value of + * An array into which to store the value, passed by reference + * The length of the string that should be stored + * + * + * This function, as of 0.3.7 R2, is deprecated. Please see + * GetConsoleVarAsString + * Using this function on anything other than a string (int, bool or float) or a nonexistent + * server variable, will crash your server! This is a bug. + * Type 'varlist' in the server console to display a list of available server variables and + * their types. + * When filterscripts or plugins is specified as the cvar, this function only returns the name + * of the first specified filterscript or plugin. This is a bug. + * The length of the returned string. 0 if the specified server variable is not + * a string or doesn't exist. + */ +#pragma deprecated Use `GetConsoleVarAsString`. +native GetServerVarAsString(const cvar[], buffer[], len = sizeof (buffer)) = GetConsoleVarAsString; + +/** + * a_samp + * Get the integer value of a server variable. + * The name of the integer variable to get the value of + * + * + * This function, as of 0.3.7 R2, is deprecated. Please see GetConsoleVarAsInt + * Type 'varlist' in the server console to display a list of available server variables and + * their types. + * The value of the specified server variable. 0 if the specified server variable is not an + * integer or doesn't exist. + */ +#pragma deprecated Use `GetConsoleVarAsInt`. +native GetServerVarAsInt(const cvar[]) = GetConsoleVarAsInt; + +/** + * a_samp + * Get the boolean value of a server variable. + * The name of the boolean variable to get the value of + * + * + * This function, as of 0.3.7 R2, is deprecated. Please see GetConsoleVarAsBool + * Type 'varlist' in the server console to display a list of available server variables and + * their types. + * The value of the specified server variable. 0 if the specified server variable + * is not a boolean or doesn't exist. + */ +#pragma deprecated Use `GetConsoleVarAsBool`. +native bool:GetServerVarAsBool(const cvar[]) = GetConsoleVarAsBool; // These are the same 3 functions as above although they avoid the name ambiguity/conflict with the SVar system. -/// Get the string value of a console variable. -/// The name of the string variable to get the value of -/// An array into which to store the value, passed by reference -/// The length of the string that should be stored -/// -/// -/// Type varlist in the server console to display a list of available console variables and their types. -/// When filterscripts or plugins are specified as the varname, this function only returns the name of the first specified filterscript or plugin. -/// Using this function with anything other than a string (integer, boolean or float) will cause your server to crash. Using it with a nonexistent console variable will also cause your server to crash. -/// The length of the returned string. 0 if the specified console variable is not a string or doesn't exist. -native GetConsoleVarAsString(const varname[], buffer[], len = sizeof buffer); - -/// Get the integer value of a console variable. -/// The name of the integer variable to get the value of -/// -/// -/// Type varlist in the server console to display a list of available console variables and their types. -/// The value of the specified console variable. 0 if the specified console variable is not an integer or doesn't exist. -native GetConsoleVarAsInt(const varname[]); - -/// Get the boolean value of a console variable. -/// The name of the boolean variable to get the value of -/// -/// -/// Type varlist in the server console to display a list of available console variables and their types. -/// The value of the specified console variable. 0 if the specified console variable is not a boolean or doesn't exist. -native GetConsoleVarAsBool(const varname[]); +/** + * a_samp + * Get the string value of a console variable. + * The name of the string variable to get the value of + * An array into which to store the value, passed by reference + * The length of the string that should be stored + * + * + * Type varlist in the server console to display a list of available console + * variables and their types. + * When filterscripts or plugins are specified as the cvar, this function only returns the + * name of the first specified filterscript or plugin. + * Using this function with anything other than a string (integer, boolean or float) + * will cause your server to crash. Using it with a nonexistent console variable will also cause your + * server to crash. + * The length of the returned string. 0 if the specified console variable is + * not a string or doesn't exist. + */ +native GetConsoleVarAsString(const cvar[], buffer[], len = sizeof (buffer)); + +/** + * a_samp + * Get the integer value of a console variable. + * The name of the integer variable to get the value of + * + * + * Type varlist in the server console to display a list of available console + * variables and their types. + * The value of the specified console variable. 0 if the specified console variable + * is not an integer or doesn't exist. + */ +native GetConsoleVarAsInt(const cvar[]); + +/** + * a_samp + * Get the boolean value of a console variable. + * The name of the boolean variable to get the value of + * + * + * Type varlist in the server console to display a list of available console + * variables and their types. + * The value of the specified console variable. 0 if the specified console variable + * is not a boolean or doesn't exist. + */ +native bool:GetConsoleVarAsBool(const cvar[]); // Extended admin network stats -/// Gets the tick rate (like FPS) of the server. -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// The server tick rate (per second). Returns 0 when the server is just started. +/** + * a_samp + * Gets the tick rate (like FPS) of the server. + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * The server tick rate (per second). Returns 0 when the server is just started. + */ native GetServerTickRate(); -/// Gets the amount of time (in milliseconds) that a player has been connected to the server for. -/// The ID of the player to get the connected time of -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// The return value is not reset to zero after changing the game mode (using the RCON command "gmx"). -/// This function returns the amount of time (in milliseconds) that a player has been connected to the server for. 0 is returned if the player is not connected. +/** + * a_samp + * Gets the amount of time (in milliseconds) that a player has been connected to the server + * for. + * The ID of the player to get the connected time of + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * The return value is not reset to zero after changing the game mode (using the RCON command + * "gmx"). + * This function returns the amount of time (in milliseconds) that a player has been connected + * to the server for. 0 is returned if the player is not connected. + */ native NetStats_GetConnectedTime(playerid); -/// Gets the number of messages the server has received from the player. -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// This function returns the number of messages the server has received from the player. 0 is returned if the player is not connected. +/** + * a_samp + * Gets the number of messages the server has received from the player. + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * This function returns the number of messages the server has received from the player. 0 + * is returned if the player is not connected. + */ native NetStats_MessagesReceived(playerid); -/// Gets the amount of data (in bytes) that the server has received from the player. -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// This function returns the number of bytes the server has received from the player. 0 is returned if the player is not connected. +/** + * a_samp + * Gets the amount of data (in bytes) that the server has received from the player. + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * This function returns the number of bytes the server has received from the player. 0 + * is returned if the player is not connected. + */ native NetStats_BytesReceived(playerid); -/// Gets the number of messages the server has sent to the player. -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// The number of messages the server has sent to the player. +/** + * a_samp + * Gets the number of messages the server has sent to the player. + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * The number of messages the server has sent to the player. + */ native NetStats_MessagesSent(playerid); -/// Gets the amount of data (in bytes) that the server has sent to the player. -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// This function returns the number of bytes the server has sent to the player. 0 is returned if the player is not connected. +/** + * a_samp + * Gets the amount of data (in bytes) that the server has sent to the player. + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * This function returns the number of bytes the server has sent to the player. 0 + * is returned if the player is not connected. + */ native NetStats_BytesSent(playerid); -/// Gets the number of messages the player has received in the last second. -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// the number of messages the player has received in the last second. +/** + * a_samp + * Gets the number of messages the player has received in the last second. + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * the number of messages the player has received in the last second. + */ native NetStats_MessagesRecvPerSecond(playerid); -/// 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). -/// The ID of the player to get the data from -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// Anything greater than 0.0% should already be a cause of concern. Anything greater than 1.0% is outright bad. -/// 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. -/// A more accurate packetloss function can be found here: http://forum.sa-mp.com/showpost.php?p=2488911&postcount=984 -/// The percentage packet loss as a float. 0.0 if player not connected. +/** + * a_samp + * 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). + * The ID of the player to get the data from + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * Anything greater than 0.0% should already be a cause of concern. Anything greater than + * 1.0% is outright bad. + * 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. + * A more accurate packetloss function can be found here: + * http://forum.sa-mp.com/showpost.php?p=2488911&postcount=984 + * The percentage packet loss as a float. 0.0 if player not connected. + */ native Float:NetStats_PacketLossPercent(playerid); -/// Gets the player's current connection status. -/// The ID of the player to get the connection status of -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -/// -/// Status:

-///

    -///
  • 0 - NO_ACTION
    • -///
  • 1 - DISCONNECT_ASAP
    • -///
  • 2 - DISCONNECT_ASAP_SILENTLY
    • -///
  • 3 - DISCONNECT_ON_NO_ACK
    • -///
  • 4 - REQUESTED_CONNECTION
    • -///
  • 5 - HANDLING_CONNECTION_REQUEST
    • -///
  • 6 - UNVERIFIED_SENDER
    • -///
  • 7 - SET_ENCRYPTION_ON_MULTIPLE_16_BYTE_PACKET
    • -///
  • 8 - CONNECTED
    • -///
-/// -/// The player's connection status, as an integer value. +/** + * a_samp + * Gets the player's current connection status. + * The ID of the player to get the connection status of + * + * + * + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + * + * Status:
+ *
    + *
  • 0 - NO_ACTION
    • + *
  • 1 - DISCONNECT_ASAP
    • + *
  • 2 - DISCONNECT_ASAP_SILENTLY
    • + *
  • 3 - DISCONNECT_ON_NO_ACK
    • + *
  • 4 - REQUESTED_CONNECTION
    • + *
  • 5 - HANDLING_CONNECTION_REQUEST
    • + *
  • 6 - UNVERIFIED_SENDER
    • + *
  • 7 - SET_ENCRYPTION_ON_MULTIPLE_16_BYTE_PACKET
    • + *
  • 8 - CONNECTED
    • + *
+ * + * The player's connection status, as an integer value. + */ native NetStats_ConnectionStatus(playerid); -/// Get a player's IP and port. -/// The ID of the player to get the IP and port of -/// A string array to store the IP and port in, passed by reference -/// The maximum length of the IP/port. 22 is recommended -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3z and will not work in earlier versions! -native NetStats_GetIpPort(playerid, ip_port[], ip_port_len = sizeof ip_port); +/** + * a_samp + * Get a player's IP and port. + * The ID of the player to get the IP and port of + * A string array to store the IP and port in, passed by reference + * The maximum length of the IP/port. 22 is recommended + * + * + * + * + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3z and will not work in earlier versions! + */ +native NetStats_GetIpPort(playerid, output[], size = sizeof (output)); // Menu -/// Creates a menu. -/// The title for the new menu -/// How many colums shall the new menu have -/// The X position of the menu (640x460 canvas - 0 would put the menu at the far left) -/// The Y position of the menu (640x460 canvas - 0 would put the menu at the far top) -/// The width for the first column -/// The width for the second column (optional=0.0) -/// -/// -/// -/// -/// -/// -/// -/// -/// This function merely CREATES the menu - ShowMenuForPlayer must be used to show it.

-/// You can only create and access 2 columns (0 and 1).

-/// If the title's length is equal to or greater than 32 chars the title is truncated to 30 characters. -/// -/// There is a limit of 12 items per menu, and a limit of 128 menus in total. -/// The ID of the new menu or -1 on failure. +/** + * a_samp + *

Creates a menu. + * The title for the new menu + * How many colums shall the new menu have + * The x position of the menu (640x460 canvas - 0 would put the menu at + * the far left) + * The y position of the menu (640x460 canvas - 0 would put the menu at + * the far top) + * The width for the first column + * The width for the second column (optional=0.0) + * + * + * + * + * + * + * + * + * This function merely CREATES the menu - ShowMenuForPlayer must + * be used to show it.
+ * You can only create and access 2 columns (0 and 1).
+ * If the title's length is equal to or greater than 32 chars the title is truncated + * to 30 characters. + * + * There is a limit of 12 items per menu, and a limit of 128 menus + * in total. + * The ID of the new menu or -1 on failure. + */ native Menu:CreateMenu(const title[], columns, Float:x, Float:y, Float:col1width, Float:col2width = 0.0); -/// Destroys the specified menu. -/// The menu ID to destroy -/// -/// -/// -/// -/// -/// 1 if the destroying was successful, otherwise 0. -native DestroyMenu(Menu:menuid); - -/// Adds an item to a specified menu. -/// The menu id to add an item to -/// The column to add the item to -/// The text for the new menu item -/// -///
    -///
  • Crashes when passed an invalid menu ID.
    • -///
  • You can only have 12 items per menu (13th goes to the right side of the header of column name (colored), 14th and higher not display at all).
    • -///
  • You can only use 2 columns (0 and 1).
    • -///
  • You can only add 8 color codes per one item (~r~, ~g~ etc.).
    • -///
  • Maximum length of menu item is 31 symbols.
    • -///
-/// -/// The index of the row this item was added to. -/// -/// -/// -/// -/// -native AddMenuItem(Menu:menuid, column, const menutext[]); - -/// Sets the caption of a column in a menu. -/// ID of the menu to change -/// The column (0 or 1) to set the header of -/// The caption text for the column -/// -/// -/// -/// Crashes when passed an invalid menu ID. -/// Note that you can add only 12 items with AddMenuItem. The 13th object of a menu would replace the header of the column which is correctly set with this function. -native SetMenuColumnHeader(Menu:menuid, column, const columnheader[]); - -/// Shows a previously created menu for a player. -/// The ID of the menu to show. Returned by CreateMenu -/// The ID of the player to whom the menu will be shown -/// -/// -/// -/// -/// -/// -/// Crashes the both server and player if an invalid menu ID given. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. Menu and/or player doesn't exist. -/// -native ShowMenuForPlayer(Menu:menuid, playerid); - -///

Hides a menu for a player. -/// The ID of the menu to hide. Returned by CreateMenu and passed to OnPlayerSelectedMenuRow -/// The ID of the player that the menu will be hidden for -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. -/// -native HideMenuForPlayer(Menu:menuid, playerid); - -///

Check if a menu ID is vliad. -/// The menu to check for existance -/// -/// -/// 1 if the menu is valid, otherwise 0. -native IsValidMenu(Menu:menuid); - -/// Disable a menu. -/// The ID of the menu to disable -/// -/// -/// -/// Crashes when passed an invalid menu ID. -native DisableMenu(Menu:menuid); - -/// Disable a specific row in a menu for all players. It will be greyed-out and can't be selected by players. -/// The ID of the menu to disable a row of. Ensure this is valid, as an invalid menu ID will crash the entire server -/// The ID of the row to disable (rows start at 0) -/// -/// -/// -/// -/// Crashes when passed an invalid menu ID.

-/// This function disabled the specified menu row for all players. 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. -/// -/// This function always returns 1, 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. -native DisableMenuRow(Menu:menuid, row); - -///

Gets the ID of the menu the player is currently viewing (shown by ShowMenuForPlayer). -/// The ID of the player to get the current menu of -/// -/// -/// -/// -/// -/// -/// -/// Returns previous menu when none is displayed. -/// The ID of the player's currently shown menu, or INVALID_MENU (255) if no menu shown. +/** + * a_samp + * Destroys the specified menu. + * The menu ID to destroy + * + * + * + * + * + * 1 if the destroying was successful, otherwise 0. + */ +native bool:DestroyMenu(Menu:menuid); + +/** + * a_samp + * Adds an item to a specified menu. + * The menu ID to add an item to + * The column to add the item to + * The text for the new menu item + * + *
    + *
  • Crashes when passed an invalid menu ID.
    • + *
  • You can only have 12 items per menu (13th goes to the right side of the header + * of column name (coloured), 14th and higher not display at all).
    • + *
  • You can only use 2 columns (0 and 1).
    • + *
  • You can only add 8 colour codes per one item (~r~, ~g~ + * etc.).
    • + *
  • Maximum length of menu item is 31 symbols.
    • + *
+ * + * The index of the row this item was added to. + * + * + * + * + * + */ +native AddMenuItem(Menu:menuid, column, const text[]); + +/** + * a_samp + * Sets the caption of a column in a menu. + * ID of the menu to change + * The column (0 or 1) to set the header of + * The caption text for the column + * + * + * + * Crashes when passed an invalid menu ID. + * Note that you can add only 12 items with AddMenuItem. + * The 13th object of a menu would replace the header of the column which is correctly set with this + * function. + */ +native bool:SetMenuColumnHeader(Menu:menuid, column, const heading[]); + +/** + * a_samp + * Shows a previously created menu for a player. + * The ID of the menu to show. Returned by CreateMenu + * The ID of the player to whom the menu will be shown + * + * + * + * + * + * + * Crashes the both server and player if an invalid menu ID given. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. Menu and/or player doesn't exist. + * + */ +native bool:ShowMenuForPlayer(Menu:menuid, playerid); + +/** + * a_samp + * Hides a menu for a player. + * The ID of the menu to hide. Returned by CreateMenu + * and passed to OnPlayerSelectedMenuRow + * The ID of the player that the menu will be hidden for + * + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. + * + */ +native bool:HideMenuForPlayer(Menu:menuid, playerid); + +/** + * a_samp + * Check if a menu ID is vliad. + * The menu to check for existance + * + * + * 1 if the menu is valid, otherwise 0. + */ +native bool:IsValidMenu(Menu:menuid); + +/** + * a_samp + * Disable a menu. + * The ID of the menu to disable + * + * + * + * Crashes when passed an invalid menu ID. + */ +native bool:DisableMenu(Menu:menuid); + +/** + * a_samp + * Disable a specific row in a menu for all players. It will be greyed-out and can't + * be selected by players. + * The ID of the menu to disable a row of. Ensure this is valid, as an invalid + * menu ID will crash the entire server + * The ID of the row to disable (rows start at 0) + * + * + * + * + * Crashes when passed an invalid menu ID.
+ * This function disabled the specified menu row for all players. 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. + * + * This function always returns 1, 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. + */ +native bool:DisableMenuRow(Menu:menuid, row); + +/** + * a_samp + * Gets the ID of the menu the player is currently viewing (shown by ShowMenuForPlayer). + * The ID of the player to get the current menu of + * + * + * + * + * + * + * + * Returns previous menu when none is displayed. + * The ID of the player's currently shown menu, or INVALID_MENU (255) + * if no menu shown. + */ native Menu:GetPlayerMenu(playerid); -/// 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. -/// The X (left/right) coordinate to create the textdraw at -/// The Y (up/down) coordinate to create the textdraw at -/// The text that will appear in the textdraw -/// -/// If you choose values for y that are less than 1, the first text row will be invisible and only the shadow is visible.

-/// text[] must not be empty or the server will crash! If you need a textdraw that shows nothing, use a space underscore. Now it's fixed.

-/// If the last character in the text is a space, the text will all be blank.

-/// If part of the text is off-screen, the color of the text will not show, only the shadow (if enabled) will. -/// -/// -/// This applies ONLY to sa-mp versions before 0.3z:

-/// Maximum length of textdraw is 800 characters. Longer text will crash the client in older versions.

-/// If you use color codes (such as ~R~ ~G~) beyond 255th character the client will crash trying to display the textdraw. -/// -/// -/// 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 TextDrawAlignment with alignment 3 (right), the x,y coordinate is the top right coordinate for the text draw.

-/// This function merely CREATES the textdraw, you must use TextDrawShowForPlayer or TextDrawShowForAll to show it.

-/// It is recommended to use WHOLE numbers instead of decimal positions when creating textdraws to ensure resolution friendly design. -/// -/// Keyboard key mapping codes (such as ~k~~VEHICLE_ENTER_EXIT~ don't work beyond 255th character. -/// The ID of the created textdraw. Textdraw IDs start at 0. +/** + * a_samp + *

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. + * The x (left/right) coordinate to create the textdraw at + * The y (up/down) coordinate to create the textdraw at + * The text that will appear in the textdraw + * + * If you choose values for y that are less than 1, the first text row will be invisible and only + * the shadow is visible.
+ * text[] must not be empty or the server will crash! If you need a textdraw that shows nothing, use + * a space underscore. Now it's fixed.
+ * If the last character in the text is a space, the text will all be blank.
+ * If part of the text is off-screen, the colour of the text will not show, only the shadow (if enabled) + * will. + * + * + * This applies ONLY to sa-mp versions before 0.3z:
+ * Maximum length of textdraw is 800 characters. Longer text will crash the client in older + * versions.
+ * If you use colour codes (such as ~R~ ~G~) beyond 255th character the client will + * crash trying to display the textdraw. + * + * + * 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 TextDrawAlignment + * with alignment 3 (right), the x, y coordinate is the top right coordinate for the text + * draw.
+ * This function merely CREATES the textdraw, you must use TextDrawShowForPlayer + * or TextDrawShowForAll to show it.
+ * It is recommended to use WHOLE numbers instead of decimal positions when creating textdraws to + * ensure resolution friendly design. + * + * Keyboard key mapping codes (such as ~k~~VEHICLE_ENTER_EXIT~ don't work beyond + * 255th character. + * The ID of the created textdraw. Textdraw IDs start at 0. + */ native Text:TextDrawCreate(Float:x, Float:y, const text[]); -/// Destroys a previously-created textdraw. -/// The ID of the textdraw to destroy. Returned by TextDrawCreate +/** + * a_samp + * Destroys a previously-created textdraw. + * The ID of the textdraw to destroy. Returned by TextDrawCreate + */ native TextDrawDestroy(Text:text); -/// Sets the width and height of the letters. -/// The TextDraw to change -/// Width of a char -/// Height of a char -/// When using this function purely for the benefit of affecting the TextDraw box, multiply 'Y' by 0.135 to convert to TextDrawTextSize-like measurements. Hint: it is easier and extremely precise to use LD_SPAC:white sprite for box-only textdraws, TextDrawTextSize will have regular offsets. -/// If you want to change the letter size of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -/// Fonts appear to look the best with an X to Y ratio of 1 to 4 (e.g. if x is 0.5 then y should be 2). -native TextDrawLetterSize(Text:text, Float:x, Float:y); - -/// Change the size of a textdraw (box if TextDrawUseBox is enabled and/or clickable area for use with TextDrawSetSelectable). -/// The TextDraw to set the size of -/// The size on the X axis (left/right) following the same 640x480 grid as TextDrawCreate -/// The size on the Y axis (up/down) following the same 640x480 grid as TextDrawCreate -/// -/// The x and y have different meanings with different TextDrawAlignment values:

-///

    -///
  • 1 (left): they are the right-most corner of the box, absolute coordinates.
    • -///
  • 2 (center): they need to inverted (switch the two) and the x value is the overall width of the box.
    • -///
  • 3 (right): the x and y are the coordinates of the left-most corner of the box
    • -///
-/// -/// -/// Using font type 4 (sprite) and 5 (model preview) converts X and Y of this function from corner coordinates to WIDTH and HEIGHT (offsets).

-/// The TextDraw box starts 10.0 units up and 5.0 to the left as the origin (TextDrawCreate coordinate).

-/// This function defines the clickable area for use with TextDrawSetSelectable, whether a box is shown or not. -/// -/// If you want to change the text size of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -native TextDrawTextSize(Text:text, Float:x, Float:y); - -///

Set the alignment of text in a text draw. -/// The ID of the textdraw to set the alignment of -/// 1-left 2-centered 3-right -/// For alignment 2 (center) the x and y values of TextSize need to be swapped, see notes at TextDrawTextSize, also position coordinate become position of center of textdraw and not left/top edges. -native TextDrawAlignment(Text:text, alignment); - -/// Sets the text color of a textdraw. -/// The ID of the textdraw to change the color of. -/// The color to set the textdraw to -/// You can also use GameText Colors in TextDraws. -/// If the TextDraw is already shown, it must be re-shown (TextDrawShowForAll/TextDrawShowForPlayer) for the changes of this function to take effect. -native TextDrawColor(Text:text, color); - -/// Toggle whether a textdraw uses a box or not. -/// The ID of the text textdraw to toggle the box of -/// 1 to show a box or 0 to not show a box -/// If the textdraw is already shown, it must be re-shown (TextDrawShowForAll/TextDrawShowForPlayer) to show the changes of this function. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the textdraw specified does not exist. -/// -native TextDrawUseBox(Text:text, use); - -///

Adjusts the text box colour (only used if TextDrawUseBox 'use' parameter is 1). -/// The TextDraw to change -/// The colour (RGBA) -/// If you want to change the boxcolour of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -native TextDrawBoxColor(Text:text, color); - -/// Sets the size of a textdraw's text's shadow. -/// The ID of the textdraw to set the shadow size of -/// The size of the shadow. 1 is generally used for a normal shadow size. 0 disables the shadow completely -/// The shadow can be cut by the box area if the size is set too big for the area. -/// If you want to change the shadow of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. The textdraw does not exist. -/// +/** + * a_samp + *

Sets the width and height of the letters. + * The TextDraw to change + * Width of a char + * Height of a char + * When using this function purely for the benefit of affecting the TextDraw box, multiply + * 'y' by 0.135 to convert to TextDrawTextSize-like measurements. + * Hint: it is easier and extremely precise to use LD_SPAC:white sprite for box-only + * textdraws, TextDrawTextSize will have regular offsets. + * If you want to change the letter size of a textdraw that is already shown, you don't have + * to recreate it. Simply use TextDrawShowForPlayer/ + * TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + * Fonts appear to look the best with an x to y ratio of 1 to 4 + * (e.g. if x is 0.5 then y should be 2). + */ +native TextDrawLetterSize(Text:text, Float:width, Float:height); + +/** + * a_samp + * Change the size of a textdraw (box if TextDrawUseBox is enabled + * and/or clickable area for use with TextDrawSetSelectable). + * The TextDraw to set the size of + * The size on the x axis (left/right) following the same 640x480 grid as + * TextDrawCreate + * The size on the y axis (up/down) following the same 640x480 grid as + * TextDrawCreate + * + * The x and y have different meanings with different TextDrawAlignment values:
+ *
    + *
  • 1 (left): they are the right-most corner of the box, absolute coordinates.
    • + *
  • 2 (center): they need to inverted (switch the two) and the x value is the overall + * width of the box.
    • + *
  • 3 (right): the x and y are the coordinates of the left-most corner of the box + *
    • + *
+ * + * + * Using font type 4 (sprite) and 5 (model preview) converts x and y of + * this function from corner coordinates to WIDTH and HEIGHT (offsets).
+ * The TextDraw box starts 10.0 units up and 5.0 to the left as the origin + * (TextDrawCreate coordinate).
+ * This function defines the clickable area for use with TextDrawSetSelectable, + * whether a box is shown or not. + * + * If you want to change the text size of a textdraw that is already shown, you don't have + * to recreate it. Simply use TextDrawShowForPlayer/ + * TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ +native TextDrawTextSize(Text:text, Float:width, Float:height); + +/** + * a_samp + * Set the alignment of text in a text draw. + * The ID of the textdraw to set the alignment of + * 1-left 2-centered 3-right + * For alignment 2 (center) the x and y values of TextSize + * need to be swapped, see notes at TextDrawTextSize, also position + * coordinate become position of center of textdraw and not left/top edges. + */ +native TextDrawAlignment(Text:text, TEXT_DRAW_ALIGN:alignment); + +/** + * a_samp + * Sets the text colour of a textdraw. + * The ID of the textdraw to change the colour of. + * The colour to set the textdraw to + * You can also use GameText Colors in TextDraws. + * If the TextDraw is already shown, it must be re-shown (TextDrawShowForAll/TextDrawShowForPlayer) for the changes of this function to take + * effect. + */ +native TextDrawColor(Text:text, colour); + +/** + * a_samp + * Toggle whether a textdraw uses a box or not. + * The ID of the text textdraw to toggle the box of + * 1 to show a box or 0 to not show a box + * If the textdraw is already shown, it must be re-shown (TextDrawShowForAll/TextDrawShowForPlayer) to show the changes of this function. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the textdraw specified does not exist. + * + */ +native TextDrawUseBox(Text:text, bool:use); + +/** + * a_samp + * Adjusts the text box colour (only used if TextDrawUseBox 'use' + * parameter is 1). + * The TextDraw to change + * The colour (RGBA) + * If you want to change the boxcolour of a textdraw that is already shown, you don't have + * to recreate it. Simply use TextDrawShowForPlayer/ + * TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ +native TextDrawBoxColor(Text:text, colour); + +/** + * a_samp + * Sets the size of a textdraw's text's shadow. + * The ID of the textdraw to set the shadow size of + * The size of the shadow. 1 is generally used for a normal shadow + * size. 0 disables the shadow completely + * The shadow can be cut by the box area if the size is set too big for the area. + * If you want to change the shadow of a textdraw that is already shown, you don't have to + * recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. The textdraw does not exist. + * + */ native TextDrawSetShadow(Text:text, size); -/// Sets the thickness of a textdraw's text's outline. TextDrawBackgroundColor can be used to change the color. -/// The ID of the text draw to set the outline thickness of -/// The thickness of the outline, as an integer. 0 for no outline -/// If you want to change the outline of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. +/** + * a_samp + * Sets the thickness of a textdraw's text's outline. TextDrawBackgroundColor + * can be used to change the colour. + * The ID of the text draw to set the outline thickness of + * The thickness of the outline, as an integer. 0 for no outline + * If you want to change the outline of a textdraw that is already shown, you don't have to + * recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ native TextDrawSetOutline(Text:text, size); -/// Adjusts the text draw area background color (the outline/shadow - NOT the box. For box color, see TextDrawBoxColor). -/// The ID of the textdraw to set the background color of -/// The color that the textdraw should be set to -/// If TextDrawSetOutline is used with size > 0, the outline color will match the color used in TextDrawBackgroundColor. Changing the value of color seems to alter the color used in TextDrawColor -/// If you want to change the background colour of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -native TextDrawBackgroundColor(Text:text, color); - -/// Changes the text font. -/// The TextDraw to change -/// There are four font styles, see http://wiki.sa-mp.com/wiki/PlayerTextDrawFont. Font value 4 specifies that this is a txd sprite; 5 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 -/// If you want to change the font of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -native TextDrawFont(Text:text, font); - -/// Appears to scale text spacing to a proportional ratio. Useful when using TextDrawLetterSize to ensure the text has even character spacing. -/// The ID of the textdraw to set the proportionality of -/// 1 to enable proportionality, 0 to disable -/// Proportionality is set to 1 by default, you might skip this function if you don't want to disable it. -/// If you want to change the proportionality of a textdraw that is already shown, you don't have to recreate it. Simply use TextDrawShowForPlayer/TextDrawShowForAll after modifying the textdraw and the change will be visible. -native TextDrawSetProportional(Text:text, set); - -/// Sets whether a textdraw can be selected (clicked on) or not. -/// The ID of the textdraw to make selectable -/// 1 to make it selectable, or 0 to make it not selectable -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// TextDrawSetSelectable must be used BEFORE the textdraw is shown to players for it to be selectable. -/// Use TextDrawTextSize to define the clickable area. -native TextDrawSetSelectable(Text:text, set); - -/// Shows a textdraw for a specific player. -/// The ID of the player to show the textdraw for -/// The ID of the textdraw to show. Returned by TextDrawCreate -/// 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. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means either the player and/or textdraw specified does not exist. -/// +/** + * a_samp + *

Adjusts the text draw area background colour (the outline/shadow - NOT the box. For box + * colour, see TextDrawBoxColor). + * The ID of the textdraw to set the background colour of + * The colour that the textdraw should be set to + * If TextDrawSetOutline is used with size > 0, + * the outline colour will match the colour used in TextDrawBackgroundColor. + * Changing the value of colour seems to alter the colour used in TextDrawColor + * If you want to change the background colour of a textdraw that is already shown, you don't + * have to recreate it. Simply use TextDrawShowForPlayer/ + * TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ +native TextDrawBackgroundColor(Text:text, colour); + +/** + * a_samp + * Changes the text font. + * The TextDraw to change + * There are four font styles, see + * http://wiki.sa-mp.com/wiki/PlayerTextDrawFont. + * Font value 4 specifies that this is a txd sprite; 5 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 + * If you want to change the font of a textdraw that is already shown, you don't have to recreate + * it. Simply use TextDrawShowForPlayer/TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ +native TextDrawFont(Text:text, TEXT_DRAW_FONT:font); + +/** + * a_samp + * Appears to scale text spacing to a proportional ratio. Useful when using TextDrawLetterSize + * to ensure the text has even character spacing. + * The ID of the textdraw to set the proportionality of + * 1 to enable proportionality, 0 to disable + * Proportionality is set to 1 by default, you might skip this function if you + * don't want to disable it. + * If you want to change the proportionality of a textdraw that is already shown, you don't + * have to recreate it. Simply use TextDrawShowForPlayer/ + * TextDrawShowForAll + * after modifying the textdraw and the change will be visible. + */ +native TextDrawSetProportional(Text:text, bool:set); + +/** + * a_samp + * Sets whether a textdraw can be selected (clicked on) or not. + * The ID of the textdraw to make selectable + * 1 to make it selectable, or 0 to make it not selectable + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * TextDrawSetSelectable must be used BEFORE the textdraw + * is shown to players for it to be selectable. + * Use TextDrawTextSize to define the clickable area. + */ +native TextDrawSetSelectable(Text:text, bool:set); + +/** + * a_samp + * Shows a textdraw for a specific player. + * The ID of the player to show the textdraw for + * The ID of the textdraw to show. Returned by TextDrawCreate + * 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. + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means either the player and/or textdraw + * specified does not exist. + * + */ native TextDrawShowForPlayer(playerid, Text:text); -/// Hides a textdraw for a specific player. -/// The ID of the player that the textdraw should be hidden for -/// The ID of the textdraw to hide -/// -/// -/// +/** + * a_samp + * Hides a textdraw for a specific player. + * The ID of the player that the textdraw should be hidden for + * The ID of the textdraw to hide + * + * + * + */ native TextDrawHideForPlayer(playerid, Text:text); -/// Shows a textdraw for all players. -/// The ID of the textdraw to show. Returned by TextDrawCreate -/// -/// -/// -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the textdraw specified does not exist. -/// +/** + * a_samp + *

Shows a textdraw for all players. + * The ID of the textdraw to show. Returned by TextDrawCreate + * + * + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the textdraw specified does not exist. + * + */ native TextDrawShowForAll(Text:text); -/// Hides a text draw for all players. -/// The ID of the textdraw to hide (returned by TextDrawCreate) -/// -/// -/// +/** + * a_samp + * Hides a text draw for all players. + * The ID of the textdraw to hide (returned by TextDrawCreate) + * + * + * + */ native TextDrawHideForAll(Text:text); -/// Changes the text on a textdraw. -/// The TextDraw to change -/// The new string for the TextDraw -/// There are limits to the length of textdraw strings - see here for more info. +/** + * a_samp + * Changes the text on a textdraw. + * The TextDraw to change + * The new string for the TextDraw + * There are limits to the length of textdraw strings - see here + * for more info. + */ native TextDrawSetString(Text:text, const string[]); -/// Set the model for a textdraw model preview. Click here to see this function's effect. -/// The textdraw id that will display the 3D preview -/// The GTA SA or SA:MP model ID to display -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order for this function to have effect. -/// Use TextDrawBackgroundColor to set the background color behind the model. -native TextDrawSetPreviewModel(Text:text, modelindex); - -/// Sets the rotation and zoom of a 3D model preview textdraw. -/// The X rotation value -/// The Y rotation value -/// The Z rotation value -/// The zoom value, smaller values make the camera closer and larger values make the camera further away (optional=1.0) -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order for this function to have effect. -native TextDrawSetPreviewRot(Text:text, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fZoom = 1.0); - -/// If a vehicle model is used in a 3D preview textdraw, this sets the two colour values for that vehicle. -/// The textdraw id that is set to display a 3D vehicle model preview -/// The primary Color ID to set the vehicle to -/// The secondary Color ID to set the vehicle to -/// This function was added in SA-MP 0.3x and will not work in earlier versions! -/// The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order for this function to have effect. -native TextDrawSetPreviewVehCol(Text:text, color1, color2); +/** + * a_samp + * Set the model for a textdraw model preview. Click here + * to see this function's effect. + * The textdraw ID that will display the 3D preview + * The GTA SA or SA:MP model ID to display + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order + * for this function to have effect. + * Use TextDrawBackgroundColor to set the background + * colour behind the model. + */ +native TextDrawSetPreviewModel(Text:text, modelIndex); + +/** + * a_samp + * Sets the rotation and zoom of a 3D model preview textdraw. + * The x rotation value + * The y rotation value + * The z rotation value + * The zoom value, smaller values make the camera closer and larger values make the + * camera further away (optional=1.0) + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order + * for this function to have effect. + */ +native TextDrawSetPreviewRot(Text:text, Float:rotX, Float:rotY, Float:rotZ, Float:zoom = 1.0); + +/** + * a_samp + * If a vehicle model is used in a 3D preview textdraw, this sets the two colour values for + * that vehicle. + * The textdraw ID that is set to display a 3D vehicle model preview + * The primary Color ID to set the vehicle to + * The secondary Color ID to set the vehicle to + * This function was added in SA-MP 0.3x and will not work in earlier versions! + * The textdraw MUST use the font type TEXT_DRAW_FONT_MODEL_PREVIEW in order + * for this function to have effect. + */ +native TextDrawSetPreviewVehCol(Text:text, colour1, colour2); // Gang Zones -/// Create a gangzone (colored radar area). -/// The X coordinate for the west side of the gangzone -/// The Y coordinate for the south side of the gangzone -/// The X coordinate for the east side of the gangzone -/// The Y coordinate for the north side of the gangzone -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// There is a limit of 1024 gangzones.

-/// Putting the parameters in the wrong order results in glitchy behavior. -/// -/// This function merely CREATES the gangzone, you must use GangZoneShowForPlayer or GangZoneShowForAll to show it. -/// The ID of the created zone, returns -1 if not created. -native GangZoneCreate(Float:minx, Float:miny, Float:maxx, Float:maxy); - -///

Destroy a gangzone. -/// The ID of the zone to destroy -/// -/// -/// -/// -/// -/// -/// -/// -/// +/** + * a_samp + * Create a gangzone (coloured radar area). + * The x coordinate for the west side of the gangzone + * The y coordinate for the south side of the gangzone + * The x coordinate for the east side of the gangzone + * The y coordinate for the north side of the gangzone + * + * + * + * + * + * + * + * + * + * + * There is a limit of 1024 gangzones.
+ * Putting the parameters in the wrong order results in glitchy behavior. + * + * This function merely CREATES the gangzone, you must use GangZoneShowForPlayer + * or GangZoneShowForAll to show it. + * The ID of the created zone, returns -1 if not created. + */ +native GangZoneCreate(Float:minX, Float:minY, Float:maxX, Float:maxY); + +/** + * a_samp + * Destroy a gangzone. + * The ID of the zone to destroy + * + * + * + * + * + * + * + * + * + */ native GangZoneDestroy(zone); -/// Show a gangzone for a player. Must be created with GangZoneCreate first. -/// The ID of the player you would like to show the gangzone for. -/// The ID of the gang zone to show for the player. Returned by GangZoneCreate -/// The color to show the gang zone, as an integer or hex in RGBA color format. Alpha transparency supported -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 1 if the gangzone was shown, otherwise 0 (non-existant). -native GangZoneShowForPlayer(playerid, zone, color); - -/// Shows a gangzone with the desired color to all players. -/// The ID of the gangzone to show (returned by GangZoneCreate) -/// The color to show the gang zone, as an integer or hex in RGBA color format. Alpha transparency supported -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully. The gang zone was shown for all players.

-/// 0: The function failed to execute. The gangzone does not exist. -/// -native GangZoneShowForAll(zone, color); - -///

Hides a gangzone for a player. -/// The ID of the player to hide the gangzone for -/// The ID of the zone to hide -/// -/// -/// -/// -/// -/// -/// -/// -/// +/** + * a_samp + * Show a gangzone for a player. Must be created with GangZoneCreate + * first. + * The ID of the player you would like to show the gangzone for. + * The ID of the gang zone to show for the player. Returned by GangZoneCreate + * The colour to show the gang zone, as an integer or hex in RGBA colour + * format. Alpha transparency supported + * + * + * + * + * + * + * + * + * + * 1 if the gangzone was shown, otherwise 0 (non-existant). + */ +native GangZoneShowForPlayer(playerid, zone, colour); + +/** + * a_samp + * Shows a gangzone with the desired colour to all players. + * The ID of the gangzone to show (returned by GangZoneCreate) + * The colour to show the gang zone, as an integer or hex in RGBA colour + * format. Alpha transparency supported + * + * + * + * + * + * + * + * + * + * + * 1: The function executed successfully. The gang zone was shown for all players.
+ * 0: The function failed to execute. The gangzone does not exist. + * + */ +native GangZoneShowForAll(zone, colour); + +/** + * a_samp + * Hides a gangzone for a player. + * The ID of the player to hide the gangzone for + * The ID of the zone to hide + * + * + * + * + * + * + * + * + * + */ native GangZoneHideForPlayer(playerid, zone); -/// GangZoneHideForAll hides a gangzone from all players. -/// The zone to hide -/// -/// -/// -/// -/// -/// -/// -/// -/// +/** + * a_samp + * GangZoneHideForAll hides a gangzone from all players. + * The zone to hide + * + * + * + * + * + * + * + * + * + */ native GangZoneHideForAll(zone); -/// Makes a gangzone flash for a player. -/// The ID of the player to flash the gangzone for -/// The ID of the zone to flash -/// The color to flash the gang zone, as an integer or hex in RGBA color format. Alpha transparency supported -/// -/// -/// -/// -/// -/// -/// -/// -/// -native GangZoneFlashForPlayer(playerid, zone, flashcolor); - -/// GangZoneFlashForAll flashes a gangzone for all players. -/// The zone to flash -/// The color to flash the gang zone, as an integer or hex in RGBA color format. Alpha transparency supported -/// -/// -/// -/// -/// -/// -/// -/// -/// -native GangZoneFlashForAll(zone, flashcolor); - -/// Stops a gangzone flashing for a player. -/// The ID of the player to stop the gangzone flashing for -/// The ID of the gangzonezone to stop flashing -/// -/// -/// -/// -/// -/// -/// -/// -/// +/** + * a_samp + * Makes a gangzone flash for a player. + * The ID of the player to flash the gangzone for + * The ID of the zone to flash + * The colour to flash the gang zone, as an integer or hex in RGBA + * colour format. Alpha transparency supported + * + * + * + * + * + * + * + * + * + */ +native GangZoneFlashForPlayer(playerid, zone, flashColour); + +/** + * a_samp + * GangZoneFlashForAll flashes a gangzone for all players. + * The zone to flash + * The colour to flash the gang zone, as an integer or hex in RGBA + * colour format. Alpha transparency supported + * + * + * + * + * + * + * + * + * + */ +native GangZoneFlashForAll(zone, flashColour); + +/** + * a_samp + * Stops a gangzone flashing for a player. + * The ID of the player to stop the gangzone flashing for + * The ID of the gangzonezone to stop flashing + * + * + * + * + * + * + * + * + * + */ native GangZoneStopFlashForPlayer(playerid, zone); -/// Stops a gangzone flashing for all players. -/// The ID of the zone to stop flashing. Returned by GangZoneCreate -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully. Success is reported even if the gang zone wasn't flashing to begin with.

-/// 0: The function failed to execute. The gangzone specified does not exist. -/// +/** + * a_samp + *

Stops a gangzone flashing for all players. + * The ID of the zone to stop flashing. Returned by GangZoneCreate + * + * + * + * + * + * + * + * + * + * + * 1: The function executed successfully. Success is reported even if the gang zone + * wasn't flashing to begin with.
+ * 0: The function failed to execute. The gangzone specified does not exist. + * + */ native GangZoneStopFlashForAll(zone); // Global 3D Text Labels -/// Creates a 3D Text Label at a specific location in the world. -/// The initial text string -/// The text Color, as an integer or hex in RGBA color format -/// X-Coordinate -/// Y-Coordinate -/// Z-Coordinate -/// The distance from where you are able to see the 3D Text Label -/// The virtual world in which you are able to see the 3D Text -/// Test the line-of-sight so this text can't be seen through objects (optional=0) -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// If is empty, the server/clients next to the text might crash!

-/// If the virtualworld is set as -1 the text will not appear. -/// -/// drawdistance seems to be a lot smaller when spectating. -/// Use color embedding for multiple colors in the text. -/// The ID of the newly created 3D Text Label, or INVALID_3DTEXT_ID if the 3D Text Label limit (MAX_3DTEXT_GLOBAL) was reached. -native Text3D:Create3DTextLabel(const text[], color, Float:X, Float:Y, Float:Z, Float:DrawDistance, virtualworld, testLOS=0); - -///

Delete a 3D text label (created with Create3DTextLabel). -/// The ID of the 3D text label to delete -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// 1 if the 3D text label was deleted, otherwise 0. -native Delete3DTextLabel(Text3D:id); - -/// Attach a 3D text label to a player. -/// The ID of the 3D text label to attach. Returned by Create3DTextLabel -/// The ID of the player to attach the label to -/// The X offset from the player -/// The Y offset from the player -/// The Z offset from the player -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player and/or label do not exist. -/// -native Attach3DTextLabelToPlayer(Text3D:id, playerid, Float:OffsetX, Float:OffsetY, Float:OffsetZ); - -///

Attaches a 3D Text Label to a specific vehicle. -/// The ID of the 3D text label to attach. Returned by Create3DTextLabel -/// The vehicle you want to attach the 3D Text Label to -/// The Offset-X coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0). -/// The Offset-Y coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0). -/// The Offset-Z coordinate of the player vehicle (the vehicle is 0.0,0.0,0.0). -/// -/// -/// -/// -/// -/// -/// -/// Attach3DTextLabelToPlayer was added in SA-MP 0.3a This function was added in SA-MP 0.3a and will not work in earlier versions! -native Attach3DTextLabelToVehicle(Text3D:id, vehicleid, Float:OffsetX, Float:OffsetY, Float:OffsetZ); - - -/// Updates a 3D Text Label text and color. -/// The 3D Text Label you want to update -/// The color the 3D Text Label should have from now on -/// The new text which the 3D Text Label should have from now on -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// If is empty, the server/clients next to the text might crash! -native Update3DTextLabelText(Text3D:id, color, const text[]); - -// Per-player 3D Text Labels - -/// Creates a 3D Text Label only for a specific player. -/// The player which should see the newly created 3DText Label -/// The text to display -/// The text color -/// X Coordinate (or offset if attached) -/// Y Coordinate (or offset if attached) -/// Z Coordinate (or offset if attached) -/// The distance where you are able to see the 3D Text Label -/// The player you want to attach the 3D Text Label to. (optional=INVALID_PLAYER_ID) -/// The vehicle you want to attach the 3D Text Label to. (optional=INVALID_VEHICLE_ID) -/// Test the line-of-sight so this text can't be seen through walls (optional=0) -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// If is empty, the server/clients next to the text might crash! -/// drawdistance seems to be a lot smaller when spectating. -/// The ID of the newly created Player 3D Text Label, or INVALID_3DTEXT_ID if the Player 3D Text Label limit (MAX_3DTEXT_PLAYER) was reached. -native PlayerText3D:CreatePlayer3DTextLabel(playerid, const text[], color, Float:X, Float:Y, Float:Z, Float:DrawDistance, attachedplayer=INVALID_PLAYER_ID, attachedvehicle=INVALID_VEHICLE_ID, testLOS=0); - -/// Destroy a 3D text label that was created using CreatePlayer3DTextLabel. -/// The ID of the player whose 3D text label to delete -/// The ID of the player's 3D text label to delete -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the label specified doesn't exist. -/// -native DeletePlayer3DTextLabel(playerid, PlayerText3D:id); - -///

Updates a player 3D Text Label's text and color. -/// The ID of the player for which the 3D Text Label was created -/// The 3D Text Label you want to update -/// The color the 3D Text Label should have from now on -/// The new text which the 3D Text Label should have from now on -/// -/// -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// If is empty, the server/clients next to the text might crash! -native UpdatePlayer3DTextLabelText(playerid, PlayerText3D:id, color, const text[]); - -/// Shows the player a synchronous (only one at a time) dialog box. -/// The ID of the player to show the dialog to -/// An ID to assign this dialog to, so responses can be processed. Max dialogid is 32767. Using negative values will close any open dialog -/// The style of the dialog -/// 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 -/// The text to display in the main dialog. Use \n to start a new line and \t to tabulate -/// The text on the left button -/// The text on the right button. Leave it blank ( "" ) to hide it -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// Use color embedding for multiple colors in the text. -/// Using -1 as dialogid closes all dialogs currently shown on the client's screen. -/// -/// 1: The function executed successfully.

-/// 0: The function failed to execute. This means the player is not connected.

-/// -native ShowPlayerDialog(playerid, dialogid, style, const caption[], const info[], const button1[], const button2[]); - -///

Get a players unique ID. -/// The player to get the unique ID of -/// Where to save the unique ID -/// The size of "serial" -native gpci(playerid, serial[], maxlen); +/** + * a_samp + * Creates a 3D Text Label at a specific location in the world. + * The initial text string + * The text Color, as an integer or hex in RGBA colour format + * x-Coordinate + * y-Coordinate + * z-Coordinate + * The distance from where you are able to see the 3D Text Label + * The virtual world in which you are able to see the 3D Text + * Test the line-of-sight so this text can't be seen through objects (optional=0) + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * If is empty, the server/clients next to the text might crash!
+ * If the virtualWorld is set as -1 the text will not appear. + * + * drawdistance seems to be a lot smaller when spectating. + * Use colour embedding + * for multiple colours in the text. + * The ID of the newly created 3D Text Label, or INVALID_3DTEXT_ID if the 3D + * Text Label limit (MAX_3DTEXT_GLOBAL) was reached. + */ +native Text3D:Create3DTextLabel(const text[], colour, Float:x, Float:y, Float:z, Float:drawDistance, virtualWorld, bool:testLOS = false); + +/** + * a_samp + * Delete a 3D text label (created with Create3DTextLabel). + * The ID of the 3D text label to delete + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * 1 if the 3D text label was deleted, otherwise 0. + */ +native Delete3DTextLabel(Text3D:textid); + +/** + * a_samp + * Attach a 3D text label to a player. + * The ID of the 3D text label to attach. Returned by Create3DTextLabel + * The ID of the player to attach the label to + * The x offset from the player + * The y offset from the player + * The z offset from the player + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player and/or label do not exist. + * + */ +native Attach3DTextLabelToPlayer(Text3D:textid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ); + +/** + * a_samp + * Attaches a 3D Text Label to a specific vehicle. + * The ID of the 3D text label to attach. Returned by Create3DTextLabel + * The vehicle you want to attach the 3D Text Label to + * The offset-x coordinate of the player vehicle (the vehicle is 0.0, 0.0, 0.0). + * The offset-y coordinate of the player vehicle (the vehicle is 0.0, 0.0, 0.0). + * The offset-z coordinate of the player vehicle (the vehicle is 0.0, 0.0, 0.0). + * + * + * + * + * + * + * + * Attach3DTextLabelToPlayer was added in SA-MP 0.3a This function was added in SA-MP 0.3a + * and will not work in earlier versions! + */ +native Attach3DTextLabelToVehicle(Text3D:textid, parentid, Float:offsetX, Float:offsetY, Float:offsetZ); + +/** + * a_samp + * Updates a 3D Text Label text and colour. + * The 3D Text Label you want to update + * The colour the 3D Text Label should have from now on + * The new text which the 3D Text Label should have from now on + * + * + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * If is empty, the server/clients next to the text might crash! + */ +native Update3DTextLabelText(Text3D:textid, colour, const text[]); + +/** + * a_samp + * Shows the player a synchronous (only one at a time) dialog box. + * The ID of the player to show the dialog to + * An ID to assign this dialog to, so responses can be processed. Max dialogid + * is 32767. Using negative values will close any open dialog + * The style of the dialog + * 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 + * The text to display in the main dialog. Use \n to start a new line + * and \t to tabulate + * The text on the left button + * The text on the right button. Leave it blank ( "" ) to hide it + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * Use colour embedding for multiple colours in the text. + * Using -1 as dialogid closes all dialogs currently shown on the client's screen. + * + * + * 1: The function executed successfully.
+ * 0: The function failed to execute. This means the player is not connected.
+ * + */ +native bool:ShowPlayerDialog(playerid, dialogid, DIALOG_STYLE:style, const caption[], const info[], const button1[], const button2[]); + +/** + * a_samp + * Get a players unique ID. + * The player to get the unique ID of + * Where to save the unique ID + * The size of "output" (the serial) + */ +#pragma deprecated Use `GPCI`. +native gpci(playerid, serial[], len = sizeof (serial)); + +/** + * a_samp + * Get a players unique ID. + * The player to get the unique ID of + * Where to save the unique ID + * The size of "serial" (the serial) + */ +native GPCI(playerid, serial[], len = sizeof (serial)) = gpci; // -------------------------------------------------- // Forwards (Callback declarations) // -------------------------------------------------- - -/// This callback is triggered when the gamemode starts. -/// -/// -/// -/// 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. -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in gamemode. -/// +/** + *

This callback is triggered when the gamemode starts. + * + * + * + * 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. + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in gamemode. + * + */ forward OnGameModeInit(); -/// This callback is called when a gamemode ends, either through 'gmx', the server being shut down, or GameModeExit. -/// -/// -/// -/// -/// 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. -/// 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 RemoveBuildingForPlayer calls during OnGameModeInit which could result in a client crash. -/// 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. -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in gamemode. -/// +/** + *

This callback is called when a gamemode ends, either through 'gmx', the server being shut + * down, or GameModeExit. + * + * + * + * + * 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. + * 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 + * RemoveBuildingForPlayer + * calls during OnGameModeInit which could result in a client crash. + * 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. + * + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in gamemode. + * + */ forward OnGameModeExit(); -/// This callback is called when a filterscript is initialized (loaded). It is only called inside the filterscript which is starting. -/// -/// -/// -/// This callback does not handle returns. +/** + * This callback is called when a filterscript is initialized (loaded). It is only called + * inside the filterscript which is starting. + * + * + * + * This callback does not handle returns. + */ forward OnFilterScriptInit(); -/// This callback is called when a filterscript is unloaded. It is only called inside the filterscript which is unloaded. -/// -/// -/// -/// This callback does not handle returns. +/** + * This callback is called when a filterscript is unloaded. It is only called inside the filterscript + * which is unloaded. + * + * + * + * This callback does not handle returns. + */ forward OnFilterScriptExit(); -/// This callback is called when a player connects to the server. -/// The ID of the player that connected -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player connects to the server. + * The ID of the player that connected + * + * + * + * This callback can also be called by NPC. + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerConnect(playerid); -/// This callback is called when a player disconnects from the server. -/// The ID of the player that disconnected -/// The reason for the disconnection. See table below -/// -/// -/// -/// This callback can also be called by NPC. -/// 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 GetPlayerIp and GetPlayerPos. -/// -/// Reasons:

-///

    -///
  • 0 - timeout/Crash - the player's connection was lost. Either their game crashed or their network had a fault.
    • -///
  • 1 - quit - the player purposefully quit, either using the /quit (/q) command or via the pause menu.
    • -///
  • 2 - kick/ban - the player was kicked or banned by the server.
    • -///
-/// -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player disconnects from the server. + * The ID of the player that disconnected + * The reason for the disconnection. See table below + * + * + * + * This callback can also be called by NPC. + * 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 GetPlayerIp and GetPlayerPos. + * + * Reasons:
+ *
    + *
  • 0 - timeout/Crash - the player's connection was lost. Either their game crashed + * or their network had a fault.
    • + *
  • 1 - quit - the player purposefully quit, either using the /quit (/q) + * command or via the pause menu.
    • + *
  • 2 - kick/ban - the player was kicked or banned by the server.
    • + *
+ * + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerDisconnect(playerid, reason); -/// This callback is called when a player spawns.(i.e. after caling SpawnPlayer function). -/// The ID of the player that spawned -/// -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// The game sometimes deducts $100 from players after spawn. -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player spawns.(i.e. after caling SpawnPlayer + * function). + * The ID of the player that spawned + * + * + * + * + * + * This callback can also be called by NPC. + * The game sometimes deducts $100 from players after spawn. + * + * 0 - Will prevent other filterscripts from receiving this callback.
+ * 1 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerSpawn(playerid); -/// This callback is called when a player dies, either by suicide or by being killed by another player. -/// The ID of the player that died -/// The ID of the player that killed the player who died, or INVALID_PLAYER_ID if there was none -/// The ID of the reason for the player's death -/// -/// -/// -/// -/// The reason will return 37 (flame thrower) from any fire sources (e.g. molotov, 18)

-/// The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)

-/// You do not need to check whether killerid is valid before using it in SendDeathMessage. INVALID_PLAYER_ID is a valid killerid ID parameter in that function.

-/// playerid is the only one who can call the callback. (good to know for anti fake death) -/// -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// -forward OnPlayerDeath(playerid, killerid, reason); - -///

This callback is called when a vehicle respawns. -/// The ID of the vehicle that spawned -/// -/// -/// -/// -/// -/// 0 - Will prevent other filterscripts from receiving this callback.

-/// 1 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// -forward OnVehicleSpawn(vehicleid); - -///

This callback is called when a vehicle is destroyed - either by exploding or becoming submerged in water. -/// The ID of the vehicle that was destroyed -/// 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 -/// -/// -/// This callback can also be called by NPC. -/// 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. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnVehicleDeath(vehicleid, killerid); - -///

Called when a player sends a chat message. -/// The ID of the player who typed the text -/// The text the player typed -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// Returning 0 in this callback will stop the text from being sent to all players.

-/// It is always called first in filterscripts so returning 0 there blocks other scripts from seeing it. -/// +/** + *

Called when a player sends a chat message. + * The ID of the player who typed the text + * The text the player typed + * + * + * + * This callback can also be called by NPC. + * + * Returning 0 in this callback will stop the text from being sent to all players.
+ * It is always called first in filterscripts so returning 0 there blocks other scripts + * from seeing it. + * + */ forward OnPlayerText(playerid, text[]); -/// 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. /help. -/// The ID of the player that entered a command -/// The command that was entered (including the forward slash) -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// Return 1 if the command was processed, otherwise 0; If the command was not found both in filterscripts and in gamemode, the player will be received a message: SERVER: Unknown command.

-/// It is always called first in filterscripts so returning 1 there blocks other scripts from seeing it. -/// +/** + *

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. /help. + * The ID of the player that entered a command + * The command that was entered (including the forward slash) + * + * + * + * This callback can also be called by NPC. + * + * Return 1 if the command was processed, otherwise 0; If the command + * was not found both in filterscripts and in gamemode, the player will be received a message: SERVER: + * Unknown command.
+ * It is always called first in filterscripts so returning 1 there blocks other scripts + * from seeing it. + * + */ forward OnPlayerCommandText(playerid, cmdtext[]); -/// Called when a player changes class at class selection (and when class selection first appears). -/// The ID of the player that changed class -/// The ID of the current class being viewed (returned by AddPlayerClass) -/// -/// -/// This callback can also be called by NPC. -/// This callback is also called when a player presses F4. -/// -/// Returning 0 in this callback will prevent the player from spawning. The player can be forced to spawn when SpawnPlayer is used.

-/// It is always called first in filterscripts. -/// +/** + *

Called when a player changes class at class selection (and when class selection first appears). + * The ID of the player that changed class + * The ID of the current class being viewed (returned by AddPlayerClass) + * + * + * This callback can also be called by NPC. + * This callback is also called when a player presses F4. + * + * Returning 0 in this callback will prevent the player from spawning. The player can + * be forced to spawn when SpawnPlayer is used.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerRequestClass(playerid, classid); -/// This callback is called when a player starts to enter a vehicle, meaning the player is not in vehicle yet at the time this callback is called. -/// ID of the player who attempts to enter a vehicle -/// ID of the vehicle the player is attempting to enter -/// 0 if entering as driver. 1 if entering as passenger -/// -/// -/// -/// -/// This callback is called when a player BEGINS to enter a vehicle, not when they HAVE entered it. See OnPlayerStateChange. -/// This callback is still called if the player is denied entry to the vehicle (e.g. it is locked or full). -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerEnterVehicle(playerid, vehicleid, ispassenger); - -///

This callback is called when a player starts to exit a vehicle. -/// The ID of the player that is exiting a vehicle -/// The ID of the vehicle the player is exiting -/// -/// -/// -/// -/// Not called if the player falls off a bike or is removed from a vehicle by other means such as using SetPlayerPos. -/// You must use OnPlayerStateChange and check if their old state is PLAYER_STATE_DRIVER or PLAYER_STATE_PASSENGER and their new state is PLAYER_STATE_ONFOOT. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerExitVehicle(playerid, vehicleid); - -///

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. -/// The ID of the player that changed state -/// The player's new state -/// The player's previous state -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// States:

-///

    -///
  • PLAYER_STATE_NONE - empty (while initializing)
    • -///
  • PLAYER_STATE_ONFOOT - player is on foot
    • -///
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • -///
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • -///
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • -///
  • PLAYER_STATE_SPAWNED - player is spawned
    • -///
  • PLAYER_STATE_SPECTATING - player is spectating
    • -///
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • -///
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger
    • -///
-/// -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerStateChange(playerid, newstate, oldstate); - -///

This callback is called when a player enters the checkpoint set for that player. -/// The player who entered the checkpoint -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// +/** + *

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. + * The ID of the player that changed state + * The player's new state + * The player's previous state + * + * + * + * + * This callback can also be called by NPC. + * + * States:
+ *
    + *
  • PLAYER_STATE_NONE - empty (while initializing)
    • + *
  • PLAYER_STATE_ONFOOT - player is on foot
    • + *
  • PLAYER_STATE_DRIVER - player is the driver of a vehicle
    • + *
  • PLAYER_STATE_PASSENGER - player is passenger of a vehicle
    • + *
  • PLAYER_STATE_WASTED - player is dead or on class selection
    • + *
  • PLAYER_STATE_SPAWNED - player is spawned
    • + *
  • PLAYER_STATE_SPECTATING - player is spectating
    • + *
  • PLAYER_STATE_EXIT_VEHICLE - player exits a vehicle
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_DRIVER - player enters a vehicle as driver
    • + *
  • PLAYER_STATE_ENTER_VEHICLE_PASSENGER - player enters a vehicle as passenger + *
    • + *
+ * + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +#if !defined PLAYER_STATE + #define PLAYER_STATE: _: +#endif +forward OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate); + +/** + * This callback is called when a player enters the checkpoint set for that player. + * The player who entered the checkpoint + * + * + * + * + * + * + * + * + * + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerEnterCheckpoint(playerid); -/// This callback is called when a player leaves the checkpoint set for them by SetPlayerCheckpoint. Only one checkpoint can be set at a time. -/// The ID of the player that left their checkpoint -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player leaves the checkpoint set for them by + * SetPlayerCheckpoint. + * Only one checkpoint can be set at a time. + * The ID of the player that left their checkpoint + * + * + * + * + * + * + * + * + * + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerLeaveCheckpoint(playerid); -/// This callback is called when a player enters a race checkpoint. -/// The ID of the player who entered the race checkpoint -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player enters a race checkpoint. + * The ID of the player who entered the race checkpoint + * + * + * + * + * + * + * + * + * + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerEnterRaceCheckpoint(playerid); -/// This callback is called when a player leaves the race checkpoint. -/// The ID of the player that left the race checkpoint -/// -/// -/// -/// -/// -/// -/// -/// -/// -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when a player leaves the race checkpoint. + * The ID of the player that left the race checkpoint + * + * + * + * + * + * + * + * + * + * This callback can also be called by NPC. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerLeaveRaceCheckpoint(playerid); -/// This callback is called when a command is sent through the server console, remote RCON, or via the in-game "/rcon command". -/// A string containing the command that was typed, as well as any passed parameters -/// -/// -/// You will need to include this callback in a loaded filterscript for it to work in the gamemode! -/// "/rcon" is not included in "cmd" when a player types a command. -/// If you use the print function here, it will send a message to the player who typed the command in-game as well as the log. -/// This callback is not called when the player is not logged in as RCON admin. -/// When the player is not logged in as RCON admin and uses /rcon login, this callback will not be called and OnRconLoginAttempt is called instead. However, when the player is logged in as RCON admin, the use of this command will call this callback. -/// -/// 0 if the command was not processed, it will be passed to another script or 1 if the command was processed, will not be passed to other scripts.

-/// It is always called first in filterscripts so returning 1 there blocks gamemode from seeing it. -/// +/** + *

This callback is called when a command is sent through the server console, remote RCON, + * or via the in-game "/rcon command". + * A string containing the command that was typed, as well as any passed parameters + * + * + * You will need to include this callback in a loaded filterscript for it to work in the gamemode! + * "/rcon" is not included in "cmd" when a player types a command. + * If you use the print function here, it will send a message to the player + * who typed the command in-game as well as the log. + * This callback is not called when the player is not logged in as RCON admin. + * When the player is not logged in as RCON admin and uses /rcon login, this callback + * will not be called and OnRconLoginAttempt is called instead. However, + * when the player is logged in as RCON admin, the use of this command will call this callback. + * + * 0 if the command was not processed, it will be passed to another script or 1 + * if the command was processed, will not be passed to other scripts.
+ * It is always called first in filterscripts so returning 1 there blocks gamemode from + * seeing it. + * + */ forward OnRconCommand(cmd[]); -/// Called when a player attempts to spawn via class selection either by pressing SHIFT or clicking the 'Spawn' button. -/// The ID of the player that requested to spawn -/// -/// -/// This callback can also be called by NPC. -/// To prevent players from spawning with certain classes, the last viewed class must be saved in a variable in OnPlayerRequestClass. -/// -/// Returning 0 in this callback will prevent the player from spawning.

-/// It is always called first in filterscripts so returning 0 there also blocks other scripts from seeing it. -/// +/** + *

Called when a player attempts to spawn via class selection either by pressing SHIFT or clicking + * the 'Spawn' button. + * The ID of the player that requested to spawn + * + * + * This callback can also be called by NPC. + * To prevent players from spawning with certain classes, the last viewed class must be saved + * in a variable in OnPlayerRequestClass. + * + * Returning 0 in this callback will prevent the player from spawning.
+ * It is always called first in filterscripts so returning 0 there also blocks other + * scripts from seeing it. + * + */ forward OnPlayerRequestSpawn(playerid); -/// This callback is called when an object is moved after MoveObject (when it stops moving). -/// The ID of the object that was moved -/// -/// -/// -/// -/// SetObjectPos does not work when used in this callback. To fix it, recreate the object. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnObjectMoved(objectid); - -///

This callback is called when a player object is moved after MovePlayerObject (when it stops moving). -/// The playerid the object is assigned to -/// The ID of the player object that was moved -/// -/// -/// -/// -/// This callback can also be called for NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerObjectMoved(playerid, objectid); - -///

Called when a player picks up a pickup created with CreatePickup. -/// The ID of the player that picked up the pickup -/// The ID of the pickup, returned by CreatePickup -/// -/// -/// -/// This callback does not handle returns.

-/// It is always called first in gamemode. -/// +/** + *

Called when a player picks up a pickup created with CreatePickup. + * The ID of the player that picked up the pickup + * The ID of the pickup, returned by CreatePickup + * + * + * + * This callback does not handle returns.
+ * It is always called first in gamemode. + * + */ forward OnPlayerPickUpPickup(playerid, pickupid); -/// This callback is called when a vehicle is modded. -/// The ID of the driver of the vehicle -/// The ID of the vehicle which is modded -/// The ID of the component which was added to the vehicle -/// -/// -/// -/// -/// This callback is NOT called by AddVehicleComponent. -/// -/// Return 0 to desync the mod (or an invalid mod) from propagating and / or crashing players.

-/// It is always called first in gamemode so returning 0 there also blocks other filterscripts from seeing it. -/// -forward OnVehicleMod(playerid, vehicleid, componentid); - -///

This callback is called when a player enters or exits a mod shop. -/// The ID of the player that entered or exited the modshop -/// 1 if the player entered or 0 if they exited -/// The interior ID of the modshop that the player is entering (or 0 if exiting) -/// -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// Players collide when they get into the same mod shop. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnEnterExitModShop(playerid, enterexit, interiorid); - -///

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. -/// The ID of the player that changed the paintjob of their vehicle -/// The ID of the vehicle that had its paintjob changed -/// The ID of the new paintjob -/// -/// -/// -/// -/// This callback is not called by ChangeVehiclePaintjob. -/// -/// This callback does not handle returns. Returning 0 won't deny the paintjob change.

-/// It is always called first in gamemode so returning 0 there blocks other filterscripts from seeing it. -/// -forward OnVehiclePaintjob(playerid, vehicleid, paintjobid); - -///

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. -/// The ID of the player that is driving the vehicle -/// The ID of the vehicle that was resprayed -/// The color that the vehicle's primary color was changed to -/// The color that the vehicle's secondary color was changed to -/// -/// -/// -/// -/// -/// Previewing a component inside a mod shop might call this callback. -/// This callback is not called by ChangeVehicleColor. -/// -/// Returning 0 in this callback will deny the colour change. Returning 1 will allow it. This can be used to prevent hackers from changing vehicle colours using cheats.

-/// It is always called first in gamemode so returning 0 there also blocks other filterscripts from seeing it. -/// -forward OnVehicleRespray(playerid, vehicleid, color1, color2); - -///

This callback is called when a vehicle element such as doors, tires, panels, or lights change their damage status. -/// The ID of the vehicle that was changed its damage status -/// The ID of the player who synced the change in the damage status (who had the car damaged or repaired) -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This does not include vehicle health changes -/// -/// 1 - Will prevent other filterscripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts.

-/// -forward OnVehicleDamageStatusUpdate(vehicleid, playerid); - -///

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. -/// The ID of the vehicle that's position was updated -/// The ID of the player that sent a vehicle position sync update -/// 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 -/// The new X coordinate of the vehicle. This parameter was added in 0.3z. Leave it out if using an earlier version -/// The new Y coordinate of the vehicle. This parameter was added in 0.3z. Leave it out if using an earlier version -/// The new Z coordinate of the vehicle. This parameter was added in 0.3z. Leave it out if using an earlier version -/// The new X velocity of the vehicle. This parameter was added in 0.3z R4. Leave it out if using an earlier version -/// The new Y velocity of the vehicle. This parameter was added in 0.3z R4. Leave it out if using an earlier version -/// The new Z velocity of the vehicle. This parameter was added in 0.3z R4. Leave it out if using an earlier version -/// -/// This callback was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// 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. -/// GetVehiclePos will return the old coordinates of the vehicle before this update. -/// -/// Returning 0 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.

-/// It is always called first in filterscripts so returning 0 there also blocks other scripts from seeing it. -/// -forward OnUnoccupiedVehicleUpdate(vehicleid, playerid, passenger_seat, Float:new_x, Float:new_y, Float:new_z, Float:vel_x, Float:vel_y, Float:vel_z); - -///

This callback is called when a player selects an item from a menu (ShowMenuForPlayer). -/// The ID of the player that selected a menu item -/// The ID of the row that was selected. The first row is ID 0 -/// -/// -/// -/// -/// -/// -/// -/// The menu ID is not passed to this callback. GetPlayerMenu must be used to determine which menu the player selected an item on. -/// -/// This callback does not handle returns.

-/// It is always called first in gamemode. -/// +/** + *

This callback is called when a player selects an item from a menu (ShowMenuForPlayer). + * The ID of the player that selected a menu item + * The ID of the row that was selected. The first row is ID 0 + * + * + * + * + * + * + * + * The menu ID is not passed to this callback. GetPlayerMenu must + * be used to determine which menu the player selected an item on. + * + * This callback does not handle returns.
+ * It is always called first in gamemode. + * + */ forward OnPlayerSelectedMenuRow(playerid, row); -/// Called when a player exits a menu. -/// The ID of the player that exited the menu -/// -/// -/// -/// -/// This callback does not handle returns.

-/// It is always called first in gamemode. -/// +/** + *

Called when a player exits a menu. + * The ID of the player that exited the menu + * + * + * + * + * This callback does not handle returns.
+ * It is always called first in gamemode. + * + */ forward OnPlayerExitedMenu(playerid); -/// Called when a player changes interior. Can be triggered by SetPlayerInterior or when a player enter/exits a building. -/// The playerid who changed interior -/// The interior the player is now in -/// The interior the player was in before -/// -/// -/// -/// -/// -/// This callback does not handle returns.

-/// It is always called first in gamemode. -/// +/** + *

Called when a player changes interior. Can be triggered by SetPlayerInterior or when a + * player enter/exits a building. + * The playerid who changed interior + * The interior the player is now in + * The interior the player was in before + * + * + * + * + * + * This callback does not handle returns.
+ * It is always called first in gamemode. + * + */ forward OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid); -/// 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). -/// The ID of the player that pressed or released a key -/// A map (bitmask) of the keys currently held - see here -/// A map (bitmask) of the keys held prior to the current change - see here -/// -/// This callback can also be called by NPC. -/// -/// Useful macros:

-/// -/// // HOLDING(keys)

-/// #define HOLDING(%0) ((newkeys & (%0)) == (%0))

-///

-/// // PRESSED(keys)

-/// #define PRESSED(%0) (((newkeys & (%0)) == (%0)) && ((oldkeys & (%0)) != (%0)))

-///

-/// // PRESSING(keyVariable, keys)

-/// #define PRESSING(%0,%1) (%0 & (%1))

-///

-/// // RELEASED(keys)

-/// #define RELEASED(%0) (((newkeys & (%0)) != (%0)) && ((oldkeys & (%0)) == (%0)))

-/// -/// -/// -/// This callback does not handle returns.

-/// It is always called first in gamemode. -/// -forward OnPlayerKeyStateChange(playerid, newkeys, oldkeys); - -///

This callback is called when someone attempts to log in to RCON in-game; successful or not. -/// The IP of the player that tried to log in to RCON -/// The password used to login with -/// 0 if the password was incorrect or 1 if it was correct -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This callback is only called when /rcon login is used in-game. -/// This callback is only called when the player is not yet logged in. When the player is logged in, OnRconCommand is called instead. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnRconLoginAttempt( ip[], password[], success ); - -///

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. -/// ID of the player sending an update packet -/// This callback can also be called by NPC. -/// 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). -/// 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. -/// -/// 0 - Update from this player will not be replicated to other clients.

-/// 1 - Indicates that this update can be processed normally and sent to other players.

-/// It is always called first in filterscripts. -/// +/** + *

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). + * The ID of the player that pressed or released a key + * A map (bitmask) of the keys currently held - see here + * A map (bitmask) of the keys held prior to the current change - see + * here + * + * This callback can also be called by NPC. + * + * Useful macros:
+ * + * // HOLDING(keys)
+ * #define HOLDING(%0) ((newkeys & (%0)) == (%0))
+ *
+ * // PRESSED(keys)
+ * #define PRESSED(%0) (((newkeys & (%0)) == (%0)) && ((oldkeys & (%0)) != (%0)))
+ *
+ * // PRESSING(keyVariable, keys)
+ * #define PRESSING(%0,%1) (%0 & (%1))
+ *
+ * // RELEASED(keys)
+ * #define RELEASED(%0) (((newkeys & (%0)) != (%0)) && ((oldkeys & (%0)) == (%0)))
+ * + * + * + * This callback does not handle returns.
+ * It is always called first in gamemode. + * + */ +#if !defined KEY + #define KEY: _: +#endif +forward OnPlayerKeyStateChange(playerid, KEY:newkeys, KEY:oldkeys); + +/** + * This callback is called when someone attempts to log in to RCON in-game; successful or not. + * The IP of the player that tried to log in to RCON + * The password used to login with + * 0 if the password was incorrect or 1 if it was + * correct + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This callback is only called when /rcon login is used in-game. + * This callback is only called when the player is not yet logged in. When the player is logged + * in, OnRconCommand is called instead. + * + * This callback does not handle returns.
+ * It is always called first in filterscripts. + * + */ +forward OnRconLoginAttempt(ip[], password[], success); + +/** + * 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. + * ID of the player sending an update packet + * This callback can also be called by NPC. + * 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). + * 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. + * + * 0 - Update from this player will not be replicated to other clients.
+ * 1 - Indicates that this update can be processed normally and sent to other players.
+ * It is always called first in filterscripts. + * + */ forward OnPlayerUpdate(playerid); -/// This callback is called when a player is streamed by some other player's client. -/// The ID of the player who has been streamed -/// The ID of the player that streamed the other player in -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerStreamIn(playerid, forplayerid); - -///

This callback is called when a player is streamed out from some other player's client. -/// The player who has been destreamed -/// The player who has destreamed the other player -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnPlayerStreamOut(playerid, forplayerid); - -///

Called when a vehicle is streamed to a player's client. -/// The ID of the vehicle that streamed in for the player -/// The ID of the player who the vehicle streamed in for -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnVehicleStreamIn(vehicleid, forplayerid); - -///

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). -/// The ID of the vehicle that streamed out -/// The ID of the player who is no longer streaming the vehicle -/// -/// -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// This callback can also be called by NPC. -/// -/// This callback does not handle returns.

-/// It is always called first in filterscripts. -/// -forward OnVehicleStreamOut(vehicleid, forplayerid); - -///

This callback is called when an actor is streamed in by a player's client. -/// The ID of the actor that has been streamed in for the player -/// The ID of the player that streamed the actor in -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This callback can also be called by NPC. -/// It is always called first in filterscripts. -/// This callback does not handle returns. -forward OnActorStreamIn(actorid, forplayerid); - -/// This callback is called when an actor is streamed out by a player's client. -/// The ID of the actor that has been streamed out for the player -/// The ID of the player that streamed the actor out -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This callback can also be called by NPC. -/// It is always called first in filterscripts. -/// This callback does not handle returns. -forward OnActorStreamOut(actorid, forplayerid); - -/// This callback is called when a player responds to a dialog shown using ShowPlayerDialog by either clicking a button, pressing ENTER/ESC or double-clicking a list item (if using a list style dialog). -/// The ID of the player that responded to the dialog -/// The ID of the dialog the player responded to, assigned in ShowPlayerDialog -/// 1 for left button and 0 for right button (if only one button shown, always 1) -/// The ID of the list item selected by the player (starts at 0) (only if using a list style dialog) -/// The text entered into the input box by the player or the selected list item text -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// A player's dialog doesn't hide when the gamemode restarts, causing the server to print "Warning: PlayerDialogResponse PlayerId: 0 dialog ID doesn't match last sent dialog ID" if a player responded to this dialog after restart. -/// Parameters can contain different values, based on dialog's style. -/// -/// Returning 0 in this callback will pass the dialog to another script in case no matching code were found in your gamemode's callback.

-/// It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it. -/// +/** + *

This callback is called when a player responds to a dialog shown using ShowPlayerDialog + * by either clicking a button, pressing ENTER/ESC or double-clicking a list item (if using a list style + * dialog). + * The ID of the player that responded to the dialog + * The ID of the dialog the player responded to, assigned in ShowPlayerDialog + * 1 for left button and 0 for right button (if only + * one button shown, always 1) + * The ID of the list item selected by the player (starts at 0) + * (only if using a list style dialog) + * The text entered into the input box by the player or the selected list item + * text + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * A player's dialog doesn't hide when the gamemode restarts, causing the server to print "Warning: + * PlayerDialogResponse PlayerId: 0 dialog ID doesn't match last sent dialog ID" if a player responded + * to this dialog after restart. + * Parameters can contain different values, based on dialog's style. + * + * + * Returning 0 in this callback will pass the dialog to another script in case no matching + * code were found in your gamemode's callback.
+ * It is always called first in filterscripts so returning 1 there blocks other filterscripts + * from seeing it. + * + */ forward OnDialogResponse(playerid, dialogid, response, listitem, inputtext[]); -/// This callback is called when a player takes damage. -/// The ID of the player that took damage -/// The ID of the player that caused the damage. INVALID_PLAYER_ID if self-inflicted -/// The amount of damage the player took (health and armour combined) -/// The ID of the weapon/reason for the damage -/// The body part that was hit. (NOTE: This parameter was added in 0.3z. Leave it out if using an older version!) -/// -/// -/// This callback was added in SA-MP 0.3d and will not work in earlier versions! -/// GetPlayerHealth and GetPlayerArmour will return the old amounts of the player before this callback. -/// -/// The weaponid will return 37 (flame thrower) from any fire sources (e.g. molotov, 18).

-/// The weaponid will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)

-/// playerid is the only one who can call the callback.

-/// 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 100.0 health and gets shot with a Desert Eagle which has a damage value of 46.2, it takes 3 shots to kill that player. All 3 shots will show an amount of 46.2, even though when the last shot hits, the player only has 7.6 health left. -/// -/// -/// 1 - Callback will not be called in other filterscripts.

-/// 0 - Allows this callback to be called in other filterscripts.

-/// It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it. -/// -forward OnPlayerTakeDamage(playerid, issuerid, Float:amount, weaponid, bodypart); - -///

This callback is called when a player gives damage to another player. -/// The ID of the player that gave damage -/// The ID of the player that received damage -/// The amount of health/armour damagedid has lost (combined) -/// The reason that caused the damage -/// The body part that was hit. (NOTE: This parameter was added in 0.3z. Leave it out if using an older version!) -/// -/// This callback was added in SA-MP 0.3d and will not work in earlier versions! -/// -/// Keep in mind this function can be inaccurate in some cases.

-/// If you want to prevent certain players from damaging eachother, use SetPlayerTeam.

-/// The weaponid will return 37 (flame thrower) from any fire sources (e.g. molotov, 18)

-/// The weaponid will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)

-/// playerid is the only one who can call the callback.

-/// 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 100.0 health and gets shot with a Desert Eagle which has a damage value of 46.2, it takes 3 shots to kill that player. All 3 shots will show an amount of 46.2, even though when the last shot hits, the player only has 7.6 health left. -/// -/// -/// 1 - Callback will not be called in other filterscripts.

-/// 0 - Allows this callback to be called in other filterscripts.

-/// It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it. -/// -forward OnPlayerGiveDamage(playerid, damagedid, Float:amount, weaponid, bodypart); - -///

This callback is called when a player gives damage to an actor. -/// The ID of the player that gave damage -/// The ID of the actor that received damage -/// The amount of health/armour damaged_actorid has lost -/// The reason that caused the damage -/// The body part that was hit -/// -/// -/// -/// -/// -/// -/// -/// -/// This callback was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This function does not get called if the actor is set invulnerable (WHICH IS BY DEFAULT). See SetActorInvulnerable. -/// -/// 1 - Callback will not be called in other filterscripts.

-/// 0 - Allows this callback to be called in other filterscripts.

-/// It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it. -/// -forward OnPlayerGiveDamageActor(playerid, damaged_actorid, Float:amount, weaponid, bodypart); - -///

OnPlayerClickMap is called when a player places a target/waypoint on the pause menu map (by right-clicking). -/// The ID of the player that placed a target/waypoint -/// The X float coordinate where the player clicked -/// The Y float coordinate where the player clicked -/// The Z float coordinate where the player clicked (inaccurate - see note below) -/// -/// -/// -/// This callback was added in SA-MP 0.3d and will not work in earlier versions! -/// The Z value returned will be 0 (invalid) if it is far away from the player; use the MapAndreas plugin to get a more accurate Z coordinate. -/// -/// 1 - Will prevent other filterscripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in gamemode. -/// +/** + *

OnPlayerClickMap is called when a player places a target/waypoint on the pause menu map + * (by right-clicking). + * The ID of the player that placed a target/waypoint + * The X float coordinate where the player clicked + * The Y float coordinate where the player clicked + * The Z float coordinate where the player clicked (inaccurate - see note below) + * + * + * + * This callback was added in SA-MP 0.3d and will not work in earlier versions! + * The Z value returned will be 0 (invalid) if it is far away from the player; + * use the MapAndreas plugin to get a more + * accurate Z coordinate. + * + * 1 - Will prevent other filterscripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in gamemode. + * + */ forward OnPlayerClickMap(playerid, Float:fX, Float:fY, Float:fZ); -/// This callback is called when a player clicks on a textdraw or cancels the select mode with the Escape key. -/// The ID of the player that clicked on the textdraw -/// The ID of the clicked textdraw. INVALID_TEXT_DRAW if selection was cancelled -/// -/// -/// This callback was added in SA-MP 0.3e and will not work in earlier versions! -/// The clickable area is defined by TextDrawTextSize. The x and y parameters passed to that function must not be zero or negative. -/// Do not use CancelSelectTextDraw unconditionally within this callback. This results in an infinite loop. -/// -/// Returning 1 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 0 if the textdraw on which they clicked wasn't found, just like in OnPlayerCommandText.

-/// It is always called first in filterscripts so returning 1 there also blocks other scripts from seeing it. -/// +/** + *

This callback is called when a player clicks on a textdraw or cancels the select mode with + * the Escape key. + * The ID of the player that clicked on the textdraw + * The ID of the clicked textdraw. INVALID_TEXT_DRAW if selection + * was cancelled + * + * + * This callback was added in SA-MP 0.3e and will not work in earlier versions! + * The clickable area is defined by TextDrawTextSize. The + * x and y parameters passed to that function must not be zero or negative. + * Do not use CancelSelectTextDraw unconditionally within + * this callback. This results in an infinite loop. + * + * Returning 1 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 0 if the textdraw on which they clicked wasn't found, + * just like in OnPlayerCommandText.
+ * It is always called first in filterscripts so returning 1 there also blocks other + * scripts from seeing it. + * + */ forward OnPlayerClickTextDraw(playerid, Text:clickedid); -/// This callback is called when a player clicks on a player-textdraw. It is not called when player cancels the select mode (ESC) - however, OnPlayerClickTextDraw is. -/// The ID of the player that selected a textdraw -/// The ID of the player-textdraw that the player selected -/// -/// -/// -/// This callback was added in SA-MP 0.3e and will not work in earlier versions! -/// When a player presses ESC to cancel selecting a textdraw, OnPlayerClickTextDraw is called with a textdraw ID of INVALID_TEXT_DRAW. OnPlayerClickPlayerTextDraw won't be called also. -/// -/// Returning 1 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 0 if the textdraw on which they clicked wasn't found, just like in OnPlayerCommandText.

-/// It is always called first in filterscripts so returning 1 there also blocks other scripts from seeing it. -/// -forward OnPlayerClickPlayerTextDraw(playerid, PlayerText:playertextid); - -///

This callback is called when an IP address attempts a connection to the server. To block incoming connections, use BlockIpAddress. -/// The ID of the player attempting to connect -/// The IP address of the player attempting to connect -/// The port of the attempted connection -/// -/// -/// -/// -/// -/// This callback was added in SA-MP 0.3z R2-2 and will not work in earlier versions! -/// -/// 1 - Will prevent other filterscripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// +/** + *

This callback is called when an IP address attempts a connection to the server. To block + * incoming connections, use BlockIpAddress. + * The ID of the player attempting to connect + * The IP address of the player attempting to connect + * The port of the attempted connection + * + * + * + * + * + * This callback was added in SA-MP 0.3z R2-2 and will not work in earlier versions! + * + * 1 - Will prevent other filterscripts from receiving this callback.
+ * 0 - Indicates that this callback will be passed to the next filterscript.
+ * It is always called first in filterscripts. + * + */ forward OnIncomingConnection(playerid, ip_address[], port); -/// This callback is called when a player sent a trailer update. -/// The ID of the player who sent a trailer update -/// The Trailer being updated -/// -/// -/// -/// -/// -/// This callback was added in SA-MP 0.3z R4 and will not work in earlier versions! -/// 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. -/// -/// 0 - Cancels any trailer updates from being sent to other players. Update is still sent to the updating player.

-/// 1 - Processes the trailer update as normal and synchronizes it between all players.

-/// It is always called first in filterscripts. -/// -forward OnTrailerUpdate(playerid, vehicleid); - -///

This callback is called when a vehicle's siren is toggled. -/// The ID of the player that toggled the siren (driver) -/// The ID of the vehicle of which the siren was toggled for -/// 0 if siren was turned off, 1 if siren was turned on -/// -/// This callback was added in SA-MP 0.3.7 and will not work in earlier versions! -/// This callback can also be called by NPC. -/// 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). -/// -/// 1 - Will prevent gamemode from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the gamemode.

-/// It is always called first in filterscripts. -/// -forward OnVehicleSirenStateChange(playerid, vehicleid, newstate); - -///

This callback is called when a player finishes downloading custom models. For more information on how to add custom models to your server, see the release thread and this tutorial. -/// The ID of the player that finished downloading custom models -/// The ID of the virtual world the player finished downloading custom models for -/// -/// -/// -/// This callback was added in SA-MP 0.3DL and will not work in earlier versions! -/// This callback is called every time a player changes virtual worlds, even if there are no custom models present in that world. -/// This callback does not handle returns. +/** + * This callback is called when a player finishes downloading custom models. For more information + * on how to add custom models to your server, see the + * release thread and this tutorial. + * The ID of the player that finished downloading custom models + * The ID of the virtual world the player finished downloading custom models + * for + * + * + * + * This callback was added in SA-MP 0.3DL and will not work in earlier versions! + * This callback is called every time a player changes virtual worlds, even if there are no + * custom models present in that world. + * This callback does not handle returns. + */ forward OnPlayerFinishedDownloading(playerid, virtualworld); -forward OnPlayerRequestDownload(playerid, type, crc); - -/// Called when a player double-clicks on a player on the scoreboard. -/// The ID of the player that clicked on a player on the scoreboard -/// The ID of the player that was clicked on -/// The source of the player's click -/// -/// This callback was added in SA-MP 0.3a and will not work in earlier versions! -/// There is currently only one (0 - CLICK_SOURCE_SCOREBOARD). The existence of this argument suggests that more sources may be supported in the future. -/// -/// 1 - Will prevent other filterscripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next filterscript.

-/// It is always called first in filterscripts. -/// -forward OnPlayerClickPlayer(playerid, clickedplayerid, source); - -///

This callback is called when a player finishes editing an object (EditObject/EditPlayerObject). -/// The ID of the player that edited an object -/// 0 if it is a global object or 1 if it is a playerobject -/// The ID of the edited object -/// The type of response -/// The X offset for the object that was edited -/// The Y offset for the object that was edited -/// The Z offset for the object that was edited -/// The X rotation for the object that was edited -/// The Y rotation for the object that was edited -/// The Z rotation for the object that was edited -/// -/// -/// -/// -/// This callback was added in SA-MP 0.3e and will not work in earlier versions! -/// When using EDIT_RESPONSE_UPDATE be aware that this callback will not be called when releasing an edit in progress resulting in the last update of EDIT_RESPONSE_UPDATE being out of sync of the objects current position. -/// -/// 1 - Will prevent other scripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next script.

-/// It is always called first in filterscripts. -/// -forward OnPlayerEditObject( playerid, playerobject, objectid, response, -Float:fX, Float:fY, Float:fZ, Float:fRotX, Float:fRotY, Float:fRotZ ); - - -///

This callback is called when a player ends attached object edition mode. -/// The ID of the player that ended edition mode -/// 0 if they cancelled (ESC) or 1 if they clicked the save icon -/// The index of the attached object -/// The model of the attached object that was edited -/// The bone of the attached object that was edited -/// The X offset for the attached object that was edited -/// The Y offset for the attached object that was edited -/// The Z offset for the attached object that was edited -/// The X rotation for the attached object that was edited -/// The Y rotation for the attached object that was edited -/// The Z rotation for the attached object that was edited -/// The X scale for the attached object that was edited -/// The Y scale for the attached object that was edited -/// The Z scale for the attached object that was edited -/// -/// -/// This callback was added in SA-MP 0.3e and will not work in earlier versions! -/// Editions should be discarded if response was 0 (cancelled). This must be done by storing the offsets etc. in an array BEFORE using EditAttachedObject. -/// -/// 1 - Will prevent other scripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next script.

-/// It is always called first in filterscripts. -/// -forward OnPlayerEditAttachedObject( playerid, response, index, modelid, boneid, -Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ, -Float:fRotX, Float:fRotY, Float:fRotZ, -Float:fScaleX, Float:fScaleY, Float:fScaleZ ); - -///

This callback is called when a player selects an object after SelectObject has been used. -/// The ID of the player that selected an object -/// The type of selection -/// The ID of the selected object -/// The model ID of the selected object -/// The X position of the selected object -/// The Y position of the selected object -/// The Z position of the selected object -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// -/// 1 - Will prevent other scripts from receiving this callback.

-/// 0 - Indicates that this callback will be passed to the next script.

-/// It is always called first in filterscripts. -/// -forward OnPlayerSelectObject(playerid, type, objectid, modelid, Float:fX, Float:fY, Float:fZ); - -///

This callback is called when a player fires a shot from a weapon. Only bullet weapons are supported. Only passenger drive-by is supported (not driver drive-by, and not sea sparrow / hunter shots). -/// The ID of the player that shot a weapon -/// The ID of the weapon shot by the player -/// The type of thing the shot hit (none, player, vehicle, or (player)object) -/// The ID of the player, vehicle or object that was hit -/// The X coordinate that the shot hit -/// The Y coordinate that the shot hit -/// The Z coordinate that the shot hit -/// -/// -/// This callback was added in SA-MP 0.3z and will not work in earlier versions! -/// -///
  • BULLET_HIT_TYPE_NONE(0)
    • -///
  • BULLET_HIT_TYPE_PLAYER(1)
    • -///
  • BULLET_HIT_TYPE_VEHICLE(2)
    • -///
  • BULLET_HIT_TYPE_OBJECT(3)
    • -///
  • BULLET_HIT_TYPE_PLAYER_OBJECT(4)
    • -///     -/// BULLET_HIT_TYPE_PLAYER is also called for NPCs. Actors are ignored by this callback and detects as BULLET_HIT_TYPE_NONE. -/// This callback is only called when lag compensation is enabled. -/// -/// If hittype is:

    -///

      -///
    • - BULLET_HIT_TYPE_NONE: 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);
      • -///
    • - Others: the fX, fY and fZ are offsets relative to the hitid.
      • -///
    -///     -/// -/// Isn't called if you fired in vehicle as driver or if you are looking behind with the aim enabled (shooting in air).

    -/// It is called as BULLET_HIT_TYPE_VEHICLE 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 BULLET_HIT_TYPE_PLAYER at all.

    -/// Partially fixed in SA-MP 0.3.7: 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. -/// -/// -/// -/// GetPlayerLastShotVectors can be used in this callback for more detailed bullet vector information. -/// -/// 0 - Prevent the bullet from causing damage.

    -/// 1 - Allow the bullet to cause damage.

    -/// It is always called first in filterscripts so returning 0 there also blocks other scripts from seeing it. -/// -forward OnPlayerWeaponShot(playerid, weaponid, hittype, hitid, Float:fX, Float:fY, Float:fZ); - -///

    This callback is called when a SendClientCheck request comletes -/// The ID of the player checked -/// The type of check performed -/// The address requested -/// The result of the check -/// + +/** + */ +#if !defined DOWNLOAD_REQUEST + #define DOWNLOAD_REQUEST: _: +#endif +forward OnPlayerRequestDownload(playerid, DOWNLOAD_REQUEST:type, crc); + +/** + * This callback is called when a player fires a shot from a weapon. Only bullet weapons are + * supported. Only passenger drive-by is supported (not driver drive-by, and not sea sparrow + * / hunter shots). + * The ID of the player that shot a weapon + * The ID of the weapon shot + * by the player + * The type of thing the shot hit (none, player, vehicle, or (player)object) + * The ID of the player, vehicle or object that was hit + * The X coordinate that the shot hit + * The Y coordinate that the shot hit + * The Z coordinate that the shot hit + * + * + * This callback was added in SA-MP 0.3z and will not work in earlier versions! + * + *
  • BULLET_HIT_TYPE_NONE(0)
    • + *
  • BULLET_HIT_TYPE_PLAYER(1)
    • + *
  • BULLET_HIT_TYPE_VEHICLE(2)
    • + *
  • BULLET_HIT_TYPE_OBJECT(3)
    • + *
  • BULLET_HIT_TYPE_PLAYER_OBJECT(4)
    • + *     + * BULLET_HIT_TYPE_PLAYER is also called for NPCs. Actors are ignored by this + * callback and detects as BULLET_HIT_TYPE_NONE. + * This callback is only called when lag compensation is enabled. + * + * If hittype is:
    + *
      + *
    • - BULLET_HIT_TYPE_NONE: 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);
      • + *
    • - Others: the fX, fY and fZ are offsets relative to the hitid.
      • + *
    + *     + * + * Isn't called if you fired in vehicle as driver or if you are looking behind with the aim enabled + * (shooting in air).
    + * It is called as BULLET_HIT_TYPE_VEHICLE 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 BULLET_HIT_TYPE_PLAYER + * at all.
    + * Partially fixed in SA-MP 0.3.7: 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. + *     + * + * + * GetPlayerLastShotVectors can be used in this callback + * for more detailed bullet vector information. + * + * 0 - Prevent the bullet from causing damage.
    + * 1 - Allow the bullet to cause damage.
    + * It is always called first in filterscripts so returning 0 there also blocks other + * scripts from seeing it. + *     + */ +#if !defined BULLET_HIT_TYPE + #define BULLET_HIT_TYPE: _: +#endif +forward OnPlayerWeaponShot(playerid, weaponid, BULLET_HIT_TYPE:hittype, hitid, Float:fX, Float:fY, Float:fZ); + +/** + * This callback is called when a SendClientCheck request comletes + * The ID of the player checked + * The type of check performed + * The address requested + * The result of the check + * + */ forward OnClientCheckResponse(playerid, actionid, memaddr, retndata); -/// This callback is called when a SendClientCheck request comletes -/// The ID of the player who got cash from the game -/// The amount of cash given -/// Where the money came from -/// Doesn't work +/** + * This callback is called when a SendClientCheck request comletes + * The ID of the player who got cash from the game + * The amount of cash given + * Where the money came from + * Doesn't work + */ forward OnScriptCash(playerid, amount, source); -// -------------------------------------------------- - diff --git a/a_sampdb.inc b/a_sampdb.inc old mode 100755 new mode 100644 index d341f3a..39515b7 --- a/a_sampdb.inc +++ b/a_sampdb.inc @@ -1,135 +1,337 @@ -// SA-MP Native SQLite Database Functions -// -// (c) Copyright 2015, SA-MP Team -// - #if defined _INC_a_sampdb #endinput #endif #define _INC_a_sampdb #define _sampdb_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2015, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ + +///

    #pragma tabsize 4 +#define SAMP_CONST_CORRECT + +// -------------------------------------------------- +// Defines +// -------------------------------------------------- + +// Limits + +// Invalids + +// Checks + +/** + * a_sampdb + *

    This function is used to open a connection to a SQLite database, which is inside the /scriptfiles + * folder. + * File name of the database + * Return type for this function has changed since version 0.3.7 R2. + * + * It will create a new SQLite database, if there is no SQLite database with the same file name available.
    + * Close your database connection with db_close! + *     + * Returns index (starting at 1) of the database connection . + */ +native DB:DB_Open(const name[]) = db_open; -/// This function is used to open a connection to a SQLite database, which is inside the /scriptfiles folder. -/// File name of the database -/// Return type for this function has changed since version 0.3.7 R2. -/// -/// It will create a new SQLite database, if there is no SQLite database with the same file name available.

    -/// Close your database connection with db_close! -/// -/// Returns index (starting at 1) of the database connection . +/** + * a_sampdb + */ +#pragma deprecated Use `DB_Open`. native DB:db_open(const name[]); -///

    Closes an SQLite database that was opened with db_open. -/// The handle of the database connection to close (returned by db_open) -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. May mean that the database handle specified is not open. -/// -native db_close(DB:db); - -///

    This function is used to execute an SQL query on an opened SQLite database. -/// The database handle to query -/// The query to execute -/// Return type for this function has changed since version 0.3.7 R2. -/// Always free the result by using db_free_result! -/// The query result index (starting at 1). +/** + * a_sampdb + * Closes an SQLite database that was opened with db_open. + * The handle of the database connection to close (returned by db_open) + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. May mean that the database handle specified is + * not open. + *     + */ +native bool:DB_Close(DB:db) = db_close; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_Close`. +native bool:db_close(DB:db); + +/** + * a_sampdb + * This function is used to execute an SQL query on an opened SQLite database. + * The database handle to query + * The query to execute + * Return type for this function has changed since version 0.3.7 R2. + * Always free the result by using db_free_result! + * The query result index (starting at 1). + */ +native DBResult:DB_Query(DB:db, const query[]) = db_query; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_Query`. native DBResult:db_query(DB:db, const query[]); -/// Frees result memory allocated from db_query. -/// The result to free -/// If DBResult:dbhandle is a valid handle, it returns 1, otherwise 0 if DBResult:dbhandle is a NULL reference. -native db_free_result(DBResult:dbresult); - -/// Returns the number of rows from a db_query. -/// The result of db_query -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// The number of rows in the result. -native db_num_rows(DBResult:dbresult); - -/// Moves to the next row of the result allocated from db_query. -/// The result of db_query -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Returns 1 on success, otherwise 0 if DBResult:dbresult is a NULL reference or the last row is reached. -native db_next_row(DBResult:dbresult); - -/// Get the number of fields in a result. -/// The result of db_query -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// The number of fields in the result. -native db_num_fields(DBResult:dbresult); - -/// Returns the name of a field at a particular index. -/// The result to get the data from; returned by db_query -/// The index of the field to get the name of -/// The result -/// The max length of the field -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Returns 1, if the function was successful, otherwise 0 if DBResult:dbresult is a NULL reference or the column index not available. -native db_field_name(DBResult:dbresult, field, result[], maxlength = sizeof result); - -/// Get the content of a field from db_query. -/// The result to get the data from -/// The field to get the data from -/// The result -/// The max length of the field -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Returns 1 if successful, otherwise 0 if DBResult:dbresult is a NULL reference or the column index not available. -native db_get_field(DBResult:dbresult, field, result[], maxlength = sizeof result); - -/// Get the content of a field as an integer from db_query. -/// The result to get the data from -/// The field to get the data from (optional=0) -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Retrieved value as integer (number). +/** + * a_sampdb + * Frees result memory allocated from db_query. + * The result to free + * If DBResult:dbhandle is a valid handle, it returns 1, otherwise + * 0 if DBResult:dbhandle is a NULL reference. + */ +native bool:DB_FreeResult(DBResult:result) = db_free_result; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_FreeResult`. +native bool:db_free_result(DBResult:result); + +/** + * a_sampdb + * Returns the number of rows from a db_query. + * The result of db_query + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * The number of rows in the result. + */ +native DB_NumRows(DBResult:result) = db_num_rows; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_NumRows`. +native db_num_rows(DBResult:result); + +/** + * a_sampdb + * Moves to the next row of the result allocated from db_query. + * The result of db_query + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Returns 1 on success, otherwise 0 if DBResult:result + * is a NULL reference or the last row is reached. + */ +native bool:DB_NextRow(DBResult:result) = db_next_row; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_NextRow`. +native bool:db_next_row(DBResult:result); + +/** + * a_sampdb + * Get the number of fields in a result. + * The result of db_query + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * The number of fields in the result. + */ +native DB_NumFields(DBResult:result) = db_num_fields; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_NumFields`. +native db_num_fields(DBResult:result); + +/** + * a_sampdb + * Returns the name of a field at a particular index. + * The result to get the data from; returned by db_query + * The index of the field to get the name of + * The returned value + * The max length of the field + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Returns 1, if the function was successful, otherwise 0 if DBResult:result + * is a NULL reference or the column index not available. + */ +native bool:DB_FieldName(DBResult:result, field, output[], size = sizeof (output)) = db_field_name; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_FieldName`. +native bool:db_field_name(DBResult:result, field, output[], size = sizeof (output)); + +/** + * a_sampdb + * Get the content of a field from db_query. + * The result to get the data from + * The field to get the data from + * The returned value + * The max length of the field + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Returns 1 if successful, otherwise 0 if DBResult:result + * is a NULL reference or the column index not available. + */ +native bool:DB_GetField(DBResult:result, field, output[], size = sizeof (output)) = db_get_field; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetField`. +native bool:db_get_field(DBResult:result, field, output[], size = sizeof (output)); + +/** + * a_sampdb + * Get the content of a field as an integer from db_query. + * The result to get the data from + * The field to get the data from (optional=0) + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Retrieved value as integer (number). + */ +native DB_GetFieldInt(DBResult:result, field = 0) = db_get_field_int; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetFieldInt`. native db_get_field_int(DBResult:result, field = 0); -/// Get the content of a field as a float from db_query. -/// The result to get the data from -/// The field to get the data from (optional=0) -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Retrieved value as floating point number. +/** + * a_sampdb + * Get the content of a field as a float from db_query. + * The result to get the data from + * The field to get the data from (optional=0) + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Retrieved value as floating point number. + */ +native Float:DB_GetFieldFloat(DBResult:result, field = 0) = db_get_field_float; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetFieldFloat`. native Float:db_get_field_float(DBResult:result, field = 0); -/// Get the contents of field with specified name. -/// The result to get the data from -/// The fieldname to get the data from -/// The result -/// The max length of the field -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Returns 1 if successful, otherwise 0 if DBResult:dbresult is a NULL reference or the column index not available. -native db_get_field_assoc(DBResult:dbresult, const field[], result[], maxlength = sizeof result); - -/// Get the contents of field as an integer with specified name. -/// The result to get the data from -/// The fieldname to get the data from -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Retrieved value as integer (number). +/** + * a_sampdb + * Get the contents of field with specified name. + * The result to get the data from + * The fieldname to get the data from + * The returned value + * The max length of the field + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Returns 1 if successful, otherwise 0 if DBResult:result + * is a NULL reference or the column index not available. + */ +native bool:DB_GetFieldAssoc(DBResult:result, const field[], output[], size = sizeof (output)) = db_get_field_assoc; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetFieldAssoc`. +native bool:db_get_field_assoc(DBResult:result, const field[], output[], size = sizeof (output)); + +/** + * a_sampdb + * Get the contents of field as an integer with specified name. + * The result to get the data from + * The fieldname to get the data from + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Retrieved value as integer (number). + */ +native DB_GetFieldAssocInt(DBResult:result, const field[]) = db_get_field_assoc_int; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetFieldAssocInt`. native db_get_field_assoc_int(DBResult:result, const field[]); -/// Get the contents of field as a float with specified name. -/// The result to get the data from -/// The fieldname to get the data from -/// Using an invalid handle will crash your server! Get a valid handle by using db_open. But it's protected against NULL references -/// Retrieved value as floating point number. +/** + * a_sampdb + * Get the contents of field as a float with specified name. + * The result to get the data from + * The fieldname to get the data from + * Using an invalid handle will crash your server! Get a valid handle by using + * db_open. But it's protected against NULL references + * Retrieved value as floating point number. + */ +native Float:DB_GetFieldAssocFloat(DBResult:result, const field[]) = db_get_field_assoc_float; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetFieldAssocFloat`. native Float:db_get_field_assoc_float(DBResult:result, const field[]); -/// Get memory handle for an SQLite database that was opened with db_open. -/// The index of the database connection (returned by db_open) -/// This function was added in SA-MP 0.3.7 R1 and will not work in earlier versions! -/// Returns the memory handle for a specified database. +/** + * a_sampdb + * Get memory handle for an SQLite database that was opened with db_open. + * The index of the database connection (returned by db_open) + * This function was added in SA-MP 0.3.7 R1 and will not work in earlier versions! + * Returns the memory handle for a specified database. + */ +native DB_GetMemHandle(DB:db) = db_get_mem_handle; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetMemHandle`. native db_get_mem_handle(DB:db); -/// Get memory handle for an SQLite query that was executed with db_query. -/// The index of the query (returned by db_query) -/// This function was added in SA-MP 0.3.7 R1 and will not work in earlier versions! -/// Returns the memory handle for a specified query. +/** + * a_sampdb + * Get memory handle for an SQLite query that was executed with db_query. + * The index of the query (returned by db_query) + * This function was added in SA-MP 0.3.7 R1 and will not work in earlier versions! + * Returns the memory handle for a specified query. + */ +native DB_GetResultMemHandle(DBResult:result) = db_get_result_mem_handle; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_GetResultMemHandle`. native db_get_result_mem_handle(DBResult:result); +/** + * a_sampdb + */ +native DB_DebugOpenFiles() = db_debug_openfiles; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_DebugOpenFiles`. native db_debug_openfiles(); + +/** + * a_sampdb + */ +native DB_DebugOpenResults() = db_debug_openresults; + +/** + * a_sampdb + */ +#pragma deprecated Use `DB_DebugOpenResults`. native db_debug_openresults(); diff --git a/a_vehicles.inc b/a_vehicles.inc old mode 100755 new mode 100644 index 2903c6a..66c01f3 --- a/a_vehicles.inc +++ b/a_vehicles.inc @@ -1,747 +1,1309 @@ -/* SA-MP Vehicle Functions - * - * (c) Copyright 2005-2012, SA-MP Team - * - */ - #if defined _INC_a_vehicles #endinput #endif #define _INC_a_vehicles #define _vehicles_included -#define SAMP_CONST_CORRECT +/** + * + * + * (c) Copyright 2005-2012, SA-MP Team + * + * + * This library uses the enhanced pawndoc.xsl from + * pawn-lang/pawndoc. + * This XSL has features such as library and markdown support, and will not + * render this message when used. + * + * + */ + +///

    #pragma tabsize 4 +#define SAMP_CONST_CORRECT // -------------------------------------------------- // Defines // -------------------------------------------------- -#define CARMODTYPE_SPOILER (0) -#define CARMODTYPE_HOOD (1) -#define CARMODTYPE_ROOF (2) -#define CARMODTYPE_SIDESKIRT (3) -#define CARMODTYPE_LAMPS (4) -#define CARMODTYPE_NITRO (5) -#define CARMODTYPE_EXHAUST (6) -#define CARMODTYPE_WHEELS (7) -#define CARMODTYPE_STEREO (8) -#define CARMODTYPE_HYDRAULICS (9) -#define CARMODTYPE_FRONT_BUMPER (10) -#define CARMODTYPE_REAR_BUMPER (11) -#define CARMODTYPE_VENT_RIGHT (12) -#define CARMODTYPE_VENT_LEFT (13) - -#define VEHICLE_PARAMS_UNSET (-1) -#define VEHICLE_PARAMS_OFF (0) -#define VEHICLE_PARAMS_ON (1) - -#define VEHICLE_MODEL_INFO_SIZE (1) -#define VEHICLE_MODEL_INFO_FRONTSEAT (2) -#define VEHICLE_MODEL_INFO_REARSEAT (3) -#define VEHICLE_MODEL_INFO_PETROLCAP (4) -#define VEHICLE_MODEL_INFO_WHEELSFRONT (5) -#define VEHICLE_MODEL_INFO_WHEELSREAR (6) -#define VEHICLE_MODEL_INFO_WHEELSMID (7) -#define VEHICLE_MODEL_INFO_FRONT_BUMPER_Z (8) -#define VEHICLE_MODEL_INFO_REAR_BUMPER_Z (9) +// Limits +/** + * a_vehicles + */ +#if defined MAX_VEHICLES + const __MAX_VEHICLES = MAX_VEHICLES; + #define __MAX_VEHICLES +#else + const MAX_VEHICLES = 2000; + #define MAX_VEHICLES 2000 +#endif + +// Invalids +/** + * a_vehicles + */ +const INVALID_VEHICLE_ID = 0xFFFF; +#define INVALID_VEHICLE_ID 0xFFFF + +// Checks +#if MAX_VEHICLES < 1 || MAX_VEHICLES > 2000 + #error MAX_VEHICLES must be >= 1 and <= 2000 +#endif + +// Enums +/// + +/** + * a_vehicles + */ +#define CARMODTYPE: __TAG(CARMODTYPE): +enum CARMODTYPE:__CARMODTYPE +{ + CARMODTYPE_NONE = -1, + CARMODTYPE_SPOILER, + CARMODTYPE_HOOD, + CARMODTYPE_ROOF, + CARMODTYPE_SIDESKIRT, + CARMODTYPE_LAMPS, + CARMODTYPE_NITRO, + CARMODTYPE_EXHAUST, + CARMODTYPE_WHEELS, + CARMODTYPE_STEREO, + CARMODTYPE_HYDRAULICS, + CARMODTYPE_FRONT_BUMPER, + CARMODTYPE_REAR_BUMPER, + CARMODTYPE_VENT_RIGHT, + CARMODTYPE_VENT_LEFT, + CARMODTYPE_FRONT_BULLBAR, + CARMODTYPE_REAR_BULLBAR +} +static stock CARMODTYPE:_@CARMODTYPE() { return __CARMODTYPE; } + +/// + +/** + * a_vehicles + */ +#define VEHICLE_PARAMS: __TAG(VEHICLE_PARAMS): +enum VEHICLE_PARAMS:__VEHICLE_PARAMS +{ + VEHICLE_PARAMS_UNSET = -1, + VEHICLE_PARAMS_OFF, + VEHICLE_PARAMS_ON +} +static stock VEHICLE_PARAMS:_@VEHICLE_PARAMS() { return __VEHICLE_PARAMS; } + +/// + +/** + * a_vehicles + */ +#define VEHICLE_MODEL_INFO: __TAG(VEHICLE_MODEL_INFO): +enum VEHICLE_MODEL_INFO:__VEHICLE_MODEL_INFO +{ + VEHICLE_MODEL_INFO_SIZE = 1, + VEHICLE_MODEL_INFO_FRONTSEAT, + VEHICLE_MODEL_INFO_REARSEAT, + VEHICLE_MODEL_INFO_PETROLCAP, + VEHICLE_MODEL_INFO_WHEELSFRONT, + VEHICLE_MODEL_INFO_WHEELSREAR, + VEHICLE_MODEL_INFO_WHEELSMID, + VEHICLE_MODEL_INFO_FRONT_BUMPER, + VEHICLE_MODEL_INFO_REAR_BUMPER +} +static stock VEHICLE_MODEL_INFO:_@VEHICLE_MODEL_INFO() { return __VEHICLE_MODEL_INFO; } +#define VEHICLE_MODEL_INFO_FRONT_BUMPER_Z VEHICLE_MODEL_INFO_FRONT_BUMPER +#define VEHICLE_MODEL_INFO_REAR_BUMPER_Z VEHICLE_MODEL_INFO_REAR_BUMPER // Vehicle -///

    Creates a vehicle in the world. Can be used in place of AddStaticVehicleEx at any time in the script. -/// The model for the vehicle -/// The X coordinate for the vehicle -/// The Y coordinate for the vehicle -/// The Z coordinate for the vehicle -/// The facing angle for the vehicle -/// The primary color ID -/// The secondary color ID -/// The delay until the car is respawned without a driver in seconds. Using -1 will prevent the vehicle from respawning -/// Added in 0.3.7; will not work in earlier versions. Enables the vehicle to have a siren, providing the vehicle has a horn (optional=0) -/// -/// -/// -/// -/// -/// -/// Trains can only be added with AddStaticVehicle and AddStaticVehicleEx. -/// -/// The vehicle ID of the vehicle created (1 to MAX_VEHICLES).

    -/// INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle limit reached or invalid vehicle model ID passed). -/// -native CreateVehicle(vehicletype, Float:x, Float:y, Float:z, Float:rotation, color1, color2, respawn_delay, addsiren=0); - -///

    Destroy a vehicle. It will disappear instantly. -/// The ID of the vehicle to destroy -/// -/// -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle does not exist. -/// -native DestroyVehicle(vehicleid); - -///

    Checks if a vehicle is streamed in for a player. Only nearby vehicles are streamed in (visible) for a player. -/// The ID of the vehicle to check -/// The ID of the player to check -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// 0: Vehicle is not streamed in for the player, or the function failed to execute (player and/or vehicle do not exist).

    -/// 1: Vehicle is streamed in for the player. -/// -native IsVehicleStreamedIn(vehicleid, forplayerid); - -///

    Gets the position of a vehicle. -/// The ID of the vehicle to get the position of -/// A float variable in which to store the X coordinate, passed by reference -/// A float variable in which to store the Y coordinate, passed by reference -/// A float variable in which to store the Z coordinate, passed by reference -/// -/// -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle specified does not exist. -/// -native GetVehiclePos(vehicleid, &Float:x, &Float:y, &Float:z); - -///

    Set a vehicle's position. -/// Vehicle ID that you want set new position -/// The X coordinate to position the vehicle at -/// The Y coordinate to position the vehicle at -/// The Z coordinate to position the vehicle at -/// -/// -/// -/// An empty vehicle will not fall after being teleported into the air. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle specified does not exist. -/// -native SetVehiclePos(vehicleid, Float:x, Float:y, Float:z); - -///

    Get the rotation of a vehicle on the Z axis (yaw). -/// The ID of the vehicle to get the Z angle of -/// A float variable in which to store the Z rotation, passed by reference -/// -/// -/// -/// -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle does not exist. -/// -native GetVehicleZAngle(vehicleid, &Float:z_angle); - -///

    Returns a vehicle's rotation on all axes as a quaternion. -/// The ID of the vehicle to get the rotation of -/// A float variable in which to store the first quaternion angle, passed by reference -/// A float variable in which to store the second quaternion angle, passed by reference -/// A float variable in which to store the third quaternion angle, passed by reference -/// A float variable in which to store the fourth quaternion angle, passed by reference -/// -/// This function was added in SA-MP 0.3b and will not work in earlier versions! -/// -/// To euler:

    -/// -/// //GetVehicleRotation Created by IllidanS4

    -/// stock GetVehicleRotation(vehicleid,&Float:rx,&Float:ry,&Float:rz){

    -/// new Float:qw,Float:qx,Float:qy,Float:qz;

    -/// GetVehicleRotationQuat(vehicleid,qw,qx,qy,qz);

    -/// rx = asin(2*qy*qz-2*qx*qw);

    -/// ry = -atan2(qx*qz+qy*qw,0.5-qx*qx-qy*qy);

    -/// rz = -atan2(qx*qy+qz*qw,0.5-qx*qx-qz*qz);

    -/// } -/// -/// -/// There is no 'set' variation of this function; you can not SET a vehicle's rotation (apart from the Z angle) -/// This function may return incorrect values for unoccupied vehicles. The reason is that the third row of the vehicle's internal rotation matrix gets corrupted if it gets updated while unoccupied. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle specified does not exist. -/// -native GetVehicleRotationQuat(vehicleid, &Float:w, &Float:x, &Float:y, &Float:z); - -///

    This function can be used to calculate the distance (as a float) between a vehicle and another map coordinate. This can be useful to detect how far a vehicle away is from a location. -/// The ID of the vehicle to calculate the distance for -/// The X map coordinate -/// The Y map coordinate -/// The Z map coordinate -/// -/// -/// This function was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// A float containing the distance from the point specified in the coordinates. -native Float:GetVehicleDistanceFromPoint(vehicleid, Float:X, Float:Y, Float:Z); - -/// Set the Z rotation (yaw) of a vehicle. -/// The ID of the vehicle to set the rotation of -/// The Z angle to set -/// -/// -/// A vehicle's X and Y (pitch and roll) rotation will be reset when this function is used. The X and Y rotations can not be set. -/// This function does not work on unoccupied vehicles. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle specified does not exist. -/// -native SetVehicleZAngle(vehicleid, Float:z_angle); - -///

    Set the parameters of a vehicle for a player. -/// The ID of the vehicle to set the parameters of -/// The ID of the player to set the vehicle's parameters for -/// 0 to disable the objective or 1 to show it. This is a bobbing yellow arrow above the vehicle -/// 0 to unlock the doors or 1 to lock them -/// -/// Vehicles must be respawned for the 'objective' to be removed. This can be circumvented somewhat using Get/SetVehicleParamsEx which do not require the vehicle to be respawned. It is worth noting however that the object will be disabled on a global scale, and this is only useful if only one player has the vehicle as an objective. -/// Since 0.3a you will have to reapply this function when OnVehicleStreamIn is called. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The player and/or vehicle specified do not exist. -/// -native SetVehicleParamsForPlayer(vehicleid, playerid, objective, doorslocked); - -///

    Use this function before any player connects (OnGameModeInit) to tell all clients that the script will control vehicle engines and lights. This prevents the game automatically turning the engine on/off when players enter/exit vehicles and headlights automatically coming on when it is dark. -/// -/// -/// -/// This Function was added in SA-MP 0.3c and will not work in earlier versions! -/// Is it not possible to reverse this function after it has been used. You must either use it or not use it. -/// This function always returns 1. It cannot fail to execute. +/** + * a_vehicles + * Creates a vehicle in the world. Can be used in place of AddStaticVehicleEx + * at any time in the script. + * The model for the vehicle + * The x coordinate for the vehicle + * The y coordinate for the vehicle + * The z coordinate for the vehicle + * The facing angle for the vehicle + * The primary colour ID + * The secondary colour ID + * The delay until the car is respawned without a driver in seconds. + * Using -1 will prevent the vehicle from respawning + * Added in 0.3.7; will not work in earlier versions. Enables the vehicle + * to have a siren, providing the vehicle has a horn (optional=false) + * + * + * + * + * + * + * Trains can only be added with AddStaticVehicle and AddStaticVehicleEx. + * + * The vehicle ID of the vehicle created (1 to MAX_VEHICLES).
    + * INVALID_VEHICLE_ID (65535) if vehicle was not created (vehicle limit reached or invalid + * vehicle model ID passed). + *     + */ +native CreateVehicle(modelid, Float:x, Float:y, Float:z, Float:rotation, colour1, colour2, respawnDelay, bool:addSiren = false); + +/** + * a_vehicles + * Destroy a vehicle. It will disappear instantly. + * The ID of the vehicle to destroy + * + * + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle does not exist. + *     + */ +native bool:DestroyVehicle(vehicleid); + +/** + * a_vehicles + * Checks if a vehicle is streamed in for a player. Only nearby vehicles are streamed in (visible) + * for a player. + * The ID of the vehicle to check + * The ID of the player to check + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * 0: Vehicle is not streamed in for the player, or the function failed to execute (player + * and/or vehicle do not exist).
    + * 1: Vehicle is streamed in for the player. + *     + */ +native bool:IsVehicleStreamedIn(vehicleid, playerid); + +/** + * a_vehicles + * Gets the position of a vehicle. + * The ID of the vehicle to get the position of + * A float variable in which to store the x coordinate, passed by reference + * A float variable in which to store the y coordinate, passed by reference + * A float variable in which to store the z coordinate, passed by reference + * + * + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle specified does not exist. + *     + */ +native bool:GetVehiclePos(vehicleid, &Float:x, &Float:y, &Float:z); + +/** + * a_vehicles + * Set a vehicle's position. + * Vehicle ID that you want set new position + * The x coordinate to position the vehicle at + * The y coordinate to position the vehicle at + * The z coordinate to position the vehicle at + * + * + * + * An empty vehicle will not fall after being teleported into the air. + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle specified does not exist. + *     + */ +native bool:SetVehiclePos(vehicleid, Float:x, Float:y, Float:z); + +/** + * a_vehicles + * Get the rotation of a vehicle on the z axis (yaw). + * The ID of the vehicle to get the z angle of + * A float variable in which to store the z rotation, passed by reference + * + * + * + * + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle does not exist. + *     + */ +native bool:GetVehicleZAngle(vehicleid, &Float:angle); + +/** + * a_vehicles + * Returns a vehicle's rotation on all axes as a quaternion. + * The ID of the vehicle to get the rotation of + * A float variable in which to store the first quaternion angle, passed by reference + * A float variable in which to store the second quaternion angle, passed by reference + * A float variable in which to store the third quaternion angle, passed by reference + * A float variable in which to store the fourth quaternion angle, passed by reference + * + * This function was added in SA-MP 0.3b and will not work in earlier versions! + * + * To euler:
    + * + * // GetVehicleRotation Created by IllidanS4
    + * stock GetVehicleRotation(vehicleid, &Float:rx, &Float:ry, &Float:rz)
    + * {
    + * new Float:qw, Float:qx, Float:qy, Float:qz;
    + * GetVehicleRotationQuat(vehicleid, qw, qx, qy, qz);
    + * rx = asin((2 * qy * qz) - (2 * qx * qw));
    + * ry = -atan2((qx * qz) + (qy * qw), 0.5 - (qx * qx) - (qy * qy));
    + * rz = -atan2((qx * qy) + (qz * qw), 0.5 - (qx * qx) - (qz * qz));
    + * } + *     + *     + * There is no 'set' variation of this function; you can not SET a vehicle's rotation (apart + * from the z angle) + * This function may return incorrect values for unoccupied vehicles. The reason is that the + * third row of the vehicle's internal rotation matrix gets corrupted if it gets updated while unoccupied. + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle specified does not exist. + *     + */ +native bool:GetVehicleRotationQuat(vehicleid, &Float:w, &Float:x, &Float:y, &Float:z); + +/** + * a_vehicles + * This function can be used to calculate the distance (as a float) between a vehicle and another + * map coordinate. This can be useful to detect how far a vehicle away is from a location. + * The ID of the vehicle to calculate the distance for + * The x map coordinate + * The y map coordinate + * The z map coordinate + * + * + * This function was added in SA-MP 0.3c R3 and will not work in earlier versions! + * A float containing the distance from the point specified in the coordinates. + */ +native Float:GetVehicleDistanceFromPoint(vehicleid, Float:x, Float:y, Float:z); + +/** + * a_vehicles + * Set the z rotation (yaw) of a vehicle. + * The ID of the vehicle to set the rotation of + * The z angle to set + * + * + * A vehicle's x and y (pitch and roll) rotation will be reset when this function is used. + * The x and y rotations can not be set. + * This function does not work on unoccupied vehicles. + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle specified does not exist. + *     + */ +native bool:SetVehicleZAngle(vehicleid, Float:angle); + +/** + * a_vehicles + * Set the parameters of a vehicle for a player. + * The ID of the vehicle to set the parameters of + * The ID of the player to set the vehicle's parameters for + * 0 to disable the objective or 1 to show it. + * This is a bobbing yellow arrow above the vehicle + * 0 to unlock the doors or 1 to lock them + * + * Vehicles must be respawned for the 'objective' to be removed. This can be circumvented + * somewhat using Get/SetVehicleParamsEx which do not require the vehicle to be respawned. It is worth + * noting however that the object will be disabled on a global scale, and this is only useful if only + * one player has the vehicle as an objective. + * Since 0.3a you will have to reapply this function when OnVehicleStreamIn + * is called. + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The player and/or vehicle specified do not exist. + *     + */ +native bool:SetVehicleParamsForPlayer(vehicleid, playerid, objective, doors); + +/** + * a_vehicles + * Use this function before any player connects (OnGameModeInit) + * to tell all clients that the script will control vehicle engines and lights. This prevents the game + * automatically turning the engine on/off when players enter/exit vehicles and headlights automatically + * coming on when it is dark. + * + * + * + * This Function was added in SA-MP 0.3c and will not work in earlier versions! + * Is it not possible to reverse this function after it has been used. You must either use + * it or not use it. + * This function always returns 1. It cannot fail to execute. + */ native ManualVehicleEngineAndLights(); -/// Sets a vehicle's parameters for all players. -/// The ID of the vehicle to set the parameters of -/// Engine status. 0 - Off, 1 - On -/// Light status. 0 - Off, 1 - On -/// Vehicle alarm status. If on, the alarm starts. 0 - Off, 1 - On -/// Door lock status. 0 - Unlocked, 1 - Locked -/// Bonnet (hood) status. 0 - Closed, 1 - Open -/// Boot/trunk status. 0 - Closed, 1 - Open -/// Toggle the objective arrow above the vehicle. 0 - Off, 1 - On -/// -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// The alarm will not reset when finished, you'll need to reset it by yourself with this function. -/// Lights also operate during the day (Only when ManualVehicleEngineAndLights is enabled). -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle does not exist. -/// -native SetVehicleParamsEx(vehicleid, engine, lights, alarm, doors, bonnet, boot, objective); - -///

    Gets a vehicle's parameters. -/// The ID of the vehicle to get the parameters from -/// Get the engine status. If 1, the engine is running. -/// Get the vehicle's lights' state. If 1 the lights are on -/// Get the vehicle's alarm state. If 1 the alarm is (or was) sounding -/// Get the lock status of the doors. If 1 the doors are locked -/// Get the bonnet/hood status. If 1, it's open -/// Get the boot/trunk status. 1 means it is open -/// Get the objective status. 1 means the objective is on -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// If a parameter is unset (SetVehicleParamsEx not used beforehand) the value will be -1 ('unset'). -native GetVehicleParamsEx(vehicleid, &engine, &lights, &alarm, &doors, &bonnet, &boot, &objective); - -/// Returns a vehicle's siren state (on/off). -/// The ID of the vehicle to get the siren state of -/// -/// This function was added in SA-MP 0.3c R3 and will not work in earlier versions! -/// -1 if unset (off), 0 if off, 1 if on -native GetVehicleParamsSirenState(vehicleid); - -/// Allows you to open and close the doors of a vehicle. -/// The ID of the vehicle to set the door state of -/// The state of the driver's door. 1 to open, 0 to close -/// The state of the passenger door. 1 to open, 0 to close -/// The state of the rear left door (if available). 1 to open, 0 to close -/// The state of the rear right door (if available). 1 to open, 0 to close -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// 1 is open, 0 is closed -native SetVehicleParamsCarDoors(vehicleid, driver, passenger, backleft, backright); - -/// Allows you to retrieve the current state of a vehicle's doors. -/// The ID of the vehicle -/// The integer to save the state of the driver's door to -/// The integer to save the state of the passenger's door to -/// The integer to save the state of the rear left door to (if available) -/// The integer to save the state of the rear right door to (if available) -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The values returned in each variable are as follows: -1 if not set, 0 if closed, 1 if open. -native GetVehicleParamsCarDoors(vehicleid, &driver, &passenger, &backleft, &backright); - -/// Allows you to open and close the windows of a vehicle. -/// The ID of the vehicle to set the window state of -/// The state of the driver's window. 0 to open, 1 to close -/// The state of the passenger window. 0 to open, 1 to close -/// The state of the rear left window (if available). 0 to open, 1 to close -/// The state of the rear right window (if available). 0 to open, 1 to close -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -native SetVehicleParamsCarWindows(vehicleid, driver, passenger, backleft, backright); - -/// Allows you to retrieve the current state of a vehicle's windows. -/// The ID of the vehicle -/// The integer to save the state of the drivers window to -/// The integer to save the state of the passengers window to -/// The integer to save the state of the rear left window to (if available) -/// The integer to save the state of the rear right window to (if available) -/// -/// -/// -/// This function was added in SA-MP 0.3.7 and will not work in earlier versions! -/// The values returned in each variable are as follows: -1 if not set, 0 if closed, 1 if open. -/// The vehicle's windows state is stored in the specified variables. -native GetVehicleParamsCarWindows(vehicleid, &driver, &passenger, &backleft, &backright); - -/// Sets a vehicle back to the position at where it was created. -/// The ID of the vehicle to respawn -/// -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle does not exist. -/// -native SetVehicleToRespawn(vehicleid); - -///

    Links a vehicle to an interior. Vehicles can only be seen by players in the same interior (SetPlayerInterior). -/// The ID of the vehicle to link to an interior -/// The Interior ID to link it to -/// -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle does not exist.

    -/// -native LinkVehicleToInterior(vehicleid, interiorid); - -///

    Adds a 'component' (often referred to as a 'mod' (modification)) to a vehicle. Valid components can be found here. -/// The ID of the vehicle to add the component to. Not to be confused with modelid -/// The ID of the component to add to the vehicle -/// -///
      -///
    • 0 - The component was not added because the vehicle does not exist.
      • -///
    • 1 - The component was successfully added to the vehicle.
      • -///
    -///     -/// Using an invalid component ID crashes the player's game. There are no internal checks for this. -/// -/// -/// -/// -/// -native AddVehicleComponent(vehicleid, componentid); - -/// Remove a component from a vehicle. -/// ID of the vehicle -/// ID of the component to remove -/// -/// -/// -/// -/// -native RemoveVehicleComponent(vehicleid, componentid); - -/// Change a vehicle's primary and secondary colors. -/// The ID of the vehicle to change the colors of -/// The new vehicle's primary Color ID -/// The new vehicle's secondary Color ID -/// -/// -/// Some vehicles have only a primary color and some can not have the color changed at all. A few (cement, squallo) have 4 colors, of which 2 can not be changed in SA:MP -/// -/// 1: The function executed successfully. The vehicle's color was successfully changed.

    -/// 0: The function failed to execute. The vehicle does not exist. -/// -native ChangeVehicleColor(vehicleid, color1, color2); - -///

    Change a vehicle's paintjob (for plain colors see ChangeVehicleColor). -/// The ID of the vehicle to change the paintjob of -/// The ID of the Paintjob to apply. Use 3 to remove a paintjob -/// -/// -/// -/// Known Bugs:

    -/// This function calls OnVehicleRespray.

    -/// Vehicles change their color to white anymore when a paintjob is removed. -/// -/// This function always returns 1 (success), even if the vehicle passed is not created. -native ChangeVehiclePaintjob(vehicleid, paintjobid); - - -///

    Set a vehicle's health. When a vehicle's health decreases the engine will produce smoke, and finally fire when it decreases to less than 250 (25%). -/// The ID of the vehicle to set the health of -/// The health, given as a float value -/// -/// -/// -/// -/// Full vehicle health is 1000, however higher values are possible and increase the health of the vehicle. -/// -/// Health:

    -///

      -///
    • > 650 - undamaged
      • -///
    • 650-550 - white Smoke
      • -///
    • 550-390 - grey Smoke
      • -///
    • 390-250 - black Smoke
      • -///
    • < 250 - on fire (will explode seconds later)
      • -///
    -///     -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle does not exist. -/// -native SetVehicleHealth(vehicleid, Float:health); - -///

    Get the health of a vehicle. -/// The ID of the vehicle to get the health of -/// A float variable in which to store the vehicle's health, passed by reference -/// -/// -/// -/// Full vehicle health is 1000, however higher values are possible and increase the health of the vehicle. -/// -/// Health:

    -///

      -///
    • > 650 - undamaged
      • -///
    • 650-550 - white Smoke
      • -///
    • 550-390 - grey Smoke
      • -///
    • 390-250 - black Smoke
      • -///
    • < 250 - on fire (will explode seconds later)
      • -///
    -///     -/// -/// 1 - success.

    -/// 0 - failure (invalid vehicle ID).

    -/// -native GetVehicleHealth(vehicleid, &Float:health); - -///

    Attach a vehicle to another vehicle as a trailer. -/// The ID of the vehicle that will be pulled -/// The ID of the vehicle that will pull the trailer -/// -/// -/// -/// This will only work if both vehicles are streamed in for a player (check IsVehicleStreamedIn). -/// This function always returns 1, even if neither of the vehicle IDs passed are valid. -native AttachTrailerToVehicle(trailerid, vehicleid); - -/// Detach the connection between a vehicle and its trailer, if any. -/// ID of the pulling vehicle -/// -/// -/// -native DetachTrailerFromVehicle(vehicleid); - -/// Checks if a vehicle has a trailer attached to it. Use GetVehicleTrailer to get the vehicle ID of the trailer (if any). -/// The ID of the vehicle to check for trailers -/// -/// -/// -/// 1 if the vehicle has a trailer attached, 0 if not. -native IsTrailerAttachedToVehicle(vehicleid); - -/// Get the ID of the trailer attached to a vehicle. -/// The ID of the vehicle to get the trailer of -/// -/// -/// -/// The vehicle ID of the trailer or 0 if no trailer is attached. +/** + * a_vehicles + * Sets a vehicle's parameters for all players. + * The ID of the vehicle to set the parameters of + * Engine status. 0 - Off, 1 - On + * Light status. 0 - Off, 1 - On + * Vehicle alarm status. If on, the alarm starts. 0 - Off, 1 + * - On + * Door lock status. 0 - Unlocked, 1 - Locked + * Bonnet (hood) status. 0 - Closed, 1 - Open + * Boot/trunk status. 0 - Closed, 1 - Open + * Toggle the objective arrow above the vehicle. 0 - Off, 1 + * - On + * + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * The alarm will not reset when finished, you'll need to reset it by yourself with this function. + * + * Lights also operate during the day (Only when ManualVehicleEngineAndLights + * is enabled). + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle does not exist. + *     + */ +native bool:SetVehicleParamsEx(vehicleid, VEHICLE_PARAMS:engine, VEHICLE_PARAMS:lights, VEHICLE_PARAMS:alarm, VEHICLE_PARAMS:doors, VEHICLE_PARAMS:bonnet, VEHICLE_PARAMS:boot, VEHICLE_PARAMS:objective); + +/** + * a_vehicles + * Gets a vehicle's parameters. + * The ID of the vehicle to get the parameters from + * Get the engine status. If 1, the engine is running. + * Get the vehicle's lights' state. If 1 the lights are on + * Get the vehicle's alarm state. If 1 the alarm is (or was) sounding + * Get the lock status of the doors. If 1 the doors are locked + * Get the bonnet/hood status. If 1, it's open + * Get the boot/trunk status. 1 means it is open + * Get the objective status. 1 means the objective is on + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * If a parameter is unset (SetVehicleParamsEx not used beforehand) the value will be -1 + * ('unset'). + */ +native bool:GetVehicleParamsEx(vehicleid, &VEHICLE_PARAMS:engine, &VEHICLE_PARAMS:lights, &VEHICLE_PARAMS:alarm, &VEHICLE_PARAMS:doors, &VEHICLE_PARAMS:bonnet, &VEHICLE_PARAMS:boot, &VEHICLE_PARAMS:objective); + +/** + * a_vehicles + * Returns a vehicle's siren state (on/off). + * The ID of the vehicle to get the siren state of + * + * This function was added in SA-MP 0.3c R3 and will not work in earlier versions! + * -1 if unset (off), 0 if off, 1 if on + */ +native VEHICLE_PARAMS:GetVehicleParamsSirenState(vehicleid); + +/** + * a_vehicles + * Allows you to open and close the doors of a vehicle. + * The ID of the vehicle to set the door state of + * The state of the driver's door. 1 to open, 0 + * to close + * The state of the passenger door. 1 to open, 0 + * to close + * The state of the rear left door (if available). 1 to open, 0 + * to close + * The state of the rear right door (if available). 1 to open, + * 0 to close + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * 1 is open, 0 is closed + */ +native bool:SetVehicleParamsCarDoors(vehicleid, frontLeft, frontRight, rearLeft, rearRight); + +/** + * a_vehicles + * Allows you to retrieve the current state of a vehicle's doors. + * The ID of the vehicle + * The integer to save the state of the driver's door to + * The integer to save the state of the passenger's door to + * The integer to save the state of the rear left door to (if available) + * The integer to save the state of the rear right door to (if available) + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The values returned in each variable are as follows: -1 if not set, 0 + * if closed, 1 if open. + */ +native bool:GetVehicleParamsCarDoors(vehicleid, &frontLeft, &frontRight, &rearLeft, &rearRight); + +/** + * a_vehicles + * Allows you to open and close the windows of a vehicle. + * The ID of the vehicle to set the window state of + * The state of the driver's window. 0 to open, 1 + * to close + * The state of the passenger window. 0 to open, 1 + * to close + * The state of the rear left window (if available). 0 to open, + * 1 to close + * The state of the rear right window (if available). 0 to open, + * 1 to close + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + */ +native bool:SetVehicleParamsCarWindows(vehicleid, frontLeft, frontRight, rearLeft, rearRight); + +/** + * a_vehicles + * Allows you to retrieve the current state of a vehicle's windows. + * The ID of the vehicle + * The integer to save the state of the drivers window to + * The integer to save the state of the passengers window to + * The integer to save the state of the rear left window to (if available) + * The integer to save the state of the rear right window to (if available) + * + * + * + * This function was added in SA-MP 0.3.7 and will not work in earlier versions! + * The values returned in each variable are as follows: -1 if not set, 0 + * if closed, 1 if open. + * The vehicle's windows state is stored in the specified variables. + */ +native bool:GetVehicleParamsCarWindows(vehicleid, &frontLeft, &frontRight, &rearLeft, &rearRight); + +/** + * a_vehicles + * Sets a vehicle back to the position at where it was created. + * The ID of the vehicle to respawn + * + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle does not exist. + *     + */ +native bool:SetVehicleToRespawn(vehicleid); + +/** + * a_vehicles + * Links a vehicle to an interior. Vehicles can only be seen by players in the same interior + * (SetPlayerInterior). + * The ID of the vehicle to link to an interior + * The Interior ID to + * link it to + * + * + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle does not exist.
    + *     + */ +native bool:LinkVehicleToInterior(vehicleid, interiorid); + +/** + * a_vehicles + * Adds a 'component' (often referred to as a 'mod' (modification)) to a vehicle. Valid components + * can be found here. + * The ID of the vehicle to add the component to. Not to be confused with modelid + * The ID of the component + * to add to the vehicle + * + *
      + *
    • 0 - The component was not added because the vehicle does not exist.
      • + *
    • 1 - The component was successfully added to the vehicle.
      • + *
    + *     + * Using an invalid component ID + * crashes the player's game. There are no internal checks for this. + * + * + * + * + * + */ +native bool:AddVehicleComponent(vehicleid, componentid); + +/** + * a_vehicles + * Remove a component from a vehicle. + * ID of the vehicle + * ID of the component + * to remove + * + * + * + * + * + */ +native bool:RemoveVehicleComponent(vehicleid, componentid); + +/** + * a_vehicles + * Change a vehicle's primary and secondary colours. + * The ID of the vehicle to change the colours of + * The new vehicle's primary Color + * ID + * The new vehicle's secondary Color + * ID + * + * + * Some vehicles have only a primary colour and some can not have the colour changed at all. + * A few (cement, squallo) have 4 colours, of which 2 can not be changed in SA:MP + * + * 1: The function executed successfully. The vehicle's colour was successfully changed.
    + * 0: The function failed to execute. The vehicle does not exist. + *     + */ +native bool:ChangeVehicleColor(vehicleid, colour1, colour2); + +/** + * a_vehicles + * Change a vehicle's paintjob (for plain colours see ChangeVehicleColor). + * The ID of the vehicle to change the paintjob of + * The ID of the Paintjob to apply. Use 3 to remove a paintjob + * + * + * + * Known Bugs:
    + * This function calls OnVehicleRespray.
    + * Vehicles change their colour to white anymore when a paintjob is removed. + *     + * This function always returns 1 (success), even if the vehicle passed is not + * created. + */ +native bool:ChangeVehiclePaintjob(vehicleid, paintjobid); + +/** + * a_vehicles + * Set a vehicle's health. When a vehicle's health decreases the engine will produce smoke, + * and finally fire when it decreases to less than 250 (25%). + * The ID of the vehicle to set the health of + * The health, given as a float value + * + * + * + * + * Full vehicle health is 1000, however higher values are possible and increase + * the health of the vehicle. + * + * Health:
    + *
      + *
    • > 650 - undamaged
      • + *
    • 650-550 - white Smoke
      • + *
    • 550-390 - grey Smoke
      • + *
    • 390-250 - black Smoke
      • + *
    • < 250 - on fire (will explode seconds later)
      • + *
    + *     + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle does not exist. + *     + */ +native bool:SetVehicleHealth(vehicleid, Float:health); + +/** + * a_vehicles + * Get the health of a vehicle. + * The ID of the vehicle to get the health of + * A float variable in which to store the vehicle's health, passed by reference + * + * + * + * Full vehicle health is 1000, however higher values are possible and increase + * the health of the vehicle. + * + * Health:
    + *
      + *
    • > 650 - undamaged
      • + *
    • 650-550 - white Smoke
      • + *
    • 550-390 - grey Smoke
      • + *
    • 390-250 - black Smoke
      • + *
    • < 250 - on fire (will explode seconds later)
      • + *
    + *     + * + * 1 - success.
    + * 0 - failure (invalid vehicle ID).
    + *     + */ +native bool:GetVehicleHealth(vehicleid, &Float:health); + +/** + * a_vehicles + * Attach a vehicle to another vehicle as a trailer. + * The ID of the vehicle that will be pulled + * The ID of the vehicle that will pull the trailer + * + * + * + * This will only work if both vehicles are streamed in for a player (check + * IsVehicleStreamedIn). + * This function always returns 1, even if neither of the vehicle IDs passed + * are valid. + */ +native bool:AttachTrailerToVehicle(trailerid, vehicleid); + +/** + * a_vehicles + * Detach the connection between a vehicle and its trailer, if any. + * ID of the pulling vehicle + * + * + * + */ +native bool:DetachTrailerFromVehicle(vehicleid); + +/** + * a_vehicles + * Checks if a vehicle has a trailer attached to it. Use GetVehicleTrailer + * to get the vehicle ID of the trailer (if any). + * The ID of the vehicle to check for trailers + * + * + * + * 1 if the vehicle has a trailer attached, 0 if not. + */ +native bool:IsTrailerAttachedToVehicle(vehicleid); + +/** + * a_vehicles + * Get the ID of the trailer attached to a vehicle. + * The ID of the vehicle to get the trailer of + * + * + * + * The vehicle ID of the trailer or 0 if no trailer is attached. + */ native GetVehicleTrailer(vehicleid); -/// Set a vehicle numberplate. -/// The ID of the vehicle to set the number plate of -/// The text that should be displayed on the number plate -/// -/// -/// -/// This function was added in SA-MP 0.3c and will not work in earlier versions! -/// You can use color embedding on the number plate text. -/// -/// This function has no internal error checking. Do not assign custom number plates to vehicles without plates (boats, planes, etc) as this will result in some unneeded processing time on the client.

    -/// The vehicle must be re-spawned or re-streamed for the changes to take effect.

    -/// There's a limit of 32 characters on each number plate (including embedded colors).

    -/// The text length that can be seen on the number plate is around 9 to 10 characters, more characters will cause the text to split.

    -/// Some vehicle models has a backward number plate, e.g. Boxville (498) (as an alternative to this vehicle you can use vehicle model ID 609, which is a duplicated Boxville (aka Boxburg), but with a regular number plate).

    -/// This function only works in versions 0.2.1, 0.2.2, 0.2x and 0.3c (and beyond). -/// -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle does not exist.

    -/// -native SetVehicleNumberPlate(vehicleid, const numberplate[]); - -///

    Gets the model ID of a vehicle. -/// The ID of the vehicle to get the model of -/// -/// -/// -/// -/// The vehicle's model ID, or 0 if the vehicle doesn't exist. +/** + * a_vehicles + * Set a vehicle numberPlate. + * The ID of the vehicle to set the number plate of + * The text that should be displayed on the number plate + * + * + * + * This function was added in SA-MP 0.3c and will not work in earlier versions! + * You can use colour embedding on the number plate text. + * + * This function has no internal error checking. Do not assign custom number plates to vehicles without + * plates (boats, planes, etc) as this will result in some unneeded processing time on the client.
    + * The vehicle must be re-spawned or re-streamed for the changes to take effect.
    + * There's a limit of 32 characters on each number plate (including embedded colours).
    + * The text length that can be seen on the number plate is around 9 to 10 characters, more characters + * will cause the text to split.
    + * Some vehicle models has a backward number plate, e.g. Boxville (498) (as an alternative to this + * vehicle you can use vehicle model ID 609, which is a duplicated Boxville (aka Boxburg), but with + * a regular number plate).
    + * This function only works in versions 0.2.1, 0.2.2, 0.2x and 0.3c (and + * beyond). + *     + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle does not exist.
    + *     + */ +native bool:SetVehicleNumberPlate(vehicleid, const numberPlate[]); + +/** + * a_vehicles + * Gets the model ID of a vehicle. + * The ID of the vehicle to get the model of + * + * + * + * + * The vehicle's model ID, or 0 + * if the vehicle doesn't exist. + */ native GetVehicleModel(vehicleid); -/// Retrieves the installed component ID (modshop mod(ification)) on a vehicle in a specific slot. -/// The ID of the vehicle to check for the component -/// The component slot to check for components (see below) -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Slots:

    -/// -/// CARMODTYPE_SPOILER -/// CARMODTYPE_HOOD -/// CARMODTYPE_ROOF -/// CARMODTYPE_SIDESKIRT -/// CARMODTYPE_LAMPS -/// CARMODTYPE_NITRO -/// CARMODTYPE_EXHAUST -/// CARMODTYPE_WHEELS -/// CARMODTYPE_STEREO -/// CARMODTYPE_HYDRAULICS -/// CARMODTYPE_FRONT_BUMPER -/// CARMODTYPE_REAR_BUMPER -/// CARMODTYPE_VENT_RIGHT -/// CARMODTYPE_VENT_LEFT -/// -/// -/// -/// Known Bugs:

    -///

      -///
    • Doesn't work for CARMODTYPE_STEREO.
      • -///
    • Both front bull bars and front bumper components are saved in the CARMODTYPE_FRONT_BUMPER slot. If a vehicle has both of them installed, this function will only return the one which was installed last.
      • -///
    • Both rear bull bars and rear bumper components are saved in the CARMODTYPE_REAR_BUMPER slot. If a vehicle has both of them installed, this function will only return the one which was installed last.
      • -///
    • Both left side skirt and right side skirt are saved in the CARMODTYPE_SIDESKIRT slot. If a vehicle has both of them installed, this function will only return the one which was installed last.
      • -///
    -///     -/// The ID of the component installed in the specified slot. Returns 0 if no component in specified vehicle's specified slot, or if vehicle doesn't exist. -native GetVehicleComponentInSlot(vehicleid, slot); // There is 1 slot for each CARMODTYPE_* - -/// Find out what type of component a certain ID is. -/// The component ID to check -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// The component slot ID of the specified component or -1 if the component is invalid. -native GetVehicleComponentType(component); // Find CARMODTYPE_* for component id - -/// Fully repairs a vehicle, including visual damage (bumps, dents, scratches, popped tires etc.). -/// The ID of the vehicle to repair -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle specified does not exist. -/// -native RepairVehicle(vehicleid); // Repairs the damage model and resets the health - -///

    Get the velocity of a vehicle on the X, Y and Z axes. -/// The ID of the vehicle to get the velocity of -/// A float variable in to which to store the vehicle's X velocity, passed by reference -/// A float variable in to which to store the vehicle's Y velocity, passed by reference -/// A float variable in to which to store the vehicle's Z velocity, passed by reference -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// Multiply vector with 250.66667 for kmph or 199.416667 for mph or something... -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle specified does not exist.

    -/// -native GetVehicleVelocity(vehicleid, &Float:X, &Float:Y, &Float:Z); - -///

    Sets the X, Y and Z velocity of a vehicle. -/// The ID of the vehicle to set the velocity of -/// The velocity in the X direction -/// The velocity in the Y direction -/// The velocity in the Z direction -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// This function has no affect on un-occupied vehicles and does not affect trains. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle does not exist. -/// -native SetVehicleVelocity(vehicleid, Float:X, Float:Y, Float:Z); - -///

    Sets the angular X, Y and Z velocity of a vehicle. -/// The ID of the vehicle to set the velocity of -/// The amount of velocity in the angular X direction -/// The amount of velocity in the angular Y direction -/// The amount of velocity in the angular Z direction -/// -/// -/// This function was added in SA-MP 0.3b and will not work in earlier versions! -/// This function has no effect on un-occupied vehicles and does not effect trains. -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. The vehicle does not exist. -/// -native SetVehicleAngularVelocity(vehicleid, Float:X, Float:Y, Float:Z); - -///

    Retrieve the damage statuses of a vehicle. -/// The ID of the vehicle to get the damage statuses of -/// A variable to store the panel damage data in, passed by reference -/// A variable to store the door damage data in, passed by reference -/// A variable to store the light damage data in, passed by reference -/// A variable to store the tire damage data in, passed by reference -/// -/// -/// -/// -/// -/// This Callback was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Door states:

    -///

      -///
    • 0x000000FF - hood
      • -///
    • 0x0000FF00 - trunk
      • -///
    • 0x00FF0000 - drivers door
      • -///
    • 0xFF000000 - co-drivers door
      • -///
    • byte meaning:
      • -///
    • 0x1 - is opened
      • -///
    • 0x2 - is damaged
      • -///
    • 0x4 - is removed
      • -///
    • other bytes are unused
      • -///
    -///     -/// -/// Light states:

    -///

      -///
    • 0x01 - front left broken
      • -///
    • 0x04 - front right broken
      • -///
    • 0x40 - back both broken
      • -///
    -///     -/// -/// Tire states:

    -///

      -///
    • 0x1 - back right popped
      • -///
    • 0x2 - front right popped
      • -///
    • 0x4 - back left popped
      • -///
    • 0x8 - front left popped
      • -///
    • only check the right states for bikes
      • -///
    -///     -/// -/// 1: The function executed successfully.

    -/// 0: The function failed to execute. This means the vehicle specified does not exist. -/// -native GetVehicleDamageStatus(vehicleid, &panels, &doors, &lights, &tires); - -///

    Sets the various visual damage statuses of a vehicle, such as popped tires, broken lights and damaged panels. -/// The ID of the vehicle to set the damage of -/// A set of bits containing the panel damage status -/// A set of bits containing the door damage status -/// A set of bits containing the light damage status -/// A set of bits containing the tire damage status -/// -/// -/// -/// -/// -/// This function was added in SA-MP 0.3a and will not work in earlier versions! -/// -/// Door states:

    -///

      -///
    • 0x000000FF - hood
      • -///
    • 0x0000FF00 - trunk
      • -///
    • 0x00FF0000 - drivers door
      • -///
    • 0xFF000000 - co-drivers door
      • -///
    • byte meaning:
      • -///
    • 0x1 - is opened
      • -///
    • 0x2 - is damaged
      • -///
    • 0x4 - is removed
      • -///
    • other bytes are unused
      • -///
    -///     -/// -/// Light states:

    -///

      -///
    • 0x01 - front left broken
      • -///
    • 0x04 - front right broken
      • -///
    • 0x40 - back both broken
      • -///
    -///     -/// -/// Tire states:

    -///

      -///
    • 0x1 - back right popped
      • -///
    • 0x2 - front right popped
      • -///
    • 0x4 - back left popped
      • -///
    • 0x8 - front left popped
      • -///
    • only check the right states for bikes
      • -///
    -///     -native UpdateVehicleDamageStatus(vehicleid, panels, doors, lights, tires); - -/// Retrieve information about a specific vehicle model such as the size or position of seats. -/// The vehicle model to get info of -/// The type of information to retrieve -/// A float to store the X value -/// A float to store the Y value -/// A float to store the Z value -/// -/// This function was added in SA-MP 0.3e and will not work in earlier versions! -/// -/// Information types:

    -///

      -///
    • VEHICLE_MODEL_INFO_SIZE - vehicle size
      • -///
    • VEHICLE_MODEL_INFO_FRONTSEAT - position of the front seat
      • -///
    • VEHICLE_MODEL_INFO_REARSEAT - position of the rear seat
      • -///
    • VEHICLE_MODEL_INFO_PETROLCAP - position of the fuel cap
      • -///
    • VEHICLE_MODEL_INFO_WHEELSFRONT - position of the front wheels
      • -///
    • VEHICLE_MODEL_INFO_WHEELSREAR - position of the rear wheels
      • -///
    • VEHICLE_MODEL_INFO_WHEELSMID - position of the middle wheels (applies to vehicles with 3 axes)
      • -///
    • VEHICLE_MODEL_INFO_FRONT_BUMPER_Z - height of the front bumper
      • -///
    • VEHICLE_MODEL_INFO_REAR_BUMPER_Z - height of the rear bumper
      • -///
    -///     -native GetVehicleModelInfo(vehiclemodel, infotype, &Float:X, &Float:Y, &Float:Z); +/** + * a_vehicles + * Retrieves the installed component ID (modshop mod(ification)) on a vehicle in a specific + * slot. + * The ID of the vehicle to check for the component + * The component slot to check for components (see below) + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Slots:
    + * + * CARMODTYPE_SPOILER + * CARMODTYPE_HOOD + * CARMODTYPE_ROOF + * CARMODTYPE_SIDESKIRT + * CARMODTYPE_LAMPS + * CARMODTYPE_NITRO + * CARMODTYPE_EXHAUST + * CARMODTYPE_WHEELS + * CARMODTYPE_STEREO + * CARMODTYPE_HYDRAULICS + * CARMODTYPE_FRONT_BUMPER + * CARMODTYPE_REAR_BUMPER + * CARMODTYPE_VENT_RIGHT + * CARMODTYPE_VENT_LEFT + * + *     + * + * Known Bugs:
    + *
      + *
    • Doesn't work for CARMODTYPE_STEREO.
      • + *
    • Both front bull bars and front bumper components are saved in the CARMODTYPE_FRONT_BUMPER + * slot. If a vehicle has both of them installed, this function will only return the one which was + * installed last.
      • + *
    • Both rear bull bars and rear bumper components are saved in the CARMODTYPE_REAR_BUMPER + * slot. If a vehicle has both of them installed, this function will only return the one which was + * installed last.
      • + *
    • Both left side skirt and right side skirt are saved in the CARMODTYPE_SIDESKIRT + * slot. If a vehicle has both of them installed, this function will only return the one which was + * installed last.
      • + *
    + *     + * The ID of the component installed in the specified slot. Returns 0 if no + * component in specified vehicle's specified slot, or if vehicle doesn't exist. + */ +native GetVehicleComponentInSlot(vehicleid, CARMODTYPE:slot); // There is 1 slot for each CARMODTYPE_* + +/** + * a_vehicles + * Find out what type of component a certain ID is. + * The component ID to check + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * The component slot ID of the specified component or -1 if the component is + * invalid. + */ +native CARMODTYPE:GetVehicleComponentType(component); // Find CARMODTYPE_* for component ID + +/** + * a_vehicles + * Fully repairs a vehicle, including visual damage (bumps, dents, scratches, popped tires + * etc.). + * The ID of the vehicle to repair + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle specified does not exist. + *     + */ +native bool:RepairVehicle(vehicleid); // Repairs the damage model and resets the health + +/** + * a_vehicles + * Get the velocity of a vehicle on the x, y and z axes. + * The ID of the vehicle to get the velocity of + * A float variable in to which to store the vehicle's x velocity, passed by reference + * A float variable in to which to store the vehicle's y velocity, passed by reference + * A float variable in to which to store the vehicle's z velocity, passed by reference + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * Multiply vector with 250.66667 for kmph or 199.416667 for mph + * or something... + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle specified does not exist.
    + *     + */ +native bool:GetVehicleVelocity(vehicleid, &Float:x, &Float:y, &Float:z); + +/** + * a_vehicles + * Sets the x, y and z velocity of a vehicle. + * The ID of the vehicle to set the velocity of + * The velocity in the x direction + * The velocity in the y direction + * The velocity in the z direction + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * This function has no affect on un-occupied vehicles and does not affect trains. + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle does not exist. + *     + */ +native bool:SetVehicleVelocity(vehicleid, Float:x, Float:y, Float:z); + +/** + * a_vehicles + * Sets the angular x, y and z velocity of a vehicle. + * The ID of the vehicle to set the velocity of + * The amount of velocity in the angular x direction + * The amount of velocity in the angular y direction + * The amount of velocity in the angular z direction + * + * + * This function was added in SA-MP 0.3b and will not work in earlier versions! + * This function has no effect on un-occupied vehicles and does not effect trains. + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. The vehicle does not exist. + *     + */ +native bool:SetVehicleAngularVelocity(vehicleid, Float:x, Float:y, Float:z); + +/** + * a_vehicles + * Retrieve the damage statuses of a vehicle. + * The ID of the vehicle to get the damage statuses of + * A variable to store the panel damage data in, passed by reference + * A variable to store the door damage data in, passed by reference + * A variable to store the light damage data in, passed by reference + * A variable to store the tire damage data in, passed by reference + * + * + * + * + * + * This Callback was added in SA-MP 0.3a and will not work in earlier versions! + * + * Door states:
    + *
      + *
    • 0x000000FF - hood
      • + *
    • 0x0000FF00 - trunk
      • + *
    • 0x00FF0000 - drivers door
      • + *
    • 0xFF000000 - co-drivers door
      • + *
    • byte meaning:
      • + *
    • 0x1 - is opened
      • + *
    • 0x2 - is damaged
      • + *
    • 0x4 - is removed
      • + *
    • other bytes are unused
      • + *
    + *     + * + * Light states:
    + *
      + *
    • 0x01 - front left broken
      • + *
    • 0x04 - front right broken
      • + *
    • 0x40 - back both broken
      • + *
    + *     + * + * Tire states:
    + *
      + *
    • 0x1 - back right popped
      • + *
    • 0x2 - front right popped
      • + *
    • 0x4 - back left popped
      • + *
    • 0x8 - front left popped
      • + *
    • only check the right states for bikes
      • + *
    + *     + * + * 1: The function executed successfully.
    + * 0: The function failed to execute. This means the vehicle specified does not exist. + *     + */ +native bool:GetVehicleDamageStatus(vehicleid, &panels, &doors, &lights, &tires); + +/** + * a_vehicles + * Sets the various visual damage statuses of a vehicle, such as popped tires, broken lights + * and damaged panels. + * The ID of the vehicle to set the damage of + * A set of bits containing the panel damage status + * A set of bits containing the door damage status + * A set of bits containing the light damage status + * A set of bits containing the tire damage status + * + * + * + * + * + * This function was added in SA-MP 0.3a and will not work in earlier versions! + * + * Door states:
    + *
      + *
    • 0x000000FF - hood
      • + *
    • 0x0000FF00 - trunk
      • + *
    • 0x00FF0000 - drivers door
      • + *
    • 0xFF000000 - co-drivers door
      • + *
    • byte meaning:
      • + *
    • 0x1 - is opened
      • + *
    • 0x2 - is damaged
      • + *
    • 0x4 - is removed
      • + *
    • other bytes are unused
      • + *
    + *     + * + * Light states:
    + *
      + *
    • 0x01 - front left broken
      • + *
    • 0x04 - front right broken
      • + *
    • 0x40 - back both broken
      • + *
    + *     + * + * Tire states:
    + *
      + *
    • 0x1 - back right popped
      • + *
    • 0x2 - front right popped
      • + *
    • 0x4 - back left popped
      • + *
    • 0x8 - front left popped
      • + *
    • only check the right states for bikes
      • + *
    + *     + */ +native bool:UpdateVehicleDamageStatus(vehicleid, panels, doors, lights, tires); + +/** + * a_vehicles + * Retrieve information about a specific vehicle model such as the size or position of seats. + * The vehicle model + * to get info of + * The type of information to retrieve + * A float to store the x value + * A float to store the y value + * A float to store the z value + * + * This function was added in SA-MP 0.3e and will not work in earlier versions! + * + * Information types:
    + *
      + *
    • VEHICLE_MODEL_INFO_SIZE - vehicle size
      • + *
    • VEHICLE_MODEL_INFO_FRONTSEAT - position of the front seat
      • + *
    • VEHICLE_MODEL_INFO_REARSEAT - position of the rear seat
      • + *
    • VEHICLE_MODEL_INFO_PETROLCAP - position of the fuel cap
      • + *
    • VEHICLE_MODEL_INFO_WHEELSFRONT - position of the front wheels
      • + *
    • VEHICLE_MODEL_INFO_WHEELSREAR - position of the rear wheels
      • + *
    • VEHICLE_MODEL_INFO_WHEELSMID - position of the middle wheels (applies to vehicles + * with 3 axes)
      • + *
    • VEHICLE_MODEL_INFO_FRONT_BUMPER_Z - height of the front bumper
      • + *
    • VEHICLE_MODEL_INFO_REAR_BUMPER_Z - height of the rear bumper
      • + *
    + *     + */ +native bool:GetVehicleModelInfo(vehiclemodel, VEHICLE_MODEL_INFO:infotype, &Float:x, &Float:y, &Float:z); // Virtual Worlds -/// Sets the 'virtual world' of a vehicle. Players will only be able to see vehicles in their own virtual world. -/// The ID of vehicle to set the virtual world of -/// The ID of the virtual world to put the vehicle in -/// -/// -native SetVehicleVirtualWorld(vehicleid, worldid); - -/// Get the virtual world of a vehicle. -/// The ID of the vehicle to get the virtual world of -/// -/// -/// The virtual world that the vehicle is in. +/** + * a_vehicles + * Sets the 'virtual world' of a vehicle. Players will only be able to see vehicles in their + * own virtual world. + * The ID of vehicle to set the virtual world of + * The ID of the virtual world to put the vehicle in + * + * + */ +native bool:SetVehicleVirtualWorld(vehicleid, virtualWorld); + +/** + * a_vehicles + * Get the virtual world of a vehicle. + * The ID of the vehicle to get the virtual world of + * + * + * The virtual world that the vehicle is in. + */ native GetVehicleVirtualWorld(vehicleid); -/// Check if a vehicle ID is valid. -/// The ID of the vehicle to check -/// -/// -/// true or false. +/** + * a_vehicles + * Check if a vehicle ID is valid. + * The ID of the vehicle to check + * + * + * true or false. + */ native bool:IsValidVehicle(vehicleid); +/** + * This callback is called when a player sent a trailer update. + * The ID of the player who sent a trailer update + * The Trailer being updated + * + * + * + * + * + * This callback was added in SA-MP 0.3z R4 and will not work in earlier versions! + * 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. + * + * + * 0 - Cancels any trailer updates from being sent to other players. Update is still + * sent to the updating player.
    + * 1 - Processes the trailer update as normal and synchronizes it between all players.
    + * It is always called first in filterscripts. + *     + */ +forward OnTrailerUpdate(playerid, vehicleid); + +/** + * This callback is called when a vehicle's siren is toggled. + * The ID of the player that toggled the siren (driver) + * The ID of the vehicle of which the siren was toggled for + * 0 if siren was turned off, 1 if siren was turned + * on + * + * This callback was added in SA-MP 0.3.7 and will not work in earlier versions! + * This callback can also be called by NPC. + * 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). + * + * 1 - Will prevent gamemode from receiving this callback.
    + * 0 - Indicates that this callback will be passed to the gamemode.
    + * It is always called first in filterscripts. + *     + */ +forward OnVehicleSirenStateChange(playerid, vehicleid, newstate); + +/** + * Called when a vehicle is streamed to a player's client. + * The ID of the vehicle that streamed in for the player + * The ID of the player who the vehicle streamed in for + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This callback can also be called by NPC. + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnVehicleStreamIn(vehicleid, forplayerid); + +/** + * 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). + * The ID of the vehicle that streamed out + * The ID of the player who is no longer streaming the vehicle + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This callback can also be called by NPC. + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnVehicleStreamOut(vehicleid, forplayerid); + +/** + * This callback is called when a player starts to enter a vehicle, meaning the + * player is not in vehicle yet at the time this callback is called. + * ID of the player who attempts to enter a vehicle + * ID of the vehicle the player is attempting to enter + * 0 if entering as driver. 1 if entering as passenger + * + * + * + * + * This callback is called when a player BEGINS to enter a vehicle, not when they HAVE + * entered it. See OnPlayerStateChange. + * This callback is still called if the player is denied entry to the vehicle (e.g. it is + * locked or full). + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnPlayerEnterVehicle(playerid, vehicleid, ispassenger); + +/** + * This callback is called when a player starts to exit a vehicle. + * The ID of the player that is exiting a vehicle + * The ID of the vehicle the player is exiting + * + * + * + * + * Not called if the player falls off a bike or is removed from a vehicle by other means such + * as using SetPlayerPos. + * You must use OnPlayerStateChange and check if their old + * state is PLAYER_STATE_DRIVER or PLAYER_STATE_PASSENGER and their new + * state is PLAYER_STATE_ONFOOT. + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnPlayerExitVehicle(playerid, vehicleid); + +/** + * This callback is called when a vehicle respawns. + * The ID of the vehicle that spawned + * + * + * + * + * + * 0 - Will prevent other filterscripts from receiving this callback.
    + * 1 - Indicates that this callback will be passed to the next filterscript.
    + * It is always called first in filterscripts. + *     + */ +forward OnVehicleSpawn(vehicleid); + +/** + * This callback is called when a vehicle is destroyed - either by exploding or becoming submerged + * in water. + * The ID of the vehicle that was destroyed + * 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 + * + * + * This callback can also be called by NPC. + * 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. + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnVehicleDeath(vehicleid, killerid); + +/** + * This callback is called when a vehicle is modded. + * The ID of the driver of the vehicle + * The ID of the vehicle which is modded + * The ID of the component which was added to the vehicle + * + * + * + * + * This callback is NOT called by AddVehicleComponent. + * + * Return 0 to desync the mod (or an invalid mod) from propagating and / or crashing + * players.
    + * It is always called first in gamemode so returning 0 there also blocks other filterscripts + * from seeing it. + *     + */ +forward OnVehicleMod(playerid, vehicleid, componentid); + +/** + * This callback is called when a player enters or exits a mod shop. + * The ID of the player that entered or exited the modshop + * 1 if the player entered or 0 if they exited + * The interior ID of the modshop that the player is entering (or 0 if exiting) + * + * + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * Players collide when they get into the same mod shop. + * + * This callback does not handle returns.
    + * It is always called first in filterscripts. + *     + */ +forward OnEnterExitModShop(playerid, enterexit, interiorid); + +/** + * 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. + * The ID of the player that changed the paintjob of their vehicle + * The ID of the vehicle that had its paintjob changed + * The ID of the new paintjob + * + * + * + * + * This callback is not called by ChangeVehiclePaintjob. + * + * This callback does not handle returns. Returning 0 won't deny the paintjob change.
    + * It is always called first in gamemode so returning 0 there blocks other filterscripts + * from seeing it. + *     + */ +forward OnVehiclePaintjob(playerid, vehicleid, paintjobid); + +/** + * 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. + * The ID of the player that is driving the vehicle + * The ID of the vehicle that was resprayed + * The color that the vehicle's primary color was changed to + * The color that the vehicle's secondary color was changed to + * + * + * + * + * + * Previewing a component inside a mod shop might call this callback. + * This callback is not called by ChangeVehicleColor. + * + * Returning 0 in this callback will deny the colour change. Returning 1 + * will allow it. This can be used to prevent hackers from changing vehicle colours using cheats.
    + * It is always called first in gamemode so returning 0 there also blocks other filterscripts + * from seeing it. + *     + */ +forward OnVehicleRespray(playerid, vehicleid, color1, color2); + +/** + * This callback is called when a vehicle element such as doors, tires, panels, or lights change + * their damage status. + * The ID of the vehicle that was changed its damage status + * The ID of the player who synced the change in the damage status (who had the + * car damaged or repaired) + * + * + * This callback was added in SA-MP 0.3a and will not work in earlier versions! + * This does not include vehicle health changes + * + * 1 - Will prevent other filterscripts from receiving this callback.
    + * 0 - Indicates that this callback will be passed to the next filterscript.
    + * It is always called first in filterscripts.
    + *     + */ +forward OnVehicleDamageStatusUpdate(vehicleid, playerid); + +/** + * 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. + * The ID of the vehicle that's position was updated + * The ID of the player that sent a vehicle position sync update + * 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 + * The new X coordinate of the vehicle. This parameter was added in 0.3z. + * Leave it out if using an earlier version + * The new Y coordinate of the vehicle. This parameter was added in 0.3z. + * Leave it out if using an earlier version + * The new Z coordinate of the vehicle. This parameter was added in 0.3z. + * Leave it out if using an earlier version + * The new X velocity of the vehicle. This parameter was added in 0.3z R4. + * Leave it out if using an earlier version + * The new Y velocity of the vehicle. This parameter was added in 0.3z R4. + * Leave it out if using an earlier version + * The new Z velocity of the vehicle. This parameter was added in 0.3z R4. + * Leave it out if using an earlier version + * + * This callback was added in SA-MP 0.3c R3 and will not work in earlier versions! + * 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. + * GetVehiclePos will return the old coordinates of the vehicle + * before this update. + * + * Returning 0 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.
    + * It is always called first in filterscripts so returning 0 there also blocks other + * scripts from seeing it. + *     + */ +forward OnUnoccupiedVehicleUpdate(vehicleid, playerid, passenger_seat, Float:new_x, Float:new_y, Float:new_z, Float:vel_x, Float:vel_y, Float:vel_z); + diff --git a/pawn.json b/pawn.json old mode 100755 new mode 100644 diff --git a/pawndoc.xsl b/pawndoc.xsl new file mode 100644 index 0000000..7b2e40c --- /dev/null +++ b/pawndoc.xsl @@ -0,0 +1,613 @@ + + + + + + + + +<xsl:value-of select="doc/assembly/name" /> + + + +

    +

    ==========================================

    + +
    + + + + +
    + +
    + + + + +
    + +
    + + + + +
    + +
    + + + + +
    + + + +
    + +
    + + + + +     + + + +
    +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    ## 


    +
    +
    +

    ### ``:

     +
    + + +

    #### Remarks


    + +     + +

    #### Members


    +
    +
    +
    +     + + +

    #### Used by


    +
    +     + +

    #### Fixes

    +
    +     + +

    #### Depends on

    +
    +     + +

    #### See Also

    +
    +     +
    +     + +

    ## 


    +
    +
    +

    ### ``:

     +

    + +

    + + + + + + +
    | **Value** | `` |
    +

    + +

    #### Remarks


    + +     + + +

    #### Used by


    +
    +     + +

    #### Fixes

    +
    +     + +

    #### Depends on

    +
    +     + +

    #### See Also

    +
    +     +
    +     + +

    ## 


    +
    +
    +

    ### ``:

     +
    + +

    #### Syntax



    ```pawn

    ```

    + +

    +     +

    + + +
    +

    + + +

    #### Remarks

    + +     + + +

    #### Used by

    +
    +     + +

    #### Fixes

    +
    +     + +

    #### Depends on

    +
    +     + +

    #### Attributes

    +
    +     + + +

    #### Transition table

    +

    + + + +
    SourceTargetCondition
    +


    +     + + +

    #### See Also


    +
    +     +
    +     + + + + +

    ## 


    +
    +
    +

    ### ``:

     +
    + +

    + + +
    +

    + +

    #### Remarks


    + +     + + +

    #### Used by


    +
    +     + +

    #### Fixes

    +
    +     + +

    #### Depends on

    +
    +     + +

    #### See Also

    +
    +     +
    +     +     +     + + + + + +
    +

    ### :

     +
    + +     +     +     + + + + +
  • * ` = `
    • +     +     +     + + +


    +     + + + + | `` |  | + + + + + `` + + + + + | **Tag** | `:` | + + + + + + | **Size** | `` | + + + + +

    #### Returns

    +


    +     + + +


    +     + + +

    #### Example

    +


    +     + + +
  • * ``
    • +     + + +
  • * #[``](#)
    • +     + + +
  • * #[``](#)
    • +     + + +

    #### Estimated stack usage

    +

    cells


    +     + + +

    #### Automaton

    +


    +     + + + + + + + + + + + 
    ```pawn

    ```

    +     + + + * #[``](#)
    +     + + + + + +`` + +** + +

     + +

     + +
  • * 
    •  + +


     + +


     + +

    ## 

     + +

    ### 

     + + +


    __________________________________________


    + +

    +

    ==========================================

    + +

    +

    ------------------------------------------

    +     +

    + +
    +

    ## Fixes


    + +
    +     + +
    + + + + + +
    + +
    + + + + + +
    + +
    + + + + + +
    + +
    + + + + + +
    +     + +
     + +
     +     + + + + []() + []() + + + + + #[``](#) + + + +
  • * #[``](#): 
    • +     + + +
  • * ``: Synonym for ``.
    • +     + + +

  • ####

    +
    • +     + + + + + +
    **Fixed in **
    +     + + +
    **Disabled By Default**
    +     +     + +

    #### Problem


    + +

    #### Solution


    + + +

    #### See


    +

    +     + +

    #### Author(s)


    +

    +     + +

    #### Post(s)


    +

    +     +     + + +
  • * []()
    • +     + +
  • * #[``](#)
    • +     + +
  • *  + + + []() + + + + + +
    • +     + +


    +     + +


    +     + + + + +
  • * #FIX_[](#FIX_)
    • +     + +     +