[SuperViper]

Introduction

This script adds some useful functions that the SA:MP team decided to not include in the default server package. This include requires your server to be running on 0.3e.


Functions

Function	Action	Returns
SetPlayerSpecialAction(playerid, actionid)	If the special action is USECELLPHONE or STOPUSECELLPHONE, it will automatically attach/detach the phone	1
IsPlayerInWater(playerid) or IsPlayerSwimming(playerid)	Checks if a player is swimming	1 if the player is swimming, otherwise 0
SetPlayerPosEx(playerid, Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0, Float: angle = 0.0)	Sets a player's position, virtual world, interior, and angle	1
GetPlayersName(playerid)	Gets the player's name	The player's name
GetPlayersNameEx(playerid)	Gets the player's name and removes the underscores	The player's name without underscores
CrashPlayer(playerid)	Crashes the player	1
GetPlayersIP(playerid)	Gets the player's IP	The player's IP
ExplodePlayer(playerid)	Explodes a player	1
ExplodeVehicle(vehicleid)	Explodes a vehicle	1
SetPlayerMoney(playerid, amount)	Sets the players money	1
GivePlayerJetpack(playerid)	Gives the player a jetpack	1
IsPlayerSpawned(playerid)	Checks if the player is spawned	1 if the player is spawned, otherwise 0
GetVehicleInfo(vehicleid, infoType)	Gets the status of one of the vehicle parameters (for infoType you can use VEHICLE_INFO_PARAMNAME)	The status of the vehicle parameter
SetVehicleInfo(vehicleid, infoType, value)	Sets the status of one of the vehicle paramters (for infoType you can use VEHICLE_INFO_PARAMNAME)	1
IsPlayerInVehicleFireMode(playerid)	Checks if the player is drivebying as a passenger	1 if the player is drivebying as a passenger, otherwise 0
GetVehicleDriver(vehicleid)	Gets the driver of the vehicle	The driver's ID
GetVehiclePassengers(vehicleid, &passengerOne = INVALID_PLAYER_ID, &passengerTwo = INVALID_PLAYER_ID, &passengerThree = INVALID_PLAYER_ID)	Gets the vehicle's passengers (will not retrieve more than the first 3 passengers for bus/coach)	The vehicle's passengers for each seat
GetVehicleNumberPlate(vehicleid)	Gets the vehicle's license plate	The vehicle's license plate
IsPlayerSpectating(playerid)	Checks if the player is spectating	1 if the player is spectating, otherwise 0
GetPlayerObjectEditingState(playerid)	Gets the player's object editing state (OBJECT_EDITING_STATE_NONE, NORMAL, PLAYER, ATTACHED)	The player's object editing state
GetPlayerEditingObject(playerid)	Gets the object the player is editing (attached object index if editing attached object)	The object the player is editing
RemovePlayerWeapon(playerid, weaponid)	Removes a weapon from a player	1
ClosePlayerDialog(playerid)	Closes a player's dialog	1
SetPlayerDeathEffect(playerid, deffid)	Sets the player's death effect (DEATH_EFFECT_NONE, REDGAS, SMOKE, EXPLODE, MINIEXPLODE, FIRE)	1
GetPlayerDeathEffect(playerid)	Gets the player's death effect	The player's death effect
DisableSprunkMachines()	Used in OnGameModeInit to remove all sprunk machines from the map	1
ChangeServerPassword(password[])	Changes the server password	1
LoadFilterscript(scriptName[], bool: reload = false)	Loads a filterscript	1
UnloadFilterscript(scriptName[])	Unloads a filterscript	1
ChangeServerName(serverName[])	Changes the server name	1
SendServerRCONMessage(message[])	Sends a message to the server via RCON 'say' command	1
SendMessageToRCONAdmins(color, message[])	Sends a message to all in-game RCON admins	1
ChangeServerWebsite(url[])	Changes the server's website URL	1
ChangeMapName(mName[])	Changes the server's map name	1
IsValidSkin(skinID)	Checks if the skin is valid	1 is the skin is valid, otherwise 0
ClearPlayersChat(playerid, bool: includeScrollingChat = false)	Clears the player's currently displayed chat or all chat	1
ClearAllPlayersChat(bool: includeScrollingChat = false)	Clears all of the player's currently displayed chat or all chat	1
TeleportPlayerToPlayer(playerid, giveplayerid, Float: offsetX = 1.0, Float: offsetY = 0.0, Float: offsetZ = 0.0)	Teleports a player to another player	1
StopVehicleMovement(vehicleid)	Smoothly stops a vehicle's movement	1
GetVehicleSpeed(vehicleid)	Gets the vehicle's speed	The vehicle's speed
GetVehicleModelName(modelID)	Gets the name of the vehicle model ID	The vehicle model ID's name
GetVehicleIDFromName(string[], bool: useFind = false)	Gets a vehicle's model ID from a name	The vehicle's model ID
GetWeaponID(weaponName[], bool: ignoreCase = true, bool: useFind = false)	Gets a weapon's ID from a weapon's name	The weapon's ID
GetPlayerIDFromIP(ip[], bool: useFind = false)	Gets the player ID that has specified IP	The player's ID
CountTotalPlayers()	Gets the amount of connected players	The amount of connected players
CountTotalRCONAdmins()	Gets the amount of connected RCON admins	The amount of connected RCON admins
CountTotalNPCs()	Gets the amount of connected NPCs	The amount of connected NPCs
CountTotalPausedPlayers()	Gets the amount of connected paused players	The amount of connected paused players
GetVehiclesAngle(vehicleid)	Gets the vehicle's angle	The vehicle's angle
GetVehiclesHealth(vehicleid)	Gets the vehicle's health	The vehicle's health
GetPlayersHealth(playerid)	Gets the player's health	The player's health
GetPlayersArmour(playerid)	Gets the player's armor	The player's armor
EnableWhitelist(mode = WHITELIST_MODE_ALLOWPLAYER, ip[] = "")	Enables RCON whitelisting with several modes (WHITELIST_MODE_NONE, ALLOWPLAYER, SPECIFICIP, IP_FIND)	1
GetWhitelistMode()	Gets the server's RCON whitelist mode	The server's RCON whitelist mode
AddPlayerToWhitelist(playerid)	Adds a player to the RCON whitelist	1
IsPlayerWhitelisted(playerid)	Checks if a player is on the RCON whitelist	1 if the player is on the RCON whitelist, otherwise 0
GetVehicleInterior(vehicleid)	Gets a vehicle's interior	The vehicle's interior
IsPlayerBehindVehicle(playerid, vehicleid)	Checks if a player is behind a vehicle	1 if the player is behind the vehicle, otherwise 0
ShakePlayerScreen(playerid, duration = 1250)	Shakes a player's screen	1
ReconnectPlayer(playerid)	Reconnects a player to the server without closing their game	1
GetVehicleTrailerCount(vehicleid)	Gets the amount of trailers attached to the vehicle	The amount of trailers attached to the vehicle
GetFreeVehicleSeat(vehicleid)	Gets the next free seat in a vehicle	If a seat is available, the seat id, otherwise INVALID_VEHICLE_ID
GetVehicleSpawnInfo(vehicleid, &Float: spawnX, &Float: spawnY, &Float: spawnZ, &Float: spawnR, &color1, &color2, &respawndelay)	Gets the information the vehicle was spawned with	The information the vehicle was spawned with
CapitalizePlayerName(playerid)	Capitalizes a player's name (including letters after underscores)	1
GetPlayerTemporaryName(playerid)	Gets a temporary name for the player if you need to use their name for something	The player's temporary name
GetStringCharacterCount(string[], character)	Gets the amount of the specified character in a string	The amount of the specified character in the string
SetVehiclePosEx(vehicleid, Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0, Float: angle = 0.0)	Sets a vehicle's position, rotation, interior, and virtual world	1
SendNearbyClientMessage(color, message[], Float: distance = 30.0, Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0)	Sends a client message to players near the specified point	1
GameTextForNearbyPlayers(text[], time, style, Float: distance = 30.0, Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0)	Displays game text on the screen of players that are near the specified point	1
ToggleNearbyPlayersControllable(bool: controllable, Float: distance = 30.0, Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0)	Toggles weather players near the point can move and turn their camera	1
TogglePlayerKickImmunity(playerid, bool: immune)	Decides weather the player can be kicked or not	1
GetPlayerKickImmunity(playerid)	Gets the player's kick immunity status	The player's kick immunity status
TogglePlayerBanImmunity(playerid, bool: immune)	Decides weather the player can be banned or not	1
GetPlayerBanImmunity(playerid)	Gets the player's ban immunity status	The player's ban immunity status
CreateTriggerPoint(Float: posX, Float: posY, Float: posZ, interior = 0, virtualworld = 0)	Creates an invisible trigger point at the specified location which calls OnPlayerTouchTrigger when a player touches it	The trigger's ID
StartCountdown(from = 3)	Starts a countdown for all players	The timer's ID
SendClientAudioMessage(playerid, message[], bool: withClientMessage = false, color = -1, language[] = "en")	Sends a message to the player in an audio stream (****** Translator)	1
DealPlayerDamage(playerid, damage)	Deals a certain amount of damage to a player (checks weather to take health, armor, or both)	1
TeleportPlayers(Float: posX, Float: posY, Float: posZ, interior, virtualworld, Float: angle, ...)	Teleports an unlimited amount of players to a location - Untested	1
CountTotalVehicles()	Gets the amount of vehicles created	The amount of vehicles created
IsVehicleOccupied(vehicleid)	Checks if the vehicle is occupied	0 if no, otherwise 1
IsPlayerDrivingVehicle(playerid, vehicleid = INVALID_VEHICLE_ID)	Checks if a player is driving a vehicle	0 if no, otherwise 1
TeleportPlayerToVehicle(playerid, vehicleid, Float: offsetX = 1.0, Float: offsetY = 0.0, Float: offsetZ = 0.0)	Teleports a player to a vehicle	1
GetPickupPos(pickupid, &Float: X, &Float: Y, &Float: Z)	Gets a pickup's position	1
GetPickupVirtualWorld(pickupid)	Gets a pickup's virtual world	1
HideAllTextDraws()	Hides all text draws for all players	1
HideAllTextDrawsForPlayer(playerid)	Hides all text draws for the specified player	1
GetSkinGender(skinid)	Get's the specified skin's gender	The skin's gender (SKIN_GENDER_NONE, SKIN_GENDER_MALE, SKIN_GENDER_FEMALE)
TogglePlayerWeaponSwitch(playerid, bool: togws)	Toggles weather the player can switch weapons or not	1
IsMeleeWeapon(weaponid)	Checks if the specified weapon is a melee weapon	1 if the weapon is a melee weapon, otherwise 0
IsPlayerPaused(playerid) or IsPlayerTabbed(playerid)	Checks if a player is paused	1 if the player is paused, otherwise 0
GetPlayerControllable(playerid)	Checks if a player can control himself	1 if the player can control himself, otherwise 0
divideRem(a, b, &answer, &remainder)	Divides two numbers and retrieves the answer with the remainder	1
CountTotalObjects()	Counts the total objects currently created on the server	The total objects currently created on the server
GetServerStats(&connections, &kicks, &vehicles, &objects, &players, &totalvehicles, &totalobjects, &kills, &deaths, &totaldamage, mode = SERVER_STATS_UPTIME, bool: errorContinue = true)	Retrieves the server's stats	1

Callbacks

Callback	Call Time
OnVehicleCreate(vehicleid)	Called when a vehicle is created (not respawned)
OnPlayerPausedUpdate(playerid, bool: paused)	Called when a player pauses or unpauses
OnPlayerWeaponUpdate(playerid, newgun, oldgun)	Called when a player changes their weapon
OnReceiveClientMessage(playerid, color, message[])	Called when a player receives a client message (includes audio stream message and does not include SendClientMessageToAll)
OnRconLoginBlocked(playerid, ip[], password[], success)	Called when a player is blocked by the RCON whitelist feature
OnPlayerWaterStatusUpdate(playerid, bool: inWater)	Called when a player enters or exits water
OnPlayerSpecialActionChange(playerid, oldaction, newaction)	Called when a player's special action changes (not yet working for sprunk and cigars)
OnPlayerTouchTrigger(playerid, triggerid)	Called when a player touches a trigger created with CreateTriggerPoint

Maximum Definitions

Definition	Value
MAX_INTEGER_LENGTH	12
MAX_IP_LENGTH	17
MAX_WEAPON_NAME	24
MAX_CLIENT_MESSAGE	128
MAX_WEAPON_AMMO	32767
MAX_INTEGER_VALUE	2147483647

Preset Variable Sizes

You can now define variables using a couple of new macros I have created. They have preset sizes specifically for the function they'll be used for.

Declaration	Size
S_IP[variable name]	17
S_Player[variable name]	MAX_PLAYER_NAME or 24
S_Weapon[variable name]	MAX_WEAPON_NAME (custom definition) or 24
S_Chat[variable name]	MAX_CLIENT_MESSAGE (custom definition) or 128

Bugs and Suggestions

Please reply to this thread with your bug report or suggestion for the include. All of these posts will be reviewed carefully and dealt with.


Versions

The download links and the include itself will be updated occasionally.

Version 1.4 - Pastebin | Mediafire | Assembla Direct Download
Version 1.3 - Pastebin | Mediafire | Assembla Direct Download
Version 1.2 - Pastebin | Mediafire | Assembla Direct Download
Version 1.1 - Pastebin | Mediafire | Assembla Direct Download
Version 1.0 - Pastebin | Mediafire | Assembla Direct Download



Don't want to wait for updates?

I'm currently uploading all of my changes to an Assembla account. Assembla will be updated before updates are released. If you wish to get the files directly from Assembla, use SVN Checkout with this URL: https://subversion.assembla.com/svn/sv-libraries/

My latest updates to Assembla are below:




Changelog

Version	Change
Version 1.4	Added preset variable sizes (more information available above)
Version 1.4	Added maximum value defines for several things (more information available above)
Version 1.4	Added the structure for the soon to come DisableLagShooting function
Version 1.4	Added GetServerStats function
Version 1.4	Added CountTotalObjects function
Version 1.4	Added divideRem function
Version 1.4	Added GetPlayerControllable function
Version 1.4	Added IsMeleeWeapon function
Version 1.4	Added IsPlayerPaused or IsPlayerTabbed function
Version 1.4	Added TogglePlayerWeaponSwitch function
Version 1.4	Added GetSkinGender function
Version 1.4	Added HideAllTextDrawsForPlayer function
Version 1.4	Added HideAllTextDraws function
Version 1.3	Added GetPickupVirtualWorld function
Version 1.3	Added GetPickupPos function
Version 1.3	Added TeleportPlayerToVehicle function
Version 1.3	Added IsPlayerDrivingVehicle function
Version 1.3	Added IsVehicleOccupied function
Version 1.3	Added CountTotalVehicles function
Version 1.3	Added TeleportPlayers function
Version 1.2	Added DealPlayerDamage function
Version 1.2	Added SendClientAudioMessage function
Version 1.2	Added StartCountdown function
Version 1.2	Added CreateTriggerPoint function
Version 1.2	Added TogglePlayerBanImmunity and GetPlayerBanImmunity functions
Version 1.2	Added TogglePlayerKickImmunity and GetPlayerKickImmunity functions
Version 1.2	Added ToggleNearbyPlayersControllable function
Version 1.2	Added GameTextForNearbyPlayers function
Version 1.2	Added SendNearbyClientMessage function
Version 1.2	Added SetVehiclePosEx function
Version 1.2	Added GetStringCharacterCount function
Version 1.2	Added GetPlayerTemporaryName function
Version 1.2	Added CapitalizePlayerName function
Version 1.2	Added GetVehicleSpawnInfo function
Version 1.2	Added GetFreeVehicleSeat function
Version 1.2	Added OnPlayerSpecialActionChange and OnPlayerTouchTrigger callbacks
Version 1.1	Added OnPlayerWaterStatusUpdate callback
Version 1.1	Added ReconnectPlayer and GetVehicleTrailerCount functions
Version 1.1	Removed IsPlayerInSpray function due to issues with camera mode detection
Version 1.0	Created the script

Using

To begin using this include, drag the file to your pawno > includes folder and put

pawn Код:

#include <svAddons>

at the top of your script.


Credits

SuperViper - Creating the script

[Shadow_]

Well done, some really useful functions. Granted some have been posted before, but great all the same.

[Dx2]

omg nice functions, thanks a lot

[Cacoby]

O: very userfull, tnx dude

[Basssiiie]

Код:

stock IsPlayerInSpray(playerid)
{
        return (GetPlayerCameraMode(playerid) == 15) ? 1 : 0;
}

Someone did not do his homework. This is very unreliable and the Wiki is quite wrong here. I regret that I can't change it, I don't have a Wiki account. (I have asked, no response.)

Yes, camera mode 15 is Pay & Spray. But Pay & Spray is not the only camera mode 15. I prefer calling camera mode 15 'scripted static camera'. It's used for a lot of different stuff, like:

• Entering and exiting interiors through the normal enex, the small cutscene of the player walking through the door is camera mode 15.
• The mod shops are camera mode 15.
• Some of the chasing sequences are camera mode 15.
• Buying food at fast food restaurants (Pizza shop, Burger Shot, Cluckin' Bell...) sets you in camera mode 15.
• SetPlayerCameraPos is camera mode 15.

They have all one thing in common: the location where the camera itself is located, isn't moving at all. (Like following a player, or attached to a vehicle) It's as static as it can be. The direction the camera is looking does change in some cases, for example with the chasing cameras.

[ikey07]

Really useful, thanks

[SuperViper]

Quote:

Originally Posted by Basssiiie Код: stock IsPlayerInSpray(playerid) { return (GetPlayerCameraMode(playerid) == 15) ? 1 : 0; } Someone did not do his homework. This is very unreliable and the Wiki is quite wrong here. I regret that I can't change it, I don't have a Wiki account. (I have asked, no response.) Yes, camera mode 15 is Pay & Spray. But Pay & Spray is not the only camera mode 15. I prefer calling camera mode 15 'scripted static camera'. It's used for a lot of different stuff, like: Entering and exiting interiors through the normal enex, the small cutscene of the player walking through the door is camera mode 15. The mod shops are camera mode 15. Some of the chasing sequences are camera mode 15. Buying food at fast food restaurants (Pizza shop, Burger Shot, Cluckin' Bell...) sets you in camera mode 15. SetPlayerCameraPos is camera mode 15. They have all one thing in common: the location where the camera itself is located, isn't moving at all. (Like following a player, or attached to a vehicle) It's as static as it can be. The direction the camera is looking does change in some cases, for example with the chasing cameras.

I don't focus on any function specifically making sure that it works just like wiki stated. I assume the wiki is correct because it's an official SA:MP wiki listed with every function. If it doesn't work, simply don't use it.

[MP2]

The SA:MP wiki is edited by anyone (that has an account) - so it's not OFFICIAL OFFICIAL.

[Invizion]

Nice man

[Firo]

Wonderful! 'ShakePlayerScreen' seems great for drunk players.

[TheArcher]

Very useful. Thanks for sharing.

Edit: Is possibile to Play 2 sounds at once? (Using AudioStream 0.3d function)

[Jochemd]

Good work. I'm only not sure if you're allowed to release a code to crash players.

[Littlehelper]

Some of them are not even 'Useful' but anyway.
Nice job.

[TheArcher]

Quote:

Originally Posted by Jochemd Good work. I'm only not sure if you're allowed to release a code to crash players.

Do you need any authorization to release a crash-player code? Since when? :/

[Roperr]

Thanks a lot for releasing this
Well done, this will surely help a lot of people and save a lot of time.

Quote:

Originally Posted by Jochemd Good work. I'm only not sure if you're allowed to release a code to crash players.

I believe that code could be used to make a /reconnect command.

[SuperViper]

Quote:

Originally Posted by TheArcher Very useful. Thanks for sharing. Edit: Is possibile to Play 2 sounds at once? (Using AudioStream 0.3d function)

There are no custom audio functions at the moment. I was planning to have audio looping and other features for it, but it kept crashing so I had to remove it for now.

It's not possible to play 2 sounds at once.

Quote:

Originally Posted by Jochemd Good work. I'm only not sure if you're allowed to release a code to crash players.

It's a function used by the server, why wouldn't it be allowed?

Quote:

Originally Posted by Roperr I believe that code could be used to make a /reconnect command.

It actually crashes the game, it can't be used for a /reconnect command, but I'll be adding a reconnect feature in version 1.1.

Quote:

Originally Posted by Y_Less Very good effort. Just one tiny minor point. The callback hooks should use "CallLocalFunction" not "CallRemoteFunction" or you could end up having callbacks being called multiple times if this include is used in multiple scripts.

I'll change that in version 1.1.

Quote:

Originally Posted by Littlehelper[MDZ] Some of them are not even 'Useful' but anyway. Nice job.

They might not be useful to you but other people might find a use for them.

[FireCat]

SetPlayerDeathEffect(playerid, deffid) Sets the player's death effect (DEATH_EFFECT_NONE, REDGAS, SMOKE, EXPLODE, MINIEXPLODE, FIRE) The player's IP
(:
Fix that "The player's IP"

[StreetGT]

good work.

[Jochemd]

Quote:

Originally Posted by TheArcher Do you need any authorization to release a crash-player code? Since when? :/

Not sure, but in fact you are bugging the client. And why would you want to CRASH players? Just kick them.

The reconnect code is different; it bans the IP, and unbans it straight away.

[SuperViper]

Feel free to post all the functions you wish to post that you think would be beneficial to others. Use the following format:

Код HTML:

Function: FunctionName(parameters)
Action: This function does something with the parameters
Returns: This function always returns 1.

[PAWN]FunctionName(parameters)
{
}[/PAWN]