• Jun 19, 2019 PUN makes it very easy to make a Prefab whose properties (Position, Rotation, etc.) have to be synced across the network during a multiplayer game using the Photon View Component. An important concept to understand about using PUN is that a Prefab that should get instantiated over the network has to be inside a folder named Resources.
• PUN PUN (Photon Unity Networking) is a clone of the original Unity networking API, powered by the reliable Photon infrastructure. Besides the omnipresent matchmaking, PUN basic building blocks are: serialization of game object states (with built in support for.
• In the Photon Cloud, an application is defined by AppId, Game- and PUN-version. 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.

• Photon Quantum Unity
• Photon Pun 2
• Photon Pun
• Photon Pun Vs Realtime
• Photon Pun2

In the Photon Cloud, an application is defined by AppId, Game- and PUN-version. 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.

In PUN, networked objects are established using the PhotonView component.Each PhotonView has a creator (instantiator), owner and controller.In this document we will discover the definitions and concepts about PhotonView's control and ownership.We will also list the expected behaviour in different situations and how to explicitly change ownerships of PhotonViews.

Contents

• Definitions
  • Networked Object
• Automatic Control Transition
• Explicit Ownership Transfer
  • Ownership Transfer Options
• PhotonView Callbacks

Definitions

Actor

An actor represents a client in a room.Each actor is incrementally assigned an new number when joining a room.The first client to join a room will be actor number 1, the second will be actor number 2 and so on.Actors can be targets of messages and one actor per room is assigned as the master client.Creator, Owner and Controller all are references to an actor.

PhotonView Creator

The creator of a PhotonView or the 'instantiator' (or 'spawner'), is the actor that calls PhotonNetwork.Instantiate.This actor number is be part of the PhotonView.ViewID and is determined using ViewID / PhotonNetwork.MAXVIEWIDS.The ViewID of a PhotonView does not change, so the creator ID also does not change.In case of 'networked room objects', there is no creator (null/0) so the networked object is not created by an actor and is instead associated with the room.

PhotonView Owner

The owner of the PhotonView indicates the default Controller of the PhotonView.

In case of 'networked room objects', there is no owner (null) as the object is owned by the room and not by an actor.In case there is an owner, if the latter is active it is also the controller.Otherwise, the master client has control.

PhotonView Controller

The actor in control of the PhotonView (has state authority).

The owner is always the controller unless:

• the owner is null; then the master client is the controller.
• the owner is disconnected from the room;If the PlayerTTL is greater than 0, it is possible for an actor to leave the room temporarily and rejoin it later.While the owner is soft-disconnected, the master client becomes controller and when the owner rejoins, the owner resumes control.

photonView.IsMine indicates if the PhotonNetwork.LocalPlayer is the current Controller for this photonView.

Networked Object

A networked object is a GameObject that has a PhotonView component, including its children.So a networked object is represented by its root PhotonView component, i.e. the PhotonView attached to the top level (root) GameObject.

Nested Networked Object

If a networked object has children GameObject in its hierarchy and one or more has a PhotonView attached then it's considered a nested networked object.So, a nested networked object is a networked object that is part of the hierarchy of another networked object.Usually when you instantiate a networked object that has netsted networked object(s), all PhotonViews will share the same instantiation ID (ViewID of the root PhotonView) and unless owner or controller is different, or re parented, they will have the same lifetime.

Room Object

A networked room object is a networked object that does not belong to an actor but it is a 'global networked object' belonging to the room.It has no owner (null), nor controller (null) and it is not a result of a PhotonNetwork.Instantiate call (but could be a result of PhotonNetwork.InstantiateRoomObject).

Scene Object

A scene object is a room object that was not runtime instantiated using PhotonNetwork.InstantiateRoomObject.It was part of the Unity scene at compile time.

Soft Disconnect

A soft disconnect is when an actor becomes inactive in a room.It happens in case of PlayerTTL different than 0 and:

• the client disconnects
• the client leaves the room temporarility with the intention of coming back

The actor remains inactive until PlayerTTL expires.If PlayerTTL < 0 or PlayerTTL int.MaxValue the actor can remain inactive forever.

You can recover from unexpected soft disconnects using PhotonNetwork.ReconnectAndRejoin() or rejoin the same room after it happens using PhotonNetwork.RejoinRoom.In both cases, the client needs to keep the same UserId and the actor reclaims the same actor number and all previous actor properties on rejoin.

Hard Disconnect

A hard disconnect is when an actor is completely removed from the room's actors list.

If PhotonNetwork.CurrentRoom.PlayerTtl 0:

• the client disconnects from Photon Server
• the client leaves the room

If PhotonNetwork.CurrentRoom.PlayerTtl != 0:

• the client leaves the room for good
• PlayerTTL expires for the inactive actor

Automatic Control Transition

On Soft Disconnect

On the local client that soft-disconnected:

• If PhotonNetwork.CurrentRoom.AutoCleanUp true:

  • Un-parent scene objects from runtime instantiated networked objects (to prevent their destruction).
  • Any nested networked objects that were not created by this actor are unparented from parent/root object before destruction.

  • All runtime instantiated networked objects created by the disconnecting actor are destroyed.

  • Other networked objects are reset to defaults.

• If PhotonNetwork.CurrentRoom.AutoCleanUp false:

  • Nothing changes. You need to do manual clean up.

On remote clients -if any-:

• Ownership unchanged for the PhotonViews previously owned by the actor that soft-disconnected.
• Master client becomes controller of the PhotonViews owned by the actor that soft-disconnected.

On Hard Disconnect

On the local client that hard-disconnected:

• If PhotonNetwork.CurrentRoom.AutoCleanUp true:

  • Un-parent nested networked scene objects from disconnecting actor's instantiated networked objects (to prevent their destruction).
  • Runtime instantiated networked objects created by the disconnected actor will be destroyed.
  • Cached instantiation events and buffered RPCs are removed from relay server.
  • Scene objects are reset.

• If PhotonNetwork.CurrentRoom.AutoCleanUp false:

  • Nothing changes. You need to do manual clean up.

On remote clients -if any-:

• Un-parent nested networked scene objects from disconnecting actor's instantiated networked objects (to prevent their destruction).
• Runtime instantiated networked objects created by the disconnected actor will be destroyed.
• Ownership reset (owner becomes null) for the remaining PhotonViews previously owned by the hard-disconnected actor.Those become 'orphan' networked objects.
• Master client becomes controller of these 'orphan' PhotonViews, as master client is always the controller when owner null.

On Rejoin

Player.HasRejoined true

If the client rejoins a room that is not empty:

• regains control of networked objects owned by the same actor.
• [optional] Master client will resend OwnershipUpdate for any networked objects with owner != creator.

If the client rejoins a room that is still on the server but empty (EmptyRoomTTL did not expire yet):

• regains control of networked objects owned by the same actor.
• since it's the master client it also controls all other networked objects.

If the client rejoins a room by 'resurrecting it' (reloading its state from an external source):

• regains control of networked objects owned by the same actor.
• since it's the master client it also controls all other networked objects.

On New Join

Player.HasRejoined false

If the client joins a room that is not empty:

• Nothing special.

If the client joins a room that is still on the server but empty (EmptyRoomTTL did not expire yet):

• regains control of networked objects owned by the same actor.
• since it's the master client it also controls all other networked objects.

Asynchronous join: if the client joins a room by 'resurrecting it' (reloading its state from an external source):

• regains control of networked objects owned by the same actor.
• since it's the master client it also controls all other networked objects.

On Master Client Change

New master becomes controller of:

• 'orphan' networked objects: networked objects with no owner.
• networked objects with inactive owner.

Note: If pervious master soft-disconnected, it retains ownership of any networked room object it has claimed ownership.

Explicit Ownership Transfer

You can explicitly change the owner of networked objects through its respective root PhotonView.By default, networked objects have a fixed ownership but you can change this to allow ownership transfer either directly or via request.Ownership change usually means controller change, unless the new owner is inactive, it will be in control of the networked object.

Photon Quantum Unity

Ownership Transfer Options

Ownership transfer behaviour for PhotonViews is defined via OwnershipOption set in PhotonView.OwnershipTransfer.PhotonView.OwnershipTransfer is not synchronized over the network and should not be changed once the PhotonView is instantiated.There are three types of ownership transfer options: Fixed, Request and Takeover.Let's find out more about each one separately.

Fixed

Ownership is fixed.For room objects, there is no owner but the master client is the controller.For player objects, the creator is always the owner.This is the default value.

Request

Any actor can request ownership of PhotonViews from their current owner (or controller) when the respective OwnershipTransfer option is set to Request.

In this case, this is a two steps process: first the actor sends a request to the owner of the PhotonView, then, if the latter accepts the transfer of ownership is done explicitly by the owner and the requesting actor becomes the new owner.The request is done via: PhotonView.RequestOwnership().

This triggers a IPunOwnershipCallbacks.OnOwnershipRequest(PhotonView targetView, Player requestingPlayer) callback on the current owner, where the developer must call targetView.TransferOwnership(requestingPlayer) to perform the actual ownership change. This allows the developer to determine in code if that request should be accepted.

Only the current owner or the current controller of the networked object are allowed to accept ownership transfer requests.

Takeover

Any actor can change the ownership of any PhotonView that has Takeover as OwnershipTransfer option.

This option is meant to directly claim ownership of PhotonViews without consent of their current owner or even attribute the PhotonView to someone else.To take over ownership in this case simply call PhotonView.TransferOwnership(Player newOwner).Notice that you can also change ownership to a different actor, meaning actor X can change the owner of a PhotonView set to Takeover from actor Y to actor Z.

If you call PhotonView.RequestOwnership() on a PhotonView that has Takeover as OwnershipTransfer option then the request is automatically accepted (unless someone else takes over before) without any need for callback handling.However, in the case of Takeover ownership option it is recommended to directly call PhotonView.TransferOwnership(Player newOwner).

Renouncing Ownership

Unless the PhotonView's ownership is fixed and not meant to be changed, any actor can transfer ownership of his own PhotonViews to any other active actor.This is done using PhotonView.TransferOwnership(Player newOwner).

PhotonView Callbacks

Ownership Change Callback

Whenever the owner of a PhotonView changes, IOnPhotonViewOwnerChange.OnOwnerChange(Player newOwner, Player previousOwner) is fired on classes that implement it and that are registered by the same respective PhotonView.

Classes implementing IOnPhotonViewOwnerChange interface need to be registered using PhotonView.AddCallbackTarget and deregistered using PhotonView.RemoveCallbackTarget.

Explicit Ownership Transfer Callbacks

There are two ownership changes callbacks in the same IPunOwnershipCallbacks interface:

• OnOwnershipRequest(PhotonView targetView, Player requestingPlayer) when someone requests ownership from the targetView.
• OnOwnershipTransfered(PhotonView targetView, Player previousOwner) whenever the owner changes for the targetView.

Classes implementing IPunOwnershipCallbacks interface need to be registered using PhotonNetwork.AddCallbackTarget and deregistered using PhotonNetwork.RemoveCallbackTarget.

Control Change Callback

Whenever the controller of a PhotonView changes, IOnPhotonViewControllerChange.OnControllerChange(Player newController, Player newController) is fired on classes that implement it and that are registered by the same respective PhotonView.

How to test your browser speed. Classes implementing IOnPhotonViewControllerChange interface need to be registered using PhotonView.AddCallbackTarget and deregistered using PhotonView.RemoveCallbackTarget.

Network Destroy Callback

Sometimes you want to be notified of when a networked object is about to be destroyed.There is a callback for this which also fires on all PhotonViews of the same networked object: the main/root PhotonView and all its nested ones -if any-.

Whenever PhotonNetwork.Destroy is called, and just before finishing the network destruction, IOnPhotonViewPreNetDestroy.OnPreNetDestroy(PhotonView rootView) is fired on classes that implement it and that are registered by the same respective PhotonView.

Classes implementing IOnPhotonViewPreNetDestroy interface need to be registered using PhotonView.AddCallbackTarget and deregistered using PhotonView.RemoveCallbackTarget.

To Document Top

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.

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

or

Instead, you should override those and call

and

.

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()

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()

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()

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()

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.

Implements IMatchmakingCallbacks.

◆ OnCustomAuthenticationFailed()

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!

Implements IConnectionCallbacks.

◆ OnCustomAuthenticationResponse()

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/realtime/current/reference/custom-authentication

Implements IConnectionCallbacks.

◆ OnDisconnected()

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()

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

Implements IErrorInfoCallback.

◆ OnFriendListUpdate()

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()

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()

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()

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.

Implements IMatchmakingCallbacks.

Reimplemented in ConnectAndJoinRandom.

◆ OnJoinRoomFailed()

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

Implements IMatchmakingCallbacks.

◆ OnLeftLobby()

Called after leaving a lobby.

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

Implements ILobbyCallbacks.

◆ OnLeftRoom()

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. Dark nights.

◆ OnLobbyStatisticsUpdate()

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()

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()

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.

Photon Pun 2

Implements IInRoomCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnPlayerLeftRoom()

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()

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.

Implements IInRoomCallbacks.

Reimplemented in PlayerNumbering, and PunTeams.

◆ OnRegionListReceived()

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.

Photon Pun

Photon Pun Vs Realtime

Implements IConnectionCallbacks.

◆ OnRoomListUpdate()

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

Photon Pun2

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()

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.

Implements IInRoomCallbacks.

Reimplemented in PunTurnManager, and CountdownTimer.

◆ OnWebRpcResponse()

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.