SetElementData: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(improved performance caveat information)
(1.5.8 changes (Element data subscription))
Line 9: Line 9:
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
{{Note|See [[Script security]] for tips on preventing cheaters when using events and element data}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions.}}
{{Note|For performance reasons, never use setElementData in events that fire often (like [[onClientRender]]) without further optimization or conditions.}}
{{New items|5.0154|1.5.8|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.
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.
}}


==Syntax==  
==Syntax==  
Line 27: Line 32:
===Returns===
===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.
Returns ''true'' if the data was set succesfully, ''false'' otherwise.
{{New items|5.0154|1.5.8|
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool setElementData ( element theElement, string key, var value [, var syncMode="broadcast"] )
</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===
*'''syncMode:''' Synchronisation mode.
**''"broadcast"'' - Synchronise to all clients (default behavior). You can also parse ''true'' for this option.
**''"local"'' - Don't synchronise. You can also parse ''false'' for this option.
**''"subscribe"'' - Only synchronise to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
</section>
<section name="Client" class="client" show="true">
<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.
</section>
===Returns===
Returns ''true'' if the data was set succesfully, ''false'' otherwise.
}}


===Issues===
===Issues===
Line 34: Line 78:


==Example==  
==Example==  
<section name="Server" class="server" show="true">
<section name="Server" class="server" show="false">
This example allows a player to add a custom tag onto their nickname, and also reverts it back to normal if they wish.
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">
<syntaxhighlight lang="lua">

Revision as of 20:41, 2 July 2020

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 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 disencouraged where your goal can be achieved with events like above, and tables for storing and retrieving data.


[[{{{image}}}|link=|]] Tip: A simple and efficient way to make a variable known to the server and clients is to use setElementData on the root element.
[[{{{image}}}|link=|]] Note: See Script security for tips on preventing cheaters when using events and element data
[[{{{image}}}|link=|]] Note: For performance reasons, never use setElementData in events that fire often (like onClientRender) without further optimization or conditions.


ADDED/UPDATED IN VERSION 1.5.8 :
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.

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.

Syntax

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

OOP Syntax Help! I don't understand this!

Method: element:setData(...)
Counterpart: 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 clients(server-side variation) or server(client-side variation)

Returns

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

ADDED/UPDATED IN VERSION 1.5.8 :

Syntax

Click to collapse [-]
Server
bool setElementData ( element theElement, string key, var value [, var syncMode="broadcast"] )

OOP Syntax Help! I don't understand this!

Method: element:setData(...)
Counterpart: 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

  • syncMode: Synchronisation mode.
    • "broadcast" - Synchronise to all clients (default behavior). You can also parse true for this option.
    • "local" - Don't synchronise. You can also parse false for this option.
    • "subscribe" - Only synchronise to specific clients. See addElementDataSubscriber and removeElementDataSubscriber.
Click to collapse [-]
Client
bool setElementData ( element theElement, string key, var value [, bool synchronize = true ] )

OOP Syntax Help! I don't understand this!

Method: element:setData(...)
Counterpart: 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.

Returns

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

Issues

Issue ID Description
#7389 [Fixed in 1.3.5-7389] Problem with floating numbers

Example

Click to expand [+]
Server

See Also