SetElementData - Revision history

O22: Issue has been closed

2025-10-31T15:07:37Z

Issue has been closed

← Older revision		Revision as of 15:07, 31 October 2025
Line 37:		Line 37:
	**''"allow"'' - Trust changes from clients.		**''"allow"'' - Trust changes from clients.
	**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.		**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
	~~{{Note\|Linux server users [https://github.com/multitheftauto/mtasa-blue/issues/4109 have reported crashes] when using the clientChangesPolicy argument.}}~~
	\|22815}}		\|22815}}
	</section>		</section>

Arran Fortuna at 18:10, 19 August 2025

2025-08-19T18:10:10Z

← Older revision		Revision as of 18:10, 19 August 2025
Line 37:		Line 37:
	**''"allow"'' - Trust changes from clients.		**''"allow"'' - Trust changes from clients.
	**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.		**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
			{{Note\|Linux server users [https://github.com/multitheftauto/mtasa-blue/issues/4109 have reported crashes] when using the clientChangesPolicy argument.}}
	\|22815}}		\|22815}}
	</section>		</section>

Zver-CR at 19:43, 26 March 2025

2025-03-26T19:43:48Z

← Older revision		Revision as of 19:43, 26 March 2025
Line 111:		Line 111:
	</syntaxhighlight>		</syntaxhighlight>
	</section>		</section>
	~~[[tr:setElementData]]~~
			==Changelog==
			{{ChangelogHeader}}
			{{ChangelogItem\|1.6.0-9.22815\|Added clientChangesPolicy argument}}

	==See Also==		==See Also==
			{{Element_functions}}

	[[pt-br:SetElementData]]		[[pt-br:SetElementData]]
	~~{{Element_functions}}~~		[[tr:setElementData]]

Zver-CR at 18:56, 26 March 2025

2025-03-26T18:56:19Z

← Older revision		Revision as of 18:56, 26 March 2025
Line 6:		Line 6:
	Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table\|tables]] for storing and retrieving data.		Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table\|tables]] for storing and retrieving data.
	{{Tip\|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}		{{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}}		{{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. 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.}}		{{Note\|For performance reasons, never use setElementData 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.}}

	{{New items\|5.~~0157~~\|1.5.7~~-9.20477~~\|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.		{{New items\|3.0158\|1.5.7\|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.		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.
	}}		\|20477}}

	==Syntax==		==Syntax==
			<section name="Server" class="server" show="true">
	<syntaxhighlight lang="lua">		<syntaxhighlight lang="lua">
	bool setElementData ( element theElement, string key, var value [, ~~bool synchronize~~ = ~~true~~ ] )		bool setElementData ( element theElement, string key, var value [, string syncMode = "broadcast", string clientChangesPolicy = "default" ] )
	</syntaxhighlight>		</syntaxhighlight>
	{{OOP\|\|[[element]]:setData\|\|getElementData}}		{{OOP\|\|[[element]]:setData\|\|getElementData}}
Line 26:		Line 26:

	===Optional Arguments===		===Optional Arguments===
	*'''synchronize:''' Determines whether or not the data will be synchronized with the clients (server-side variation) or server (client-side variation)		{{New items\|3.0158\|1.5.7\|
			*'''syncMode:''' Synchronization mode.
	~~===Returns===~~		**''"broadcast"'' - Synchronize to all clients (default behavior). You can also parse ''true'' for this option.
	~~Returns ''true'' if the data was set successfully, ''false'' otherwise.~~		**''"local"'' - Don't synchronize. You can also parse ''false'' for this option.
			**''"subscribe"'' - Only synchronize to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
	{{New items\|5.~~0157~~\|1.5.7~~-9.20477\|~~		\|20477}}
	~~==Syntax==~~		{{New items\|3.0161\|1.6.0\|
	~~<section name="Server" class="server" show="true">~~
	~~<syntaxhighlight lang="lua">~~
	~~bool setElementData ( element theElement, string key, var value [, string syncMode="broadcast", string clientChangesPolicy="default" ] )~~
	~~</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]].
	{{New items\|6.~~0160~~\|1.6.0~~-22790~~\|
	*'''clientChangesPolicy:''' Client changes policy.		*'''clientChangesPolicy:''' Client changes policy.
	**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]		**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]
	**''"allow"'' - Trust changes from clients.		**''"allow"'' - Trust changes from clients.
	**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.		**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.
	}}		\|22815}}
	</section>		</section>

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

Line 74:		Line 57:
	===Returns===		===Returns===
	Returns ''true'' if the data was set successfully, ''false'' otherwise.		Returns ''true'' if the data was set successfully, ''false'' otherwise.
	}}

	==Example==		==Example==

Srslyyyy: Direct link to elementdata_whitelisted

2024-12-19T20:36:22Z

Direct link to elementdata_whitelisted

← Older revision		Revision as of 20:36, 19 December 2024
Line 26:		Line 26:

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

	===Returns===		===Returns===
Line 51:		Line 51:
	{{New items\|6.0160\|1.6.0-22790\|		{{New items\|6.0160\|1.6.0-22790\|
	*'''clientChangesPolicy:''' Client changes policy.		*'''clientChangesPolicy:''' Client changes policy.
	**''"default"'' - Use '''elementdata_whitelisted''' setting from [[Server_mtaserver.conf~~\|'''~~mtaserver.conf~~''']~~]		**''"default"'' - Use '''elementdata_whitelisted''' setting from [https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#elementdata_whitelisted mtaserver.conf]
	**''"allow"'' - Trust changes from clients.		**''"allow"'' - Trust changes from clients.
	**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.		**''"deny"'' - Deny client changes. The server will trigger the [[onPlayerChangesProtectedData]] event when the client attempts to change the value.

TheNormalnij: clientChangesPolicy

2024-12-06T13:12:43Z

clientChangesPolicy

← Older revision		Revision as of 13:12, 6 December 2024
Line 35:		Line 35:
	<section name="Server" class="server" show="true">		<section name="Server" class="server" show="true">
	<syntaxhighlight lang="lua">		<syntaxhighlight lang="lua">
	bool setElementData ( element theElement, string key, var value [, ~~var~~ syncMode="broadcast"] )		bool setElementData ( element theElement, string key, var value [, string syncMode="broadcast", string clientChangesPolicy="default" ] )
	</syntaxhighlight>		</syntaxhighlight>
	{{OOP\|\|[[element]]:setData\|\|getElementData}}		{{OOP\|\|[[element]]:setData\|\|getElementData}}
Line 49:		Line 49:
	**''"local"'' - Don't synchronise. You can also parse ''false'' 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]].		**''"subscribe"'' - Only synchronise to specific clients. See [[addElementDataSubscriber]] and [[removeElementDataSubscriber]].
			{{New items\|6.0160\|1.6.0-22790\|
			*'''clientChangesPolicy:''' Client changes policy.
			**''"default"'' - Use '''elementdata_whitelisted''' setting from [[Server_mtaserver.conf\|'''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.
			}}
	</section>		</section>

Srslyyyy: Remove dot.

2023-06-10T19:10:50Z

Remove dot.

← Older revision		Revision as of 19:10, 10 June 2023
Line 7:		Line 7:
	{{Tip\|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}		{{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}}		{{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. 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.}}.		{{Note\|For performance reasons, never use setElementData 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.}}

	{{New items\|5.0157\|1.5.7-9.20477\|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.		{{New items\|5.0157\|1.5.7-9.20477\|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.

Lettify at 16:31, 12 February 2022

2022-02-12T16:31:32Z

← Older revision		Revision as of 16:31, 12 February 2022
Line 70:		Line 70:
	}}		}}

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

FeaturedPro: corrected spelling and grammar

2022-02-02T23:17:10Z

corrected spelling and grammar

← Older revision		Revision as of 23:17, 2 February 2022
Line 1:		Line 1:
	{{Server client function}}		{{Server client function}}
	__NOTOC__		__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.		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. <br/>		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. <br/>
	Usage of element data should be ~~disencouraged~~ where your goal can be achieved with events like above, and [[table\|tables]] for storing and retrieving data.		Usage of element data should be discouraged where your goal can be achieved with events like above, and [[table\|tables]] for storing and retrieving data.
	{{Tip\|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}		{{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}}		{{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. In fact, using element data in general can take such a toll on performance that not using it unless strictly ~~neccesary~~ (e.g use alternatives such as storing data in tables) is recommended.}}.		{{Note\|For performance reasons, never use setElementData 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.}}.

	{{New items\|5.0157\|1.5.7-9.20477\|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.		{{New items\|5.0157\|1.5.7-9.20477\|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.
Line 29:		Line 29:

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

	{{New items\|5.0157\|1.5.7-9.20477\|		{{New items\|5.0157\|1.5.7-9.20477\|
Line 67:		Line 67:

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

Zangomangu: Removed fixed issue

2022-01-30T10:46:39Z

Removed fixed issue

← Older revision		Revision as of 10:46, 30 January 2022
Line 68:		Line 68:
	===Returns===		===Returns===
	Returns ''true'' if the data was set succesfully, ''false'' otherwise.		Returns ''true'' if the data was set succesfully, ''false'' otherwise.
	}}

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

← Older revision		Revision as of 19:10, 10 June 2023
Line 7:		Line 7:
	{{Tip\|A simple and efficient way to make a variable known to the server and clients is to use setElementData on the [[root]] element.}}		{{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}}		{{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. 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.}}.		{{Note\|For performance reasons, never use setElementData 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.}}

	{{New items\|5.0157\|1.5.7-9.20477\|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.		{{New items\|5.0157\|1.5.7-9.20477\|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.