SFSEvent

Kind of class:public class
Package:it.gotoandplay.smartfoxserver
Inherits from:Event
Dispatched by:
Version:1.1.0
Author:The gotoAndPlay() Team
http://www.smartfoxserver.com
http://www.gotoandplay.it
Classpath:it.gotoandplay.smartfoxserver.SFSEvent
File last modified:Thursday, 09 April 2009, 11:22:31
SFSEvent is the class representing all events dispatched by the SmartFoxClient instance.
The SFSEvent class extends the flash.events.Event class and provides a public property called params of type Object that can contain any number of parameters.
Usage:
  • The following example show a generic usage of a SFSEvent. Please refer to the specific events for the params object content.
    package sfsTest
    {
    import it.gotoandplay.smartfoxserver.SmartFoxClient
    import it.gotoandplay.smartfoxserver.SFSEvent
    
    public class MyTest
    {
        private var smartFox:SmartFoxClient
    
        public function MyTest()
        {
            // Create instance
            smartFox = new SmartFoxClient()
    
            // Add event handler for connection 
            smartFox.addEventListener(SFSEvent.onConnection, onConnectionHandler)
    
            // Connect to server
            smartFox.connect("127.0.0.1", 9339)	
        }
    
        // Handle connection event
        public function onConnectionHandler(evt:SFSEvent):void
        {
            if (evt.params.success)
                trace("Great, successfully connected!")
            else
                trace("Ouch, connection failed!")
        }	
    }
    }
    NOTE: in the following examples, smartFox always indicates a SmartFoxClient instance.

Summary


Instance properties
  • params : Object
    • An object containing all the parameters related to the dispatched event.
Instance methods
  • clone : Event
    • Get a copy of the current instance.
  • toString : String
    • Get a string containing all the properties of the current instance.
Event handlers
  • onAdminMessage : String
    • Dispatched when a message from the Administrator is received.
  • onBuddyList : String
    • Dispatched when the buddy list for the current user is received or a buddy is added/removed.
  • onBuddyListError : String
    • Dispatched when an error occurs while loading the buddy list.
  • onBuddyListUpdate : String
    • Dispatched when the status or variables of a buddy in the buddy list change.
  • onBuddyPermissionRequest : String
    • Dispatched when the current user receives a request to be added to the buddy list of another user.
  • onBuddyRoom : String
    • Dispatched in response to a SmartFoxClient.getBuddyRoom request.
  • onConfigLoadFailure : String
    • Dispatched when an error occurs while loading the external SmartFoxClient configuration file.
  • onConfigLoadSuccess : String
    • Dispatched when the external SmartFoxClient configuration file has been loaded successfully.
  • onConnection : String
    • Dispatched in response to the SmartFoxClient.connect request.
  • onConnectionLost : String
    • Dispatched when the connection with SmartFoxServer is closed (either from the client or from the server).
  • onCreateRoomError : String
    • Dispatched when an error occurs during the creation of a room.
  • onDebugMessage : String
    • Dispatched when a debug message is traced by the SmartFoxServer API.
  • onExtensionResponse : String
    • Dispatched when a command/response from a server-side extension is received.
  • onJoinRoom : String
    • Dispatched when a room is joined successfully.
  • onJoinRoomError : String
    • Dispatched when an error occurs while joining a room.
  • onLogin : String
    • Dispatched when the login to a SmartFoxServer zone has been attempted.
  • onLogout : String
    • Dispatched when the user logs out successfully.
  • onModeratorMessage : String
    • Dispatched when a message from a Moderator is received.
  • onObjectReceived : String
    • Dispatched when an Actionscript object is received.
  • onPrivateMessage : String
    • Dispatched when a private chat message is received.
  • onPublicMessage : String
    • Dispatched when a public chat message is received.
  • onRandomKey : String
    • Dispatched in response to a SmartFoxClient.getRandomKey request.
  • onRoomAdded : String
    • Dispatched when a new room is created in the zone where the user is currently logged in.
  • onRoomDeleted : String
    • Dispatched when a room is removed from the zone where the user is currently logged in.
  • onRoomLeft : String
    • Dispatched when a room is left in multi-room mode, in response to a SmartFoxClient.leaveRoom request.
  • onRoomListUpdate : String
    • Dispatched when the list of rooms available in the current zone is received.
  • onRoomVariablesUpdate : String
    • Dispatched when Room Variables are updated.
  • onRoundTripResponse : String
    • Dispatched when a response to the SmartFoxClient.roundTripBench request is received.
  • onSpectatorSwitched : String
    • Dispatched in response to the SmartFoxClient.switchSpectator request.
  • onPlayerSwitched : String
    • Dispatched in response to the SmartFoxClient.switchPlayer request.
  • onUserCountChange : String
    • Dispatched when the number of users and/or spectators changes in a room within the current zone.
  • onUserEnterRoom : String
    • Dispatched when another user joins the current room.
  • onUserLeaveRoom : String
    • Dispatched when a user leaves the current room.
  • onUserVariablesUpdate : String
    • Dispatched when a user in the current room updates his/her User Variables.

Instance properties

params

public params:Object
(read,write)

An object containing all the parameters related to the dispatched event.
See the class constants for details on the specific parameters contained in this object.

Instance methods

clone

override public function clone (
) : Event

Get a copy of the current instance.
Returns:
  • a copy of the current instance.
Overrides:
  • Event.clone
Version:
  • SmartFoxServer Basic / Pro

toString

override public function toString (
) : String

Get a string containing all the properties of the current instance.
Returns:
  • a string representation of the current instance.
Overrides:
  • Event.toString
Version:
  • SmartFoxServer Basic / Pro

Event handlers

onAdminMessage

public static const onAdminMessage:String = "onAdminMessage"
(read)

Dispatched when a message from the Administrator is received.
Admin messages are special messages that can be sent by an Administrator to a user or group of users.
All client applications should handle this event, or users won't be be able to receive important admin notifications!

The params object contains the following parameters.
Parameters:
message:
(String) the Administrator's message.
Example:
  • The following example shows how to handle a message coming from the Administrator.
    smartFox.addEventListener(SFSEvent.onAdminMessage, onAdminMessageHandler)
    
    function onAdminMessageHandler(evt:SFSEvent):void
    {
        trace("Administrator said: " + evt.params.message)
    }
Version:
  • SmartFoxServer Basic / Pro

onBuddyList

public static const onBuddyList:String = "onBuddyList"
(read)

Dispatched when the buddy list for the current user is received or a buddy is added/removed.

The params object contains the following parameters.
Parameters:
list:
(Array) the buddy list. Refer to the SmartFoxClient.buddyList property for a description of the buddy object's properties.
Example:
  • The following example shows how to retrieve the properties of each buddy when the buddy list is received.
    smartFox.addEventListener(SFSEvent.onBuddyList, onBuddyListHandler)
    
    smartFox.loadBuddyList()		
    
    function onBuddyListHandler(evt:SFSEvent):void
    {
        for (var b:String in evt.params.list)
        {
            var buddy:Object = evt.params.list[b]
    
            trace("Buddy id: " + buddy.id)
            trace("Buddy name: " + buddy.name)
            trace("Is buddy online? " + buddy.isOnline ? "Yes" : "No")
            trace("Is buddy blocked? " + buddy.isBlocked ? "Yes" : "No")
    
            trace("Buddy Variables:")
            for (var v:String in buddy.variables)
                trace("\t" + v + " --> " + buddy.variables[v])
        }
    }
Version:
  • SmartFoxServer Basic / Pro

onBuddyListError

public static const onBuddyListError:String = "onBuddyListError"
(read)

Dispatched when an error occurs while loading the buddy list.

The params object contains the following parameters.
Parameters:
error:
(String) the error message.
Example:
  • The following example shows how to handle a potential error in buddy list loading.
    smartFox.addEventListener(SFSEvent.onBuddyListError, onBuddyListErrorHandler)
    
    function onBuddyListErrorHandler(evt:SFSEvent):void
    {
        trace("An error occurred while loading the buddy list: " + evt.params.error)
    }
See also:
Version:
  • SmartFoxServer Basic / Pro

onBuddyListUpdate

public static const onBuddyListUpdate:String = "onBuddyListUpdate"
(read)

Dispatched when the status or variables of a buddy in the buddy list change.

The params object contains the following parameters.
Parameters:
buddy:
(Object) an object representing the buddy whose status or Buddy Variables have changed. Refer to the SmartFoxClient.buddyList property for a description of the buddy object's properties.
Example:
  • The following example shows how to handle the online status change of a buddy.
    smartFox.addEventListener(SFSEvent.onBuddyListUpdate, onBuddyListUpdateHandler)
    
    function onBuddyListUpdateHandler(evt:SFSEvent):void
    {
        var buddy:Object = evt.params.buddy
    
        var name:String = buddy.name
        var status:String = (buddy.isOnline) ? "online" : "offline"
    
        trace("Buddy " + name + " is currently " + status)
    }
Version:
  • SmartFoxServer Basic / Pro

onBuddyPermissionRequest

public static const onBuddyPermissionRequest:String = "onBuddyPermissionRequest"
(read)

Dispatched when the current user receives a request to be added to the buddy list of another user.

The params object contains the following parameters.
Parameters:
sender :
(String) the name of the user requesting to add the current user to his/her buddy list.
message:
(String) a message accompaining the permission request. This message can't be sent from the client-side, but it's part of the advanced server-side buddy list features.
Example:
  • The following example shows how to handle the request to be added to a buddy list.
    smartFox.addEventListener(SFSEvent.onBuddyPermissionRequest, onBuddyPermissionRequestHandler)
    
    function onBuddyPermissionRequestHandler(evt:SFSEvent):void
    {
        // Create alert using custom class from Flash library
        var alert_mc:CustomAlertPanel = new CustomAlertPanel()
    
        alert_mc.name_lb.text = evt.params.sender
        alert_mc.message_lb.text = evt.params.message
    
        // Display alert
        addChild(alert_mc)
    }
Since:
  • SmartFoxServer Pro v1.6.0
Version:
  • SmartFoxServer Pro

onBuddyRoom

public static const onBuddyRoom:String = "onBuddyRoom"
(read)

Dispatched in response to a SmartFoxClient.getBuddyRoom request.

The params object contains the following parameters.
Parameters:
idList:
(Array) the list of id of the rooms in which the buddy is currently logged; if users can't be present in more than one room at the same time, the list will contain one room id only, at 0 index.
Example:
  • The following example shows how to join the same room in which the buddy currently is.
    smartFox.addEventListener(SFSEvent.onBuddyRoom, onBuddyRoomHandler)
    
    var buddy:Object = smartFox.getBuddyByName("jack")
    smartFox.getBuddyRoom(buddy)
    
    function onBuddyRoomHandler(evt:SFSEvent):void
    {
        // Reach the buddy in his room
        smartFox.join(evt.params.idList[0])
    }
Version:
  • SmartFoxServer Basic / Pro

onConfigLoadFailure

public static const onConfigLoadFailure:String = "onConfigLoadFailure"
(read)

Dispatched when an error occurs while loading the external SmartFoxClient configuration file.

The params object contains the following parameters.
Parameters:
message:
(String) the error message.
Example:
  • The following example shows how to handle a potential error in configuration loading.
    smartFox.addEventListener(SFSEvent.onConfigLoadFailure, onConfigLoadFailureHandler)
    
    smartFox.loadConfig("testEnvironmentConfig.xml")
    
    function onConfigLoadFailureHandler(evt:SFSEvent):void
    {
        trace("Failed loading config file: " + evt.params.message)
    }
Since:
  • SmartFoxServer Pro v1.6.0
Version:
  • SmartFoxServer Pro

onConfigLoadSuccess

public static const onConfigLoadSuccess:String = "onConfigLoadSuccess"
(read)

Dispatched when the external SmartFoxClient configuration file has been loaded successfully.
This event is dispatched only if the autoConnect parameter of the SmartFoxClient.loadConfig method is set to false; otherwise the connection is made and the onConnection event fired.

No parameters are provided.
Example:
  • The following example shows how to handle a successful configuration loading.
    smartFox.addEventListener(SFSEvent.onConfigLoadSuccess, onConfigLoadSuccessHandler)
    
    smartFox.loadConfig("testEnvironmentConfig.xml", false)
    
    function onConfigLoadSuccessHandler(evt:SFSEvent):void
    {
        trace("Config file loaded, now connecting...")
    
        smartFox.connect(smartFox.ipAddress, smartFox.port)
    }
Since:
  • SmartFoxServer Pro v1.6.0
Version:
  • SmartFoxServer Pro

onConnection

public static const onConnection:String = "onConnection"
(read)

Dispatched in response to the SmartFoxClient.connect request.
The connection to SmartFoxServer may have succeeded or failed: the success parameter must be checked.

The params object contains the following parameters.
Parameters:
success:
(Boolean) the connection result: true if the connection succeeded, false if the connection failed.
error :
(String) the error message in case of connection failure.
Example:
  • The following example shows how to handle the connection result.
        smartFox.addEventListener(SFSEvent.onConnection, onConnectionHandler)
    
    smartFox.connect("127.0.0.1", 9339)
    
    function onConnectionHandler(evt:SFSEvent):void
    {
        if (evt.params.success)
            trace("Connection successful")
        else
            trace("Connection failed")
    }
Version:
  • SmartFoxServer Basic / Pro

onConnectionLost

public static const onConnectionLost:String = "onConnectionLost"
(read)

Dispatched when the connection with SmartFoxServer is closed (either from the client or from the server).

No parameters are provided.
Example:
  • The following example shows how to handle a "connection lost" event.
    smartFox.addEventListener(SFSEvent.onConnectionLost, onConnectionLostHandler)
    
    function onConnectionLostHandler(evt:SFSEvent):void
    {
        trace("Connection lost!")
    
        // TODO: disable application interface
    }
Version:
  • SmartFoxServer Basic / Pro

onCreateRoomError

public static const onCreateRoomError:String = "onCreateRoomError"
(read)

Dispatched when an error occurs during the creation of a room.
Usually this happens when a client tries to create a room but its name is already taken.

The params object contains the following parameters.
Parameters:
error:
(String) the error message.
Example:
  • The following example shows how to handle a potential error in room creation.
    smartFox.addEventListener(SFSEvent.onCreateRoomError, onCreateRoomErrorHandler)
    
    var roomObj:Object = new Object()
    roomObj.name = "The Entrance"
    roomObj.maxUsers = 50
    
    smartFox.createRoom(roomObj)
    
    function onCreateRoomErrorHandler(evt:SFSEvent):void
    {
        trace("Room creation error; the following error occurred: " + evt.params.error)
    }
Version:
  • SmartFoxServer Basic / Pro

onDebugMessage

public static const onDebugMessage:String = "onDebugMessage"
(read)

Dispatched when a debug message is traced by the SmartFoxServer API.
In order to receive this event you have to previously set the SmartFoxClient.debug flag to true.

The params object contains the following parameters.
Parameters:
message:
(String) the debug message.
Example:
  • The following example shows how to handle a SmartFoxServer API debug message.
    smartFox.addEventListener(SFSEvent.onDebugMessage, onDebugMessageHandler)
    
    smartFox.debug = true
    
    function onDebugMessageHandler(evt:SFSEvent):void
    {
        trace("[SFS DEBUG] " + evt.params.message)
    }
Version:
  • SmartFoxServer Basic / Pro

onExtensionResponse

public static const onExtensionResponse:String = "onExtensionResponse"
(read)

Dispatched when a command/response from a server-side extension is received.

The params object contains the following parameters.
Parameters:
dataObj:
(Object) an object containing all the data sent by the server-side extension; by convention, a String property called _cmd should always be present, to distinguish between different responses coming from the same extension.
type :
(String) one of the following response protocol types: SmartFoxClient.XTMSG_TYPE_XML, SmartFoxClient.XTMSG_TYPE_STR, SmartFoxClient.XTMSG_TYPE_JSON. By default SmartFoxClient.XTMSG_TYPE_XML is used.
Example:
  • The following example shows how to handle an extension response.
    smartFox.addEventListener(SFSEvent.onExtensionResponse, onExtensionResponseHandler)
    
    function onExtensionResponseHandler(evt:SFSEvent):void
    {
        var type:String = evt.params.type
        var data:Object = evt.params.dataObj
    
        var command:String = data._cmd
    
        // Handle XML responses
        if (type == SmartFoxClient.XTMSG_TYPE_XML)
        {
            // TODO: check command and perform required actions
        }
    
        // Handle RAW responses
        else if (type == SmartFoxClient.XTMSG_TYPE_STR)
        {
            // TODO: check command and perform required actions
        }
    
        // Handle JSON responses
        else if (type == SmartFoxClient.XTMSG_TYPE_JSON)
        {
            // TODO: check command and perform required actions
        }
    }
Version:
  • SmartFoxServer Pro

onJoinRoom

public static const onJoinRoom:String = "onJoinRoom"
(read)

Dispatched when a room is joined successfully.

The params object contains the following parameters.
Parameters:
room:
(Room) the Room object representing the joined room.
Example:
  • The following example shows how to handle an successful room joining.
    smartFox.addEventListener(SFSEvent.onJoinRoom, onJoinRoomHandler)
    
    smartFox.joinRoom("The Entrance")
    
    function onJoinRoomHandler(evt:SFSEvent):void
    {
        var joinedRoom:Room = evt.params.room
    
        trace("Room " + joinedRoom.getName() + " joined successfully")
    }
Version:
  • SmartFoxServer Basic / Pro

onJoinRoomError

public static const onJoinRoomError:String = "onJoinRoomError"
(read)

Dispatched when an error occurs while joining a room.
This error could happen, for example, if the user is trying to join a room which is currently full.

The params object contains the following parameters.
Parameters:
error:
(String) the error message.
Example:
  • The following example shows how to handle a potential error in room joining.
    smartFox.addEventListener(SFSEvent.onJoinRoomError, onJoinRoomErrorHandler)
    
    smartFox.joinRoom("The Entrance")
    
    function onJoinRoomErrorHandler(evt:SFSEvent):void
    {
        trace("Room join error; the following error occurred: " + evt.params.error)
    }
Version:
  • SmartFoxServer Basic / Pro

onLogin

public static const onLogin:String = "onLogin"
(read)

Dispatched when the login to a SmartFoxServer zone has been attempted.

The params object contains the following parameters.
Parameters:
success:
(Boolean) the login result: true if the login to the provided zone succeeded; false if login failed.
name :
(String) the user's actual username.
error :
(String) the error message in case of login failure.

NOTE 1: the server sends the username back to the client because not all usernames are valid: for example, those containing bad words may have been filtered during the login process.

NOTE 2: for SmartFoxServer PRO. If the Zone you are accessing uses a custom login the login-response will be sent from server side and you will need to handle it using the onExtensionResponse handler.
Additionally you will need to manually set the myUserId and myUserName properties if you need them. (This is automagically done by the API when using a default login)
Example:
  • The following example shows how to handle the login result.
    smartFox.addEventListener(SFSEvent.onLogin, onLoginHandler)
    
    smartFox.login("simpleChat", "jack")
    
    function onLoginHandler(evt:SFSEvent):void
    {
        if (evt.params.success)
            trace("Successfully logged in as " + evt.params.name)
        else
            trace("Zone login error; the following error occurred: " + evt.params.error)
    }
Version:
  • SmartFoxServer Basic / Pro

onLogout

public static const onLogout:String = "onLogout"
(read)

Dispatched when the user logs out successfully.
After a successful logout the user is still connected to the server, but he/she has to login again into a zone, in order to be able to interact with the server.

No parameters are provided.
Example:
  • The following example shows how to handle the "logout" event.
    smartFox.addEventListener(SFSEvent.onLogout, onLogoutHandler)
    
    smartFox.logout()
    
    function onLogoutHandler(evt:SFSEvent):void
    {
        trace("Logged out successfully")
    }
Since:
  • SmartFoxServer Pro v1.5.5
Version:
  • SmartFoxServer Basic / Pro

onModeratorMessage

public static const onModeratorMessage:String = "onModMessage"
(read)

Dispatched when a message from a Moderator is received.

The params object contains the following parameters.
Parameters:
message:
(String) the Moderator's message.
sender :
(User) the User object representing the Moderator.
Example:
  • The following example shows how to handle a message coming from a Moderator.
    smartFox.addEventListener(SFSEvent.onModeratorMessage, onModeratorMessageHandler)
    
    function onModeratorMessageHandler(evt:SFSEvent):void
    {
        trace("Moderator " + evt.params.sender.getName() + " said: " + evt.params.message)
    }
Since:
  • SmartFoxServer Pro v1.4.5
Version:
  • SmartFoxServer Basic / Pro

onObjectReceived

public static const onObjectReceived:String = "onObjectReceived"
(read)

Dispatched when an Actionscript object is received.

The params object contains the following parameters.
Parameters:
obj :
(Object) the Actionscript object received.
sender:
(User) the User object representing the user that sent the Actionscript object.
Example:
  • The following example shows how to handle an Actionscript object received from a user.
    smartFox.addEventListener(SFSEvent.onObjectReceived, onObjectReceivedHandler)
    
    function onObjectReceivedHandler(evt:SFSEvent):void
    {
        // Assuming another client sent his X and Y positions in two properties called px, py
        trace("Data received from user: " + evt.params.sender.getName())
        trace("X = " + evt.params.obj.px + ", Y = " + evt.params.obj.py)
    }
Version:
  • SmartFoxServer Basic / Pro

onPlayerSwitched

public static const onPlayerSwitched:String = "onPlayerSwitched"
(read)

Dispatched in response to the SmartFoxClient.switchPlayer request.
The request to turn a player into a spectator may fail if another user did the same before your request, and there was only one spectator slot available.

The params object contains the following parameters.
Parameters:
success:
(Boolean) the switch result: true if the player was turned into a spectator, otherwise false.
newId :
(int) the player id assigned by the server to the user.
room :
(Room) the Room object representing the room where the switch occurred.
Example:
  • The following example shows how to handle the spectator switch.
    smartFox.addEventListener(SFSEvent.onPlayerSwitched, onPlayerSwitchedHandler)
    
    smartFox.switchPlayer()
    
    function onPlayerSwitchedHandler(evt:SFSEvent):void
    {
        if (evt.params.success)
            trace("You have been turned into a spectator; your id is " + evt.params.newId)
        else
            trace("The attempt to switch from player to spectator failed!")
    }
Version:
  • SmartFoxServer Pro

onPrivateMessage

public static const onPrivateMessage:String = "onPrivateMessage"
(read)

Dispatched when a private chat message is received.

The params object contains the following parameters.
Parameters:
message:
(String) the private message received.
sender :
(User) the User object representing the user that sent the message; this property is undefined if the sender isn't in the same room of the recipient.
roomId :
(int) the id of the room where the sender is.
Example:
  • The following example shows how to handle a private message.
    smartFox.addEventListener(SFSEvent.onPrivateMessage, onPrivateMessageHandler)
    
    smartFox.sendPrivateMessage("Hallo Jack!", 22)
    
    function onPrivateMessageHandler(evt:SFSEvent):void
    {
        trace("User " + evt.params.sender.getName() + " sent the following private message: " + evt.params.message)
    }
Version history:
  • SmartFoxServer Pro v1.5.0 - roomId and userId parameters added.
Version:
  • SmartFoxServer Basic / Pro

onPublicMessage

public static const onPublicMessage:String = "onPublicMessage"
(read)

Dispatched when a public chat message is received.

The params object contains the following parameters.
Parameters:
message:
(String) the public message received.
sender :
(User) the User object representing the user that sent the message.
roomId :
(int) the id of the room where the sender is.
Example:
  • The following example shows how to handle a public message.
    smartFox.addEventListener(SFSEvent.onPublicMessage, onPublicMessageHandler)
    
    smartFox.sendPublicMessage("Hello world!")
    
    function onPublicMessageHandler(evt:SFSEvent):void
    {
        trace("User " + evt.params.sender.getName() + " said: " + evt.params.message)
    }
Version:
  • SmartFoxServer Basic / Pro

onRandomKey

public static const onRandomKey:String = "onRandomKey"
(read)

Dispatched in response to a SmartFoxClient.getRandomKey request.

The params object contains the following parameters.
Parameters:
key:
(String) a unique random key generated by the server.
Example:
  • The following example shows how to handle the key received from the server.
    smartFox.addEventListener(SFSEvent.onRandomKey, onRandomKeyHandler)
    
    smartFox.getRandomKey()
    
    function onRandomKeyHandler(evt:SFSEvent):void
    {
        trace("Random key received from server: " + evt.params.key)
    }
Version:
  • SmartFoxServer Pro

onRoomAdded

public static const onRoomAdded:String = "onRoomAdded"
(read)

Dispatched when a new room is created in the zone where the user is currently logged in.

The params object contains the following parameters.
Parameters:
room:
(Room) the Room object representing the room that was created.
Example:
  • The following example shows how to handle a new room being created in the zone.
    smartFox.addEventListener(SFSEvent.onRoomAdded, onRoomAddedHandler)
    
    var roomObj:Object = new Object()
    roomObj.name = "The Entrance"
    roomObj.maxUsers = 50
    
    smartFox.createRoom(roomObj)
    
    function onRoomAddedHandler(evt:SFSEvent):void
    {
        trace("Room " + evt.params.room.getName() + " was created")
    
        // TODO: update available rooms list in the application interface
    }
Version:
  • SmartFoxServer Basic / Pro

onRoomDeleted

public static const onRoomDeleted:String = "onRoomDeleted"
(read)

Dispatched when a room is removed from the zone where the user is currently logged in.

The params object contains the following parameters.
Parameters:
room:
(Room) the Room object representing the room that was removed.
Example:
  • The following example shows how to handle a new room being removed in the zone.
    smartFox.addEventListener(SFSEvent.onRoomDeleted, onRoomDeletedHandler)
    
    function onRoomDeletedHandler(evt:SFSEvent):void
    {
        trace("Room " + evt.params.room.getName() + " was removed")
    
        // TODO: update available rooms list in the application interface
    }
See also:
Version:
  • SmartFoxServer Basic / Pro

onRoomLeft

public static const onRoomLeft:String = "onRoomLeft"
(read)

Dispatched when a room is left in multi-room mode, in response to a SmartFoxClient.leaveRoom request.

The params object contains the following parameters.
Parameters:
roomId:
(int) the id of the room that was left.
Example:
  • The following example shows how to handle the "room left" event.
    smartFox.addEventListener(SFSEvent.onRoomLeft, onRoomLeftHandler)
    
    function onRoomLeftHandler(evt:SFSEvent):void
    {
        trace("You left room " + evt.params.roomId)
    }
Version:
  • SmartFoxServer Basic / Pro

onRoomListUpdate

public static const onRoomListUpdate:String = "onRoomListUpdate"
(read)

Dispatched when the list of rooms available in the current zone is received.
If the default login mechanism provided by SmartFoxServer is used, then this event is dispatched right after a successful login.
This is because the SmartFoxServer API, internally, call the SmartFoxClient.getRoomList method after a successful login is performed.
If a custom login handler is implemented, the room list must be manually requested to the server by calling the mentioned method.

The params object contains the following parameters.
Parameters:
roomList:
(Array) a list of Room objects for the zone logged in by the user.
Example:
  • The following example shows how to handle the list of rooms sent by SmartFoxServer.
    smartFox.addEventListener(SFSEvent.onRoomListUpdate, onRoomListUpdateHandler)
    
    smartFox.login("simpleChat", "jack")
    
    function onRoomListUpdateHandler(evt:SFSEvent):void
    {
        // Dump the names of the available rooms in the "simpleChat" zone
        for (var r:String in evt.params.roomList)
            trace(evt.params.roomList[r].getName())
    }
Version:
  • SmartFoxServer Basic / Pro

onRoomVariablesUpdate

public static const onRoomVariablesUpdate:String = "onRoomVariablesUpdate"
(read)

Dispatched when Room Variables are updated.
A user receives this notification only from the room(s) where he/she is currently logged in. Also, only the variables that changed are transmitted.

The params object contains the following parameters.
Parameters:
room :
(Room) the Room object representing the room where the update took place.
changedVars:
(Array) an associative array with the names of the changed variables as keys. The array can also be iterated through numeric indexes (0 to changedVars.length) to get the names of the variables that changed.
NOTE: the changedVars array contains the names of the changed variables only, not the actual values. To retrieve them the Room.getVariable / Room.getVariables methods can be used.
Example:
  • The following example shows how to handle an update in Room Variables.
    smartFox.addEventListener(SFSEvent.onRoomVariablesUpdate, onRoomVariablesUpdateHandler)
    
    function onRoomVariablesUpdateHandler(evt:SFSEvent):void
    {
        var changedVars:Array = evt.params.changedVars
    
        // Iterate on the 'changedVars' array to check which variables were updated
        for (var v:String in changedVars)
            trace(v + " room variable was updated; new value is: " + evt.params.room.getVariable(v))
    }
Version:
  • SmartFoxServer Basic / Pro

onRoundTripResponse

public static const onRoundTripResponse:String = "onRoundTripResponse"
(read)

Dispatched when a response to the SmartFoxClient.roundTripBench request is received.
The "roundtrip time" represents the number of milliseconds that it takes to a message to go from the client to the server and back to the client.
A good way to measure the network lag is to send continuos requests (every 3 or 5 seconds) and then calculate the average roundtrip time on a fixed number of responses (i.e. the last 10 measurements).

The params object contains the following parameters.
Parameters:
elapsed:
(int) the roundtrip time.
Example:
  • The following example shows how to check the average network lag time.
    smartFox.addEventListener(SFSEvent.onRoundTripResponse, onRoundTripResponseHandler)
    
    var totalPingTime:Number = 0
    var pingCount:int = 0
    
    smartFox.roundTripBench() // TODO: this method must be called repeatedly every 3-5 seconds to have a significant average value
    
    function onRoundTripResponseHandler(evt:SFSEvent):void
    {
        var time:int = evt.params.elapsed
    
        // We assume that it takes the same time to the ping message to go from the client to the server
        // and from the server back to the client, so we divide the elapsed time by 2.
        totalPingTime += time / 2
        pingCount++
    
        var avg:int = Math.round(totalPingTime / pingCount)
    
        trace("Average lag: " + avg + " milliseconds")
    }
Version:
  • SmartFoxServer Basic / Pro

onSpectatorSwitched

public static const onSpectatorSwitched:String = "onSpectatorSwitched"
(read)

Dispatched in response to the SmartFoxClient.switchSpectator request.
The request to turn a spectator into a player may fail if another user did the same before your request, and there was only one player slot available.

The params object contains the following parameters.
Parameters:
success:
(Boolean) the switch result: true if the spectator was turned into a player, otherwise false.
newId :
(int) the player id assigned by the server to the user.
room :
(Room) the Room object representing the room where the switch occurred.
Example:
  • The following example shows how to check the handle the spectator switch.
    smartFox.addEventListener(SFSEvent.onSpectatorSwitched, onSpectatorSwitchedHandler)
    
    smartFox.switchSpectator()
    
    function onSpectatorSwitchedHandler(evt:SFSEvent):void
    {
        if (evt.params.success)
            trace("You have been turned into a player; your id is " + evt.params.newId)
        else
            trace("The attempt to switch from spectator to player failed")
    }
Version:
  • SmartFoxServer Basic / Pro

onUserCountChange

public static const onUserCountChange:String = "onUserCountChange"
(read)

Dispatched when the number of users and/or spectators changes in a room within the current zone.
This event allows to keep track in realtime of the status of all the zone rooms in terms of users and spectators.
In case many rooms are used and the zone handles a medium to high traffic, this notification can be turned off to reduce bandwidth consumption, since a message is broadcasted to all users in the zone each time a user enters or exits a room.

The params object contains the following parameters.
Parameters:
room:
(Room) the Room object representing the room where the change occurred.
Example:
  • The following example shows how to check the handle the spectator switch notification.
    smartFox.addEventListener(SFSEvent.onUserCountChange, onUserCountChangeHandler)
    
    function onUserCountChangeHandler(evt:SFSEvent):void
    {
        // Assuming this is a game room
    
        var roomName:String = evt.params.room.getName()
        var playersNum:int = evt.params.room.getUserCount()
        var spectatorsNum:int = evt.params.room.getSpectatorCount()
    
        trace("Room " + roomName + "has " + playersNum + " players and " + spectatorsNum + " spectators")
    }
Version:
  • SmartFoxServer Basic / Pro

onUserEnterRoom

public static const onUserEnterRoom:String = "onUserEnterRoom"
(read)

Dispatched when another user joins the current room.

The params object contains the following parameters.
Parameters:
roomId:
(int) the id of the room joined by a user (useful in case multi-room presence is allowed).
user :
(User) the User object representing the user that joined the room.
Example:
  • The following example shows how to check the handle the user entering room notification.
    smartFox.addEventListener(SFSEvent.onUserEnterRoom, onUserEnterRoomHandler)
    
    function onUserEnterRoomHandler(evt:SFSEvent):void
    {
        trace("User " + evt.params.user.getName() + " entered the room")
    }
Version:
  • SmartFoxServer Basic / Pro

onUserLeaveRoom

public static const onUserLeaveRoom:String = "onUserLeaveRoom"
(read)

Dispatched when a user leaves the current room.
This event is also dispatched when a user gets disconnected from the server.

The params object contains the following parameters.
Parameters:
roomId :
(int) the id of the room left by a user (useful in case multi-room presence is allowed).
userId :
(int) the id of the user that left the room (or got disconnected).
userName:
(String) the name of the user.
Example:
  • The following example shows how to check the handle the user leaving room notification.
    smartFox.addEventListener(SFSEvent.onUserLeaveRoom, onUserLeaveRoomHandler)
    
    function onUserLeaveRoomHandler(evt:SFSEvent):void
    {
        trace("User " + evt.params.userName + " left the room")
    }
Version:
  • SmartFoxServer Basic / Pro

onUserVariablesUpdate

public static const onUserVariablesUpdate:String = "onUserVariablesUpdate"
(read)

Dispatched when a user in the current room updates his/her User Variables.

The params object contains the following parameters.
Parameters:
user :
(User) the User object representing the user who updated his/her variables.
changedVars:
(Array) an associative array with the names of the changed variables as keys. The array can also be iterated through numeric indexes (0 to changedVars.length) to get the names of the variables that changed.
NOTE: the changedVars array contains the names of the changed variables only, not the actual values. To retrieve them the User.getVariable / User.getVariables methods can be used.
Example:
  • The following example shows how to handle an update in User Variables.
    smartFox.addEventListener(SFSEvent.onUserVariablesUpdate, onUserVariablesUpdateHandler)
    
    function onUserVariablesUpdateHandler(evt:SFSEvent):void
    {
        // We assume that each user has px and py variables representing the users's avatar coordinates in a 2D environment
    
        var changedVars:Array = evt.params.changedVars
    
        if (changedVars["px"] != null || changedVars["py"] != null)
        {
            trace("User " + evt.params.user.getName() + " moved to new coordinates:")
            trace("\t px: " + evt.params.user.getVariable("px"))
            trace("\t py: " + evt.params.user.getVariable("py"))
        }
    }
Version:
  • SmartFoxServer Basic / Pro