Multi Theft Auto: Wiki - User contributions [en]

SetElementData

2017-03-17T21:00:53Z

F9SoOoL: /* Example */

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and consume server CPU. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client.

{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}

==Syntax==

<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 31 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server (client-side variation) and remote clients (both variations).

===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.

===Issues===
{{Issues|
{{Issue|7389|[Fixed in 1.3.5-7389] Problem with floating numbers}}
}}

==Example==
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</syntaxhighlight>
</section>

==See Also==
{{Element_functions}}

SetElementData

2017-03-17T20:59:54Z

F9SoOoL: /* Example */

{{Server client function}}
__NOTOC__
This function stores [[element data]] under a certain key, attached to an element. Element data set using this is then synced with all clients and the server. The data can contain server created elements, but you should avoid passing data that is not able to be synced such as xmlnodes, acls, aclgroups etc.

As element data is synced to all clients, it can generate a lot of network traffic and consume server CPU. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client.

{{Tip|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}

==Syntax==

<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )
</syntaxhighlight>
{{OOP||[[element]]:setData||getElementData}}

===Required Arguments===
*'''theElement:''' The [[element]] you wish to attach the data to.
*'''key:''' The key you wish to store the data under. (Maximum 31 characters.)
*'''value:''' The value you wish to store. See [[element data]] for a list of acceptable datatypes.

===Optional Arguments===
*'''synchronize:''' Determines whether or not the data will be synchronized with the server (client-side variation) and remote clients (both variations).

===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.

===Issues===
{{Issues|
{{Issue|7389|[Fixed in 1.3.5-7389] Problem with floating numbers}}
}}

==Example==
<section name="Server" class="server" show="true">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
<syntaxhighlight lang="lua">
function addPlayerCustomTag ( thePlayer, command, newTag )
--Let's make sure the newTag param has been entered...
if ( newTag ) then
--Grab their current playername for saving.
local sPlayerNickname = getPlayerName ( thePlayer )
--Create their new nickname with their tag
local sNewPlayerNickname = newTag .. " " .. sPlayerNickname

--Let's first load the element data, see if it's there already
--The reason for this is that if a player were to do /addtag twice,
--the tag would be prepended a second time
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick == false ) then
--Save their orignal nickname in their element data
setElementData ( thePlayer, "tempdata.originalnick", sPlayerNickname )
end

--Set their new nickname globally
setPlayerName ( thePlayer, sNewPlayerNickname )

--Tell them it's done
outputChatBox ( "Your new nickname has been set, to put it back to its original state you can use /deltag", thePlayer )
else
--The newTag param was not entered, give an error message
outputChatBox ( "/addtag - Incorrect syntax, Correct: /addtag <newtag>", thePlayer )
end
end
addCommandHandler ( "addtag", addPlayerCustomTag )

function removePlayerCustomTag ( thePlayer, command )
--We first need to check that they have already used /addtag, let's do that now
local sOldNick = getElementData( thePlayer, "tempdata.originalnick" )
if ( sOldNick ) then
--Great, they have a tag added, let's reset them

--First we will want to reset the element data back to its default (that being false)
setElementData ( thePlayer, "tempdata.originalnick", false )

--Now set the client name back
setPlayerName( thePlayer, sOldNick )

--Notify them
outputChatBox ( "Your old nickname has been set", thePlayer )
end
end
addCommandHandler ( "deltag", removePlayerCustomTag )
</section>
</syntaxhighlight>

==See Also==
{{Element_functions}}

SetElementData

2017-03-17T20:59:27Z

F9SoOoL: /* Example */

SetElementData

2017-03-17T20:58:58Z

F9SoOoL: /* Example */

SetElementHealth

2016-11-17T17:01:05Z

F9SoOoL: /* Example */

{{Server client function}}
__NOTOC__
This function sets the health for the specified [[element]]. This can be a [[ped]], [[object]] or a [[vehicle]].

==Syntax==
<syntaxhighlight lang="lua">
bool setElementHealth ( element theElement, float newHealth )
</syntaxhighlight>
{{OOP||[[element]]:setHealth|health|getElementHealth}}

===Required Arguments===
*'''theElement:''' The [[ped]], [[vehicle]] or [[object]] whose health you want to set.
*'''newHealth:''' A float indicating the new health to set for the element.

===Returns===
Returns ''true'' if the new health was set successfully, or ''false'' if invalid arguments were passed.

==Example==
<section name="Server" class="server" show="true">
This example adds a 'hpslap' console command that lets players "slap" others (doing 20 damage).
<syntaxhighlight lang="lua">
function hpSlap ( sourcePlayer, command, targetPlayerName )
-- check if the user has access to it first
if not hasObjectPermissionTo(sourcePlayer, "command.slap", false) then
outputChatBox ( "You cannot use this command.", sourcePlayer )
return false
end
-- look up the player to be slapped
local targetPlayer = getPlayerFromName ( targetPlayerName )
-- if there's a player with such name,
if targetPlayer then
-- subtract 20 from his health
setElementHealth ( targetPlayer, getElementHealth(targetPlayer) - 20 )
else
-- otherwise, output an error message
outputChatBox ( "There is no player named " .. targetPlayerName .. "!", sourcePlayer )
end
end
-- add our function as a handler for "hpslap"
addCommandHandler ( "hpslap", hpSlap )
</syntaxhighlight>
</section>
<section name="Example 1" class="server" show="true">
This example setting health by a command.
<syntaxhighlight lang="lua">
function Health(player, command, amount)
setElementHealth(player, tonumber(amount))
end
addCommandHandler("set", Health)
</syntaxhighlight>
</section>

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

SetElementData

2016-11-17T16:56:36Z

F9SoOoL: /* Example */

SetElementData

2016-11-17T16:55:18Z

F9SoOoL: /* Example */

OnPlayerSpawn

2016-11-17T16:21:34Z

F9SoOoL: /* Example */

__NOTOC__
{{Server event}}
This event is called when a player spawns.

==Parameters==
<syntaxhighlight lang="lua">
float posX, float posY, float posZ, float spawnRotation, team theTeam, int theSkin, int theInterior, int theDimension
</syntaxhighlight>

*'''posX''': The X position the player spawned at
*'''posY''': The Y position the player spawned at
*'''posZ''': The Z position the player spawned at
*'''spawnRotation''': The rotation the player spawned with
*'''theTeam''': The team the player spawned with
*'''theSkin''': The skin / model the player spawned with
*'''theInterior''': The interior the player spawned in
*'''theDimension''': The dimension the player spawned in


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

==Example==
This example plays a sound when a player spawns.
<syntaxhighlight lang="lua">
-- when a player spawns,
function player_Spawn ( posX, posY, posZ, spawnRotation, theTeam, theSkin, theInterior, theDimension )
-- play a frontend sound for him
playSoundFrontEnd ( source, 16 )
end
-- add the player_Spawn function as a handler for onPlayerSpawn
addEventHandler ( "onPlayerSpawn", getRootElement(), player_Spawn )
</syntaxhighlight>

<section name="Example 1" class="server" show="true">
This example spawn the player in a specific place in the map.
<syntaxhighlight lang="lua">
function Spawn()
spawnPlayer(source, 0, 0, 0) --Change the positions
end --End function
addEventHandler("onPlayerSpawn", getRootElement(), Spawn)
</syntaxhighlight>
</section>

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

OnPlayerJoin

2016-11-17T16:06:47Z

F9SoOoL: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a player joins the server.

==Parameters==
No parameters.

==Source==
The source of this event is the [[player]] who joined.

==Example==
This example gets the joined client's name and sends him a welcome message including his name.

<syntaxhighlight lang="lua">
-- we register greetPlayer as a handler for the event
function greetPlayer ( )
-- we store the player's name
local joinedPlayerName = getPlayerName ( source )
local serverName = getServerName( )
-- and send him a greeting
outputChatBox ( "Welcome " .. joinedPlayerName .. " to ".. serverName .."!" , source, 255, 255, 255 )
end
addEventHandler ( "onPlayerJoin", getRootElement(), greetPlayer )
</syntaxhighlight>
This example sets random color to every player who joins.
<syntaxhighlight lang="lua">
-- create a table to save the color
ChatColors = {}

-- sets colors when player join
function onJoin ()
-- create a table to add rgb values. Index will be the player element
ChatColors[source] = {math.random (50, 255), math.random (50, 255), math.random (50, 255)}
end
-- checks if player has sent a message
function onChat ( message, messageType )
if messageType == 0 then
-- use the table to get the saved rgb values
outputChatBox ( getPlayerName ( source ) .. ": #E0D0B0" .. message, getRootElement(), ChatColors[source][1], ChatColors[source][2], ChatColors[source][3], true )
cancelEvent()
end
end
addEventHandler ( "onPlayerJoin", getRootElement(), onJoin)
addEventHandler ( "onPlayerChat", getRootElement(), onChat )
</syntaxhighlight>
<section name="Example 1" class="server" show="true">
This example rediercts any player joins to the server automatically to any other server, add the script for admin group.
<syntaxhighlight lang="lua">
function Redirect()
redirectPlayer (source, "server ip", "server port")
end --End function
addEventHandler("onPlayerJoin", getRootElement(), Redirect)
</syntaxhighlight>
</section>

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

OnPlayerWasted

2016-11-17T15:54:40Z

F9SoOoL: /* Example */

__NOTOC__
{{Server event}}
This event is triggered when a player is killed or dies.

==Parameters==
{{New feature/item|3|1.0||<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart, bool stealth
</syntaxhighlight>}}

{{Deprecated_feature|3|1.0|<syntaxhighlight lang="lua">
int totalAmmo, element killer, int killerWeapon, int bodypart
</syntaxhighlight>}}

*'''totalAmmo''': an integer representing the total ammo the victim had when he died.
*'''killer''': an [[element]] representing the player or vehicle who was the killer. If there was no killer this is ''false''.
*'''killerWeapon''': an integer representing the [[Weapons|killer weapon]] or the [[Death Reasons|death reason]].
*'''bodypart''': an integer representing the bodypart ID the victim was hit on when he died.
{{BodyParts}}
*{{New feature/item|3|1.0||'''stealth''': boolean value representing whether or not this was a stealth kill}}

==Source==
The [[event system#Event source|source]] of this event is the [[player]] that died or got killed.

==Example==
This example prints the killer and bodypart to the chat when a player dies.
<syntaxhighlight lang="lua">
-- register player_Wasted as a handler for onPlayerWasted
function player_Wasted ( ammo, attacker, weapon, bodypart )
-- if there was an attacker
if ( attacker ) then
-- we declare our variable outside the following checks
local tempString
-- if the element that killed him was a player,
if ( getElementType ( attacker ) == "player" ) then
-- put the attacker, victim and weapon info in the string
tempString = getPlayerName ( attacker ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
-- else, if it was a vehicle,
elseif ( getElementType ( attacker ) == "vehicle" ) then
-- we'll get the name from the attacker vehicle's driver
tempString = getPlayerName ( getVehicleController ( attacker ) ).." killed "..getPlayerName ( source ).." ("..getWeaponNameFromID ( weapon )..")"
end
-- if the victim was shot in the head, append a special message
if ( bodypart == 9 ) then
tempString = tempString.." (HEADSHOT!)"
-- else, just append the bodypart name
else
tempString = tempString.." ("..getBodyPartName ( bodypart )..")"
end
-- display the message
outputChatBox ( tempString )
-- if there was no attacker,
else
-- output a death message without attacker info
outputChatBox ( getPlayerName ( source ).." died. ("..getWeaponNameFromID ( weapon )..") ("..getBodyPartName ( bodypart )..")" )
end
end
addEventHandler ( "onPlayerWasted", getRootElement(), player_Wasted )
</syntaxhighlight>

And another example, this will spawn you in the middle of GTA SA world (x=0, y=0, z=3) after 2 seconds of your death
<syntaxhighlight lang="lua">
addEventHandler( "onPlayerWasted", getRootElement( ),
function()
setTimer( spawnPlayer, 2000, 1, source, 0, 0, 3 )
end
)
</syntaxhighlight>
<section name="Example 1" class="server" show="true">
This Example is a script for Tactics Servers , the script giving the killer health as a reward for killing.
<syntaxhighlight lang="lua">
function GiveHealth(ammo, killer, killerweapon, bodypart)
if ( killer ) and ( killer ~= source ) and ( (getElementHealth(killer)) ~= 100 ) --Here we have selcted that who will be gave a health is the killer
setElementHealth(killer, (getElementHealth(killer)) + 20) --He will get +20 health, if you want to reward him by sitting him health 100 you can just type 100 after (killer,
outputChatBox("#ff0000[ Server ] : #ffff00You Have Got Health +20",killer,255,0,0,true) --out put chat box for the killer
end --End if
end --End function
addEventHandler("onPlayerWasted", getRootElement(), GiveHealth)
</syntaxhighlight>
</section>

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

OnPlayerChat

2016-11-17T15:39:46Z

F9SoOoL: /* Examples */

__NOTOC__
{{Server event}}
This event is triggered when a player chats inside the chat box.

==Parameters==
<syntaxhighlight lang="lua">
string message, int messageType
</syntaxhighlight>

*'''message''': A string representing the message typed into the chat.
*'''messageType''': An integer value representing the message type:
**'''0''': normal message
**'''1''': action message (/me)
**'''2''': team message

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

==Cancel effect==
If this event is [[Event system#Canceling|canceled]], the game's chat system won't deliver the posts. You may use [[outputChatBox]] to send the messages then.
Cancelling this event also means the chat will not appear in the server console or logs. If you want chat logging, you will have to add a call to [[outputServerLog]] - See the second example.

==Examples==

<section name="Example 1" class="server" show="true">
This example limits receiving of chat messages to a spherical area around the player who sent the message, also blocking action and team text.

<syntaxhighlight lang="lua">
-- define our chat radius
local chatRadius = 20 --units

-- define a handler that will distribute the message to all nearby players
function sendMessageToNearbyPlayers( message, messageType )
-- we will only send normal chat messages, action and team types will be ignored
if messageType == 0 then
-- get the chatting player's position
local posX, posY, posZ = getElementPosition( source )

-- create a sphere of the specified radius in that position
local chatSphere = createColSphere( posX, posY, posZ, chatRadius )
-- get a table all player elements inside it
local nearbyPlayers = getElementsWithinColShape( chatSphere, "player" )
-- and destroy the sphere, since we're done with it
destroyElement( chatSphere )

-- deliver the message to each player in that table
for index, nearbyPlayer in ipairs( nearbyPlayers ) do
outputChatBox( message, nearbyPlayer )
end
end
end
-- attach our new chat handler to onPlayerChat
addEventHandler( "onPlayerChat", getRootElement(), sendMessageToNearbyPlayers )

-- define another handler function that cancels the event so that the message won't be delivered through the
function blockChatMessage()
cancelEvent()
end
-- attach it as a handler to onPlayerChat
addEventHandler( "onPlayerChat", getRootElement(), blockChatMessage )
</syntaxhighlight>
</section>

<section name="Example 2" class="server" show="true">
This example implements colored player names in chat.

<syntaxhighlight lang="lua">
--This function is executed when a player joins, it sets the player's name-tag color to a random color.
local function playerJoin()
local red, green, blue = math.random (50, 255), math.random (50, 255), math.random (50, 255)
setPlayerNametagColor(source, red, green, blue)
end
addEventHandler ("onPlayerJoin", root, playerJoin)

--This function is executed when a player says something in chat, it outputs the player's message, with their nick colored to match their name tag color.
local function playerChat(message, messageType)
if messageType == 0 then --Global (main) chat
cancelEvent()
local red, green, blue = getPlayerNametagColor(source)
outputChatBox(getPlayerName(source)..": #FFFFFF"..message, root, red, green, blue, true )
outputServerLog("CHAT: "..getPlayerName(source)..": "..message)--NOTE: Beacuse we cancelled the onPlayerChat event, we need to log chat manually.
end
end
addEventHandler("onPlayerChat", root, playerChat)
</syntaxhighlight>
</section>

<section name="Example 3" class="server" show="true">
This is a script for slap the player by a word in the chat.

<syntaxhighlight lang="lua">

function Slap(thePlayer, msg)
if string.find(msg, 'slap') then --Here we have put the word or the msg that will be used to slap the player
killPed (thePlayer, thePlayer) --This the action >> killing the player
end --End if
end --End function
addEventHandler("onPlayerChat", getRootElement(), Slap)
</syntaxhighlight>
</section>

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