[Include] svAddons - Useful Scripting Addons - SA-MP Forums

SuperViper · 03/06/2012, 11:14 PM

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 (Google 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 Code:

#include <svAddons>

at the top of your script.

Credits

SuperViper - Creating the script

Shadow_ · 03/06/2012, 11:18 PM

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

Dx2 · 03/06/2012, 11:23 PM

omg nice functions, thanks a lot

Cacoby · 03/06/2012, 11:59 PM

O: very userfull, tnx dude

Basssiiie · 04/06/2012, 12:28 AM

Code:

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 · 04/06/2012, 01:01 AM

Really useful, thanks

SuperViper · 04/06/2012, 01:27 AM

Quote:

Originally Posted by Basssiiie

Code:

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 · 04/06/2012, 01:29 AM

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

Y_Less · 04/06/2012, 10:38 AM

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.

Invizion · 04/06/2012, 10:41 AM

Nice man

03/06/2012, 11:18 PM	#2
Shadow_ Gangsta Join Date: Nov 2008 Location: Vatican City Posts: 528 Reputation: 37	Re: svAddons - Useful Scripting Addons Well done, some really useful functions. Granted some have been posted before, but great all the same. __________________

03/06/2012, 11:23 PM	#3
Dx2 Little Clucker Join Date: May 2012 Location: Uruguay Posts: 44 Reputation: 0	Respuesta: svAddons - Useful Scripting Addons omg nice functions, thanks a lot

03/06/2012, 11:59 PM	#4
Cacoby Huge Clucker Join Date: Jul 2010 Posts: 223 Reputation: 0	Re: svAddons - Useful Scripting Addons O: very userfull, tnx dude

04/06/2012, 12:28 AM	#5
Basssiiie Gangsta Join Date: Mar 2011 Location: The Netherlands Posts: 726 Reputation: 138	Re: svAddons - Useful Scripting Addons Code: 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. __________________ Media: Tablet / iPad look-a-like in SA-MP Advanced Fireworks - build your own firework shows! April Fools' Day - Upside Down Island Debug Textdraws with Player, Vehicle & Server Info Releases: Random Race Generator

04/06/2012, 01:01 AM	#6
ikey07 Gangsta Join Date: Jul 2010 Location: Latvia,Riga Posts: 728 Reputation: 74	Re: svAddons - Useful Scripting Addons Really useful, thanks __________________

04/06/2012, 01:29 AM	#8
MP2 Godfather Join Date: Jan 2011 Location: England Posts: 5,265 Reputation: 748	Re: svAddons - Useful Scripting Addons The SA:MP wiki is edited by anyone (that has an account) - so it's not OFFICIAL OFFICIAL. __________________ >> Click here for ALL of my releases mGates - Create AUTOMATIC gates with ONE FUNCTION (+ restrictions i.e. team members only) IEE (Interior Enter/Exits) - Create enex markers with one function Cuffs - Cuff offsets for ALL SKINS! vfunc - Vehicle functions. GetVehicleColor and synced random colors. gBug - Prevent the 'G' bug (players being able to enter moving vehicles by pressing G then running after them).

04/06/2012, 10:38 AM	#9
Y_Less Beta Tester Join Date: Jun 2008 Location: 629 Posts: 13,319 Reputation: 1910	Re: svAddons - Useful Scripting Addons 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. __________________ YSI.tl All My Topics

04/06/2012, 10:41 AM	#10
Invizion Little Clucker Join Date: Apr 2012 Posts: 17 Reputation: 0	AW: svAddons - Useful Scripting Addons Nice man __________________

Thread Tools
Show Printable Version Email this Page
Display Modes
Linear Mode Switch to Hybrid Mode Switch to Threaded Mode

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
[FilterScript] Nice Addons For Gym	kuberaland	Filterscripts	4	25/04/2011 03:26 PM
[FS/MAP]Area 51 Addons (Decide to release now)	HlHl	Filterscripts	2	14/03/2010 05:25 AM
[FS/MAP]Area 51 Addons	HlHl	Filterscripts	3	02/03/2010 10:38 AM
[Map] [MAP] Unity Station Addons	RastamaN[BzD]	Maps	11	11/12/2009 04:51 AM
Useful FireFox addons :D [List on first post :P ]	Rozzie	Everything and Nothing	19	18/01/2009 10:16 PM