Class: LoadBalancingClient

Photon.LoadBalancing. LoadBalancingClient

Implements the Photon LoadBalancing workflow. This class should be extended to handle system or custom events and operation responses.

new LoadBalancingClient(protocol, appId, appVersion)

Parameters:
Name Type Description
protocol Photon.ConnectionProtocol Connecton protocol.
appId string Cloud application ID.
appVersion string Cloud application version.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2187

Members

<static, readonly> PeerErrorCode

Enum for client peers error codes.

Properties:
Name Type Description
Ok number No Error.
MasterError number General Master server peer error.
MasterConnectFailed number Master server connection error.
MasterConnectClosed number Disconnected from Master server.
MasterTimeout number Disconnected from Master server for timeout.
MasterEncryptionEstablishError number Master server encryption establishing failed.
MasterAuthenticationFailed number Master server authentication failed.
GameError number General Game server peer error.
GameConnectFailed number Game server connection error.
GameConnectClosed number Disconnected from Game server.
GameTimeout number Disconnected from Game server for timeout.
GameEncryptionEstablishError number Game server encryption establishing failed.
GameAuthenticationFailed number Game server authentication failed.
NameServerError number General NameServer peer error.
NameServerConnectFailed number NameServer connection error.
NameServerConnectClosed number Disconnected from NameServer.
NameServerTimeout number Disconnected from NameServer for timeout.
NameServerEncryptionEstablishError number NameServer encryption establishing failed.
NameServerAuthenticationFailed number NameServer authentication failed.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3775

<static, readonly> State

Enum for client states.

Properties:
Name Type Description
Error number Critical error occurred.
Uninitialized number Client is created but not used yet.
ConnectingToNameServer number Connecting to NameServer.
ConnectedToNameServer number Connected to NameServer.
ConnectingToMasterserver number Connecting to Master (includes connect, authenticate and joining the lobby).
ConnectedToMaster number Connected to Master server.
JoinedLobby number Connected to Master and joined lobby. Display room list and join/create rooms at will.
ConnectingToGameserver number Connecting to Game server(client will authenticate and join/create game).
ConnectedToGameserver number Connected to Game server (going to auth and join game).
Joined number The client joined room.
Disconnected number The client is no longer connected (to any server). Connect to Master to go on.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3820

Methods

<static> StateToName(state) → {string}

Converts State element to string name.

Parameters:
Name Type Description
state Photon.LoadBalancing.LoadBalancingClient.State Client state enum element.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3760
Returns:
Specified element name or undefined if not found.
Type
string

actorFactory(name, actorNr, isLocal)

Override with creation of custom actor (extended from Actor): { return new CustomActor(...); }

Parameters:
Name Type Description
name string Actor name. Pass to super() in custom room constructor.
actorNr number Actor ID. Pass to super() in custom room constructor.
isLocal boolean Actor is local. Pass to super() in custom room constructor.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2405

availableRooms() → {Photon.LoadBalancing.RoomInfo[]}

Current room list from Master server.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3097
Returns:
Current room list
Type
Photon.LoadBalancing.RoomInfo[]

changeGroups(groupsToRemove, groupsToAdd)

Changes client's interest groups (for events in room).
Note the difference between passing null and []: null won't add/remove any groups, [] will add/remove all (existing) groups.
First, removing groups is executed. This way, you could leave all groups and join only the ones provided.

Parameters:
Name Type Description
groupsToRemove number[] Groups to remove from interest. Null will not leave any. A [] will remove all.
groupsToAdd number[] Groups to add to interest. Null will not add any. A [] will add all current.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2894

connect(options) → {boolean}

Starts connection to Master server.

Parameters:
Name Type Argument Description
options object <optional>
Additional options
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
keepMasterConnection boolean <optional>
false Don't disconnect from Master server after joining room.
lobbyName string <optional>
Name of the lobby connect to.
lobbyType Photon.LoadBalancing.Constants.LobbyType <optional>
LobbyType.Default Type of the lobby.
lobbyStats boolean <optional>
false If true, Master server will be sending lobbies statistics periodically.
Override onLobbyStats to handle request results.
Alternatively, requestLobbyStats can be used.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2534
Returns:
True if current client state allows connection.
Type
boolean

connectToNameServer(options)

Starts connection to NameServer.

Parameters:
Name Type Argument Description
options object <optional>
Additional options
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2575

connectToRegionMaster(region) → {boolean}

Connects to a specific region's Master server, using the NameServer to find the IP. Override onWebRpcResult to handle request results.

Parameters:
Name Type Description
region string Region connect to Master server of.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3038
Returns:
True if current client state allows connection.
Type
boolean

createRoom(roomName, options)

Creates a new room on the server (or fails when the name is already taken).

Parameters:
Name Type Argument Description
roomName string <optional>
The name to create a room with. Must be unique and not in use or can't be created. If not specified or null, the server will assign a GUID as name.
options object <optional>
Additional options
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
isVisible boolean <optional>
true Shows the room in the lobby's room list.
isOpen boolean <optional>
true Keeps players from joining the room (or opens it to everyone).
maxPlayers number <optional>
0 Max players before room is considered full (but still listed).
customGameProperties object <optional>
Custom properties to apply to the room on creation (use string-typed keys but short ones).
propsListedInLobby string[] <optional>
Defines the custom room properties that get listed in the lobby.
emptyRoomLiveTime number <optional>
0 Room live time (ms) in the server room cache after all clients have left the room.
suspendedPlayerLiveTime number <optional>
0 Player live time (ms) in the room after player suspended.
plugins string[] <optional>
Expected server plugins.
uniqueUserId number <optional>
false Allowing a users to be only once in the room.
lobbyName string <optional>
Name of the lobby to create room in.
lobbyType Photon.LoadBalancing.Constants.LobbyType <optional>
LobbyType.Default Type of the lobby.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2664

createRoomFromMy(roomName, options)

Creates a new room on the server (or fails when the name is already taken). Takes parameters (except name) for new room from myRoom() object. Set them before call.

Parameters:
Name Type Argument Description
roomName string <optional>
New room name. Assigned automatically by server if empty or not specified.
options object <optional>
Additional options
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
lobbyName string <optional>
Name of the lobby to create room in.
lobbyType Photon.LoadBalancing.Constants.LobbyType <optional>
LobbyType.Default Type of the lobby.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2636

disconnect()

Disconnects from all servers.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2818

findFriends(friendsToFind)

Requests Master server for actors online status and joined rooms.
Override onFindFriendsResult to handle request results.

Parameters:
Name Type Description
friendsToFind string[] Actors names.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2908

getMasterServerAddress() → {string}

Returns current Master server address.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2496
Returns:
Master server address.
Type
string

getNameServerAddress() → {string}

Returns current NameServer address.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2480
Returns:
NameServer address address.
Type
string

getRegions()

Requests NameServer for regions list.
Override onGetRegionsResult to handle request results.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3002

getUserId() → {string}

Returns previously set user id.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2512
Returns:
User id.
Type
string

isConnectedToMaster() → {boolean}

Checks if client is connected to Master server (usually joined to lobby and receives room list updates).

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3059
Returns:
True if client is connected to Master server.
Type
boolean

isConnectedToNameServer() → {boolean}

Checks if client is connected to NameServer server.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3067
Returns:
True if client is connected to NameServer server.
Type
boolean

isInLobby() → {boolean}

Checks if client is in lobby and ready to join or create game.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3075
Returns:
True if client is in lobby.
Type
boolean

isJoinedToRoom() → {boolean}

Checks if client is joined to game.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3083
Returns:
True if client is joined to game.
Type
boolean

joinRandomRoom(options)

Joins a random, available room. This operation fails if all rooms are closed or full.

Parameters:
Name Type Argument Description
options object <optional>
Additional options
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
expectedCustomRoomProperties object <optional>
If specified, a room will only be joined, if it matches these custom properties. Use null to accept rooms with any properties.
expectedMaxPlayers number <optional>
If specified, filters for a particular maxPlayer setting. Use 0 to accept any maxPlayer value.
matchmakingMode Photon.LoadBalancing.Constants.MatchmakingMode <optional>
MatchmakingMode.FillRoom Selects one of the available matchmaking algorithms.
lobbyName string <optional>
Name of the lobby to search rooms in.
lobbyType Photon.LoadBalancing.Constants.LobbyType <optional>
LobbyType.Default Type of the lobby.
sqlLobbyFilter string <optional>
Basically the "where" clause of a sql statement. Examples: 'C0 = 1 AND C2 > 50'. 'C5 = "Map2" AND C2 > 10 AND C2 < 20'
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2731

joinRoom(roomName, options, createOptions)

Joins a room by name and sets this player's properties.

Parameters:
Name Type Argument Description
roomName string The name of the room to join. Must be existing already, open and non-full or can't be joined.
options object <optional>
Additional options
createOptions object <optional>
Room options for creation
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
joinToken string <optional>
null Try to rejoin with given token. Set to myActor().getJoinToken() to use last automatically saved token.
createIfNotExists boolean <optional>
false Create room if not exists.
createOptions object Room options for creation
Properties
Name Type Argument Default Description
isVisible boolean <optional>
true Shows the room in the lobby's room list.
isOpen boolean <optional>
true Keeps players from joining the room (or opens it to everyone).
maxPlayers number <optional>
0 Max players before room is considered full (but still listed).
customGameProperties object <optional>
Custom properties to apply to the room on creation (use string-typed keys but short ones).
propsListedInLobby string[] <optional>
Defines the custom room properties that get listed in the lobby.
emptyRoomLiveTime number <optional>
0 Room live time (ms) in the server room cache after all clients have left the room.
suspendedPlayerLiveTime number <optional>
0 Player live time (ms) in the room after player suspended.
plugins string[] <optional>
Informs the server of the expected plugin setup.
uniqueUserId number <optional>
false Allowing a users to be only once in the room.
lobbyName string <optional>
"" Name of the lobby to create room in.
lobbyType Photon.LoadBalancing.Constants.LobbyType <optional>
LobbyType.Default Type of the lobby.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2687

leaveRoom()

Leaves room and connects to Master server if not connected.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2856

myActor() → {Photon.LoadBalancing.Actor}

Returns local actor. Client always has local actor even if not joined.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2414
Returns:
Local actor.
Type
Photon.LoadBalancing.Actor

myRoom() → {Photon.LoadBalancing.Room}

Returns client's room. Client always has it's room even if not joined. It's used for room creation operation.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2421
Returns:
Current room.
Type
Photon.LoadBalancing.Room

myRoomActorCount() → {number}

Returns numer of actors in room client currently joined including local actor.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2434
Returns:
Number of actors.
Type
number

myRoomActors() → {object}

Returns actors in room client currently joined including local actor.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2428
Returns:
actorNr -> Photon.LoadBalancing.Actor map of actors in room.
Type
object

onActorJoin(actor)

Called when new actor joins the room client joined to. Override to handle it.

Parameters:
Name Type Description
actor Photon.LoadBalancing.Actor New actor.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2322

onActorLeave(actor, cleanup)

Called when actor leaves the room client joined to. Also called for every actor during room cleanup. Override to handle it.

Parameters:
Name Type Description
actor Photon.LoadBalancing.Actor Actor left the room.
cleanup boolean True if called during room cleanup (e.g. on disconnect).
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2328

onActorPropertiesChange(actor)

Called on actor properties changed event. Override to handle it.

Parameters:
Name Type Description
actor Photon.LoadBalancing.Actor Actor whose properties were changed.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2310

onActorSuspend(actor)

Called when actor suspended in the room client joined to.Override to handle it.

Parameters:
Name Type Description
actor Photon.LoadBalancing.Actor Actor suspended in the room.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2335

onAppStats(errorCode, errorMsg, stats)

Called when application statistics update received.
Override to handle request results.

Parameters:
Name Type Description
errorCode number Result error code. Currently is always 0.
errorMsg string Error message. Currently is always empty.
stats object Application statistics.
Properties:
Name Type Description
stats object Application statistics.
Properties
Name Type Description
peerCount number Count of players currently online on Game servers.
masterPeerCount number Count of players on Master server (looking for game).
gameCount number Count of games currently in use (includes invisible and full rooms, so it doesn't match lobby list).
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2368

onError(errorCode, errorMsg)

Called if client error occures. Override to handle it.

Parameters:
Name Type Description
errorCode Photon.LoadBalancing.LoadBalancingClient.PeerErrorCode Client error code.
errorMsg string Error message.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2265

onEvent(code, content, actorNr)

Called on custom event. Override to handle it.

Parameters:
Name Type Description
code number Event code.
content object Event content.
actorNr number Actor ID event raised by.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2281

onFindFriendsResult(errorCode, errorMsg, friends)

Called when findFriends request completed.
Override to handle request results.

Parameters:
Name Type Description
errorCode number Result error code. 0 if request is successful.
errorMsg string Error message.
friends object Table with actors names as keys and friend statuses as values: {name1: friendStatus1, name2: friendStatus2, ... }.
Properties:
Name Type Description
friendStatus object Friend status.
Properties
Name Type Description
online boolean Online status.
roomId string Joined room.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2341

onJoinRoom(createdByMe)

Called when client joins room. Override to handle it.

Parameters:
Name Type Description
createdByMe boolean True if room is created by client.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2316

onLobbyStats(errorCode, errorMsg, lobbies)

Called when lobbies statistics update received.
Update can be automated by set up during connect or requested explicitly by requestLobbyStats.
Override to handle request results.

Parameters:
Name Type Description
errorCode number Result error code. 0 if request is successful. For automated updates is always 0.
errorMsg string Error message. For automated updates is always empty.
lobbies object[] Array of lobbies statistics: [lobbyStats1, lobbyStats1, ... ].
Properties:
Name Type Description
lobbyStats object Lobby statistics.
Properties
Name Type Description
lobbyName string Lobby name.
lobbyType number Lobby type.
peerCount number The number of players in the lobby (on Master, not playing).
gameCount number The number of games in the lobby.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2353

onMyRoomPropertiesChange()

Called on joined room properties changed event. Override to handle it.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2305

onOperationResponse(errorCode, errorMsg, code, content)

Called on operation response. Override if need custom workflow or response error handling.

Parameters:
Name Type Description
errorCode number Server error code.
errorMsg string Error message.
code number Operation code.
content object Operation response content.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2272

onRoomList(rooms)

Called on room list received from Master server (on connection). Override to handle it.

Parameters:
Name Type Description
rooms Photon.LoadBalancing.RoomInfo[] Room list.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2289

onRoomListUpdate(rooms, roomsUpdated, roomsAdded, roomsRemoved)

Called on room list updates received from Master server. Override to handle it.

Parameters:
Name Type Description
rooms Photon.LoadBalancing.RoomInfo[] Updated room list.
roomsUpdated Photon.LoadBalancing.RoomInfo[] Rooms whose properties were changed.
roomsAdded Photon.LoadBalancing.RoomInfo[] New rooms in list.
roomsRemoved Photon.LoadBalancing.RoomInfo[] Rooms removed from list.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2295

onStateChange(state)

Called on client state change. Override to handle it.

Parameters:
Name Type Description
state Photon.LoadBalancing.LoadBalancingClient.State New client state.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2259

raiseEvent(eventCode, data, options)

Raises game custom event

Parameters:
Name Type Argument Description
eventCode number Identifies this type of event (and the content). Your game's event codes can start with 0.
data object <optional>
Custom data you want to send along (use null, if none).
options object <optional>
Additional options
Properties:
Name Type Description
options object Additional options
Properties
Name Type Argument Default Description
interestGroup number <optional>
The ID of the interest group this event goes to (exclusively).
cache Photon.LoadBalancing.Constants.EventCaching <optional>
EventCaching.DoNotCache Events can be cached (merged and removed) for players joining later on.
receivers Photon.LoadBalancing.Constants.ReceiverGroup <optional>
ReceiverGroup.Others Defines to which group of players the event is passed on.
targetActors number[] <optional>
Defines the target players who should receive the event (use only for small target groups).
webForward boolean <optional>
false Forward to web hook.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2876

requestLobbyStats(lobbiesToRequest)

Requests Master server for lobbies statistics.
Override onLobbyStats to handle request results.
Alternatively, automated updates can be set up during connect.

Parameters:
Name Type Description
lobbiesToRequest any[] Array of lobbies id pairs [ [lobbyName1, lobbyType1], [lobbyName2, lobbyType2], ... ]. If not specified or null, statistics for all lobbies requested.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2941

roomFactory(name)

Override with creation of custom room (extended from Room): { return new CustomRoom(...); }

Parameters:
Name Type Description
name string Room name. Pass to super() in custom actor constructor.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2399

setCustomAuthentication(authParameters, authType, authData)

Enables custom authentication and sets it's parameters.

Parameters:
Name Type Argument Default Description
authParameters string This string must contain any (http get) parameters expected by the used authentication service.
authType Photon.LoadBalancing.Constants.CustomAuthenticationType <optional>
Photon.LoadBalancing.Constants.CustomAuthenticationType.Custom The type of custom authentication provider that should be used.
authData string The data to be passed-on to the auth service via POST.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2520

setLogLevel(level)

Sets client logger level

Parameters:
Name Type Description
level Exitgames.Common.Logger.Level Logging level.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3103

setMasterServerAddress(address)

Changes default Master server address and port before connecting to Master server.

Parameters:
Name Type Description
address string New address and port.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2488

setNameServerAddress(address)

Changes default NameServer address and port before connecting to NameServer.

Parameters:
Name Type Description
address string New address and port.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2472

setUserId(userId)

Sets optional user id(required by some cloud services)

Parameters:
Name Type Description
userId string New user id.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2504

suspendRoom()

Disconnects client from Game server keeping player in room (to rejoin later) and connects to Master server if not connected.

Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 2837

webRpc(uriPath, parameters)

Sends web rpc request to Master server.
Override onWebRpcResult to handle request results.

Parameters:
Name Type Description
uriPath string Request path.
parameters object Request parameters.
Source:
  • Photon-Javascript_v4-0-0-7_Cloud_SDK.js, line 3017