Pair: getElementData

Updated in 1.6.0-9.22815

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 (by default).

Tip

• A simple and efficient way to make a variable known to the server and clients is to use setElementData on the root element.
• See element data perfromance for tips on optimizing the use of element data.

Note

• 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.
• A subscription mode has been introduced for setElementData serverside. When setting data in subscription mode, only clients that are added through addElementDataSubscriber will receive the data, which is good for performance. Note this mode only works when setting element data serverside. Setting data clientside still sends the update to all clients if 'synchronize' is set to true.

Caution

For performance reasons, never use setElementData (with sync = true) in events that fire often (like onClientRender) without further optimization or conditions. In fact, using element data in general, can take such a toll on performance that not using it unless strictly necessary (e.g use alternatives such as storing data in tables) is recommended.

Important

• As element data is synced to all clients (by default), it can generate a lot of network traffic and be heavy on performance. Events are much more efficient for sending data from a client to the server only, or from the server to a specific client. Usage of element data should be discouraged where your goal can be achieved with events, and tables for storing and retrieving data. You can also use the subscription mode on serverside.
• See Element data security for tips on preventing cheaters when using events and element data.

OOP Syntax Help! I don't understand this!

• Method:element:setData(...)

Client Syntax

​bool setElementData ( ​element theElement, ​string key, ​var value, [ ​bool synchronize = true ] )

Required Arguments

• theElement: The element you wish to attach the data to.
• key: The key you wish to store the data under. (Maximum 128 characters.)
• value: The value you wish to store. See element data restrictions.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

• synchronize (default: true): Determines whether or not the data will be synchronized with the server.

Returns

• bool: result

Returns true if the data was set successfully, false otherwise.

Server Syntax

​bool setElementData ( ​element theElement, ​string key, ​var value, [ ​string syncMode = "broadcast", ​string clientChangesPolicy = "default" ] )

Required Arguments

• theElement: The element you wish to attach the data to.
• key: The key you wish to store the data under. (Maximum 128 characters.)
• value: The value you wish to store. See element data restrictions.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

• syncMode (default: "broadcast"): Synchronization mode.
  • broadcast: Synchronize to all clients (default behavior). You can also parse true for this option.
  • local: Don't synchronize. You can also parse false for this option.
  • subscribe: Only synchronize to specific clients. See addElementDataSubscriber and removeElementDataSubscriber.
• clientChangesPolicy (default: "default"): Client changes policy.
  • default: Use elementdata_whitelisted setting from mtaserver.conf.
  • allow: Trust changes from clients.
  • deny: Deny client changes. The server will trigger the onPlayerChangesProtectedData event when the client attempts to change the value.

Returns

• bool: result

Returns true if the data was set successfully, false otherwise.

Code Examples

Example 1 Example 2 Example 3 (OOP)

client

This example gives the player a score for each kill they make.

addEventHandler("onClientPlayerWasted", root, function(killer, weapon)
    if (killer == localPlayer) then
        local scoreToAdd = weapon == 0 and 10 or 5 -- Fist kills give more points
        local currentScore = getElementData(localPlayer, "playerScore") or 0
        setElementData(localPlayer, "playerScore", currentScore + scoreToAdd, false) -- Data not synchronized to server
    end
end)

addCommandHandler("showscore", root, function()
    local score = getElementData(localPlayer, "playerScore") or 0
    outputChatBox("Your current score is: " .. score)
end)

addEventHandler('onClientResourceStart', resourceRoot, function()
    setElementData(localPlayer, "playerScore", 0, false) -- Data not synchronized to server
end)

server

This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.

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)

server

OOP Required

This example allow a player to set maximum passengers number for their vehicle.

addCommandHandler('setmaxpassengers', function(plr, cmd, maxPassengers)
    if (not tonumber(maxPassengers)) then
        plr:outputChat('Usage: /' .. cmd .. ' [maxPassengers]', 255, 0, 0)
        return
    end

    local veh = plr.vehicle
    if (not veh) then
        plr:outputChat('You are not in a vehicle.', 255, 0, 0)
        return
    end

    if (tonumber(maxPassengers) < 0) then
        plr:outputChat('Max passengers cannot be negative.', 255, 0, 0)
        return
    end

    if (tonumber(maxPassengers) > veh.maxPassengers) then
        plr:outputChat('Max passengers cannot exceed the vehicle\'s maximum of ' .. veh.maxPassengers .. '.', 255, 0, 0)
        return
    end

    veh:setData('maxPassengers', tonumber(maxPassengers), false) -- Keep data server-side only, no need to sync to clients
    plr:outputChat('Max passengers for this vehicle set to ' .. maxPassengers .. '.', 0, 255, 0)
end)

addEventHandler('onVehicleStartEnter', root, function(plr, seat)
    if (seat == 0) then return end -- Driver seat, ignore

    local maxPassengers = source:getData('maxPassengers')
    if (maxPassengers) then
        local occupants = source.occupants
        local passengersCount = #occupants - 1 -- Exclude driver

        if (passengersCount >= maxPassengers) then
            plr:outputChat('This vehicle has reached its maximum number of passengers (' .. maxPassengers .. ').', 255, 0, 0)
            cancelEvent()
        end
    end
end)

Changelog

1.5.8-9.20477

Added syncMode argument.

1.6.0-9.22815

Added clientChangesPolicy argument.

See Also

Element Functions

• addElementDataSubscriber
• attachElements
• clearElementVisibleTo
• cloneElement
• createElement
• destroyElement
• detachElements
• getAllElementDataUpdated
• getAttachedElements
• getElementAlpha
• getElementAngularVelocity
• getElementAttachedOffsets
• getElementAttachedTo
• getElementBonePosition
• getElementBoneQuaternionNew
• getElementBoneRotation
• getElementBoundingBox
• getElementByID
• getElementByIndex
• getElementChild
• getElementChildren
• getElementChildrenCount
• getElementCollisionsEnabled
• getElementColShape
• getElementData
• getElementDimension
• getElementDistanceFromCentreOfMassToBaseOfModel
• getElementHealth
• getElementID
• getElementInterior
• getElementLighting
• getElementMatrix
• getElementModel
• getElementParent
• getElementPosition
• getElementRadius
• getElementRotation
• getElementsByType
• getElementsWithinColShape
• getElementsWithinRange
• getElementSyncer
• getElementType
• getElementVelocity
• getElementZoneName
• getLowLODElement
• getRootElement
• hasElementData
• hasElementDataSubscriber
• isElement
• isElementAttached
• isElementCallPropagationEnabled
• isElementCollidableWith
• isElementDoubleSided
• isElementFrozen
• isElementInWater
• isElementLocal
• isElementLowLOD
• isElementOnFireNew
• isElementOnScreen
• isElementStreamable
• isElementStreamedIn
• isElementSyncer
• isElementVisibleTo
• isElementWaitingForGroundToLoad
• isElementWithinColShape
• isElementWithinMarker
• removeElementData
• removeElementDataSubscriber
• setElementAlpha
• setElementAngularVelocity
• setElementAttachedOffsets
• setElementBonePosition
• setElementBoneQuaternionNew
• setElementBoneRotation
• setElementCallPropagationEnabled
• setElementCollidableWith
• setElementCollisionsEnabled
• setElementDataUpdated
• setElementDimension
• setElementDoubleSided
• setElementFrozen
• setElementHealth
• setElementID
• setElementInterior
• setElementLightingNew
• setElementMatrix
• setElementModel
• setElementOnFireNew
• setElementParent
• setElementPosition
• setElementRotation
• setElementStreamable
• setElementSyncer
• setElementVelocity
• setElementVisibleTo
• setLowLODElement
• updateElementRpHAnim

Element Events

• onClientElementColShapeHit
• onClientElementColShapeLeave
• onClientElementDataChange
• onClientElementDestroy
• onClientElementDimensionChange
• onClientElementInteriorChange
• onClientElementModelChange
• onClientElementStreamIn
• onClientElementStreamOut
• onElementClicked
• onElementColShapeHit
• onElementColShapeLeave
• onElementDataChange
• onElementDestroy
• onElementDimensionChange
• onElementInteriorChange
• onElementModelChange
• onElementStartSync
• onElementStopSync

Reference

• Scripting Functions