IPunCallbacks Interface Reference

This interface is used as definition of all callback methods of PUN, except OnPhotonSerializeView. Preferably, implement them individually. More...

Inherited by Photon.PunBehaviour.

Public Member Functions
void	OnConnectedToPhoton ()
	Called when the initial connection got established but before you can use the server. OnJoinedLobby() or OnConnectedToMaster() are called when PUN is ready. More...
void	OnLeftRoom ()
	Called when the local user/client left a room. More...
void	OnMasterClientSwitched (PhotonPlayer newMasterClient)
	Called after switching to a new MasterClient when the current one leaves. More...
void	OnPhotonCreateRoomFailed (object[] codeAndMsg)
	Called when a CreateRoom() call failed. The parameter provides ErrorCode and message (as array). More...
void	OnPhotonJoinRoomFailed (object[] codeAndMsg)
	Called when a JoinRoom() call failed. The parameter provides ErrorCode and message (as array). More...
void	OnCreatedRoom ()
	Called when this client created a room and entered it. OnJoinedRoom() will be called as well. More...
void	OnJoinedLobby ()
	Called on entering a lobby on the Master Server. The actual room-list updates will call OnReceivedRoomListUpdate(). More...
void	OnLeftLobby ()
	Called after leaving a lobby. More...
void	OnFailedToConnectToPhoton (DisconnectCause cause)
	Called if a connect call to the Photon server failed before the connection was established, followed by a call to OnDisconnectedFromPhoton(). More...
void	OnConnectionFail (DisconnectCause cause)
	Called when something causes the connection to fail (after it was established), followed by a call to OnDisconnectedFromPhoton(). More...
void	OnDisconnectedFromPhoton ()
	Called after disconnecting from the Photon server. More...
void	OnPhotonInstantiate (PhotonMessageInfo info)
	Called on all scripts on a GameObject (and children) that have been Instantiated using PhotonNetwork.Instantiate. More...
void	OnReceivedRoomListUpdate ()
	Called for any update of the room-listing while in a lobby (PhotonNetwork.insideLobby) on the Master Server or when a response is received for PhotonNetwork.GetCustomRoomList(). More...
void	OnJoinedRoom ()
	Called when entering a room (by creating or joining it). Called on all clients (including the Master Client). More...
void	OnPhotonPlayerConnected (PhotonPlayer newPlayer)
	Called when a remote player entered the room. This PhotonPlayer is already added to the playerlist at this time. More...
void	OnPhotonPlayerDisconnected (PhotonPlayer otherPlayer)
	Called when a remote player left the room. This PhotonPlayer is already removed from the playerlist at this time. More...
void	OnPhotonRandomJoinFailed (object[] codeAndMsg)
	Called when a JoinRandom() call failed. The parameter provides ErrorCode and message. More...
void	OnConnectedToMaster ()
	Called after the connection to the master is established and authenticated but only when PhotonNetwork.autoJoinLobby is false. More...
void	OnPhotonMaxCccuReached ()
	Because the concurrent user limit was (temporarily) reached, this client is rejected by the server and disconnecting. More...
void	OnPhotonCustomRoomPropertiesChanged (Hashtable propertiesThatChanged)
	Called when a room's custom properties changed. The propertiesThatChanged contains all that was set via Room.SetCustomProperties. More...
void	OnPhotonPlayerPropertiesChanged (object[] playerAndUpdatedProps)
	Called when custom player-properties are changed. Player and the changed properties are passed as object[]. More...
void	OnUpdatedFriendList ()
	Called when the server sent the response to a FindFriends request and updated PhotonNetwork.Friends. More...
void	OnCustomAuthenticationFailed (string debugMessage)
	Called when the custom authentication failed. Followed by disconnect! More...
void	OnCustomAuthenticationResponse (Dictionary< string, object > data)
	Called when your Custom Authentication service responds with additional data. More...
void	OnWebRpcResponse (OperationResponse response)
	Called by PUN when the response to a WebRPC is available. See PhotonNetwork.WebRPC. More...
void	OnOwnershipRequest (object[] viewAndPlayer)
	Called when another player requests ownership of a PhotonView from you (the current owner). More...
void	OnLobbyStatisticsUpdate ()
	Called when the Master Server sent an update for the Lobby Statistics, updating PhotonNetwork.LobbyStatistics. More...
void	OnPhotonPlayerActivityChanged (PhotonPlayer otherPlayer)
	Called when a remote Photon Player activity changed. This will be called ONLY if PlayerTtl is greater than 0. More...
void	OnOwnershipTransfered (object[] viewAndPlayers)
	Called when ownership of a PhotonView is transfered to another player. More...

Detailed Description

This interface is used as definition of all callback methods of PUN, except OnPhotonSerializeView. Preferably, implement them individually.

This interface is available for completeness, more than for actually implementing it in a game. You can implement each method individually in any MonoMehaviour, without implementing IPunCallbacks.

PUN calls all callbacks by name. Don't use implement callbacks with fully qualified name. Example: IPunCallbacks.OnConnectedToPhoton won't get called by Unity's SendMessage().

PUN will call these methods on any script that implements them, analog to Unity's events and callbacks. The situation that triggers the call is described per method.

OnPhotonSerializeView is NOT called like these callbacks! It's usage frequency is much higher and it is implemented in: IPunObservable.

Member Function Documentation

OnConnectedToMaster()

void IPunCallbacks.OnConnectedToMaster

(

)

Called after the connection to the master is established and authenticated but only when PhotonNetwork.autoJoinLobby is false.

If you set PhotonNetwork.autoJoinLobby to true, OnJoinedLobby() will be called instead of this.

You can join rooms and create them even without being in a lobby. The default lobby is used in that case. The list of available rooms won't become available unless you join a lobby via PhotonNetwork.joinLobby.

Implemented in Photon.PunBehaviour.

OnConnectedToPhoton()

void IPunCallbacks.OnConnectedToPhoton

(

)

Called when the initial connection got established but before you can use the server. OnJoinedLobby() or OnConnectedToMaster() are called when PUN is ready.

This callback is only useful to detect if the server can be reached at all (technically). Most often, it's enough to implement OnFailedToConnectToPhoton() and OnDisconnectedFromPhoton().

OnJoinedLobby() or OnConnectedToMaster() are called when PUN is ready.

When this is called, the low level connection is established and PUN will send your AppId, the user, etc in the background. This is not called for transitions from the masterserver to game servers.

Implemented in Photon.PunBehaviour.

OnConnectionFail()

void IPunCallbacks.OnConnectionFail

(

DisconnectCause

cause

)

Called when something causes the connection to fail (after it was established), followed by a call to OnDisconnectedFromPhoton().

If the server could not be reached in the first place, OnFailedToConnectToPhoton is called instead. The reason for the error is provided as DisconnectCause.

Implemented in Photon.PunBehaviour.

OnCreatedRoom()

void IPunCallbacks.OnCreatedRoom

(

)

Called when this client created a room and entered it. OnJoinedRoom() will be called as well.

This callback is only called on the client which created a room (see PhotonNetwork.CreateRoom).

As any client might close (or drop connection) anytime, there is a chance that the creator of a room does not execute OnCreatedRoom.

If you need specific room properties or a "start signal", it is safer to implement OnMasterClientSwitched() and to make the new MasterClient check the room's state.

Implemented in Photon.PunBehaviour.

OnCustomAuthenticationFailed()

void IPunCallbacks.OnCustomAuthenticationFailed

(

string

debugMessage

)

Called when the custom authentication failed. Followed by disconnect!

Custom Authentication can fail due to user-input, bad tokens/secrets. If authentication is successful, this method is not called. Implement OnJoinedLobby() or OnConnectedToMaster() (as usual).

During development of a game, it might also fail due to wrong configuration on the server side. In those cases, logging the debugMessage is very important.

Unless you setup a custom authentication service for your app (in the Dashboard), this won't be called!

Parameters

debugMessage

Contains a debug message why authentication failed. This has to be fixed during development time.

Implemented in Photon.PunBehaviour.

OnCustomAuthenticationResponse()

void IPunCallbacks.OnCustomAuthenticationResponse

(

Dictionary< string, object >

data

)

Called when your Custom Authentication service responds with additional data.

Custom Authentication services can include some custom data in their response. When present, that data is made available in this callback as Dictionary. While the keys of your data have to be strings, the values can be either string or a number (in Json). You need to make extra sure, that the value type is the one you expect. Numbers become (currently) int64.

Example: void OnCustomAuthenticationResponse(Dictionary<string, object> data) { ... }

https://doc.photonengine.com/en-us/pun/current/connection-and-authentication/custom-authentication

Implemented in Photon.PunBehaviour.

OnDisconnectedFromPhoton()

void IPunCallbacks.OnDisconnectedFromPhoton

(

)

Called after disconnecting from the Photon server.

In some cases, other callbacks are called before OnDisconnectedFromPhoton is called. Examples: OnConnectionFail() and OnFailedToConnectToPhoton().

Implemented in Photon.PunBehaviour.

OnFailedToConnectToPhoton()

void IPunCallbacks.OnFailedToConnectToPhoton

(

DisconnectCause

cause

)

Called if a connect call to the Photon server failed before the connection was established, followed by a call to OnDisconnectedFromPhoton().

This is called when no connection could be established at all. It differs from OnConnectionFail, which is called when an existing connection fails.

Implemented in Photon.PunBehaviour.

OnJoinedLobby()

void IPunCallbacks.OnJoinedLobby

(

)

Called on entering a lobby on the Master Server. The actual room-list updates will call OnReceivedRoomListUpdate().

Note: When PhotonNetwork.autoJoinLobby is false, OnConnectedToMaster() will be called and the room list won't become available.

While in the lobby, the roomlist is automatically updated in fixed intervals (which you can't modify). The room list gets available when OnReceivedRoomListUpdate() gets called after OnJoinedLobby().

Implemented in Photon.PunBehaviour.

OnJoinedRoom()

void IPunCallbacks.OnJoinedRoom

(

)

Called when entering a room (by creating or joining it). Called on all clients (including the Master Client).

This method is commonly used to instantiate player characters. If a match has to be started "actively", you can call an PunRPC triggered by a user's button-press or a timer.

When this is called, you can usually already access the existing players in the room via PhotonNetwork.playerList. Also, all custom properties should be already available as Room.customProperties. Check Room.playerCount to find out if enough players are in the room to start playing.

Implemented in Photon.PunBehaviour.

OnLeftLobby()

void IPunCallbacks.OnLeftLobby

(

)

Called after leaving a lobby.

When you leave a lobby, CreateRoom and JoinRandomRoom automatically refer to the default lobby.

Implemented in Photon.PunBehaviour.

OnLeftRoom()

void IPunCallbacks.OnLeftRoom

(

)

Called when the local user/client left a room.

When leaving a room, PUN brings you back to the Master Server. Before you can use lobbies and join or create rooms, OnJoinedLobby() or OnConnectedToMaster() will get called again.

Implemented in Photon.PunBehaviour.

OnLobbyStatisticsUpdate()

void IPunCallbacks.OnLobbyStatisticsUpdate

(

)

Called when the Master Server sent an update for the Lobby Statistics, updating PhotonNetwork.LobbyStatistics.

This callback has two preconditions: EnableLobbyStatistics must be set to true, before this client connects. And the client has to be connected to the Master Server, which is providing the info about lobbies.

Implemented in Photon.PunBehaviour.

OnMasterClientSwitched()

void IPunCallbacks.OnMasterClientSwitched

(

PhotonPlayer

newMasterClient

)

Called after switching to a new MasterClient when the current one leaves.

This is not called when this client enters a room. The former MasterClient is still in the player list when this method get called.

Implemented in Photon.PunBehaviour.

OnOwnershipRequest()

void IPunCallbacks.OnOwnershipRequest

(

object[]

viewAndPlayer

)

Called when another player requests ownership of a PhotonView from you (the current owner).

The parameter viewAndPlayer contains:

PhotonView view = viewAndPlayer[0] as PhotonView;

PhotonPlayer requestingPlayer = viewAndPlayer[1] as PhotonPlayer;

Parameters

viewAndPlayer

The PhotonView is viewAndPlayer[0] and the requesting player is viewAndPlayer[1].

Implemented in Photon.PunBehaviour.

OnOwnershipTransfered()

void IPunCallbacks.OnOwnershipTransfered

(

object[]

viewAndPlayers

)

Called when ownership of a PhotonView is transfered to another player.

The parameter viewAndPlayers contains:

PhotonView view = viewAndPlayers[0] as PhotonView;

PhotonPlayer newOwner = viewAndPlayers[1] as PhotonPlayer;

PhotonPlayer oldOwner = viewAndPlayers[2] as PhotonPlayer;

void OnOwnershipTransfered(object[] viewAndPlayers) {} //

Implemented in Photon.PunBehaviour.

OnPhotonCreateRoomFailed()

void IPunCallbacks.OnPhotonCreateRoomFailed

(

object[]

codeAndMsg

)

Called when a CreateRoom() call failed. The parameter provides ErrorCode and message (as array).

Most likely because the room name is already in use (some other client was faster than you). PUN logs some info if the PhotonNetwork.logLevel is >= PhotonLogLevel.Informational.

Parameters

codeAndMsg

codeAndMsg[0] is short ErrorCode and codeAndMsg[1] is a string debug msg.

Implemented in Photon.PunBehaviour.

OnPhotonCustomRoomPropertiesChanged()

void IPunCallbacks.OnPhotonCustomRoomPropertiesChanged

(

Hashtable

propertiesThatChanged

)

Called when a room's custom properties changed. The propertiesThatChanged contains all that was set via Room.SetCustomProperties.

Since v1.25 this method has one parameter: Hashtable propertiesThatChanged.
Changing properties must be done by Room.SetCustomProperties, which causes this callback locally, too.

Parameters

propertiesThatChanged

Implemented in Photon.PunBehaviour.

OnPhotonInstantiate()

void IPunCallbacks.OnPhotonInstantiate

(

PhotonMessageInfo

info

)

Called on all scripts on a GameObject (and children) that have been Instantiated using PhotonNetwork.Instantiate.

PhotonMessageInfo parameter provides info about who created the object and when (based off PhotonNetworking.time).

Implemented in Photon.PunBehaviour.

OnPhotonJoinRoomFailed()

void IPunCallbacks.OnPhotonJoinRoomFailed

(

object[]

codeAndMsg

)

Called when a JoinRoom() call failed. The parameter provides ErrorCode and message (as array).

Most likely error is that the room does not exist or the room is full (some other client was faster than you). PUN logs some info if the PhotonNetwork.logLevel is >= PhotonLogLevel.Informational.

Parameters

codeAndMsg

codeAndMsg[0] is short ErrorCode and codeAndMsg[1] is string debug msg.

Implemented in Photon.PunBehaviour.

OnPhotonMaxCccuReached()

void IPunCallbacks.OnPhotonMaxCccuReached

(

)

Because the concurrent user limit was (temporarily) reached, this client is rejected by the server and disconnecting.

When this happens, the user might try again later. You can't create or join rooms in OnPhotonMaxCcuReached(), cause the client will be disconnecting. You can raise the CCU limits with a new license (when you host yourself) or extended subscription (when using the Photon Cloud). The Photon Cloud will mail you when the CCU limit was reached. This is also visible in the Dashboard (webpage).

Implemented in Photon.PunBehaviour.

OnPhotonPlayerActivityChanged()

void IPunCallbacks.OnPhotonPlayerActivityChanged

(

PhotonPlayer

otherPlayer

)

Called when a remote Photon Player activity changed. This will be called ONLY if PlayerTtl is greater than 0.

Use PhotonPlayer.IsInactive to check a player's current activity state.

Example: void OnPhotonPlayerActivityChanged(PhotonPlayer otherPlayer) {...}

This callback has precondition: PlayerTtl must be greater than 0.

Implemented in Photon.PunBehaviour.

OnPhotonPlayerConnected()

void IPunCallbacks.OnPhotonPlayerConnected

(

PhotonPlayer

newPlayer

)

Called when a remote player entered the room. This PhotonPlayer is already added to the playerlist at this time.

If your game starts with a certain number of players, this callback can be useful to check the Room.playerCount and find out if you can start.

Implemented in Photon.PunBehaviour.

OnPhotonPlayerDisconnected()

void IPunCallbacks.OnPhotonPlayerDisconnected

(

PhotonPlayer

otherPlayer

)

Called when a remote player left the room. This PhotonPlayer is already removed from the playerlist at this time.

When your client calls PhotonNetwork.leaveRoom, PUN will call this method on the remaining clients. When a remote client drops connection or gets closed, this callback gets executed. after a timeout of several seconds.

Implemented in Photon.PunBehaviour.

OnPhotonPlayerPropertiesChanged()

void IPunCallbacks.OnPhotonPlayerPropertiesChanged

(

object[]

playerAndUpdatedProps

)

Called when custom player-properties are changed. Player and the changed properties are passed as object[].

Since v1.25 this method has one parameter: object[] playerAndUpdatedProps, which contains two entries.
[0] is the affected PhotonPlayer.
[1] is the Hashtable of properties that changed.

We are using a object[] due to limitations of Unity's GameObject.SendMessage (which has only one optional parameter).

Changing properties must be done by PhotonPlayer.SetCustomProperties, which causes this callback locally, too.

Example:

void OnPhotonPlayerPropertiesChanged(object[] playerAndUpdatedProps) {
    PhotonPlayer player = playerAndUpdatedProps[0] as PhotonPlayer;
    Hashtable props = playerAndUpdatedProps[1] as Hashtable;
    //...
}

Parameters

playerAndUpdatedProps

Contains PhotonPlayer and the properties that changed See remarks.

Implemented in Photon.PunBehaviour.

OnPhotonRandomJoinFailed()

void IPunCallbacks.OnPhotonRandomJoinFailed

(

object[]

codeAndMsg

)

Called when a JoinRandom() call failed. The parameter provides ErrorCode and message.

Most likely all rooms are full or no rooms are available.
When using multiple lobbies (via JoinLobby or TypedLobby), another lobby might have more/fitting rooms.
PUN logs some info if the PhotonNetwork.logLevel is >= PhotonLogLevel.Informational.

Parameters

codeAndMsg

codeAndMsg[0] is short ErrorCode. codeAndMsg[1] is string debug msg.

Implemented in Photon.PunBehaviour.

OnReceivedRoomListUpdate()

void IPunCallbacks.OnReceivedRoomListUpdate

(

)

Called for any update of the room-listing while in a lobby (PhotonNetwork.insideLobby) on the Master Server or when a response is received for PhotonNetwork.GetCustomRoomList().

PUN provides the list of rooms by PhotonNetwork.GetRoomList().
Each item is a RoomInfo which might include custom properties (provided you defined those as lobby-listed when creating a room).

Not all types of lobbies provide a listing of rooms to the client. Some are silent and specialized for server-side matchmaking.

Implemented in Photon.PunBehaviour.

OnUpdatedFriendList()

void IPunCallbacks.OnUpdatedFriendList

(

)

Called when the server sent the response to a FindFriends request and updated PhotonNetwork.Friends.

The friends list is available as PhotonNetwork.Friends, listing name, online state and the room a user is in (if any).

Implemented in Photon.PunBehaviour.

OnWebRpcResponse()

void IPunCallbacks.OnWebRpcResponse

(

OperationResponse

response

)

Called by PUN when the response to a WebRPC is available. See PhotonNetwork.WebRPC.

Important: The response.ReturnCode is 0 if Photon was able to reach your web-service.
The content of the response is what your web-service sent. You can create a WebRpcResponse from it.
Example: WebRpcResponse webResponse = new WebRpcResponse(operationResponse);

Please note: Class OperationResponse is in a namespace which needs to be "used":
using ExitGames.Client.Photon; // includes OperationResponse (and other classes)

The OperationResponse.ReturnCode by Photon is:

 0 for "OK"
-3 for "Web-Service not configured" (see Dashboard / WebHooks)
-5 for "Web-Service does now have RPC path/name" (at least for Azure)

Implemented in Photon.PunBehaviour.