Multi Theft Auto: Wiki - User contributions [en]

OnPlayerPickupHit

2010-08-19T04:16:37Z

Ca11um: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a [[player]] hits a [[pickup]].

==Parameters==
<syntaxhighlight lang="lua">
pickup pickupHit, bool matchingDimension
</syntaxhighlight>

*'''pickupHit''': The pickup the player hit
*'''matchingDimension''': Whether the player and the pickup he hit are in the same dimension

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that hit the pickup.


==Cancel effect==
If this event is [[Event system#Canceling|canceled]], the player will not be able to pick up this pickup.

==Example==

This example disables the use of armour pickups.

<syntaxhighlight lang="lua">
function armourBlock(pickup,dimension)
if (getPickupType(pickup) == 1) then -- If it's an armour pickup
cancelEvent() -- Cancel the event
outputChatBox("Armour pickups are disabled.",source,255,0,0)
end
end
addEventHandler("onPlayerPickupHit",getRootElement(),armourBlock)
</syntaxhighlight>

{{See also/Server event|Player events}}

OnPlayerPrivateMessage

2010-08-16T01:19:06Z

Ca11um: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a player sends a private message with ''msg'' command.

==Parameters==
<syntaxhighlight lang="lua">
string message, player recipient
</syntaxhighlight>
*'''message''': A string representing the private message typed.
*'''recipient''': The [[player]] to whom the message is being sent.

==Source==
The [[event system#Event source|source]] of this event is the [[player]] who sent the private message.

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], the game's chat system won't deliver the message. You may use [[outputChatBox]] to send the messages then.

==Example==
This example blocks players sending a PM to a player named "Bob".
<syntaxhighlight lang="lua">
function blockPM(msg,r)
if (getPlayerName(r) == "Bob") then -- If they sent a PM to "Bob"
cancelEvent() -- Then cancel it
outputChatBox("Bob is not accepting PM's at this time.",source,255,0,0) -- And output it was cancelled.
end
end
addEventHandler("onPlayerPrivateMessage",getRootElement(),blockPM)
</syntaxhighlight>
{{See also/Server event|Player events}}

SetVehicleRotation

2010-08-05T04:09:15Z

Ca11um: Deprecated.

__NOTOC__
{{Needs Checking|the server side function seems to work counter clockwise meaning setting the rotation to (0 0 90) will make the vehicle face West serverside and East clentside, also serverside 0 rotation is displayed as 360 no biggie though, #2421 --[[User:Norby89|Norby89]] 09:17, 5 August 2007 (CDT)}}
{{Server client function}}
{{Deprecated}}
This function rotates a vehicle around a single point.

==Syntax==
<syntaxhighlight lang="lua">bool setVehicleRotation ( vehicle theVehicle, rx, ry, rz )</syntaxhighlight>

===Required Arguments===
*'''theVehicle''': The [[vehicle]] that you wish to apply the warp to.
*'''x''': The x-axis rotation in degrees.
*'''y''': The y-axis rotation in degrees.
*'''z''': The z-axis rotation in degrees.

==Returns==
Returns a boolean value ''true'' or ''false'' that tells you if it was successful or not.

==Example==
<syntaxhighlight lang="lua">local newcar = createVehicle ( 520, 1024, 1024, 1024 )
if setVehicleRotation ( newcar, 0, 0, 270 ) then
outputChatBox ( "Rotation change successful." )
end</syntaxhighlight>

==See Also==
{{Vehicle functions}}

SetAccountData

2010-07-28T14:20:01Z

Ca11um: removed false error.

{{Server function}}
__NOTOC__
{{Note_box|It is strongly recommended that you use the standard ''module.key'' naming for your keys, as shown in the example below. This prevents collisions between different scripts.}}
This function sets a string to be stored in an account. This can then be retrieved using [[getAccountData]]. Data stored as account data is persistent across user's sessions and maps, unless they are logged into a guest account. Even if logged into a guest account, account data can be useful as a way to store a reference to your own account system, though it's persistence is equivalent to that of using [[setElementData]] on the player's element.

==Syntax==
<syntaxhighlight lang="lua">
bool setAccountData ( account theAccount, string key, string value )
</syntaxhighlight>

===Required Arguments===
*'''theAccount:''' The account you wish to retrieve the data from.
*'''key:''' The key under which you wish to store the data
*'''value:''' The value you wish to store

===Returns===
Returns a ''true'' if the account data was set, ''false'' if an invalid argument was specified.

==Example==
For a pirate roleplaying gametype, the amount of money a player has is made persistent by storing it in his account. Note the code uses "piraterpg.money" as key instead of just "money", as the player may be participating in other gametypes that also save his money amount to his account. If both gametypes would use "money" as the account key, they'd overwrite each other's data.
<syntaxhighlight lang="lua">
function onPlayerQuit ( )
-- when a player leaves, store his current money amount in his account data
local playeraccount = getPlayerAccount ( source )
if ( playeraccount ) then
local playermoney = getPlayerMoney ( source )
setAccountData ( playeraccount, "piraterpg.money", playermoney )
end
end

function onPlayerJoin ( )
-- when a player joins, retrieve his money amount from his account data and set it
local playeraccount = getPlayerAccount ( source )
if ( playeraccount ) then
local playermoney = getAccountData ( playeraccount, "piraterpg.money" )
-- make sure there was actually a value saved under this key (check if playermoney is not false).
-- this will for example not be the case when a player plays the gametype for the first time
if ( playermoney ) then
setPlayerMoney ( source, playermoney )
end
end
end

addEventHandler ( "onPlayerQuit", getRootElement ( ), onPlayerQuit )
addEventHandler ( "onPlayerJoin", getRootElement ( ), onPlayerJoin )
</syntaxhighlight>

==See Also==
{{Account_functions}}

IsElementWithinMarker

2010-06-05T17:25:32Z

Ca11um: Removed from needs example category (it has one).

{{Server client function}}
__NOTOC__
This function is used to determine if an [[element]] is within a [[marker]].

==Syntax==
<syntaxhighlight lang="lua">bool isElementWithinMarker ( element theElement, marker theMarker )</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The [[element]] you're checking.
*'''theMarker:''' The [[marker]] you're checking.

===Returns===
Returns ''true'' if the element is within the marker, ''false'' otherwise

==Example==
<syntaxhighlight lang="lua">
dutymarker = createMarker(126.56,254.98,78.9,'cylinder', 2.0, 255, 0, 0, 150)

function duty(player, matchingDimension)
if (isElementWithinMarker(player, dutymarker) == true ) then
giveWeapon(player, 22, 100, 1)
else
outputChatBox("You are not at the right place!", player,255,0,0)
end
end
addCommandHandler("duty", duty)
</syntaxhighlight>

==See Also==
{{Marker functions}}

GetBanAdmin

2010-06-05T03:54:22Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function will return the responsible admin (nickname of the admin) of the specified [[ban]] pointer.

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

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

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

==Example==
<syntaxhighlight lang="lua">
function outputBan(ban)
local banned = getBanNick(ban) -- Get the name of the player who was banned
local banner = getBanAdmin(ban) -- Get the name of the admin who banned the player
local reason = getBanReason(ban) -- Get the reason the player was banned
outputChatBox("-----BAN-----",getRootElement(),255,0,0)
if (banned) then
outputChatBox("Player banned: "..banned,getRootElement(),255,0,0) -- Output the player name who was banned
end
if (banner) then
outputChatBox("Banner: "..banner,getRootElement(),255,0,0) -- Output the admin name who performed the ban
end
if (reason) then
outputChatBox("Reason: "..reason,getRootElement(),255,0,0) -- outputt the reason the player was banned
end
end
addEventHandler("onBan",getRootElement(),outputBan) -- When a player is banned trigger the outputBan function
</syntaxhighlight>

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

GetBanReason

2010-06-05T03:53:59Z

Ca11um: Added an example.

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

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

===Required Arguments===
*'''theBan:''' The [[ban]] in which you want to return the reason of.

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

==Example==
<syntaxhighlight lang="lua">
function outputBan(ban)
local banned = getBanNick(ban) -- Get the name of the player who was banned
local banner = getBanAdmin(ban) -- Get the name of the admin who banned the player
local reason = getBanReason(ban) -- Get the reason the player was banned
outputChatBox("-----BAN-----",getRootElement(),255,0,0)
if (banned) then
outputChatBox("Player banned: "..banned,getRootElement(),255,0,0) -- Output the player name who was banned
end
if (banner) then
outputChatBox("Banner: "..banner,getRootElement(),255,0,0) -- Output the admin name who performed the ban
end
if (reason) then
outputChatBox("Reason: "..reason,getRootElement(),255,0,0) -- outputt the reason the player was banned
end
end
addEventHandler("onBan",getRootElement(),outputBan) -- When a player is banned trigger the outputBan function
</syntaxhighlight>

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

GetBanNick

2010-06-05T03:53:37Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function will return the nickname (nickname that the player had when he was banned) of the specified [[ban]] element.

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

===Required Arguments===
*'''theBan:''' The [[ban]] element which nickname you want to return.

===Returns===
Returns a ''string'' of the nickname if everything was successfull, ''false'' if invalid arguments are specified if there was no nickname specified for the [[ban]] element.

==Example==
<syntaxhighlight lang="lua">
function outputBan(ban)
local banned = getBanNick(ban) -- Get the name of the player who was banned
local banner = getBanAdmin(ban) -- Get the name of the admin who banned the player
local reason = getBanReason(ban) -- Get the reason the player was banned
outputChatBox("-----BAN-----",getRootElement(),255,0,0)
if (banned) then
outputChatBox("Player banned: "..banned,getRootElement(),255,0,0) -- Output the player name who was banned
end
if (banner) then
outputChatBox("Banner: "..banner,getRootElement(),255,0,0) -- Output the admin name who performed the ban
end
if (reason) then
outputChatBox("Reason: "..reason,getRootElement(),255,0,0) -- outputt the reason the player was banned
end
end
addEventHandler("onBan",getRootElement(),outputBan) -- When a player is banned trigger the outputBan function
</syntaxhighlight>

==See Also==
{{Admin functions}}

OnPlayerClick

2010-06-05T03:44:23Z

Ca11um: Added an example.

__NOTOC__
{{Server event}}
This event is triggered when a player clicks using the mouse cursor.

==Parameters==
<syntaxhighlight lang="lua">
string mouseButton, string buttonState, element clickedElement, float worldPosX, float worldPosY, float worldPosZ, float screenPosX, float screenPosY
</syntaxhighlight>

*'''mouseButton''': A string representing the mousebutton that was pressed. Value can be ''left'', ''middle'' or ''right''.
*'''buttonState''': A string representing the button state. Value can be ''up'' or ''down''.
*'''clickedElement''': The element the player clicked on. This value is ''nil'' if none.
*'''worldPosX''': The X position in the world the player clicked on
*'''worldPosY''': The Y position in the world the player clicked on
*'''worldPosZ''': The Z position in the world the player clicked on
*'''screenPosX''': The X position on the screen the player clicked on
*'''screenPosY''': The Y position on the screen the player clicked on

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that clicked.

==Example==
This example outputs the state of the button they just pressed.
<syntaxhighlight lang="lua">
function outputClick(mouseButton,buttonState)
outputChatBox("Your "..mouseButton.." mouse button is now "..buttonState,source,255,255,0) -- output the state of the button they just pressed.
end
addEventHandler("onPlayerClick",getRootElement(),outputClick) -- When a player clicks trigger the outputClick function
</syntaxhighlight>

{{See also/Server event|Player events}}

SetWeaponAmmo

2010-06-05T03:35:37Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
Sets the ammo to a certain amount for a specified weapon (if they already have it), regardless of current ammo.

==Syntax==
<syntaxhighlight lang="lua">bool setWeaponAmmo ( player thePlayer, int weapon, int totalAmmo, [int ammoInClip = 0] )</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' A [[player]] object referencing the specified player
*'''weapon:''' A whole number integer that refers to a [[weapon]] ID.
*'''totalAmmo:''' A whole number integer serving as the total ammo amount for the given weapon (including ammo in clip).

===Optional Arguments===
{{OptionalArg}}
*'''ammoInClip:''' The amount of ammo to set in the player's clip. This will be taken from the main ammo. If left unspecified or set to 0, the current clip will remain.

==Returns==
Returns a boolean value ''true'' or ''false'' that tells you if it was successful or not.

==Example==
<syntaxhighlight lang="lua">
local randPlayer = getRandomPlayer() -- Get a random player
giveWeapon(randPlayer,35,100) -- Give them a rocket launcher with 100 rockets.
setWeaponAmmo(randPlayer,35,50) -- Decide we're only going to give them 50 rockets.
</syntaxhighlight>

==See Also==
{{Weapon functions}}
[[ru:setWeaponAmmo]]

MakePedUseGun

2010-06-05T03:28:16Z

Ca11um: May not be Deprecated after all.

__NOTOC__
{{Client function}}
This function is used to force a ped to use a gun.

==Syntax==
<syntaxhighlight lang="lua">
bool makePedUseGun ( ped thePed, int useType, element target )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] you wish to force the use of a gun upon.
*'''useType:''' How the weapon should be used, will accept the following values:
** '''0:''' Do nothing
** '''1:''' Aim weapon
** '''2:''' Fire
** '''3:''' Burst-fire
** '''4:''' Reload
** '''5:''' Pistolwhip (Weapon melee)
** '''6:''' Cancel use
** '''7:''' Cancel use immediately
*'''target:''' An [[element]] referring to the target that the ped will use its weapon against.

===Returns===
Returns ''true'' if the command was successful, false otherwise.

==Example==
This page lacks an example
<syntaxhighlight lang="lua">
--add an example here
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}
[[Category:Needs_Example]]

UsePickup

2010-06-05T03:24:21Z

Ca11um: Added example.

__NOTOC__
{{Server client function}}
This function is used to simulate the player using a pickup

==Syntax==
<syntaxhighlight lang="lua">
bool usePickup ( pickup thePickup, player thePlayer )
</syntaxhighlight>

===Required Arguments===
* '''thePickup''': The pickup element to be picked up/used.
* '''thePlayer''': The player to use the pickup.

==Example==
<section name="Server" class="server" show="true">
This example gives a random player 100% armor by using a pickup.
<syntaxhighlight lang="lua">
local pickup = createPickup(3,3,3,1,100) -- Create a pickup for 100% armor
usePickup(pickup,getRandomPlayer()) -- Make a random player use the pickup (shall recieve 100% armor)
</syntaxhighlight>
</section>

==See Also==
{{Pickup functions}}

MakePedUseGun

2010-06-05T03:15:27Z

Ca11um: Deprecated

__NOTOC__
{{Client function}}
{{Deprecated}}
This function is used to force a ped to use a gun.

==Syntax==
<syntaxhighlight lang="lua">
bool makePedUseGun ( ped thePed, int useType, element target )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] you wish to force the use of a gun upon.
*'''useType:''' How the weapon should be used, will accept the following values:
** '''0:''' Do nothing
** '''1:''' Aim weapon
** '''2:''' Fire
** '''3:''' Burst-fire
** '''4:''' Reload
** '''5:''' Pistolwhip (Weapon melee)
** '''6:''' Cancel use
** '''7:''' Cancel use immediately
*'''target:''' An [[element]] referring to the target that the ped will use its weapon against.

===Returns===
Returns ''true'' if the command was successful, false otherwise.

==Example==
This page lacks an example
<syntaxhighlight lang="lua">
--add an example here
</syntaxhighlight>

==See Also==
{{Client_ped_functions}}
[[Category:Needs_Example]]

OnClientConsole

2010-05-31T03:15:14Z

Ca11um: ouputChatBox had a player arg (only required server-side).

[[Category:Incomplete Event]]
{{Client event}}
__NOTOC__
This event is triggered when the local player enters text in the console. Note that, if you want to add custom console commands, it is easier to the [[addCommandHandler]] function.

==Parameters==
<syntaxhighlight lang="lua">
string text
</syntaxhighlight>
*'''text:''' the text line that was entered.

==Example==
This example outputs any text you input into the console.
<syntaxhighlight lang="lua">
function consoleCheck(text)
outputChatBox("You entered into the console: "..text,255,255,0)
end
addEventHandler("onClientConsole",getLocalPlayer(),consoleCheck)
</syntaxhighlight>

==See Also==
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

SetCameraInterior

2010-05-31T03:14:14Z

Ca11um: Added example.

__NOTOC__
{{Server client function}}
Sets the interior of the local camera. Only the interior of the camera is changed, the local player stays in the interior he was in.

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

===Required Arguments===
*'''thePlayer:''' the player whose camera interior will be set.
*'''interior:''' the interior to place the camera in.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool setCameraInterior ( int interior )
</syntaxhighlight>

===Required Arguments===
*'''interior:''' the interior to place the camera in.
</section>

===Returns===
Returns ''true'' if the camera's interior was changed successfully, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">

<strong> This example make a command to change your cam interior to a selected one. </strong>

<syntaxhighlight lang="lua">
function setCamInt( thePlayer, commandName, intID )
if( intID )then
local seted = setCameraInterior( thePlayer, intID )
if( seted )then
outputChatBox( "Your camera's interior has been seted to "..intID, thePlayer )
else
outputChatBox( "Can't change your camera's interior...", thePlayer, 255, 0, 0 )
end
else
outputChatBox( "Syntax: /caminterior [interiorID] ", thePlayer, 255, 0, 0 )
end
end
addCommandHandler( "caminterior", setCamInt )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<strong> This example make a command to change your cam interior to a selected one. </strong>
<syntaxhighlight lang="lua">
function setCam(thePlayer,command,int)
if (int) then
local setInt = setCameraInterior(thePlayer,int)
if (setInt) then
outputChatBox("Your camera's interior has been set to "..int,255,255,0)
else
outputChatBox("Can't change your camera's interior...",255,0,0)
end
else
outputChatBox("Syntax: /camera [interiorID] ",255,0,0)
end
end
addCommandHandler("camera",setCam)
</syntaxhighlight>
</section>

==See Also==
{{Client_camera_functions}}

GetTrainDirection

2010-05-31T03:06:52Z

Ca11um: Added an example.

__NOTOC__
{{Server client function}}
Gets the direction in which a train is driving (clockwise or counterclockwise).

==Syntax==
<syntaxhighlight lang="lua">bool getTrainDirection ( vehicle train )</syntaxhighlight>

===Required Arguments===
*'''train:''' the train of which to get the driving direction.

===Returns===
Returns ''true'' if the train is driving clockwise on the train track, ''false'' if it is going counterclockwise or a failure occured.

==Example==
This example outputs to the player the direction the train they're driving is travelling.
<syntaxhighlight lang="lua">
function trainDir(thePlayer,command)
if (isPedInVehicle(thePlayer)) then -- Check if they're even in a vehicle.
if (getVehicleType(getPedOccupiedVehicle(thePlayer)) == "Train") then -- Check if they're in a train.
local direction = getTrainDirection(getPedOccupiedVehicle(thePlayer)) -- Get the train's direction.
if (direction) then
outputChatBox("You're driving clockwise.",thePlayer,255,255,0) -- Output that they're driving clockwise.
else
outputChatBox("You're driving anti-clockwise.",thePlayer,255,255,0) -- Output that they're driving anti-clockwise.
end
else
outputChatBox("You must be in a train to use this command.",thePlayer,255,0,0) -- Output that they're not in a train.
end
else
outputChatBox("You must be in a train to use this command.",thePlayer,255,0,0) -- Output that they're not in a vehicle.
end
end
addCommandHandler("direction",trainDir)
</syntaxhighlight>

==See Also==
{{Vehicle functions}}

OnPlayerMarkerHit

2010-05-31T02:58:27Z

Ca11um: Added an example.

__NOTOC__
{{Server event}}
This event is triggered when a [[player]] hits a [[marker]].

==Parameters==
<syntaxhighlight lang="lua">
marker markerHit, bool matchingDimension
</syntaxhighlight>

*'''markerHit''': The marker the player hit
*'''matchingDimension''': Whether the player and the marker he hit are in the same dimension

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that hit the marker.

==Example==
This example outputs when a player hits a marker.
<syntaxhighlight lang="lua">
function markerAlert(markerHit,matchingDimension)
if (matchingDimension) then -- Make sure the player is in the same dimension as the marker (so they're actually going into it).
outputChatBox("You have just entered a marker.",source,255,255,0) -- Output that they are.
end
end
addEventHandler("onPlayerMarkerHit",getRootElement(),markerAlert)
</syntaxhighlight>

{{See also/Server event|Player events}}

GetMarkerCount

2010-05-31T02:50:24Z

Ca11um: Added an example.

__NOTOC__
{{Server client function}}
Returns the number of markers that currently exist in the world.

==Syntax==
<syntaxhighlight lang="lua">
int getMarkerCount ( )
</syntaxhighlight>

===Required Arguments===
''None''

===Returns===
Returns the number of markers that currently exist.

==Example==
This example outputs the amount of markers to the player.
<syntaxhighlight lang="lua">
function howManyMarkers(thePlayer,command)
local ammount = getMarkerCount()
outputChatBox("There are "..ammount.." markers.",thePlayer,255,255,0)
end
addCommandHandler("markers",howManyMarkers)
</syntaxhighlight>

==See Also==
{{Marker functions}}

GetCameraInterior

2010-05-31T02:47:22Z

Ca11um: Removed page from "Needs example" category.

__NOTOC__
{{Server client function}}
Returns the interior of the local camera (independent of the interior of the local player).

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

===Required Arguments===
'''thePlayer''': the player whose camera interior you want to check.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
int getCameraInterior ( )
</syntaxhighlight>

===Required Arguments===
''None''
</section>

===Returns===
Returns an ''integer'' indicating the camera's interior, ''false'' if the argument is invalid.

==Example==
This example outputs the interior the player's camera is in.
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
function camInt(thePlayer,command)
local interior = getCameraInterior(thePlayer)
outputChatBox("The camera is in interior "..interior,thePlayer,255,255,0)
end
addCommandHandler("camera",camInt)
</syntaxhighlight>
</section>

==See Also==
{{Camera functions}}

GetCameraInterior

2010-05-31T02:46:20Z

Ca11um: Added a server-side example.

OnClientConsole

2010-05-31T02:41:00Z

Ca11um: Added example.

[[Category:Incomplete Event]]
{{Client event}}
__NOTOC__
This event is triggered when the local player enters text in the console. Note that, if you want to add custom console commands, it is easier to the [[addCommandHandler]] function.

==Parameters==
<syntaxhighlight lang="lua">
string text
</syntaxhighlight>
*'''text:''' the text line that was entered.

==Example==
This example outputs any text you input into the console.
<syntaxhighlight lang="lua">
function consoleCheck(text)
outputChatBox("You entered into the console: "..text,getLocalPlayer(),255,255,0)
end
addEventHandler("onClientConsole",getLocalPlayer(),consoleCheck)
</syntaxhighlight>

==See Also==
===Other client events===
{{Client_other_events}}
===Client event functions===
{{Client_event_functions}}

IsGlitchEnabled

2010-05-31T02:34:03Z

Ca11um: Added example.

__NOTOC__
{{Server function}}
This function retrieves whether San Andreas game glitches are enabled or not, set by using [[setGlitchEnabled]]

==Syntax==
<syntaxhighlight lang="lua">bool isGlitchEnabled ( string glitchName )</syntaxhighlight>

===Required Arguments===
*'''glitchName:''' the name of the property to set. Possible values are:
**'''quickreload''' - This is the glitch where switching weapons auto-reloads your weapon, without actually performing the reload animation.
**'''fastmove''' - This is the glitch that can be achieved by a certain key combinations whilst standing up after crouching, which allows you to move quickly with slow weapons (e.g. deagle).
**'''fastfire''' - This is the glitch that can be achieved by cancelling the full fire animation, allowing you to shoot with slow-fire weapons (e.g. deagle) much faster.

===Returns===
Returns ''true'' if if the glitch was enabled, or ''false'' if it is disabled.

==Example==
This example outputs weather the "fastmove" glitch is enabled or not.
<syntaxhighlight lang="lua">
setGlitchEnabled("fastmove",true) -- Enable the fastmove glitch at resource start.

function checkIsEnabled(thePlayer,command)
if (isGlitchEnabled("fastmove")) then -- Check weather fastmove is enabled or not.
outputChatBox("fastmove is enabled.",thePlayer,255,255,0) -- If so, output that it's enabled.
else
outputChatBox("fastmove is not enabled.",thePlayer,255,0,0) -- If not, output that it isn't enabled.
end
end
addCommandHandler("glitch",checkIsEnabled)
</syntaxhighlight>

==See Also==
{{Server functions}}

OnClientPlayerStuntStart

2010-05-15T17:39:39Z

Ca11um: Typo in the event handler in example.

__NOTOC__
{{Client event}}
This event is triggered whenever the local player starts doing a vehicle stunt.

==Parameters==
<syntaxhighlight lang="lua">
string stuntType
</syntaxhighlight>

*'''stuntType''': the type of stunt the player is starting to perform. Valid types are:
{{StuntTypes}}

==Source==
The [[event system#Event source|source]] of this event is the local [[player]].

==Example==
This is a simple stunt script which tells player what stunt he/she started and finished, time the stunt taken to perform and distance travelled while stunting.
<syntaxhighlight lang="lua">
addEventHandler( "onClientPlayerStuntStart", getRootElement( ),
function ( stuntType )
outputChatBox( "You started stunt: " .. stuntType );
end
);

addEventHandler( "onClientPlayerStuntFinish", getRootElement( ),
function ( stuntType, stuntTime, distance )
outputChatBox( "You finished stunt: " .. stuntType ..", Time: " .. tostring( stuntTime ).. ", Distance: " .. tostring( distance ) );
end
);
</syntaxhighlight>

==See Also==
===Client player events===
{{Client_player_events}}
===Client event functions===
{{Client_event_functions}}

SetElementVisibleTo

2010-04-20T18:22:57Z

Ca11um: Forgot about 2nd example.

__NOTOC__
{{Server function}}
{{Needs_Checking|Can an element only be visible to one element (and its children) at a time? If so, do we need clearElementVisibleTo? If not, surely we need to remove the root element before using this function?|[[User:EAi|EAi]]
}}

This function can change an [[element]]'s [[visibility]]. This does not work with all entities - [[vehicle]]s, [[player]]s and [[object]]s are exempt. This is because these objects are required for accurate sync (they're physical objects). This function is particularily useful for changing the visibility of markers, radar blips and radar areas.

==Syntax==
<syntaxhighlight lang="lua">
bool setElementVisibleTo ( element theElement, element visibleTo, bool visible )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element you want to control the visibility of.
*'''visibleTo:''' The element you wish the element to be visible or invisible to. Any child elements that are players will also be able to see the element. See [[visibility]].
*'''visible:''' Whether you are making it visible or invisible to the player.

===Returns===
Returns ''true'' if the element's visibility was changed successfully, ''false'' otherwise, for example if you are trying to change the visibility of a vehicle, player or object.

==Example==
This example creates a marker and makes it only visibile to the player called 'someguy'.
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromName ( "someguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )
-- First off make the marker invisible to the whole dimension
setElementVisibleTo ( myMarker, getRootElement ( ), false )
-- Then make the marker visible again, but only to someguy
setElementVisibleTo ( myMarker, someguy, true )
end
</syntaxhighlight>

The following example shows how to hide the marker on 'someguy' from 'anotherguy'
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromName ( "someguy" )
local anotherguy = getPlayerFromNick ( "anotherguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )
-- First off make the marker visible especially to 'anotherguy'
setElementVisibleTo ( myMarker, anotherguy, true )
-- Then hide it
setElementVisibleTo ( myMarker, anotherguy, false )
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

SetElementVisibleTo

2010-04-20T18:21:24Z

Ca11um: Example: getPlayerFromNick -> getPlayerFromName (Deprecated)

__NOTOC__
{{Server function}}
{{Needs_Checking|Can an element only be visible to one element (and its children) at a time? If so, do we need clearElementVisibleTo? If not, surely we need to remove the root element before using this function?|[[User:EAi|EAi]]
}}

This function can change an [[element]]'s [[visibility]]. This does not work with all entities - [[vehicle]]s, [[player]]s and [[object]]s are exempt. This is because these objects are required for accurate sync (they're physical objects). This function is particularily useful for changing the visibility of markers, radar blips and radar areas.

==Syntax==
<syntaxhighlight lang="lua">
bool setElementVisibleTo ( element theElement, element visibleTo, bool visible )
</syntaxhighlight>

===Required Arguments===
*'''theElement:''' The element you want to control the visibility of.
*'''visibleTo:''' The element you wish the element to be visible or invisible to. Any child elements that are players will also be able to see the element. See [[visibility]].
*'''visible:''' Whether you are making it visible or invisible to the player.

===Returns===
Returns ''true'' if the element's visibility was changed successfully, ''false'' otherwise, for example if you are trying to change the visibility of a vehicle, player or object.

==Example==
This example creates a marker and makes it only visibile to the player called 'someguy'.
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromName ( "someguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )
-- First off make the marker invisible to the whole dimension
setElementVisibleTo ( myMarker, getRootElement ( ), false )
-- Then make the marker visible again, but only to someguy
setElementVisibleTo ( myMarker, someguy, true )
end
</syntaxhighlight>

The following example shows how to hide the marker on 'someguy' from 'anotherguy'
<syntaxhighlight lang="lua">
-- Find the player called someguy
local someguy = getPlayerFromNick ( "someguy" )
local anotherguy = getPlayerFromNick ( "anotherguy" )
-- If the player was found then
if ( someguy ) then
-- Get the player's position into the variables x, y and z
x, y, z = getElementPosition ( someguy )
-- Create a marker at the player's position
myMarker = createMarker ( x, y, z )
-- First off make the marker visible especially to 'anotherguy'
setElementVisibleTo ( myMarker, anotherguy, true )
-- Then hide it
setElementVisibleTo ( myMarker, anotherguy, false )
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

GetBans

2010-02-24T19:52:49Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

==Syntax==
<syntaxhighlight lang="lua">
table getBans ()
</syntaxhighlight>

===Returns===
Returns a [[table]] over all the [[ban]] pointers.

==Example==
This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ()
local bansList = getBans() -- Return a table of all the bans.
local banID = 0 -- Set "banID" to 0.
for k, ban in ipairs ( banList ) do -- For every ban do the following...
banID = banID + 1 -- Each ban has a uniuqe ID.
outputChatBox ( "Ban #" .. banID .. ": " .. ban .. "", source, 255, 0, 0 ) -- Output the ban.
end
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>

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

OnPickupSpawn

2010-02-24T16:25:12Z

Ca11um: Added an example.

__NOTOC__
{{Server event}}
This event is triggered when a pickup is spawned or respawned.

==Parameters==
This event has no arguments


==Source==
The [[event system#Event source|source]] of this event is the [[pickup]] that just spawned or respawned.

==Example==

This example get's the area and city name when a pickup spawns and outputs it to all the players.

<syntaxhighlight lang="lua">
function outputSpawn ()
local area = getElementZoneName ( source ) -- Get the area name where the pickup spawned.
local city = getElementZoneName ( source, true ) -- Get the city name where the pickup spawned.
outputChatBox ( "A pickup has spawned in " .. area .. " ( " .. city .. " )", getRootElement(), 255, 0, 0 ) -- Output the pickup spawn.
end
addEventHandler ( "onPickupSpawn", getRootElement(), outputSpawn ) -- Trigger the function when a pickup spawns.
</syntaxhighlight>

{{See also/Server event|Pickup events}}

OnPlayerBan

2010-02-24T16:14:54Z

Ca11um: Added an example.

__NOTOC__
{{Server event}}
This event is triggered when a player added a ban (like onBan).

==Parameters==
<syntaxhighlight lang="lua">
ban banPointer, player responsibleElement
</syntaxhighlight>

*'''banPointer''': The ban pointer which was added.
*'''responsibleElement''': The player who added the ban

==Source==
The [[event system#Event source|source]] of this event is the [[element]] that was responsible for the banning. If no responsible was specified, the source is the global root element.

==Example==
This example outputs the responcible element and the ban pointer when a ban takes place.
<syntaxhighlight lang="lua">
function outputBan ( banPointer, responcibleElement ) -- Define the banner and the ban pointer in the function.
outputChatBox ( getPlayerName(responcibleElement ).." has banned ".. banPointer ..".", getRootElement(), 255, 0, 0 ) -- Output the ban.
end
addEventHandler ( "onPlayerBan", getRootElement(), outputBan ) -- Trigger the function when there is a ban.
</syntaxhighlight>

{{See also/Server event|Player events}}

SetPedSkin

2010-02-23T20:59:04Z

Ca11um: Removed duplicate Deprecated status (me and MCvarial edited both at once)

__NOTOC__
{{Server client function}}
{{Deprecated}}
This function changes the skin of a ped.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedSkin ( ped thePed, int skinID )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] whose model will be changed.
*'''skinID:''' A GTASA player model (skin) ID. See [[Character Skins]].

==Example==
<section show="true" name="Server" class="server">
This example sets a players skin to the cop skin when they spawn.
<syntaxhighlight lang="lua">
function setCopSkin ()
setPedSkin ( source, 280 )
outputChatBox ( "You are now a cop.", source, 255, 0, 0 )
end
addEventHandler ( "onPlayerSpawn", getRootElement(), setCopSkin )
</syntaxhighlight>
</section>
==See Also==
{{Client_ped_functions}}

SetPedSkin

2010-02-23T20:57:30Z

Ca11um: Added example and added to Deprecated category.

__NOTOC__
{{Deprecated}}
{{Server client function}}
{{Deprecated}}
This function changes the skin of a ped.

==Syntax==
<syntaxhighlight lang="lua">
bool setPedSkin ( ped thePed, int skinID )
</syntaxhighlight>

===Required Arguments===
*'''thePed:''' The [[ped]] whose model will be changed.
*'''skinID:''' A GTASA player model (skin) ID. See [[Character Skins]].

==Example==
<section show="true" name="Server" class="server">
This example sets a players skin to the cop skin when they spawn.
<syntaxhighlight lang="lua">
function setCopSkin ()
setPedSkin ( source, 280 )
outputChatBox ( "You are now a cop.", source, 255, 0, 0 )
end
addEventHandler ( "onPlayerSpawn", getRootElement(), setCopSkin )
</syntaxhighlight>
</section>
==See Also==
{{Client_ped_functions}}

GetTrainSpeed

2010-02-23T20:44:35Z

Ca11um: Added an example.

__NOTOC__
{{Server client function}}

Gets the speed at which a train is traveling on the rails.

==Syntax==
<syntaxhighlight lang="lua">float getTrainSpeed ( vehicle train )</syntaxhighlight>

===Required Arguments===
*'''train:''' the train of which to retrieve the speed.

===Returns===
Returns the train's speed if successful, ''false'' otherwise.

==Example==
<section name="Server" class="server" show="true">
This example outputs how fast a player is going if they're in a train. The command is "/speed".
<syntaxhighlight lang="lua">
function getPlayersTrainSpeed ( source, command ) -- Define source in the function header.
if ( isPedInVehicle ( source ) ) -- Check if they're in a vehicle.
local veh = getPedOccupiedVehicle ( source ) -- Get the vehicle they're in.
if ( getVehicleType ( veh ) == "Train" ) then -- Check if the vehicle they're in is a train.
local speed = getTrainSpeed ( veh ) -- Get the trains speed.
outputChatBox ( "You are travelling at a speed of " .. speed, source, 255, 0, 0 ) -- Output their speed.
else
outputChatBox ( "You must be in a train to use this command.", source, 255, 0, 0 ) -- Tell them they're not in a train.
end
else
outputChatBox ( "You must be in a train to use this command.", source, 255, 0, 0 ) -- Tell them they're not in a train.
end
end
addCommandHandler ( "speed", getPlayersTrainSpeed ) -- Make the function trigger when a player types "/speed".
</syntaxhighlight>
</section>

==See Also==
{{Vehicle functions}}

CreateResource

2010-02-23T20:33:21Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function creates an empty resource.

==Syntax==
<syntaxhighlight lang="lua">
resource createResource ( string resourceName )
</syntaxhighlight>

===Required Arguments===
*'''resourceName:''' The name of the new resource.

===Returns===
Returns ''true'' if the resource has been created successfully, ''false'' otherwise.

==Example==
This example creates a new resource named what the player specified. The command is "/new-resource <name>".
<syntaxhighlight lang="lua">
function createNewResource ( source, command, resourceName ) -- Define the source and add a resourceName argument.
if ( resourceName ) then -- Check if they entered a resource name, and if they did...
local resourceName = tostring ( resourceName ) -- Convert the name into a string.
local newResource = createResource ( resourceName ) -- Create the new resource.
if ( newResource ) then -- Check if the resource has been created, if so then...
outputChatBox ( "New resource created succcessfully.", source, 255, 0, 0 ) -- Output it's done.
else -- If the resource wasn't made successfully then...
outputChatBox ( "An un-expected error occured.", source, 255, 0, 0 ) -- Output it failed.
end
else -- If they didn't enter a resource name...
outputChatBox ( "Please specify a name for your new resource.", source, 255, 0, 0 ) -- Tell them to specify a name.
end
end
addCommandHandler ( "new-resource", createNewResource ) -- Make it trigger when somebody types "/new-resource <name>".
</syntaxhighlight>

==See Also==
{{Resource_functions}}

ResetVehicleExplosionTime

2010-02-23T20:18:31Z

Ca11um: Added an example.

{{Server function}}
__NOTOC__
Resets the vehicle explosion time. This is the point in time at which the vehicle last exploded: at this time plus the vehicle's respawn delay, the vehicle is respawned. You can use this function to prevent the vehicle from respawning.

==Syntax==
<syntaxhighlight lang="lua">
bool resetVehicleExplosionTime ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The vehicle you wish to reset the explosion time from.

===Returns===
Returns ''true'' if the vehicle explosion time has been reset, ''false'' if it failed to reset the explosion time.

==Example==
This example resets every vehicle's explosion time when the resource is stopped.
<syntaxhighlight lang="lua">
function resetVehiclesExplosionTime ()
local vehicles = getElementsByType ( "vehicle" ) -- Return all the vehicles in a table
for k, vehicle in ipairs ( vehicles ) do -- For every vehicle do the following...
resetVehicleExplosionTime ( vehicle ) -- Reset the vehicle's explosion time
end
end
-- When this resource is stopped, trigger the resetVehiclesExplosionTime function (above).
addEventHandler ( "onResourceStop", getResourceRootElement(getThisResource()), resetVehiclesExplosionTime )
</syntaxhighlight>

==See Also==
{{Vehicle functions}}

ResetVehicleIdleTime

2010-02-23T20:12:34Z

Ca11um: Added an example.

{{Server function}}
__NOTOC__
Resets the vehicle idle time

==Syntax==
<syntaxhighlight lang="lua">
bool resetVehicleIdleTime ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The vehicle you wish to reset the idle time from.

===Returns===
Returns ''true'' if the vehicle idle time has been reset, ''false'' if it failed to reset the idle time.

==Example==
This example resets every vehicle's idle time when the resource is stopped.
<syntaxhighlight lang="lua">
function resetVehiclesIdleTime ()
local vehicles = getElementsByType ( "vehicle" ) -- Return all the vehicles in a table
for k, vehicle in ipairs ( vehicles ) do -- For every vehicle do the following...
resetVehicleIdleTime ( vehicle ) -- Reset the vehicle's idle time
end
end
-- When this resource is stopped, trigger the resetVehiclesIdleTime function (above).
addEventHandler ( "onResourceStop", getResourceRootElement(getThisResource()), resetVehiclesIdleTime )
</syntaxhighlight>

==See Also==
{{Vehicle functions}}

AddBan

2010-02-23T19:58:32Z

Ca11um: Removed <section> (function is server-side only (not needed))

__NOTOC__
{{Server function}}
This function will add a ban for the specified IP/username/serial to the server.

==Syntax==
<syntaxhighlight lang="lua">
ban addBan ( [ string IP, string Username, string Serial, player responsibleElement, string reason, int seconds = 0 ] )
</syntaxhighlight>
'''Note:''' One of the three: IP, Username or Serial have to be specified.

===Required Arguments===
*'''IP:''' The IP to be banned. If you don't want to ban by IP, set this to ''nil''.
'''or'''
*'''Username:''' The username to be banned. If you don't want to ban by username, set this to ''nil''.
'''or'''
*'''Serial:''' The serial to be banned. If you don't want to ban by serial, set this to ''nil''.
''' or any combination.'''

===Optional Arguments===
{{OptionalArg}}
*'''responsibleElement:''' The element that is responsible for banning the IP/username/serial. This can be a player or the root ([[getRootElement]]()).
*'''reason:''' The reason the IP/username/serial 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===
Returns ''true'' if the IP/username/serial was banned succesfully, ''false'' if invalid arguments are specified.

==Example==
This example bans a player's IP with the reason "Requested" when they type "/ban-me".
<syntaxhighlight lang="lua">
function banMe ( source, command ) -- The function header and where source is defined
local ipToBan = getPlayerIP ( source ) -- Get the player's IP
addBan ( ipToBan, source, "Requested" ) -- Ban him with the reason; Requested
end
addCommandHandler ( "ban-me", banMe ) -- Make it trigger when a player types "/ban-me"
</syntaxhighlight>
==See Also==
{{Admin functions}}
[[ru:addBan]]

AclSave

2010-02-23T19:57:31Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}

This function saves the ACL from the memory back to the XML file. That must be done after changing the ACL so your changes are remembered for the next server restart. This does not need to be done after every change, but after you're done changing it.

==Syntax==

<syntaxhighlight lang="lua">
bool aclSave ()
</syntaxhighlight>

===Returns===

Returns ''true'' if the ACL was successfully changed, ''false'' or ''nil'' if it could not be saved for some reason, ie. file in use.

==Example==

This example saves the ACL when somebody types "/save-acl".

<syntaxhighlight lang="lua">
function saveACL ( thePlayer, command ) -- Function header. Also where thePlayer is defined.
local saved = aclSave() -- Save the ACL
if ( saved ) then -- If it was successfully saved then...
outputChatBox ( "ACL was successfully saved.", source, 255, 0, 0 ) -- Output it saved
else -- If it wasn't saved for whatever reason then...
outputChatBox ( "An unexpected error occured.", source, 255, 0, 0 ) -- Output it didn't save
end
end
addCommandHandler ( "save-acl", saveACL ) -- Make it trigger for "/save-acl".
</syntaxhighlight>
==See Also==

{{ACL_functions}}

AddBan

2010-02-23T19:49:23Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function will add a ban for the specified IP/username/serial to the server.

==Syntax==
<syntaxhighlight lang="lua">
ban addBan ( [ string IP, string Username, string Serial, player responsibleElement, string reason, int seconds = 0 ] )
</syntaxhighlight>
'''Note:''' One of the three: IP, Username or Serial have to be specified.

===Required Arguments===
*'''IP:''' The IP to be banned. If you don't want to ban by IP, set this to ''nil''.
'''or'''
*'''Username:''' The username to be banned. If you don't want to ban by username, set this to ''nil''.
'''or'''
*'''Serial:''' The serial to be banned. If you don't want to ban by serial, set this to ''nil''.
''' or any combination.'''

===Optional Arguments===
{{OptionalArg}}
*'''responsibleElement:''' The element that is responsible for banning the IP/username/serial. This can be a player or the root ([[getRootElement]]()).
*'''reason:''' The reason the IP/username/serial 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===
Returns ''true'' if the IP/username/serial was banned succesfully, ''false'' if invalid arguments are specified.

==Example==
<section name="Serverside example" class="server" show="true">
This example bans a player's IP with the reason "Requested" when they type "/ban-me".
<syntaxhighlight lang="lua">
function banMe ( source, command ) -- The function header and where source is defined
local ipToBan = getPlayerIP ( source ) -- Get the player's IP
addBan ( ipToBan, source, "Requested" ) -- Ban him with the reason; Requested
end
addCommandHandler ( "ban-me", banMe ) -- Make it trigger when a player types "/ban-me"
</syntaxhighlight>
</section>
==See Also==
{{Admin functions}}
[[ru:addBan]]

IsVehicleBlown

2010-02-22T19:03:36Z

Ca11um: Doesn't "Need example".

{{Server client function}}
__NOTOC__
This function allows you to determine whether a vehicle is blown or still intact.

==Syntax==
<syntaxhighlight lang="lua">bool isVehicleBlown ( vehicle theVehicle )</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] that you want to obtain the blown status of.

===Returns===
Returns ''true'' if the vehicle specified has blown up, ''false'' if it is still intact or the vehicle specified is invalid.

==Example==
<section name="Server" class="server" show="true">
This example creates a taxi and checks whether the taxi has blown up or not every time somebody types "/taxi".
<syntaxhighlight lang="lua">
theTaxi = createVehicle ( 420, 1, 1, 17 ) -- Add a taxi in the middle of SA

function checkTaxi ( thePlayer, command )
if ( isVehicleBlown ( theTaxi ) ) then -- Check whether it's blown or not
outputChatBox ( "The taxi has blown up.", thePlayer, 255, 0, 0 ) -- If so, we'll output it
else -- Anything else (if it's not)
outputChatBox ( "The taxi has not blown.", thePlayer, 255, 0, 0 ) -- If not, we'll output that instead
end
end
addCommandHandler ( "taxi", checkTaxi ) -- Make it check when somebody types "/taxi"
</syntaxhighlight>
</section>

==See Also==
{{Vehicle functions}}

LogIn

2010-02-22T07:33:56Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This functions logs the given player in to the given account. You need to provide the password needed to log into that account.

==Syntax==
<syntaxhighlight lang="lua">
bool logIn ( player thePlayer, account theAccount, string thePassword )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player to log into an account
*'''theAccount:''' The account to log the player into
*'''thePassword:''' The password needed to sign into this account

===Returns===
Returns ''true'' if the player was successfully logged into the given account. Returns ''false'' or ''nil'' if the log in failed for some reason, ie. the player was already logged in to some account (use [[logOut]] first), if the account was already in use or if it failed for some other reason.

==Example==
<syntaxhighlight lang="lua">
function loginPlayer ( thePlayer, command, username, password )
local account = getAccount ( username, password ) -- Return the account
if ( account ~= false ) then -- If the account exists.
logIn ( thePlayer, account, password ) -- Log them in.
else
outputChatBox ( "Wrong username or password!", thePlayer, 255, 255, 0 ) -- Output they got the details wrong.
end
end
addCommandHandler ( "log-in", loginPlayer ) -- Make it trigger for "/log-in", NOTE: /login is hardcored and cannot be used.
</syntaxhighlight>

==See Also==
{{Account_functions}}

StartResource

2010-02-22T07:26:27Z

Ca11um: Removed from "Needs example".

__NOTOC__
{{Server function}}
This function starts a resource either persistently or as a dependency of the current resource. If you start the resource persistently, the resource will run until stopped either using [[stopResource]] or by the server admin. A resource started as a dependency will stop when your resource stops, if no other resources have it as a depdendency. This is the same effect as using an ''include'' in your [[meta.xml]] file.

The function also allows you to specify a number of boolean options. These allow you to disable the loading of various aspects of the resource. This is generally useful for editors rather than for actual gamemodes. It could also be used as a way to preview a resource before enabling the scripting aspects, though this could produce unreliable results. There is no way for a resource to tell if it is being run with any of these booleans set.

==Syntax==
<syntaxhighlight lang="lua">
bool startResource ( resource resourceToStart, [bool persistent = false, bool startIncludedResources = true, bool loadServerConfigs = true, bool loadMaps = true, bool loadServerScripts = true, bool loadHTML = true, bool loadClientConfigs = true, bool loadClientScripts = true, bool loadFiles = true] )
</syntaxhighlight>

===Required Arguments===
*'''resourceToStart:''' The resource that should be started.

===Optional Arguments===
{{OptionalArg}}
*'''persistent:''' A boolean specifying if the resource should continue to run even after this resource has been stopped or not. If this is ''true'' then the resource will run until another resource or user terminates it or the server shuts down.
*'''startIncludedResources:''' A boolean specifying if the resource's included/dependant resources will be started.
*'''loadServerConfigs:''' A boolean specifying if server side config (XML) files should be loaded with the resource.
*'''loadMaps:''' A boolean specifying if any .map files will be started with the resource.
*'''loadServerScripts:''' A boolean specifying if server side script files should be started alongside the resource.
*'''loadHTML:''' A boolean specifying if HTML files should be started alongside the resource.
*'''loadClientConfigs:''' A boolean specifying if client configs should be loaded alongside the resource.
*'''loadClientScripts:''' A boolean specifying if client scripts should be loaded and started alongside the resource.
*'''loadFiles:''' A boolean specifying if client-side files should be loaded alongside the resource.

===Returns===
Returns ''true'' if the resource has been started successfully, ''false'' otherwise.

==Example==
This example starts a specified resource with the command; "/resource-start".
<syntaxhighlight lang="lua">
function startTheResource ( thePlayer, command, resource )
if ( resource ) then -- Check if they specified a resource name
local resource = tostring ( resource ) -- This prevents "a userdata value" error
local start = startResource ( resource ) -- Start the resource
if ( start ) then -- If it was successfully started...
outputChatBox ( resource .. " was started successfully.", thePlayer, 255, 0, 0 )
else -- If it wasn't successfully started...
outputChatBox ( "An unexpected error occured.", thePlayer, 255, 0, 0 )
end
else -- If they didn't put a resource name...
outputChatBox ( "Please specify a resource to start.", thePlayer, 255, 0, 0 )
end
end
addCommandHandler ( "resource-start", startTheResource ) -- Make it trigger when somebody types "/resource-start"
</syntaxhighlight>

==See Also==
{{Resource_functions}}

StartResource

2010-02-22T07:25:35Z

Ca11um: Added an example.

SetPedHeadless

2010-02-21T22:33:20Z

Ca11um: Doesn't need example.

__NOTOC__
{{Server client function}}
With this function, you can set if a ped has a head or not.
==Syntax==
<syntaxhighlight lang="lua">bool setPedHeadless ( ped thePed, bool headState )</syntaxhighlight>

===Required Arguments===
*'''thePed''': The [[ped]] to check.
*'''headState''': head state, use true if you want the ped be headless, use false to give back the head.

===Returns===
Returns ''true'' if successful, ''false'' otherwise

==Example==
<section name="Server" class="server" show="true">
This example enables a player to behead themselves, and give them their head back.
<syntaxhighlight lang="lua">
function removeMyHead(thePlayer)
setPedHeadless(thePlayer, true) -- Removes the players head
outputChatBox("You have been beheaded!", thePlayer, 255, 0, 0) -- A confirmation message for the player
end
addCommandHandler("beheadme", removeMyHead)

function giveBackHead(thePlayer)
setPedHeadless(thePlayer, false) -- Gives the player a head
outputChatBox("You have been given a head!", thePlayer, 255, 0, 0) -- A confirmation message for the player
end
addCommandHandler("headmeup", giveBackHead)
</syntaxhighlight>
</section>

==See Also==
{{Ped functions}}

LogOut

2010-02-21T18:59:14Z

Ca11um: Added comments.

__NOTOC__
{{Server function}}
This function logs the given player out of his current account.

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

===Required Arguments===
*'''thePlayer:''' The player to log out of his current account

===Returns===
Returns ''true'' if the player was successfully logged out, ''false'' or ''nil'' if it failed for some reason, ie. the player was never logged in.

==Example==
This example logs every player out of their account when the resource is (re)started. This would be handy for resources that show a login scren onClientResourceStart.
<syntaxhighlight lang="lua">
function logoutAll ()
local players = getElementsByType ( "player" ) -- Get every player
for k, player in ipairs ( players ) do -- For every player do the follwing...
account = getPlayerAccount ( player ) -- Get every player's account
if ( not isGuestAccount ( account ) ) then -- For every player that's logged in....
logOut ( player ) -- Log them out.
end
end
end
-- Trigger it when the resource (re)starts
addEventHandler ( "onResourceStart", getResourceRootElement(getThisResource()), logoutAll )</syntaxhighlight>

==See Also==
{{Account_functions}}

LogOut

2010-02-21T18:56:57Z

Ca11um: Removed "Needs example" category.

__NOTOC__
{{Server function}}
This function logs the given player out of his current account.

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

===Required Arguments===
*'''thePlayer:''' The player to log out of his current account

===Returns===
Returns ''true'' if the player was successfully logged out, ''false'' or ''nil'' if it failed for some reason, ie. the player was never logged in.

==Example==
This example logs every player out of their account when the resource is (re)started. This would be handy for resources that show a login scren onClientResourceStart.
<syntaxhighlight lang="lua">
function logoutAll ()
local players = getElementsByType ( "player" )
for k, player in ipairs ( players ) do
account = getPlayerAccount ( player )
if ( not isGuestAccount ( account ) ) then
logOut ( player )
end
end
end
addEventHandler ( "onResourceStart", getResourceRootElement(getThisResource()), logoutAll )
</syntaxhighlight>

==See Also==
{{Account_functions}}

LogOut

2010-02-21T18:56:26Z

Ca11um: Added an example.

__NOTOC__
{{Server function}}
This function logs the given player out of his current account.

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

===Required Arguments===
*'''thePlayer:''' The player to log out of his current account

===Returns===
Returns ''true'' if the player was successfully logged out, ''false'' or ''nil'' if it failed for some reason, ie. the player was never logged in.

==Example==
This example logs every player out of their account when the resource is (re)started. This would be handy for resources that show a login scren onClientResourceStart.
<syntaxhighlight lang="lua">
function logoutAll ()
local players = getElementsByType ( "player" )
for k, player in ipairs ( players ) do
account = getPlayerAccount ( player )
if ( not isGuestAccount ( account ) ) then
logOut ( player )
end
end
end
addEventHandler ( "onResourceStart", getResourceRootElement(getThisResource()), logoutAll )
</syntaxhighlight>

==See Also==
{{Account_functions}}
[[Category:Needs Example]]

AclReload

2010-02-21T18:46:28Z

Ca11um: Removed from "Needs Example" category.

__NOTOC__
{{Server function}}

This function reloads the ACL's and the ACL groups from the ACL XML file. All ACL and ACL group elements are invalid after a call to this and should not be used anymore.

==Syntax==

<syntaxhighlight lang="lua">
bool aclReload ()
</syntaxhighlight>

===Returns===

Returns ''true'' if the XML was successfully reloaded from the file, ''false'' or ''nil'' if the XML was invalid, didn't exist or could not be loaded for some other reason.

==Example==

This example allows an admin to reload the ACL by typing "/reloadACL".

<syntaxhighlight lang="lua">
function reloadACL ( source, command )
-- Check if they're an admin...
if ( isObjectInACLGroup ( "user." .. getAccountName ( getPlayerAccount ( source )), aclGetGroup ( "Admin" ) ) ) then
local reload = aclReload() -- Reload the ACL
if ( reload ) then -- Check it was reloaded successfully
outputChatBox ( "ACL was successfully reloaded.", source, 255, 0, 0 ) -- If so, output it
else -- If not, output it (line below)
outputChatBox ( "An unknown error occured. Please check the ACL file exists.", source, 255, 0, 0 )
end
else -- If they're not an admin, output it (below)
outputChatBox ( "You must be an admin to use this command!", source, 255, 0, 0 )
end
end
addCommandHandler ( "reloadACL", reloadACL )
</syntaxhighlight>

==See Also==

{{ACL_functions}}

AclReload

2010-02-21T18:45:32Z

Ca11um: Example added.

AclDestroyGroup

2010-02-21T18:33:39Z

Ca11um: Removed "Needs example" category.

__NOTOC__
{{Server function}}

This function destroys the given ACL group. The destroyed ACL group will no longer be valid.

==Syntax==

<syntaxhighlight lang="lua">
bool aclDestroyGroup ( string aclGroupName )
</syntaxhighlight>

===Required Arguments===

*'''aclGroupName:''' The name of ACL group to destroy

===Returns===

Returns ''true'' if the ACL group was successfully deleted, ''false'' if it could not be deleted for some reason (ie. invalid argument).

==Example==

This example allows admins to remove an ACL group they specify.

<syntaxhighlight lang="lua">
function removeACLGroup ( source, command, groupName )
-- Check if they're an admin...
if ( isObjectInACLGroup ( "user." .. getAccountName ( getPlayerAccount ( source )), aclGetGroup ( "Admin" ) ) ) then
if ( groupName ) then -- Check if they specified the group name
local group = aclGetGroup ( groupName ) -- Return any groups matching the name
if ( group ) then -- If any were returned then...
aclDestroyGroup ( group ) -- Destroy that group
else
-- Tell them if no groups with that name were found...
outputChatBox ( "No group with that name was found.", source, 255, 0, 0 )
end

else -- If they didn't specify the group
outputChatBox ( "Please specify the group name.", source, 255, 0, 0 ) -- Tell them that they must
end
else -- If they're not an admin....
outputChatBox ( "You must be an admin to use this command", source, 255, 0, 0 ) -- Tell them it's restricted
end
end
addCommandHandler ( "removeACL", removeACLGroup ) -- Make it happen when somebody types "/removeACL"
</syntaxhighlight>

==See Also==

{{ACL_functions}}

AclDestroyGroup

2010-02-21T18:32:46Z

Ca11um: Added example.

IsVehicleBlown

2010-02-21T17:48:02Z

Ca11um: Added an example.

{{Server client function}}
__NOTOC__
This function allows you to determine whether a vehicle is blown or still intact.

==Syntax==
<syntaxhighlight lang="lua">bool isVehicleBlown ( vehicle theVehicle )</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] that you want to obtain the blown status of.

===Returns===
Returns ''true'' if the vehicle specified has blown up, ''false'' if it is still intact or the vehicle specified is invalid.

==Example==
This example creates a taxi and checks weather the taxi has blown up or not every time somebody types "/taxi".
<syntaxhighlight lang="lua">
theTaxi = createVehicle ( 420, 1, 1, 17 ) -- Add a taxi in the middle of SA

function checkTaxi ( source, command )
if ( isVehicleBlown ( theTaxi ) ) then -- Check weather it's blown or not
outputChatBox ( "The taxi has blown up.", source, 255, 0, 0 ) -- If so, we'll output it
else -- Anything else (if it's not)
outputChatBox ( "The taxi has not blown.", source, 255, 0, 0 ) -- If not, we'll output that instead
end
addCommandHandler ( "taxi", checkTaxi ) -- Make it check when somebody types "/taxi"
</syntaxhighlight>

==See Also==
{{Vehicle functions}}
[[Category:Needs Example]]