setRoomVariables()

Availability:

Flash Player 7, 8
SmartFoxServer Lite / Basic / Pro

Usage:

smartFox.setRoomVariables(variables:Array, roomId:Number, setOwnership:Boolean)

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   an array of variables. Each variable is an object with the following properties:
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 boolean 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, Numbers, Booleans.
If a room variable is set to null it is going to be deleted from the server.

To save bandwidth arrays and objects 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.

var rVars:Array = []
rVars.push( {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.

var rVars:Array = []
rVars.push( {name:"bestTime", val:100, priv:true} )
rVars.push( {name:"bestLap", val:120} )

smartFox.setRoomVariables(rVars)

Example #3


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

var rVars:Array = []
rVars.push( {name:"bestTime", val:null} )

smartFox.setRoomVariables(rVars)

Example #4


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

var rVars:Array = []
var names:Array = ["john", "dave", "sam"]

for (var i = 0; i < names.length; i++)
{
	rVars.push( {name:"name" + i, val:names[i]} )
}

smartFox.setRoomVariables(rVars)

Here's how you can handle this data when the other users receive the onRoomVariablesUpdate event:
smartFox.onRoomVariablesUpdate = function(roomVars:Object)
{
	for (var i:Number = 0; i < 3; i++)
	{
		trace("name " + i + ": " + roomVars["name" + i])
	}
}


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.


var rVars:Array = []
rVars.push( {name:"shipPosX", val:100} )
rVars.push( {name:"shipPosY", val:200} )
smartFox.setRoomVariables(rVars, smartFox.getActiveRoom(), false)


See also:

onRoomVariablesUpdate