setRoomVariables()

Availability:

SmartFoxServer Lite / Basic / Pro

Usage:

smartFox.setRoomVariables(variables <proplist>, roomId <integer>, setOwnership <true/false>)

Description:

Stores data on the server side. When you set one or more Room Variables all the other users in the room will be notified.
It is a usefull feature to share data across the client, keeping it in a centralized place: the server.

Parameters:

variables   a propertylist of variables. Each variable is a propertylist, see below.
roomId   (optional) The id of the room where the variables are going to be stored.
By default SmartFoxServer uses the current room, that is stored in the activeRoomId property.
You can pass this extra argument if you are allowing users to be present in more than one room at the same time.
setOwnership   A flag, by default = true. If set to false the room variable won't change ownership.

Each variable object can have the following properties:

name   the variable name
val   value of the variable
priv   true if a variable is private. A private variable can only be overwritten by the user that created it
persistent   true if the variable is persistent. A persistent variable is not destroyed when the user goes out of the room.
The default behaviour deletes all the variables of a user that left the room

Allowed datatypes are Strings, integers, rectangles, points and rgb
If a room variable is set to void it is going to be deleted from the server.

To save bandwidth lists and propertylists are not supported but it is easy to "simulate them". Check the examples below.

Returns:

Fires the onRoomVariablesUpdate event

Example:

Example #1
save a persistent "score" room variable. This variable will not be destroyed when the user that created it leaves the room.

rVars = [ [#name:"score", #val:2500, #persistent:true]  ]

smartFox.setRoomVariables(rVars)


Example #2


Save two room variables at once. The one called "bestTime" is private and no other users except its owner will be able to modify it.

rVars = []
rVars.append( [#name:"bestTime", #val:100, #priv:true] )
rVars.append( [#name:"bestLap", #val:120] )

smartFox.setRoomVariables(rVars)

Example #3


Delete a variable called "myVar". To delete a room variable just set it to null

rVars = []
rVars.append( [#name:"bestTime", #val:void] )

smartFox.setRoomVariables(rVars)

Example #4


Simulate a list of values, by using an index in front of the name of the variable. This way you can send list-like of data without consuming too much bandwidth.

rVars = []
names = ["john", "dave", "sam"]

repeat with i=1 to names.count
	rVars.append( [#name:"name"&i, #val:names[i]] )
end repeat

smartFox.setRoomVariables(rVars)

Here's how you can handle this data when the other users receive the onRoomVariablesUpdate event:
on onRoomVariablesUpdate me, roomVars
	repeat with i=1 to roomVars.count
	    put "name " & i &" "& roomVars["name"&i])
	end repeat
end


Example #5
This example shows how to update Room Variables without affecting the variable ownership.
By default, when a user updates a server variable, he becomes the "owner" of that variable. In some cases you may need to disable this behavoir by setting the setOwnership to false.

For example: a variable that is defined in the config.xml will be owned by the Server. If it's not set to private its owner will change as soon as a client updates it. To avoid this change of ownership set the flag to false.


rVars = []
rVars.append( [#name:"shipPosX", #val:100] )
rVars.append( [#name:"shipPosY", #val:200] )
smartFox.setRoomVariables(rVars, smartFox.getActiveRoom()[#id], false)


See also:

onRoomVariablesUpdate