This class implements the Photon LoadBalancing workflow by using a LoadBalancingPeer. It keeps a state and will automatically execute transitions between the Master and Game Servers. More...

Inherits IPhotonPeerListener.

Public Member Functions
	LoadBalancingClient (ConnectionProtocol protocol=ConnectionProtocol.Udp)
	Creates a LoadBalancingClient with UDP protocol or the one specified. More...

	LoadBalancingClient (string masterAddress, string appId, string gameVersion, ConnectionProtocol protocol=ConnectionProtocol.Udp)
	Creates a LoadBalancingClient, setting various values needed before connecting. More...

virtual bool	ConnectUsingSettings (AppSettings appSettings)
	Starts the "process" to connect as defined by the appSettings (AppId, AppVersion, Transport Protocol, Port and more). More...

bool	Connect ()

virtual bool	ConnectToMasterServer ()
	Starts the "process" to connect to a Master Server, using MasterServerAddress and AppId properties. More...

bool	ConnectToNameServer ()
	Connects to the NameServer for Photon Cloud, where a region and server list can be obtained. More...

bool	ConnectToRegionMaster (string region)
	Connects you to a specific region's Master Server, using the Name Server to get the IP. More...

bool	ReconnectToMaster ()
	Can be used to reconnect to the master server after a disconnect. More...

bool	ReconnectAndRejoin ()
	Can be used to return to a room quickly by directly reconnecting to a game server to rejoin a room. More...

void	Disconnect (DisconnectCause cause=DisconnectCause.DisconnectByClientLogic)
	Disconnects the peer from a server or stays disconnected. If the client / peer was connected, a callback will be triggered. More...

void	SimulateConnectionLoss (bool simulateTimeout)
	Useful to test loss of connection which will end in a client timeout. This modifies LoadBalancingPeer.NetworkSimulationSettings. Read remarks. More...

void	Service ()
	This method dispatches all available incoming commands and then sends this client's outgoing commands. It uses DispatchIncomingCommands and SendOutgoingCommands to do that. More...

bool	OpFindFriends (string[] friendsToFind, FindFriendsOptions options=null)
	Request the rooms and online status for a list of friends. All clients should set a unique UserId before connecting. The result is available in this.FriendList. More...

bool	OpJoinLobby (TypedLobby lobby)
	If already connected to a Master Server, this joins the specified lobby. This request triggers an OnOperationResponse() call and the callback OnJoinedLobby(). More...

bool	OpLeaveLobby ()
	Opposite of joining a lobby. You don't have to explicitly leave a lobby to join another (client can be in one max, at any time). More...

bool	OpJoinRandomRoom (OpJoinRandomRoomParams opJoinRandomRoomParams=null)
	Joins a random room that matches the filter. Will callback: OnJoinedRoom or OnJoinRandomFailed. More...

bool	OpJoinRandomOrCreateRoom (OpJoinRandomRoomParams opJoinRandomRoomParams, EnterRoomParams createRoomParams)
	Attempts to join a room that matches the specified filter and creates a room if none found. More...

bool	OpCreateRoom (EnterRoomParams enterRoomParams)
	Creates a new room. Will callback: OnCreatedRoom and OnJoinedRoom or OnCreateRoomFailed. More...

bool	OpJoinOrCreateRoom (EnterRoomParams enterRoomParams)
	Joins a specific room by name and creates it on demand. Will callback: OnJoinedRoom or OnJoinRoomFailed. More...

bool	OpJoinRoom (EnterRoomParams enterRoomParams)
	Joins a room by name. Will callback: OnJoinedRoom or OnJoinRoomFailed. More...

bool	OpRejoinRoom (string roomName)
	Rejoins a room by roomName (using the userID internally to return). Will callback: OnJoinedRoom or OnJoinRoomFailed. More...

bool	OpLeaveRoom (bool becomeInactive, bool sendAuthCookie=false)
	Leaves the current room, optionally telling the server that the user is just becoming inactive. Will callback: OnLeftRoom. More...

bool	OpGetGameList (TypedLobby typedLobby, string sqlLobbyFilter)
	Gets a list of rooms matching the (non empty) SQL filter for the given SQL-typed lobby. More...

bool	OpSetCustomPropertiesOfActor (int actorNr, Hashtable propertiesToSet, Hashtable expectedProperties=null, WebFlags webFlags=null)
	Updates and synchronizes a Player's Custom Properties. Optionally, expectedProperties can be provided as condition. More...

bool	OpSetCustomPropertiesOfRoom (Hashtable propertiesToSet, Hashtable expectedProperties=null, WebFlags webFlags=null)
	Updates and synchronizes this Room's Custom Properties. Optionally, expectedProperties can be provided as condition. More...

virtual bool	OpRaiseEvent (byte eventCode, object customEventContent, RaiseEventOptions raiseEventOptions, SendOptions sendOptions)
	Send an event with custom code/type and any content to the other players in the same room. More...

virtual bool	OpChangeGroups (byte[] groupsToRemove, byte[] groupsToAdd)
	Operation to handle this client's interest groups (for events in room). More...

void	ChangeLocalID (int newID)
	Internally used to set the LocalPlayer's ID (from -1 to the actual in-room ID). More...

virtual void	DebugReturn (DebugLevel level, string message)
	Debug output of low level api (and this client). More...

virtual void	OnOperationResponse (OperationResponse operationResponse)
	Uses the OperationResponses provided by the server to advance the internal state and call ops as needed. More...

virtual void	OnStatusChanged (StatusCode statusCode)
	Uses the connection's statusCodes to advance the internal state and call operations as needed. More...

virtual void	OnEvent (EventData photonEvent)
	Uses the photonEvent's provided by the server to advance the internal state and call ops as needed. More...

virtual void	OnMessage (object message)
	In Photon 4, "raw messages" will get their own callback method in the interface. Not used yet. More...

bool	OpWebRpc (string uriPath, object parameters, bool sendAuthCookie=false)
	This operation makes Photon call your custom web-service by path/name with the given parameters (converted into Json). Use IWebRpcCallback.OnWebRpcResponse as a callback. More...

void	AddCallbackTarget (object target)
	Registers an object for callbacks for the implemented callback-interfaces. More...

void	RemoveCallbackTarget (object target)
	Unregisters an object from callbacks for the implemented callback-interfaces. More...

Public Attributes
AuthModeOption	AuthMode = AuthModeOption.Auth
	Enables the new Authentication workflow. More...

EncryptionMode	EncryptionMode = EncryptionMode.PayloadEncryption
	Defines how the communication gets encrypted. More...

string	NameServerHost = "ns.photonengine.io"
	Name Server Host Name for Photon Cloud. Without port and without any prefix. More...

PhotonPortDefinition	ServerPortOverrides
	Defines overrides for server ports. Used per server-type if > 0. Important: You must change these when the protocol changes! More...

string	ProxyServerAddress
	Defines a proxy URL for WebSocket connections. Can be the proxy or point to a .pac file. More...

ConnectionCallbacksContainer	ConnectionCallbackTargets
	Wraps up the target objects for a group of callbacks, so they can be called conveniently. More...

MatchMakingCallbacksContainer	MatchMakingCallbackTargets
	Wraps up the target objects for a group of callbacks, so they can be called conveniently. More...

SystemConnectionSummary	SystemConnectionSummary
	After a to a connection loss or timeout, this summarizes the most relevant system conditions which might have contributed to the loss. More...

bool	EnableLobbyStatistics
	If enabled, the client will get a list of available lobbies from the Master Server. More...

RegionHandler	RegionHandler
	Contains the list if enabled regions this client may use. Null, unless the client got a response to OpGetRegions. More...

string	SummaryToCache
	Set when the best region pinging is done. More...

int	NameServerPortInAppSettings

Properties
LoadBalancingPeer	LoadBalancingPeer `[get]`
	The client uses a LoadBalancingPeer as API to communicate with the server. This is public for ease-of-use: Some methods like OpRaiseEvent are not relevant for the connection state and don't need a override. More...

SerializationProtocol	SerializationProtocol `[get, set]`
	Gets or sets the binary protocol version used by this client More...

string	AppVersion `[get, set]`
	The version of your client. A new version also creates a new "virtual app" to separate players from older client versions. More...

string	AppId `[get, set]`
	The AppID as assigned from the Photon Cloud. If you host yourself, this is the "regular" Photon Server Application Name (most likely: "LoadBalancing"). More...

ClientAppType	ClientType `[get, set]`
	The ClientAppType defines which sort of AppId should be expected. The LoadBalancingClient supports Realtime and Voice app types. Default: Realtime. More...

AuthenticationValues	AuthValues `[get, set]`
	User authentication values to be sent to the Photon server right after connecting. More...

ConnectionProtocol?	ExpectedProtocol `[get, set]`
	Optionally contains a protocol which will be used on Master- and GameServer. More...

bool	IsUsingNameServer `[get, set]`
	True if this client uses a NameServer to get the Master Server address. More...

string	NameServerAddress `[get]`
	Name Server Address for Photon Cloud (based on current protocol). You can use the default values and usually won't have to set this value. More...

bool	UseAlternativeUdpPorts `[get, set]`
	Replaced by ServerPortOverrides. More...

bool	EnableProtocolFallback `[get, set]`
	Enables a fallback to another protocol in case a connect to the Name Server fails. More...

string	CurrentServerAddress `[get]`
	The currently used server address (if any). The type of server is define by Server property. More...

string	MasterServerAddress `[get, set]`
	Your Master Server address. In PhotonCloud, call ConnectToRegionMaster() to find your Master Server. More...

string	GameServerAddress `[get, set]`
	The game server's address for a particular room. In use temporarily, as assigned by master. More...

ServerConnection	Server `[get]`
	The server this client is currently connected or connecting to. More...

ClientState	State `[get, set]`
	Current state this client is in. Careful: several states are "transitions" that lead to other states. More...

bool	IsConnected `[get]`
	Returns if this client is currently connected or connecting to some type of server. More...

bool	IsConnectedAndReady `[get]`
	A refined version of IsConnected which is true only if your connection is ready to send operations. More...

DisconnectCause	DisconnectedCause `[get, protected set]`
	Summarizes (aggregates) the different causes for disconnects of a client. More...

bool	InLobby `[get]`
	Internal value if the client is in a lobby. More...

TypedLobby	CurrentLobby `[get, set]`
	The lobby this client currently uses. Defined when joining a lobby or creating rooms More...

Player	LocalPlayer `[get, set]`
	The local player is never null but not valid unless the client is in a room, too. The ID will be -1 outside of rooms. More...

string	NickName `[get, set]`
	The nickname of the player (synced with others). Same as client.LocalPlayer.NickName. More...

string	UserId `[get, set]`
	An ID for this user. Sent in OpAuthenticate when you connect. If not set, the PlayerName is applied during connect. More...

Room	CurrentRoom `[get, set]`
	The current room this client is connected to (null if none available). More...

bool	InRoom `[get]`
	Is true while being in a room (this.state == ClientState.Joined). More...

int	PlayersOnMasterCount `[get, set]`
	Statistic value available on master server: Players on master (looking for games). More...

int	PlayersInRoomsCount `[get, set]`
	Statistic value available on master server: Players in rooms (playing). More...

int	RoomsCount `[get, set]`
	Statistic value available on master server: Rooms currently created. More...

bool	IsFetchingFriendList `[get]`
	Internal flag to know if the client currently fetches a friend list. More...

string	CloudRegion `[get]`
	The cloud region this client connects to. Set by ConnectToRegionMaster(). Not set if you don't use a NameServer! More...

string	CurrentCluster `[get]`
	The cluster name provided by the Name Server. More...

Events
Action< ClientState, ClientState >	StateChanged
	Register a method to be called when this client's ClientState gets set. More...

Action< EventData >	EventReceived
	Register a method to be called when an event got dispatched. Gets called after the LoadBalancingClient handled the internal events first. More...

Action< OperationResponse >	OpResponseReceived
	Register a method to be called when an operation response is received. More...

Detailed Description

This class implements the Photon LoadBalancing workflow by using a LoadBalancingPeer. It keeps a state and will automatically execute transitions between the Master and Game Servers.

This class (and the Player class) should be extended to implement your own game logic. You can override CreatePlayer as "factory" method for Players and return your own Player instances. The State of this class is essential to know when a client is in a lobby (or just on the master) and when in a game where the actual gameplay should take place. Extension notes: An extension of this class should override the methods of the IPhotonPeerListener, as they are called when the state changes. Call base.method first, then pick the operation or state you want to react to and put it in a switch-case. We try to provide demo to each platform where this api can be used, so lookout for those.

Constructor & Destructor Documentation

◆ LoadBalancingClient() [1/2]

LoadBalancingClient ( ConnectionProtocol protocol = ConnectionProtocol.Udp )

Creates a LoadBalancingClient with UDP protocol or the one specified.

Parameters

protocol Specifies the network protocol to use for connections.

◆ LoadBalancingClient() [2/2]

LoadBalancingClient	(	string	masterAddress,
		string	appId,
		string	gameVersion,
		ConnectionProtocol	protocol = `ConnectionProtocol.Udp`
	)

Creates a LoadBalancingClient, setting various values needed before connecting.

Parameters

masterAddress	The Master Server's address to connect to. Used in Connect.
appId	The AppId of this title. Needed for the Photon Cloud. Find it in the Dashboard.
gameVersion	A version for this client/build. In the Photon Cloud, players are separated by AppId, GameVersion and Region.
protocol	Specifies the network protocol to use for connections.

Member Function Documentation

◆ AddCallbackTarget()

void AddCallbackTarget ( object target )

Registers an object for callbacks for the implemented callback-interfaces.

Adding and removing callback targets is queued to not mess with callbacks in execution. Internally, this means that the addition/removal is done before the LoadBalancingClient calls the next callbacks. This detail should not affect a game's workflow.

The covered callback interfaces are: IConnectionCallbacks, IMatchmakingCallbacks, ILobbyCallbacks, IInRoomCallbacks, IOnEventCallback and IWebRpcCallback.

See: DotNet Callbacks

Parameters

target The object that registers to get callbacks from this client.

◆ ChangeLocalID()

void ChangeLocalID ( int newID )

Internally used to set the LocalPlayer's ID (from -1 to the actual in-room ID).

Parameters

newID New actor ID (a.k.a actorNr) assigned when joining a room.

◆ ConnectToMasterServer()

virtual bool ConnectToMasterServer ( )

virtual

Starts the "process" to connect to a Master Server, using MasterServerAddress and AppId properties.

To connect to the Photon Cloud, use ConnectUsingSettings() or ConnectToRegionMaster().

The process to connect includes several steps: the actual connecting, establishing encryption, authentification (of app and optionally the user) and connecting to the MasterServer

Users can connect either anonymously or use "Custom Authentication" to verify each individual player's login. Custom Authentication in Photon uses external services and communities to verify users. While the client provides a user's info, the service setup is done in the Photon Cloud Dashboard. The parameter authValues will set this.AuthValues and use them in the connect process.

Connecting to the Photon Cloud might fail due to:

Network issues (OnStatusChanged() StatusCode.ExceptionOnConnect)
Region not available (OnOperationResponse() for OpAuthenticate with ReturnCode == ErrorCode.InvalidRegion)
Subscription CCU limit reached (OnOperationResponse() for OpAuthenticate with ReturnCode == ErrorCode.MaxCcuReached)

◆ ConnectToNameServer()

bool ConnectToNameServer ( )

Connects to the NameServer for Photon Cloud, where a region and server list can be obtained.

OpGetRegions

Returns: If the workflow was started or failed right away.

◆ ConnectToRegionMaster()

bool ConnectToRegionMaster ( string region )

Connects you to a specific region's Master Server, using the Name Server to get the IP.

If the region is null or empty, no connection will be made. If the region (code) provided is not available, the connection process will fail on the Name Server. This method connects only to the region defined. Any "Best Region" pinging should get done beforehand.

To support "sharding", a region string may contain a "/*" to pick a random cluster or "/clustername" to connect to a specific cluster. With a "/" or no cluster postfix, the client connects to the default cluster (a specific one for a region).

By default, the region string provided by the Name Server does not contain a cluster (and only the default cluster is used).

Returns: If the operation could be sent. If false, no operation was sent.

◆ ConnectUsingSettings()

virtual bool ConnectUsingSettings ( AppSettings appSettings )

virtual

Starts the "process" to connect as defined by the appSettings (AppId, AppVersion, Transport Protocol, Port and more).

A typical connection process wraps up these steps:

Low level connect and init (which establishes a connection that enables operations and responses for the Realtime API).
GetRegions and select best (unless FixedRegion is being used).
Authenticate user for a specific region (this provides a Master Server address to go to and a token).
Disconnect Name Server and connect to Master Server (using the token).
The callback OnConnectedToMaster gets called.

Connecting to the servers is a process and this is a non-blocking method.
Implement and register the IConnectionCallbacks interface to get callbacks about success or failing connects.

Basically all settings for the connection, AppId and servers can be done via the provided parameter.

Connecting to the Photon Cloud might fail due to:
Network issues
Region not available
Subscription CCU limit

IConnectionCallbacks AuthValues

Parameters

appSettings Collection of settings defining this app and how to connect.

Returns: True if the client can attempt to connect.

◆ DebugReturn()

virtual void DebugReturn	(	DebugLevel	level,
		string	message
	)

virtual

Debug output of low level api (and this client).

This method is not responsible to keep up the state of a LoadBalancingClient. Calling base.DebugReturn on overrides is optional.

◆ Disconnect()

void Disconnect ( DisconnectCause cause = DisconnectCause.DisconnectByClientLogic )

Disconnects the peer from a server or stays disconnected. If the client / peer was connected, a callback will be triggered.

Disconnect will attempt to notify the server of the client closing the connection.

Clients that are in a room, will leave the room. If the room's playerTTL > 0, the player will just become inactive (and may rejoin).

This method will not change the current State, if this client State is PeerCreated, Disconnecting or Disconnected. In those cases, there is also no callback for the disconnect. The DisconnectedCause will only change if the client was connected.

◆ OnEvent()

virtual void OnEvent ( EventData photonEvent )

virtual

Uses the photonEvent's provided by the server to advance the internal state and call ops as needed.

This method is essential to update the internal state of a LoadBalancingClient. Overriding methods must call base.OnEvent.

◆ OnMessage()

virtual void OnMessage ( object message )

virtual

In Photon 4, "raw messages" will get their own callback method in the interface. Not used yet.

◆ OnOperationResponse()

virtual void OnOperationResponse ( OperationResponse operationResponse )

virtual

Uses the OperationResponses provided by the server to advance the internal state and call ops as needed.

When this method finishes, it will call your OnOpResponseAction (if any). This way, you can get any operation response without overriding this class.

To implement a more complex game/app logic, you should implement your own class that inherits the LoadBalancingClient. Override this method to use your own operation-responses easily.

This method is essential to update the internal state of a LoadBalancingClient, so overriding methods must call base.OnOperationResponse().

Parameters

operationResponse Contains the server's response for an operation called by this peer.

◆ OnStatusChanged()

virtual void OnStatusChanged ( StatusCode statusCode )

virtual

Uses the connection's statusCodes to advance the internal state and call operations as needed.

This method is essential to update the internal state of a LoadBalancingClient. Overriding methods must call base.OnStatusChanged.

◆ OpChangeGroups()

virtual bool OpChangeGroups	(	byte[]	groupsToRemove,
		byte[]	groupsToAdd
	)

virtual

Operation to handle this client's interest groups (for events in room).

Note the difference between passing null and byte[0]: null won't add/remove any groups. byte[0] will add/remove all (existing) groups. First, removing groups is executed. This way, you could leave all groups and join only the ones provided.

Changes become active not immediately but when the server executes this operation (approximately RTT/2).

Parameters

groupsToRemove	Groups to remove from interest. Null will not remove any. A byte[0] will remove all.
groupsToAdd	Groups to add to interest. Null will not add any. A byte[0] will add all current.

Returns: If operation could be enqueued for sending. Sent when calling: Service or SendOutgoingCommands.

◆ OpCreateRoom()

bool OpCreateRoom ( EnterRoomParams enterRoomParams )

Creates a new room. Will callback: OnCreatedRoom and OnJoinedRoom or OnCreateRoomFailed.

When successful, the client will enter the specified room and callback both OnCreatedRoom and OnJoinedRoom. In all error cases, OnCreateRoomFailed gets called.

Creating a room will fail if the room name is already in use or when the RoomOptions clashing with one another. Check the EnterRoomParams reference for the various room creation options.

This method can only be called while the client is connected to a Master Server so you should implement the callback OnConnectedToMaster. Check the return value to make sure the operation will be called on the server. Note: There will be no callbacks if this method returned false.

When you're in the room, this client's State will become ClientState.Joined.

When entering a room, this client's Player Custom Properties will be sent to the room. Use LocalPlayer.SetCustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and are not wiped when leaving a room.

You can define an array of expectedUsers, to block player slots in the room for these users. The corresponding feature in Photon is called "Slot Reservation" and can be found in the doc pages.

Parameters

enterRoomParams Definition of properties for the room to create.

Returns: If the operation could be sent currently (requires connection to Master Server).

◆ OpFindFriends()

bool OpFindFriends	(	string[]	friendsToFind,
		FindFriendsOptions	options = `null`
	)

Request the rooms and online status for a list of friends. All clients should set a unique UserId before connecting. The result is available in this.FriendList.

Used on Master Server to find the rooms played by a selected list of users. The result will be stored in LoadBalancingClient.FriendList, which is null before the first server response.

Users identify themselves by setting a UserId in the LoadBalancingClient instance. This will send the ID in OpAuthenticate during connect (to master and game servers). Note: Changing a player's name doesn't make sense when using a friend list.

The list of usernames must be fetched from some other source (not provided by Photon).

Internal:
The server response includes 2 arrays of info (each index matching a friend from the request):
ParameterCode.FindFriendsResponseOnlineList = bool[] of online states
ParameterCode.FindFriendsResponseRoomIdList = string[] of room names (empty string if not in a room)

The options may be used to define which state a room must match to be returned.

Parameters

friendsToFind	Array of friend's names (make sure they are unique).
options	Options that affect the result of the FindFriends operation.

Returns: If the operation could be sent (requires connection).

◆ OpGetGameList()

bool OpGetGameList	(	TypedLobby	typedLobby,
		string	sqlLobbyFilter
	)

Gets a list of rooms matching the (non empty) SQL filter for the given SQL-typed lobby.

Operation is only available for lobbies of type SqlLobby and the filter can not be empty. It will check those conditions and fail locally, returning false.

This is an async request which triggers a OnOperationResponse() call.

Parameters

typedLobby	The lobby to query. Has to be of type SqlLobby.
sqlLobbyFilter	The sql query statement.

Returns: If the operation could be sent (has to be connected).

◆ OpJoinLobby()

bool OpJoinLobby ( TypedLobby lobby )

If already connected to a Master Server, this joins the specified lobby. This request triggers an OnOperationResponse() call and the callback OnJoinedLobby().

Parameters

lobby The lobby to join. Use null for default lobby.

Returns: If the operation could be sent. False, if the client is not IsConnectedAndReady or when it's not connected to a Master Server.

◆ OpJoinOrCreateRoom()

bool OpJoinOrCreateRoom ( EnterRoomParams enterRoomParams )

Joins a specific room by name and creates it on demand. Will callback: OnJoinedRoom or OnJoinRoomFailed.

Useful when players make up a room name to meet in: All involved clients call the same method and whoever is first, also creates the room.

When successful, the client will enter the specified room. The client which creates the room, will callback both OnCreatedRoom and OnJoinedRoom. Clients that join an existing room will only callback OnJoinedRoom. In all error cases, OnJoinRoomFailed gets called.

Joining a room will fail, if the room is full, closed or when the user already is present in the room (checked by userId).

To return to a room, use OpRejoinRoom.

This method can only be called while the client is connected to a Master Server so you should implement the callback OnConnectedToMaster. Check the return value to make sure the operation will be called on the server. Note: There will be no callbacks if this method returned false.

This client's State is set to ClientState.Joining immediately, when the operation could be called. In the background, the client will switch servers and call various related operations.

When you're in the room, this client's State will become ClientState.Joined.

If you set room properties in roomOptions, they get ignored when the room is existing already. This avoids changing the room properties by late joining players.

When entering a room, this client's Player Custom Properties will be sent to the room. Use LocalPlayer.SetCustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and are not wiped when leaving a room.

You can define an array of expectedUsers, to block player slots in the room for these users. The corresponding feature in Photon is called "Slot Reservation" and can be found in the doc pages.

Parameters

enterRoomParams Definition of properties for the room to create or join.

Returns: If the operation could be sent currently (requires connection to Master Server).

◆ OpJoinRandomOrCreateRoom()

bool OpJoinRandomOrCreateRoom	(	OpJoinRandomRoomParams	opJoinRandomRoomParams,
		EnterRoomParams	createRoomParams
	)

Attempts to join a room that matches the specified filter and creates a room if none found.

This operation is a combination of filter-based random matchmaking with the option to create a new room, if no fitting room exists. The benefit of that is that the room creation is done by the same operation and the room can be found by the very next client, looking for similar rooms.

There are separate parameters for joining and creating a room.

This method can only be called while connected to a Master Server. This client's State is set to ClientState.Joining immediately.

For success, IMatchmakingCallbacks.OnJoinedRoom or IMatchmakingCallbacks.OnCreatedRoom get called. In error cases IMatchmakingCallbacks.OnJoinRoomFailed or IMatchmakingCallbacks.OnJoinRandomRoomFailed get called.

More about matchmaking: https://doc.photonengine.com/en-us/realtime/current/reference/matchmaking-and-lobby

Check the return value to make sure the operation will be called on the server. Note: There will be no callbacks if this method returned false.

Returns: If the operation will be sent (requires connection to Master Server).

◆ OpJoinRandomRoom()

bool OpJoinRandomRoom ( OpJoinRandomRoomParams opJoinRandomRoomParams = null )

Joins a random room that matches the filter. Will callback: OnJoinedRoom or OnJoinRandomFailed.

Used for random matchmaking. You can join any room or one with specific properties defined in opJoinRandomRoomParams.

You can use expectedCustomRoomProperties and expectedMaxPlayers as filters for accepting rooms. If you set expectedCustomRoomProperties, a room must have the exact same key values set at Custom Properties. You need to define which Custom Room Properties will be available for matchmaking when you create a room. See: OpCreateRoom(string roomName, RoomOptions roomOptions, TypedLobby lobby)

This operation fails if no rooms are fitting or available (all full, closed or not visible). It may also fail when actually joining the room which was found. Rooms may close, become full or empty anytime.

This method can only be called while the client is connected to a Master Server so you should implement the callback OnConnectedToMaster. Check the return value to make sure the operation will be called on the server. Note: There will be no callbacks if this method returned false.

This client's State is set to ClientState.Joining immediately, when the operation could be called. In the background, the client will switch servers and call various related operations.

When you're in the room, this client's State will become ClientState.Joined.

When entering a room, this client's Player Custom Properties will be sent to the room. Use LocalPlayer.SetCustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and are not wiped when leaving a room.

More about matchmaking: https://doc.photonengine.com/en-us/realtime/current/reference/matchmaking-and-lobby

You can define an array of expectedUsers, to block player slots in the room for these users. The corresponding feature in Photon is called "Slot Reservation" and can be found in the doc pages.

Parameters

opJoinRandomRoomParams Optional definition of properties to filter rooms in random matchmaking.

Returns: If the operation could be sent currently (requires connection to Master Server).

◆ OpJoinRoom()

bool OpJoinRoom ( EnterRoomParams enterRoomParams )

Joins a room by name. Will callback: OnJoinedRoom or OnJoinRoomFailed.

Useful when using lobbies or when players follow friends or invite each other.

When successful, the client will enter the specified room and callback via OnJoinedRoom. In all error cases, OnJoinRoomFailed gets called.

Joining a room will fail if the room is full, closed, not existing or when the user already is present in the room (checked by userId).

To return to a room, use OpRejoinRoom. When players invite each other and it's unclear who's first to respond, use OpJoinOrCreateRoom instead.

This method can only be called while the client is connected to a Master Server so you should implement the callback OnConnectedToMaster. Check the return value to make sure the operation will be called on the server. Note: There will be no callbacks if this method returned false.

A room's name has to be unique (per region, appid and gameversion). When your title uses a global matchmaking or invitations (e.g. an external solution), keep regions and the game versions in mind to join a room.

This client's State is set to ClientState.Joining immediately, when the operation could be called. In the background, the client will switch servers and call various related operations.

When you're in the room, this client's State will become ClientState.Joined.

When entering a room, this client's Player Custom Properties will be sent to the room. Use LocalPlayer.SetCustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and are not wiped when leaving a room.

You can define an array of expectedUsers, to reserve player slots in the room for friends or party members. The corresponding feature in Photon is called "Slot Reservation" and can be found in the doc pages.

Parameters

enterRoomParams Definition of properties for the room to join.

Returns: If the operation could be sent currently (requires connection to Master Server).

◆ OpLeaveLobby()

bool OpLeaveLobby ( )

Opposite of joining a lobby. You don't have to explicitly leave a lobby to join another (client can be in one max, at any time).

Returns: If the operation could be sent (has to be connected).

◆ OpLeaveRoom()

bool OpLeaveRoom	(	bool	becomeInactive,
		bool	sendAuthCookie = `false`
	)

Leaves the current room, optionally telling the server that the user is just becoming inactive. Will callback: OnLeftRoom.

OpLeaveRoom skips execution when the room is null or the server is not GameServer or the client is disconnecting from GS already. OpLeaveRoom returns false in those cases and won't change the state, so check return of this method.

In some cases, this method will skip the OpLeave call and just call Disconnect(), which not only leaves the room but also the server. Disconnect also triggers a leave and so that workflow is is quicker.

Parameters

becomeInactive	If true, this player becomes inactive in the game and can return later (if PlayerTTL of the room is != 0).
sendAuthCookie	WebFlag: Securely transmit the encrypted object AuthCookie to the web service in PathLeave webhook when available

Returns: If the current room could be left (impossible while not in a room).

◆ OpRaiseEvent()

virtual bool OpRaiseEvent	(	byte	eventCode,
		object	customEventContent,
		RaiseEventOptions	raiseEventOptions,
		SendOptions	sendOptions
	)

virtual

Send an event with custom code/type and any content to the other players in the same room.

Parameters

eventCode	Identifies this type of event (and the content). Your game's event codes can start with 0.
customEventContent	Any serializable datatype (including Hashtable like the other OpRaiseEvent overloads).
raiseEventOptions	Contains used send options. If you pass null, the default options will be used.
sendOptions	Send options for reliable, encryption etc

Returns: If operation could be enqueued for sending. Sent when calling: Service or SendOutgoingCommands.

◆ OpRejoinRoom()

bool OpRejoinRoom ( string roomName )

Rejoins a room by roomName (using the userID internally to return). Will callback: OnJoinedRoom or OnJoinRoomFailed.

Used to return to a room, before this user was removed from the players list. Internally, the userID will be checked by the server, to make sure this user is in the room (active or inactice).

In contrast to join, this operation never adds a players to a room. It will attempt to retake an existing spot in the playerlist or fail. This makes sure the client doesn't accidentally join a room when the game logic meant to re-activate an existing actor in an existing room.

This method will fail on the server, when the room does not exist, can't be loaded (persistent rooms) or when the userId is not in the player list of this room. This will lead to a callback OnJoinRoomFailed.

Rejoining room will not send any player properties. Instead client will receive up-to-date ones from server. If you want to set new player properties, do it once rejoined.

◆ OpSetCustomPropertiesOfActor()

bool OpSetCustomPropertiesOfActor	(	int	actorNr,
		Hashtable	propertiesToSet,
		Hashtable	expectedProperties = `null`,
		WebFlags	webFlags = `null`
	)

Updates and synchronizes a Player's Custom Properties. Optionally, expectedProperties can be provided as condition.

Custom Properties are a set of string keys and arbitrary values which is synchronized for the players in a Room. They are available when the client enters the room, as they are in the response of OpJoin and OpCreate.

Custom Properties either relate to the (current) Room or a Player (in that Room).

Both classes locally cache the current key/values and make them available as property: CustomProperties. This is provided only to read them. You must use the method SetCustomProperties to set/modify them.

Any client can set any Custom Properties anytime (when in a room). It's up to the game logic to organize how they are best used.

You should call SetCustomProperties only with key/values that are new or changed. This reduces traffic and performance.

Unless you define some expectedProperties, setting key/values is always permitted. In this case, the property-setting client will not receive the new values from the server but instead update its local cache in SetCustomProperties.

If you define expectedProperties, the server will skip updates if the server property-cache does not contain all expectedProperties with the same values. In this case, the property-setting client will get an update from the server and update it's cached key/values at about the same time as everyone else.

The benefit of using expectedProperties can be only one client successfully sets a key from one known value to another. As example: Store who owns an item in a Custom Property "ownedBy". It's 0 initally. When multiple players reach the item, they all attempt to change "ownedBy" from 0 to their actorNumber. If you use expectedProperties {"ownedBy", 0} as condition, the first player to take the item will have it (and the others fail to set the ownership).

Properties get saved with the game state for Turnbased games (which use IsPersistent = true).

Parameters

actorNr	Defines which player the Custom Properties belong to. ActorID of a player.
propertiesToSet	Hashtable of Custom Properties that changes.
expectedProperties	Provide some keys/values to use as condition for setting the new values. Client must be in room.
webFlags	Defines if the set properties should be forwarded to a WebHook. Client must be in room.

Returns: False if propertiesToSet is null or empty or have zero string keys. If not in a room, returns true if local player and expectedProperties and webFlags are null. False if actorNr is lower than or equal to zero. Otherwise, returns if the operation could be sent to the server.

◆ OpSetCustomPropertiesOfRoom()

bool OpSetCustomPropertiesOfRoom	(	Hashtable	propertiesToSet,
		Hashtable	expectedProperties = `null`,
		WebFlags	webFlags = `null`
	)

Updates and synchronizes this Room's Custom Properties. Optionally, expectedProperties can be provided as condition.