Multi Theft Auto: Wiki - User contributions [en]

CreatePickup

2012-07-20T08:45:31Z

VWOer:

__NOTOC__
{{Server client function}}
This function creates a pickup element, which is placed in the GTA world and can be picked up to retrieve a health, armour or a weapon.

==Syntax==
<syntaxhighlight lang="lua">
pickup createPickup ( float x, float y, float z, int theType, int amount/weapon/model, [ int respawnTime = 30000, int ammo = 50 ] )
</syntaxhighlight>

===Required Arguments===
* '''x''': A floating point number representing the X coordinate on the map.
* '''y''': A floating point number representing the Y coordinate on the map.
* '''z''': A floating point number representing the Z coordinate on the map.
* '''theType''': This is an integer representing the type of pickup, representing the following types:
** '''0''': Health Pickup
** '''1''': Armour Pickup
** '''2''': Weapon Pickup
** '''3''': Custom Pickup
* '''amount''': This is an integer representing the amount of Health points or Armour points a pickup has.
'''OR'''
* '''weapon''': If the type is a Weapon pickup, then it represents the [[Weapon|weapon ID]] of the weapon pickup. When used with the weapon pickup type set, the ammo parameter must be filled in as well.
'''OR'''
* '''model''': If the pickup is a custom model, this is the model id to use. Many non-pickup models can be used, though some may cause crashes. The following is a list of models designed to be used as pickups.
** '''370:''' Jetpack
** '''1212:''' Money (Wad of Cash)
** '''1240:''' Health (heart)
** '''1242:''' Armour
** '''1272:''' House (blue)
** '''1273:''' House (green)
** '''1274:''' Money (dollar symbol)
** '''1277:''' Save (floppy disk)

===Optional Arguments===
{{OptionalArg}}
* '''respawnTime''': How long before the pickup respawns in milliseconds
* '''ammo''': An integer representing the amount of ammo a pickup contains. This is only valid when the pickup type is a Weapon Pickup, and must be entered.

===Returns===
Returns [[pickup]] [[element]] if the pickup was created succesfully, otherwise returns ''false''.

==Example==
<section name="Server" class="server" show="true">
This example creates a pickup after a player dies so that he drops his weapon.
<syntaxhighlight lang="lua">
function createDeathPickup ( totalammo, killer, killerweapon, bodypart ) --when a player dies
x, y, z = getElementPosition ( source ) --get the position of the person who died and define it as x, y and z
currentweapon = getPlayerWeapon ( source ) --get the current weapon of the dead person
createPickup ( x, y, z, 2, currentweapon, 10000, totalammo )
end
addEventHandler ( "onPlayerWasted", getRootElement(), createDeathPickup ) --add an event handler for onPlayerWasted
</syntaxhighlight>
</section>

==See Also==

{{Pickup functions}}

GetPedAmmoInClip

2011-11-22T16:20:18Z

VWOer:

__NOTOC__
{{Server client function}}
This function returns an integer that contains the ammo in a specified [[ped]]'s weapon. See [[weapon|Weapon Info]]

==Syntax==
<syntaxhighlight lang="lua">
int getPedAmmoInClip ( ped thePed [, int weaponSlot = current ] )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] whose ammo you want to check.

===Optional Arguments===
*'''weaponSlot:''' an integer representing the weapon slot (set to the ped's currently selected slot if not specified).

===Returns===
Returns an [[int]] containing the amount of ammo in the specified ped's currently selected or specified clip, or 0 if the ped specified is invalid.

==Example==
This example outputs the amount of ammo the specified player has in his current slot. For example: 'ammo someguy'.
<syntaxhighlight lang="lua">
function showAmmo( command, who )
local targetPlayer = getPlayerFromName ( who )
if ( thePlayer ) then
local ammo = getPedAmmoInClip ( targetPlayer )
outputChatBox ( who .. " has " .. ammo .. " ammo in his active clip" )
else
outputChatBox ( "Player '" .. who .. "' not found." )
end
end
addCommandHandler( "ammo", showAmmo )
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}

GetBanSerial

2011-11-22T16:20:06Z

VWOer:

__NOTOC__
{{Server function}}
This function will return the [[serial]] of the specified [[ban]].

==Syntax==
<syntaxhighlight lang="lua">
string getBanSerial ( ban theBan )
</syntaxhighlight>

===Required Arguments===
*'''theBan:''' The [[ban]] you want to retrieve the serial of.

===Returns===
Returns a ''string'' of the serial if everything was successful, ''false'' if invalid arguments are specified or if there was no serial specified for the [[ban]].

==Example==
This example will show the user who banned a player the serial of that banned player.
<syntaxhighlight lang="lua">
function banPlayerCommand ( thisPlayer, commandName, bannedName, reason )
if ( hasObjectPermissionTo ( thisPlayer, "function.banPlayer" ) ) then -- If the command user has the rights
local bannedPlayer = getPlayerFromName ( bannedName ) -- Get the ID from the player who gets banned
if getElementType ( bannedPlayer ) == "player" then -- If it's a player
local theBan = banPlayer ( bannedPlayer, thisPlayer, reason ) -- Ban the player
outputChatBox ( "ban: " .. bannedName .. " successfully banned", thisPlayer ) -- Send the banner a succes message
outputChatBox ( "At Serial: " ..getBanSerial ( theBan ), thisPlayer ) -- And send him the serial of the banned player
end
else
outputChatBox ( "ban: You don't have enough permissions", thisPlayer ) -- If the command user doesn't have the permissions
end
end
addCommandHandler ( "ban", banPlayerCommand )
</syntaxhighlight>

==See Also==
{{Admin functions}}
[[ru:getBanSerial]]

SetPlayerName

2011-11-22T16:19:58Z

VWOer:

{{Server function}}
__NOTOC__
This function changes the specified [[player]]'s name.

==Syntax==
<syntaxhighlight lang="lua">
bool setPlayerName ( player thePlayer, string newName )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' the [[player]] that will have its name set.
*'''newName:''' the new name to set for the player.

===Returns===
Returns ''true'' if the player name was changed succesfully, ''false'' if invalid arguments are specified.

===Limits===
* Only ASCII characters between 33 and 126 are allowed (basic latin):
<nowiki>!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~</nowiki>
* Minimal player name length is 1 character.
* Maximum player name length is 22 characters.
* Player names are case-insensitive. It is not possible to have two clients with same name but different character case.

==Example==
<section name="Server" class="server" show="true">
This example adds a tag before a player's nickname via a /changetag command
<syntaxhighlight lang="lua">

-- Define the function for this command (/changetag, as defined below)
-- source = the player that triggered this command
-- command = the command passed into the function (changetag)
-- thePlayer = the player that you wish to add a tag to
-- tag = the tag to add to the players nickname
function tagPlayer ( source, command, thePlayer, tag )
-- Attempt to grab the element id for the player from the parsed name.
local sPlayerElement = getPlayerFromName ( thePlayer )
-- Check to see if the player were changing the tag for exists.
if ( sPlayerElement ) then
-- make sure that the element type of thePlayer is acctually pointing to a player element
if getElementType ( sPlayerElement ) == "player" then
-- we store the player's current name,
local oldName = getPlayerName ( sPlayerElement )
-- append the tag passed to this function before it
local taggedName = tag .. oldName
-- then set it as his new name
setPlayerName ( sPlayerElement, taggedName )
-- Tell the player who triggerd the command that the tag has been applied
outputChatBox ( "Player " .. thePlayer .. "'s tag changed to " .. taggedName, source )
end
else
-- Tell the player who triggerd the command that the player could not be found
outputChatBox ( "Unable to change player tag: Player " .. thePlayer .. " not found", source )
end
end
-- Add a command handler for either the console or / chat commands
-- Example: /changetag <playername> <tag>
addCommandHandler ( "changetag", tagPlayer )
</syntaxhighlight>
</section>

==See Also==
{{Player functions}}
[[ru:setPlayerName]]

IsPlayerNametagShowing

2011-11-22T16:19:20Z

VWOer:

__NOTOC__
{{Server client function}}
{{Deprecated feature|3|1.0|Serverside only in DP2.x}}

This function will allow you to determine if a player's name tag is currently showing.

==Syntax==

<syntaxhighlight lang="lua">
bool isPlayerNametagShowing ( player thePlayer )
</syntaxhighlight>

===Required Arguments===

*'''thePlayer:''' The player whose current name tag condition you want to check

===Returns===

Returns ''true'' if the player's name tag is being shown, ''false'' otherwise.

==Example==

This example toggles a player's nametag. If no playername is given, it toggles the nametag of the player who entered the command.

<syntaxhighlight lang="lua">
function toggleNametag ( sourcePlayer, command, who )
local tplayer = sourcePlayer -- by default, toggle the name tag of the player who issued the command
if ( who ) then -- if there was a nick entered in the command
tplayer = getPlayerFromName ( who ) -- search for the player
else
whoNick = getPlayerName(sourcePlayer)
end
if ( tplayer ~= false ) then -- if the player was found (or no playername was entered)
if isPlayerNametagShowing ( tplayer ) then -- if the nametag is shown
setPlayerNametagShowing ( tplayer, false ) -- hide it
outputChatBox ( who .. "'s nametag is now hidden", sourcePlayer ) -- output a message to the player who entered the command
else -- if the nametag is not shown
setPlayerNametagShowing ( tplayer, true ) -- show it
outputChatBox ( who .. "'s nametag is now showing", sourcePlayer ) -- output a message to the player who entered the command
end
else
outputChatBox ( "Player not found.", sourcePlayer )
end
end
addCommandHandler ( "toggleNametag", toggleNametag )
</syntaxhighlight>

==See Also==

{{Player_functions}}

IsPlayerNametagShowing

2011-11-22T16:19:10Z

VWOer:

GetWaterLevel

2011-11-22T16:17:57Z

VWOer:

__NOTOC__
{{Client function}}
This function allows you to retrieve the water level from a certain location. The water level is 0 in most places though it can vary (e.g. it's higher near the dam).

''Note: Some small water areas within parts of the city do not count as water to be used with this function. For example, the shallow water area in Northwest San Fierro.''

==Syntax==
<syntaxhighlight lang="lua">
float getWaterLevel ( float posX, float posY, float posZ [ , bool bCheckWaves = false ] )
float getWaterLevel ( water theWater )
</syntaxhighlight>

===Required Arguments===
*'''x:''' The X axis position
*'''y:''' The Y axis position
*'''z:''' The Z axis position

''or:''
*'''theWater:''' the water element

===Optional Arguments===
*'''bCheckWaves''' ask arc_

===Returns===
Returns ''false'' if there's no water in that location or the water level as an ''integer'' if you're near the water (-3 to 20 on the Z coordinate).

==Example==
This example will tell you what's the water level where the specified player is located.
<syntaxhighlight lang="lua">
function scriptGetLevel ( command, playername ) --when getlevel is called
local thePlayer = getPlayerFromName ( playername ) --get the player from nickname
if ( thePlayer ~= false ) then --if there is a player from the nickname
local x, y, z = getElementPosition ( thePlayer ) -- get his position
local level = getWaterLevel ( x, y, z )
if level then -- if it's not false
level = z - level -- calculate how far away is he from the water
outputChatBox( "You are " .. level .. " units away from the water!", source )
else outputChatBox ( "There's no sign of water" )
end
else outputChatBox ( "Player does not exist" )
end
end
addCommandHandler( "getlevel", scriptGetLevel ) -- add a command "getloc" which
</syntaxhighlight>

==See Also==
{{Client water functions}}

BanPlayer

2011-11-22T16:17:12Z

VWOer:

__NOTOC__
{{Server function}}
{{New feature|3|1.0|
This function will ban the specified player by either IP, [[serial]] or username
}}

{{Deprecated_feature|3|1.0|
This function will ban the specified player from the server by IP.
}}

==Syntax==
{{New feature|3|1.0|
<syntaxhighlight lang="lua">
ban banPlayer ( player bannedPlayer, [ bool IP = true, bool Username = false, bool Serial = false,
player responsiblePlayer = nil, string reason = nil, int seconds = 0 ] )
</syntaxhighlight>
}}

{{Deprecated_feature|3|1.0|
<syntaxhighlight lang="lua">
bool banPlayer ( player bannedPlayer , [ element responsibleElement, string reason ] )
</syntaxhighlight>
}}

===Required Arguments===
*'''bannedPlayer:''' The player that will be banned from the server.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''IP:''' Will player be banned by IP?
*'''Username:''' Will player be banned by username?
*'''Serial:''' Will player be banned by serial?

:'''Note:''' to ban by username or serial, ''verifyserials'' must be enabled in the server configuration file.

}}
*'''responsibleElement:''' The element that is responsible for banning the player. This can be a player or the root ([[getRootElement]]()) (Maximum 30 characters if using a string).
*'''reason:''' The reason the player will be banned from the server.
*'''seconds:''' The amount of seconds the player will be banned from the server for. This can be 0 for an infinite amount of time.

===Returns===
{{Deprecated_feature|3|1.0|
Returns ''true'' if the player was banned succesfully, ''false'' if invalid arguments are specified.
}}

{{New feature|3|1.0|
Returns a [[ban]] object if banned successfully, or ''false'' if unsuccessful.
}}

==Example==
This example lets a player ban anyone if he has ACL rights.
<syntaxhighlight lang="lua">
--Add the "ban" command handler
-- Example with the player
function banPlayerCommand ( theClient, commandName, bannedName, reason )

-- Give the player a nice error if he doesn't have rights
if ( hasObjectPermissionTo ( theClient, "function.banPlayer" ) ) then
--Get player element from the name
local bannedPlayer = getPlayerFromName ( bannedName )

--Ban the player
banPlayer ( bannedPlayer, theClient, reason )
outputChatBox ( "ban: " .. bannedName .. " successfully banned", theClient )

else
outputChatBox ( "ban: You don't have enough permissions", theClient )
end

end
addCommandHandler ( "ban", banPlayerCommand )

-- Example function with the root element. Here you would pass a player element to the function.
function banCheater(theCheater)
banPlayer(theCheater, getRootElement(), "You are banned because of cheating.")
end
</syntaxhighlight>

==See Also==
{{Admin_functions}}
[[es:banPlayer]]
[[ru:BanPlayer]]

KickPlayer

2011-11-22T16:17:04Z

VWOer:

{{Server function}}
__NOTOC__
This function will kick the specified player from the server.

==Syntax==
<syntaxhighlight lang="lua">
bool kickPlayer ( player kickedPlayer, [ player responsiblePlayer, string reason = "" ] )
</syntaxhighlight>
''or''
<syntaxhighlight lang="lua">
bool kickPlayer ( player kickedPlayer, [ string reason = "" ] )
</syntaxhighlight>

===Required Arguments===
*'''kickedPlayer:''' The player that will be kicked from the server

===Optional Arguments===
{{OptionalArg}}
*'''responsiblePlayer:''' The player that is responsible for the event. '''Note''': If left out as in the second syntax, responsible player for the kick will be "Console" (Maximum 30 characters if using a string).
*'''reason:''' The reason for the kick.

===Returns===
Returns ''true'' if the player was kicked succesfully, ''false'' if invalid arguments are specified.

==Example==
This example lets a player kick anyone who has a lower level.
<syntaxhighlight lang="lua">
function kickPlayerHandler ( sourcePlayer, commandname, kickedname, reason )
-- Get player element from the name
local kicked = getPlayerFromName ( kickedname )
-- If the client who sent the command has a higher level
if ( hasObjectPermissionTo ( sourcePlayer, "function.kickPlayer" ) ) then
-- Kick the player
kickPlayer ( kicked, sourcePlayer, reason )
end
end
-- Add the "kick" command handler
addCommandHandler ( "kick", kickPlayerHandler )
</syntaxhighlight>

==See Also==
{{Admin_functions}}
[[es:kickPlayer]]
[[ru:kickPlayer]]

GetZoneName

2011-11-22T16:16:56Z

VWOer:

__NOTOC__
{{Server client function}}
This function allows you to retrieve the zone name of a certain location.

==Syntax==
<syntaxhighlight lang="lua">
string getZoneName ( float x, float y, float z, [bool citiesonly=false] )
</syntaxhighlight>

===Required Arguments===
*'''x:''' The X axis position
*'''y:''' The Y axis position
*'''z:''' The Z axis position

===Optional Arguments===
{{OptionalArg}}
* '''citiesonly''': An optional argument to choose if you want to return the city name (eg Las Venturas)

===Returns===
Returns the string of the zone name

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example shows you how to return a zone name by doing /loc x y z in the chatbox or just loc x y z in console ( replace x, y and z with the co-ords you wanna check, eg /loc 1200 523 12.3 )
<syntaxhighlight lang="lua">
function playerLoc ( source, command, x, y, z )
local location = getZoneName ( x, y, z )
outputChatBox ( "* Location: " .. location, getRootElement(), 0, 255, 255 ) -- Output the zone name
end
addCommandHandler( "loc", playerLoc )
</syntaxhighlight>

'''Example 2:''' This example will tell you what zone a specified player is in when the "getloc" console command is used.
<syntaxhighlight lang="lua">
function scriptGetLoc ( source, command, playername ) --when getloc is called
local thePlayer = getPlayerFromName ( playername ) --get the player from nickname
if ( thePlayer ~= false ) then --if there is a player from the nickname
local x, y, z = getElementPosition ( player )
local location = getZoneName ( x, y, z )
local city = getZoneName ( x, y, z, true )
outputChatBox ( playername .. " is at " .. location .. " (" .. city .. ")", source ) --announce his zone
else outputChatBox ( "Player does not exist" )
end
end
addCommandHandler( "getloc", scriptGetLoc ) -- add a command "getloc" which initiates "scriptGetloc" function
</syntaxhighlight>
</section>

==See Also==
{{World functions}}

[[ru:getZoneName]]

RemoveAccount

2011-11-22T16:16:48Z

VWOer:

{{Server function}}
__NOTOC__
This function is used to delete existing player accounts.

==Syntax==
<syntaxhighlight lang="lua">
bool removeAccount ( account theAccount )
</syntaxhighlight>

===Required Arguments===
*'''theAccount:''' The account you wish to remove

===Returns===
Returns ''true'' if account was successfully removed, ''false'' if the account does not exist.

==Example==
This example does...
<syntaxhighlight lang="lua">
function onCmdRemove ( playerSource, commandName, playerName )
-- Lets make sure they didn't put nothing for the playername
if playerName ~= nil then
-- Lets get the player from the nick provided
local targetPlayer = getPlayerFromName ( playerName )
-- Checking if the player actually exists
if targetPlayer ~= nil then
-- grab the accounts
local sourceAccount = getPlayerAccount ( playerSource )
local targetAccount = getPlayerAccount ( targetPlayer )
-- Now check to see if the player has greater priviledges (or levels)
if getAccountLevel ( sourceAccount ) > getAccountLevel ( targetAccount ) then
removeAccount ( targetAccount )
outputChatBox ( getPlayerName ( playerSource ) .. " removed " .. playerName .. "'s account" )
else
outputChatBox ( "You don't have authority to remove " .. playerName .. "'s account", playerSource )
end
else
outputChatBox ( "There is no player by the name of " .. playerName, playerSource )
end
else
outputChatBox ( "USAGE: /remove [playername]", playerSource )
end
end

addCommandHandler("remove",onCmdRemove)
</syntaxhighlight>

==See Also==

{{Account_functions}}

ShowCursor

2011-11-22T16:16:40Z

VWOer:

__NOTOC__
{{Server client function}}
This function is used to show or hide a [[player]]'s cursor.

Note that, regardless of the cursor state you set using this function, the cursor will always be visible while the menu, the chatbox input line or the console are active, or if another resource has called this function.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( player thePlayer, bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you want to show or hide the cursor of.
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
}}

</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool showCursor ( bool show, [ bool toggleControls = true ] )
</syntaxhighlight>

===Required Arguments===
*'''show:''' A boolean value determining whether to show (''true'') or hide (''false'') the cursor.

===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''toggleControls:''' A boolean value determining whether to disable controls whilst the cursor is showing. ''true'' implies controls are disabled, ''false'' implies controls remain enabled.
}}

</section>

===Returns===
Returns ''true'' if the player's cursor was shown or hidden successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example shows the cursor for a player named "Dave", then outputs a message if it was shown successfully.
<syntaxhighlight lang="lua">
local thePlayer = getPlayerFromName ( "Dave" ) -- get the player named Dave
if thePlayer then -- if we got him
showCursor ( thePlayer, true ) -- make his cursor show
if isCursorShowing ( thePlayer ) then -- did it show?
outputChatBox ( "Cursor is now showing for Dave." ) -- print a message to the chat box
end
end
</syntaxhighlight>
</section>

<section name="Client" class="client" show="true">
This example shows the cursor all the time
<syntaxhighlight lang="lua">
showCursor ( true ) -- Shows cursor
showCursor ( false ) -- Doesnt Show Cursor
</syntaxhighlight>
</section>

==See Also==
{{Cursor_functions}}

IsPlayerMapForced

2011-11-22T16:16:30Z

VWOer:

__NOTOC__
{{Server client function}}
This function checks if the specified player's radar map has been forced on or not.

==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">bool isPlayerMapForced ( player thePlayer )</syntaxhighlight>

===Required Arguments===
* '''thePlayer:''' A [[player]] object referencing the specified player

===Returns===
Returns ''true'' if the player's radar map is forced on, ''false'' otherwise.
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">bool isPlayerMapForced ()</syntaxhighlight>

===Returns===
Returns ''true'' if the local player's radar map is forced on, ''false'' otherwise.
</section>

==Example==
<section name="Server" class="server" show="true">
This example forces a players radar map on for 10 seconds if it hasn't been already.
<syntaxhighlight lang="lua">
function forceMapForPlayer ( callingPlayer, command, whoNick )
local who = getPlayerFromName ( whoNick ) -- Look up the specified player
if ( who ) then
if ( not isPlayerMapForced ( who ) ) then -- if his radar map isn't already forced on
forcePlayerMap ( who, true ) -- force it on
setTimer ( forcePlayerMap, 10000, 1, who, false ) -- force it off in 10secs
outputChatBox ( "Forcing Map for " .. whoNick, callingPlayer ) -- output a message to the one who entered the command
else
outputChatBox ( "Map already forced for " .. whoNick, callingPlayer ) -- if the map is already forced, output a message
end
else
outputChatBox ( "Couldn't find " .. whoNick, callingPlayer ) -- if the player wasn't found, output a message
end
end
addCommandHandler ( "forcemap", forceMapForPlayer ) -- add a command handler
</syntaxhighlight>
</section>

==See Also==
{{Player functions}}

SetElementVelocity

2011-11-22T16:15:58Z

VWOer:

{{Server client function}}
__NOTOC__
This function sets the velocity (movement speeds) along each axis, for an element.

This is not compatible with all elements. The following elements are compatible:
* [[Ped]]s
* [[Vehicle]]s
* [[Object]]s (Clientside only)
* [[Projectile]]s (Clientside only)

==Syntax==
<syntaxhighlight lang="lua">bool setElementVelocity ( element theElement, float speedX, float speedY, float speedZ )</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The [[element]] you wish to set the velocity of.
*'''speedX:''' A floating point value determining the speed along the X axis.
*'''speedY:''' A floating point value determining the speed along the Y axis.
*'''speedZ:''' A floating point value determining the speed along the Z axis.

===Returns===
Returns ''true'' if the speed was set successfully, ''false'' if a bad element was specified or other bad arguments.

==Example==
This example 'copies' the speed of a specific player (called ''someguy'' in this example) to another player (called ''Ted'' in this example).

<syntaxhighlight lang="lua">
speedx, speedy, speedz = getElementVelocity ( getPlayerFromName ( "someguy" ) ) -- get the velocity of the player named "someguy"
setElementVelocity ( getPlayerFromName ( "Ted" ), speedx, speedy, speedz ) -- copy the velocity to a player named "Ted"
</syntaxhighlight>

==See Also==
{{element functions}}

GetElementData

2011-11-22T16:15:42Z

VWOer:

__NOTOC__
{{Server client function}}
This function retrieves [[element data]] attached to an element under a certain key.

==Syntax==
<syntaxhighlight lang="lua">var getElementData ( element theElement, string key [, inherit = true] )</syntaxhighlight>

===Required Arguments===
*'''theElement:''' This is the element with data you want to retrieve.
*'''key:''' The name of the element data entry you want to retrieve. (Maximum 31 characters.)

===Optional Arguments===
*'''inherit:''' - toggles whether or not the function should go up the hierarchy to find the requested key in case the specified element doesn't have it.

===Returns===
This function returns a ''variable'' containing the requested element data, or ''false'' if the element or the element data does not exist. When getting data corresponding to a XML attribute, this is always a ''string''.

==Example==
This example stores the tick count when a player joins and then allows players to see how long they are connected using a console function 'joinTime'.
<section show="true" name="Server" class="server">
<syntaxhighlight lang="lua">
function joinTime ( )
setElementData ( source, "joinTime", getTickCount() ) -- Store the current tick count in the player's data with the key 'joinTime'
end
-- Make our 'joinTime' function be called when a player joins
addEventHandler ( "onPlayerJoin", getRootElement(), joinTime )

function showJoinTime ( source, commandName, playerName )
if ( playerName ) then -- see if a player was specified
thePlayer = getPlayerFromName ( playerName ) -- get the player element for the specified player
if ( thePlayer ) then -- if one was found...
local timeOnline = (getTickCount() - getElementData ( thePlayer, "joinTime" )) / 1000 -- calculates the time since join
outputChatBox ( getPlayerName ( thePlayer ).." joined "..timeOnline.." seconds ago", source ) -- output the player's join time
else
outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
end
else
-- display when the player who used the function joined and inform how to see other people's join time
local timeOnline = (getTickCount() - getElementData ( source, "joinTime" )) / 1000 -- calculate the time since join
outputChatBox ( "You joined " ..timeOnline.." seconds ago", source )
outputChatBox ( "Use 'join_time <player name>' to see other people's join time", source )
end
end
-- Add a console command joinTime, that takes an optional parameter of a player's name
addCommandHandler ( "joinTime", showJoinTime )
</syntaxhighlight>
</section>

==See Also==
{{Element functions}}

MoveObject

2011-11-22T16:15:28Z

VWOer:

{{Server client function}}
__NOTOC__
This function will smoothly move an object from its current position to a specified rotation and position.

==Syntax==
<syntaxhighlight lang="lua">
bool moveObject ( object theObject, int time,
float targetx, float targety, float targetz,
[ float moverx, float movery, float moverz,
string strEasingType, float fEasingPeriod, float fEasingAmplitude, float fEasingOvershoot ] )
</syntaxhighlight>

===Required Arguments===
* '''theObject:''' The object that will be moved.
* '''time:''' The time in milliseconds the object will arrive at the destination.
* '''targetx:''' The X value of the target position
* '''targety:''' The Y value of the target position
* '''targetz:''' The Z value of the target position

===Optional Arguments===
* '''moverx:''' The rotation along the X axis '''relative''' to its current rotation, which is its starting angle.
* '''movery:''' The rotation along the Y axis '''relative''' to its current rotation, which is its starting angle.
* '''moverz:''' The rotation along the Z axis '''relative''' to its current rotation, which is its starting angle.
*'''strEasingType:''' the [[Easing|easing function]] to use for the interpolation (default is "Linear")
*'''fEasingPeriod:''' the period of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingAmplitude:''' the amplitude of the [[Easing|easing function]] (only some easing functions use this parameter)
*'''fEasingOvershoot:''' the overshoot of the [[Easing|easing function]] (only some easing functions use this parameter)

===Returns===
Returns ''true'' if the function moved the object succesfully, and returns ''false'' otherwise.

==Examples ==
<section name="Server" class="server" show="true">
'''Example 1:''' This example moves every object in the game up 100 units in ten seconds.
<syntaxhighlight lang="lua">
allObjects = getElementsByType ( "object" )
for key, theObject in ipairs ( allObjects ) do
local origX, origY, origZ = getElementPosition ( theObject ) --get the origanal position
local newZ = origZ + 100 -- make a new z position
moveObject ( theObject, 10000, origX, origY, newZ ) --move the object to this position in 10 seconds.
end
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
'''Example 2:''' This example created a model (of a bed) near a player called ''someguy'', if they exist in the game. It will then move the model towards the player over 3 seconds.
<syntaxhighlight lang="lua">
-- Find a player called 'someguy'
someGuy = getPlayerFromName ( "someguy" )
-- If a player called someguy was found then
if ( someGuy ) then
-- Get the player's position
x, y, z = getElementPosition ( someGuy )
-- Create a bed (1700) object near to the player
bed = createObject ( 1700, x + 5, y, z )
-- Move the bed towards the player over 3 seconds (3000 milliseconds)
moveObject ( bed, 3000, x, y, z )
-- Tell the player in the chat box
outputChatBox ( "Moving a bed towards you!", someGuy )
else
-- Tell everyone that a player called 'someguy' could not be found
outputChatBox ( "Player someguy doesn't exist" )
end
</syntaxhighlight>
</section>

<section name="Server" class="server" show="true">
'''Example 3:''' This example creates a ball moving (in front of CJ's house in Grove Street) using easing functions. Test command is "/smove" for instance "/smove OutBounce". This example is a serverside code but the same could be done clientside (adapting the command handler)
<syntaxhighlight lang="lua">
local START_POS = {2497.203125, -1672.4864501953, 12.640947341919}
local STOP_POS = {2480.2595214844, -1666.521484375, 12.640114784241}
local MOTION_DURATION = 5000
local WAIT_DURATION = 1000

addCommandHandler("smove",
function (player, cmd, strEasingType, period, amplitude, overshoot)
local x, y, z = unpack(START_POS)
local object = createObject(1598, x, y, z)
x, y, z = unpack(STOP_POS)

period = period or 0.3
amplitude = amplitude or 1.0
overshoot = overshoot or 1.70158

outputChatBox(string.format("Server Easing %s %s %s %s", strEasingType, tostring(period), tostring(amplitude), tostring(overshoot)))
moveObject(object, MOTION_DURATION, x, y, z, 0, 0, 360, strEasingType, period, amplitude, overshoot)
setTimer(destroyElement, MOTION_DURATION+WAIT_DURATION, 1, object)
end)
</section>

==See Also==
{{Object functions}}

IsPlayerMuted

2011-11-22T16:14:38Z

VWOer:

__NOTOC__
{{Server function}}
Use this function to check if a player has been muted.

==Syntax==
<syntaxhighlight lang="lua">bool isPlayerMuted ( player thePlayer )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you are checking.

===Returns===
Returns ''true'' if the player is muted and ''false'' otherwise.

==Example==
<syntaxhighlight lang="lua">
someguy = getPlayerFromName ( "someGuy" )
if isPlayerMuted ( someguy ) then
outputChatBox ( "It seems Someguy can't speak." )
end
</syntaxhighlight>

==See Also==
{{Player functions}}

SetTimer

2011-08-30T14:50:28Z

VWOer:

__NOTOC__
{{Server client function}}
This function allows you to trigger a function after a number of milliseconds have elapsed. You can call one of your own functions or a built-in function. For example, you could set a timer to spawn a player after a number of seconds have elapsed.

Once a timer has finished repeating, it no longer exists.

'''The minimum accepted interval is 50ms.'''

Multi Theft Auto guarantees that the timer will be triggered after ''at least'' the interval you specify. The resolution of the timer is tied to the frame rate (server side and client-side). All the overdue timers are triggered at a single point each frame. This means that if, for example, the player is running at 30 frames per second, then two timers specified to occur after 100ms and 110ms would more than likely occur during the same frame, as the difference in time between the two timers (10ms) is less than half the length of the frame (33ms). As with most timers provided by other languages, you shouldn't rely on the timer triggering at an exact point in the future.

==Syntax==
<syntaxhighlight lang="lua">
timer setTimer ( function theFunction, int timeInterval, int timesToExecute, [ var arguments... ] )
</syntaxhighlight>

===Required Arguments===
*'''theFunction:''' The function you wish the timer to call. (Notice: Do not use a 'local' function, it must be global!)
*'''timeInterval:''' The number of milliseconds that should elapse before the function is called. (the minimum is 50)(1000 milliseconds = 1 second)
*'''timesToExecute:''' The number of times you want the timer to execute, or 0 for infinite repetitions.

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you wish to pass to the function can be listed after the ''timesToExecute'' argument. Note that any tables you want to pass will get cloned, whereas metatables will get lost. Also changes you make in the original table before the function gets called won't get transferred.

===Returns===
Returns a [[timer]] pointer if the timer was set successfully, ''false'' if the arguments are invalid or the timer could not be set.

==Example==
<section name="Example" class="both" show="true">
This example will output some text after a small delay.

<syntaxhighlight lang="lua">
-- define function to be called
function delayedChat ( text )
outputChatBox ( "Delayed text: " .. text )
end

-- set a timer so the function is called after 1 second
setTimer ( delayedChat, 1000, 1, "Hello, World!" )
</syntaxhighlight>

1 second after the line above has been executed, the text ''Delayed text: Hello, World!'' will be displayed in the chat box.
</section>

==See Also==
{{Utility functions}}

CreateColTube

2011-08-29T09:44:09Z

VWOer:

__NOTOC__
{{Server client function}}
This function creates a collision tube. This is a shape that has a position and a 2D (X/Y) radius and a height. See [http://en.wikipedia.org/wiki/Cylinder_(geometry) Cylinder] for a definition of a tube. A tube is similar to a colcircle, except that it has a limited height, this means you can limit the distance above the position defined by (fX, fY, fZ) that the collision is detected.

==Syntax==
<syntaxhighlight lang="lua">
colshape createColTube ( float fX, float fY, float fZ, float fRadius, float fHeight)
</syntaxhighlight>

===Required Arguments===
*'''fX:''' The position of the base of the tube's center on the X axis
*'''fY:''' The position of the base of the tube's center on the Y axis
*'''fZ:''' The position of the base of the tube's center on the Z axis
*'''fRadius:''' The collision tube's radius
*'''fHeight:''' The collision tube's height

===Returns===
Returns a [[colshape]] element if successful, ''false'' if invalid arguments were passed to the function.

==Example==
<section name="Server" class="server" show="true">
This example displays a chat message when a player enters the colshape and allows the colshape to be created using a console function ''set_zone''.
<syntaxhighlight lang="lua">
theZone = false

function shapeHit ( thePlayer )
outputChatBox ( getPlayerName ( thePlayer ) .. " is in the zone!" ) -- display a message in everyone's chat box
end

function setZone ( playerSource, commandName, fX, fY, fZ )
if ( fZ and fY and fX ) then -- check we've got all 3 args we need
local tempCol = createColTube ( fX, fY, fZ, 10.0, 10.0 ) -- create a col
if ( tempCol == false ) then -- did the col get created successfully?
outputConsole ( "Syntax is: set_zone <X> <Y> <Z>" ) -- inform the user what the valid syntax is
else
if ( theZone ~= false ) then -- did we already have a zone?
destroyElement ( theZone ) -- if so, destroy it
else
addEventHandler ( "onColShapeHit", theZone, shapeHit ) -- add a handler for the onColShapeHit event
end
theZone = tempCol -- and store the new zone we've made
outputChatBox ( "Zone has moved!" ) -- and tell everyone
end
end
end
addCommandHandler ( "set_zone", setZone ) -- add a console function called set_zone that will trigger the function setZone
</syntaxhighlight>
</section>

==See Also==
{{Collision shape functions}}

IsGarageOpen

2011-08-29T09:37:25Z

VWOer:

__NOTOC__
{{Server client function}}
This function checks whether or not a specific garage door is open.

==Syntax==
<syntaxhighlight lang="lua">
bool isGarageOpen ( int garageID )
</syntaxhighlight>

===Required Arguments===
*'''garageID:''' The [[Garage|garage ID]] that represents the garage door that is being checked.

===Returns===
Returns ''true'' if the garage is open, ''false'' if it is closed or an invalid garage ID was given.

==Example==
<section name="Server" class="server" show="true">
This example opens a garage door when a player enters a collision shape near it, and closes it when they leave:
<syntaxhighlight lang="lua">
GARAGE_ID = 25

-- create a collision shape and attach event handlers to it when the resource starts
addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
function (resource)
local garageCube = createColCuboid(1337, 194, 28, 6, 10, 4)
addEventHandler("onColShapeHit", garageCube, onGarageCubeHit)
addEventHandler("onColShapeLeave", garageCube, onGarageCubeLeave)
end)

-- open the door when someone enters the garage's collision shape
function onGarageCubeHit(hitElement, matchingDimension)
if (getElementType(hitElement) == "player") then
-- check to make sure the door is closed
if (not isGarageOpen(GARAGE_ID)) then
-- open the door
setGarageOpen(GARAGE_ID, true)
end
end
end

-- close the door when someone leaves the garage's collision shape
function onGarageCubeLeave(leaveElement, matchingDimension)
if (getElementType(leaveElement) == "player") then
-- check to make sure the door is open
if (isGarageOpen(GARAGE_ID)) then
-- close the door
setGarageOpen(GARAGE_ID, false)
end
end
end
</syntaxhighlight>
</section>

==See Also==
{{World functions}}

[[ru:isGarageOpen]]

Element/Marker

2011-08-27T15:08:31Z

VWOer:

__NOTOC__
The marker class represents colored, 3D shapes in the GTA world. There are several types of markers, including cylinders and checkpoints. In scripts, markers are often used to mark spots and trigger some sort of action when a player goes into them.

The element type of this class is '''"marker"'''.

The size of the marker cannot be specified from XML and defaults to 4.0.

==XML syntax==
<syntaxhighlight lang="xml">
<marker posX="" posY="" posZ="" type="" .../>
</syntaxhighlight>

===Required Attributes===
* '''posX''': A float representing the X position of the pickup.
* '''posY''': A float representing the Y position of the pickup.
* '''posZ''': A float representing the Z position of the pickup.

===Optional Attributes===
* '''type:''' The visual type of the marker to be created. Possible values:
{{Marker types}}
* '''color:''' The color of the marker in HTML style format #RRGGBB, defaults to red if not specified.

==Related scripting functions==
{{Marker functions}}
[[Category:Element Types]]

[[it:Elemento/Marker]]
[[ru:Элемент/Маркер]]

GivePedJetPack

2011-08-27T11:08:43Z

VWOer:

__NOTOC__
{{Server function}}
This function is used to give a ped a jetpack, it won't work if the ped is in a vehicle.

As such, you should either expect it to fail sometimes, or repeatedly try to give a jetpack every second or so until [[doesPlayerHaveJetPack]] returns true. Alternatively, you can force the ped into a 'safe' position (e.g. standing on the ground) before giving the jetpack, or use a [[pickup]] to handle it.

==Syntax==
<syntaxhighlight lang="lua">bool givePedJetPack ( ped thePed )</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] you want to give a jetpack to.

===Returns===
Returns ''true'' if a jetpack was successfully given to the ped, ''false'' if it could not be given.

==Example==
This examples adds a "jetpack" console command, which gives or removes a jetpack from the player.
<syntaxhighlight lang="lua">
-- Checks whether or not the player has a jetpack, and gives or removes it from the player
function consoleJetPack ( thePlayer, commandName )
if not doesPedHaveJetPack ( thePlayer ) then -- if the player doesn't have a jetpack
local status = givePedJetPack ( thePlayer ) -- give him one
if not status then
outputConsole ( "Failed to give jetpack.", thePlayer ) -- tell him if it failed
end
else
local status = removePedJetPack ( thePlayer ) -- remove his jetpack
if ( not status ) then
outputConsole ( "Failed to remove jetpack.", thePlayer ) -- tell him if it failed
end
end
end

-- add the function above to handle the "jetpack" command
addCommandHandler ( "jetpack", consoleJetPack )
</syntaxhighlight>

==See Also==
{{Ped functions}}
[[ru:givePedJetPack]]

SetGarageOpen

2011-08-19T15:17:44Z

VWOer:

__NOTOC__
{{Server client function}}
This function opens or closes the specified garage door in the world.

==Syntax==
<syntaxhighlight lang="lua">
bool setGarageOpen ( int garageID, bool open )
</syntaxhighlight>

===Required Arguments===
*'''garageID:''' The [[Garage|garage ID]] that represents the garage door being opened or closed.
*'''isOpen:''' A boolean indicating whether or not to open the door.

===Returns===
Returns ''true'' if successful, ''false'' if an invalid garage id was given.

==Example==
<section name="Server" class="server" show="true">
This example opens a garage door when a player enters a collision shape near it, and closes it when they leave:
<syntaxhighlight lang="lua">
GARAGE_ID = 25

-- create a collision shape and attach event handlers to it when the resource starts
addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
function (resource)
local garageCube = createColCuboid(1337, 194, 28, 6, 10, 4)
addEventHandler("onColShapeHit", garageCube, onGarageCubeHit)
addEventHandler("onColShapeLeave", garageCube, onGarageCubeLeave)
end)

-- open the door when someone enters the garage's collision shape
function onGarageCubeHit(hitElement, matchingDimension)
if (getElementType(hitElement) == "player") then
-- check to make sure the door is closed
if (not isGarageOpen(GARAGE_ID)) then
-- open the door
setGarageOpen(GARAGE_ID, true)
end
end
end

-- close the door when someone leaves the garage's collision shape
function onGarageCubeLeave(leaveElement, matchingDimension)
if (getElementType(leaveElement) == "player") then
-- check to make sure the door is open
if (isGarageOpen(GARAGE_ID)) then
-- close the door
setGarageOpen(GARAGE_ID, false)
end
end
end
</syntaxhighlight>
</section>

==See Also==
{{World functions}}

[[ru:setGarageOpen]]