Photon Unity Networking 2 2.45

Public Member Functions | List of all members
MonoBehaviourPunCallbacks Class Reference

This class provides a .photonView and all callbacks/events that PUN can call. Override the events/methods you want to use. More...

Inherits MonoBehaviourPun, IConnectionCallbacks, IMatchmakingCallbacks, IInRoomCallbacks, ILobbyCallbacks, IWebRpcCallback, and IErrorInfoCallback.

Inherited by ConnectAndJoinRandom, CountdownTimer, PlayerNumbering, PunTeams, and PunTurnManager.

Public Member Functions

virtual void OnEnable ()
 
virtual void OnDisable ()
 
virtual void OnConnected ()
 Called to signal that the raw connection got established but before the client can call operation on the server. More...
 
virtual void OnLeftRoom ()
 Called when the local user/client left a room, so the game's logic can clean up it's internal state. More...
 
virtual void OnMasterClientSwitched (Player newMasterClient)
 Called after switching to a new MasterClient when the current one leaves. More...
 
virtual void OnCreateRoomFailed (short returnCode, string message)
 Called when the server couldn't create a room (OpCreateRoom failed). More...
 
virtual void OnJoinRoomFailed (short returnCode, string message)
 Called when a previous OpJoinRoom call failed on the server. More...
 
virtual void OnCreatedRoom ()
 Called when this client created a room and entered it. OnJoinedRoom() will be called as well. More...
 
virtual void OnJoinedLobby ()
 Called on entering a lobby on the Master Server. The actual room-list updates will call OnRoomListUpdate. More...
 
virtual void OnLeftLobby ()
 Called after leaving a lobby. More...
 
virtual void OnDisconnected (DisconnectCause cause)
 Called after disconnecting from the Photon server. It could be a failure or intentional More...
 
virtual void OnRegionListReceived (RegionHandler regionHandler)
 Called when the Name Server provided a list of regions for your title. More...
 
virtual void OnRoomListUpdate (List< RoomInfo > roomList)
 Called for any update of the room-listing while in a lobby (InLobby) on the Master Server. More...
 
virtual void OnJoinedRoom ()
 Called when the LoadBalancingClient entered a room, no matter if this client created it or simply joined. More...
 
virtual void OnPlayerEnteredRoom (Player newPlayer)
 Called when a remote player entered the room. This Player is already added to the playerlist. More...
 
virtual void OnPlayerLeftRoom (Player otherPlayer)
 Called when a remote player left the room or became inactive. Check otherPlayer.IsInactive. More...
 
virtual void OnJoinRandomFailed (short returnCode, string message)
 Called when a previous OpJoinRandom call failed on the server. More...
 
virtual void OnConnectedToMaster ()
 Called when the client is connected to the Master Server and ready for matchmaking and other tasks. More...
 
virtual void OnRoomPropertiesUpdate (Hashtable propertiesThatChanged)
 Called when a room's custom properties changed. The propertiesThatChanged contains all that was set via Room.SetCustomProperties. More...
 
virtual void OnPlayerPropertiesUpdate (Player targetPlayer, Hashtable changedProps)
 Called when custom player-properties are changed. Player and the changed properties are passed as object[]. More...
 
virtual void OnFriendListUpdate (List< FriendInfo > friendList)
 Called when the server sent the response to a FindFriends request. More...
 
virtual void OnCustomAuthenticationResponse (Dictionary< string, object > data)
 Called when your Custom Authentication service responds with additional data. More...
 
virtual void OnCustomAuthenticationFailed (string debugMessage)
 Called when the custom authentication failed. Followed by disconnect! More...
 
virtual void OnWebRpcResponse (OperationResponse response)
 Called when the response to a WebRPC is available. See LoadBalancingClient.OpWebRpc. More...
 
virtual void OnLobbyStatisticsUpdate (List< TypedLobbyInfo > lobbyStatistics)
 Called when the Master Server sent an update for the Lobby Statistics. More...
 
virtual void OnErrorInfo (ErrorInfo errorInfo)
 Called when the client receives an event from the server indicating that an error happened there. More...
 

Additional Inherited Members

- Properties inherited from MonoBehaviourPun
PhotonView photonView [get]
 A cached reference to a PhotonView on this GameObject. More...
 

Detailed Description

This class provides a .photonView and all callbacks/events that PUN can call. Override the events/methods you want to use.

By extending this class, you can implement individual methods as override.

Do not add new

MonoBehaviour.OnEnable

or

MonoBehaviour.OnDisable

Instead, you should override those and call

base.OnEnable

and

base.OnDisable

.

Visual Studio and MonoDevelop should provide the list of methods when you begin typing "override". Your implementation does not have to call "base.method()".

This class implements all callback interfaces and extends Photon.Pun.MonoBehaviourPun.

Member Function Documentation

◆ OnConnected()

virtual void OnConnected ( )
virtual

Called to signal that the raw connection got established but before the client can call operation on the server.

After the (low level transport) connection is established, the client will automatically send the Authentication operation, which needs to get a response before the client can call other operations.

Your logic should wait for either: OnRegionListReceived or OnConnectedToMaster.

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

This is not called for transitions from the masterserver to game servers.

Implements IConnectionCallbacks.

◆ OnConnectedToMaster()

virtual void OnConnectedToMaster ( )
virtual

Called when the client is connected to the Master Server and ready for matchmaking and other tasks.

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

Implements IConnectionCallbacks.

Reimplemented in ConnectAndJoinRandom.

◆ OnCreatedRoom()

virtual void OnCreatedRoom ( )
virtual

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 OpCreateRoom).

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", implement OnMasterClientSwitched() and make each new MasterClient check the room's state.

Implements IMatchmakingCallbacks.

◆ OnCreateRoomFailed()

virtual void OnCreateRoomFailed ( short  returnCode,
string  message 
)
virtual

Called when the server couldn't create a room (OpCreateRoom failed).

The most common cause to fail creating a room, is when a title relies on fixed room-names and the room already exists.

Parameters
returnCodeOperation ReturnCode from the server.
messageDebug message for the error.

Implements IMatchmakingCallbacks.

◆ OnCustomAuthenticationFailed()

virtual void OnCustomAuthenticationFailed ( string  debugMessage)
virtual

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
debugMessageContains a debug message why authentication failed. This has to be fixed during development.

Implements IConnectionCallbacks.

◆ OnCustomAuthenticationResponse()

virtual void OnCustomAuthenticationResponse ( Dictionary< string, object >  data)
virtual

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) { ... }

Implements IConnectionCallbacks.

◆ OnDisconnected()

virtual void OnDisconnected ( DisconnectCause  cause)
virtual

Called after disconnecting from the Photon server. It could be a failure or intentional

The reason for this disconnect is provided as DisconnectCause.

Implements IConnectionCallbacks.

Reimplemented in ConnectAndJoinRandom.

◆ OnErrorInfo()

virtual void OnErrorInfo ( ErrorInfo  errorInfo)
virtual

Called when the client receives an event from the server indicating that an error happened there.

In most cases this could be either:

  1. an error from webhooks plugin (if HasErrorInfo is enabled), read more here: https://doc.photonengine.com/en-us/realtime/current/gameplay/web-extensions/webhooks#options
  2. an error sent from a custom server plugin via PluginHost.BroadcastErrorInfoEvent, see example here: https://doc.photonengine.com/en-us/server/current/plugins/manual#handling_http_response
  3. an error sent from the server, for example, when the limit of cached events has been exceeded in the room (all clients will be disconnected and the room will be closed in this case) read more here: https://doc.photonengine.com/en-us/realtime/current/gameplay/cached-events#special_considerations
Parameters
errorInfoobject containing information about the error

Implements IErrorInfoCallback.

◆ OnFriendListUpdate()

virtual void OnFriendListUpdate ( List< FriendInfo friendList)
virtual

Called when the server sent the response to a FindFriends request.

After calling OpFindFriends, the Master Server will cache the friend list and send updates to the friend list. The friends includes the name, userId, online state and the room (if any) for each requested user/friend.

Use the friendList to update your UI and store it, if the UI should highlight changes.

Implements IMatchmakingCallbacks.

◆ OnJoinedLobby()

virtual void OnJoinedLobby ( )
virtual

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

While in the lobby, the roomlist is automatically updated in fixed intervals (which you can't modify in the public cloud). The room list gets available via OnRoomListUpdate.

Implements ILobbyCallbacks.

Reimplemented in ConnectAndJoinRandom.

◆ OnJoinedRoom()

virtual void OnJoinedRoom ( )
virtual

Called when the LoadBalancingClient entered a room, no matter if this client created it or simply joined.

When this is called, you can access the existing players in Room.Players, their custom properties and Room.CustomProperties.

In this callback, you could create player objects. For example in Unity, instantiate a prefab for the player.

If you want a match to be started "actively", enable the user to signal "ready" (using OpRaiseEvent or a Custom Property).

Implements IMatchmakingCallbacks.

Reimplemented in ConnectAndJoinRandom, PlayerNumbering, and PunTeams.

◆ OnJoinRandomFailed()

virtual void OnJoinRandomFailed ( short  returnCode,
string  message 
)
virtual

Called when a previous OpJoinRandom call failed on the server.

The most common causes are that a room is full or does not exist (due to someone else being faster or closing the room).

When using multiple lobbies (via OpJoinLobby or a TypedLobby parameter), another lobby might have more/fitting rooms.

Parameters
returnCodeOperation ReturnCode from the server.
messageDebug message for the error.

Implements IMatchmakingCallbacks.

Reimplemented in ConnectAndJoinRandom.

◆ OnJoinRoomFailed()

virtual void OnJoinRoomFailed ( short  returnCode,
string  message 
)
virtual

Called when a previous OpJoinRoom call failed on the server.

The most common causes are that a room is full or does not exist (due to someone else being faster or closing the room).

Parameters
returnCodeOperation ReturnCode from the server.
messageDebug message for the error.

Implements IMatchmakingCallbacks.

◆ OnLeftLobby()

virtual void OnLeftLobby ( )
virtual

Called after leaving a lobby.

When you leave a lobby, OpCreateRoom and OpJoinRandomRoom automatically refer to the default lobby.

Implements ILobbyCallbacks.

◆ OnLeftRoom()

virtual void OnLeftRoom ( )
virtual

Called when the local user/client left a room, so the game's logic can clean up it's internal state.

When leaving a room, the LoadBalancingClient will disconnect the Game Server and connect to the Master Server. This wraps up multiple internal actions.

Wait for the callback OnConnectedToMaster, before you use lobbies and join or create rooms.

Implements IMatchmakingCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnLobbyStatisticsUpdate()

virtual void OnLobbyStatisticsUpdate ( List< TypedLobbyInfo lobbyStatistics)
virtual

Called when the Master Server sent an update for the Lobby Statistics.

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.

Implements ILobbyCallbacks.

◆ OnMasterClientSwitched()

virtual void OnMasterClientSwitched ( Player  newMasterClient)
virtual

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.

Implements IInRoomCallbacks.

◆ OnPlayerEnteredRoom()

virtual void OnPlayerEnteredRoom ( Player  newPlayer)
virtual

Called when a remote player entered the room. This Player is already added to the playerlist.

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.

Implements IInRoomCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnPlayerLeftRoom()

virtual void OnPlayerLeftRoom ( Player  otherPlayer)
virtual

Called when a remote player left the room or became inactive. Check otherPlayer.IsInactive.

If another player leaves the room or if the server detects a lost connection, this callback will be used to notify your game logic.

Depending on the room's setup, players may become inactive, which means they may return and retake their spot in the room. In such cases, the Player stays in the Room.Players dictionary.

If the player is not just inactive, it gets removed from the Room.Players dictionary, before the callback is called.

Implements IInRoomCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnPlayerPropertiesUpdate()

virtual void OnPlayerPropertiesUpdate ( Player  targetPlayer,
Hashtable  changedProps 
)
virtual

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

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

Parameters
targetPlayerContains Player that changed.
changedPropsContains the properties that changed.

Implements IInRoomCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnRegionListReceived()

virtual void OnRegionListReceived ( RegionHandler  regionHandler)
virtual

Called when the Name Server provided a list of regions for your title.

Check the RegionHandler class description, to make use of the provided values.

Parameters
regionHandlerThe currently used RegionHandler.

Implements IConnectionCallbacks.

◆ OnRoomListUpdate()

virtual void OnRoomListUpdate ( List< RoomInfo roomList)
virtual

Called for any update of the room-listing while in a lobby (InLobby) on the Master Server.

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.

Implements ILobbyCallbacks.

◆ OnRoomPropertiesUpdate()

virtual void OnRoomPropertiesUpdate ( Hashtable  propertiesThatChanged)
virtual

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

Implements IInRoomCallbacks.

Reimplemented in PunTurnManager, and CountdownTimer.

◆ OnWebRpcResponse()

virtual void OnWebRpcResponse ( OperationResponse  response)
virtual

Called when the response to a WebRPC is available. See LoadBalancingClient.OpWebRpc.

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)

public void OnWebRpcResponse(OperationResponse response) { Debug.LogFormat("WebRPC operation response {0}", response.ToStringFull()); switch (response.ReturnCode) { case ErrorCode.Ok: WebRpcResponse webRpcResponse = new WebRpcResponse(response); Debug.LogFormat("Parsed WebRPC response {0}", response.ToStringFull()); if (string.IsNullOrEmpty(webRpcResponse.Name)) { Debug.LogError("Unexpected: WebRPC response did not contain WebRPC method name"); } if (webRpcResponse.ResultCode == 0) // success { switch (webRpcResponse.Name) { // todo: add your code here case GetGameListWebRpcMethodName: // example // ... break; } } else if (webRpcResponse.ResultCode == -1) { Debug.LogErrorFormat("Web server did not return ResultCode for WebRPC method=\"{0}", Message={1}", webRpcResponse.Name, webRpcResponse.Message); } else { Debug.LogErrorFormat("Web server returned ResultCode={0} for WebRPC method=\"{1}", Message={2}", webRpcResponse.ResultCode, webRpcResponse.Name, webRpcResponse.Message); } break; case ErrorCode.ExternalHttpCallFailed: // web service unreachable Debug.LogErrorFormat("WebRPC call failed as request could not be sent to the server. {0}", response.DebugMessage); break; case ErrorCode.HttpLimitReached: // too many WebRPCs in a short period of time // the debug message should contain the limit exceeded Debug.LogErrorFormat("WebRPCs rate limit exceeded: {0}", response.DebugMessage); break; case ErrorCode.InvalidOperation: // WebRPC not configured at all OR not configured properly OR trying to send on name server if (PhotonNetwork.Server == ServerConnection.NameServer) { Debug.LogErrorFormat("WebRPC not supported on NameServer. {0}", response.DebugMessage); } else { Debug.LogErrorFormat("WebRPC not properly configured or not configured at all. {0}", response.DebugMessage); } break; default: // other unknown error, unexpected Debug.LogErrorFormat("Unexpected error, {0} {1}", response.ReturnCode, response.DebugMessage); break; } }

Implements IWebRpcCallback.