Migration v4 to v5

Overview

Realtime 5 renames the client class and its namespaces, and it moves the operations from the peer into the client. The concepts do not change: connecting, matchmaking, rooms, players and events work as before.

Most of the migration is a mechanical rename pass, followed by a smaller number of real API changes in connecting, logging and a few removed features. Doing the renaming first gets the project close to compiling again and makes the remaining work easy to spot. The using aliases below let you postpone part of the renaming.

Namespaces and Types

The assembly definitions (Unity only) now match the namespaces they contain:

v4	v5
PhotonRealtime	Photon.Realtime
PhotonChat	Photon.Chat

All namespaces starting with ExitGames are obsolete. Their content is now in Photon.Client (peer, transport, serialization) and Photon.Realtime (client, matchmaking, callbacks).

v4	v5
LoadBalancingClient	RealtimeClient
ExitGames.Client.Photon.Hashtable	Photon.Client.PhotonHashtable

PhotonHashtable is the only hashtable type the client can send now.

Replace these using statements where your project has them:

v4	v5
using ExitGames.Client.Photon;	using Photon.Client;
using SupportClassPun = ExitGames.Client.Photon.SupportClass;	using SupportClassPun = Photon.Client.SupportClass;

To split up the work, add these aliases to files you have not renamed yet. They make the v4 names compile against the v5 API and can be removed once the rename is done:

C#

using LoadBalancingClient = Photon.Realtime.RealtimeClient;
using RaiseEventOptions = Photon.Realtime.RaiseEventArgs;
using DebugLevel = Photon.Client.LogLevel;
using Hashtable = Photon.Client.PhotonHashtable;

Connecting

ConnectUsingSettings() is the only connect method in v5. ConnectToRegionMaster(), ConnectToMasterServer() and ConnectToNameServer() are removed.

Everything that was configured on the client before connecting now belongs to the AppSettings passed into ConnectUsingSettings():

v4	v5
LoadBalancingClient.AppId	AppSettings.AppId
LoadBalancingClient.AppVersion	AppSettings.AppVersion
LoadBalancingClient.CloudRegion	RealtimeClient.CurrentRegion
LoadBalancingClient.ServerPortOverrides	RealtimeClient.ProtocolPorts
RealtimeClient.EnableLobbyStatistics	AppSettings.EnableLobbyStatistics

CloudRegion and AppVersion are obsolete and still compile with a warning. The client's AppId setter throws a NotImplementedException. EnableLobbyStatistics can be read back from RealtimeClient.AppSettings.EnableLobbyStatistics.

AppSettings has a separate AppId field per product: AppIdRealtime, AppIdFusion and AppIdQuantum. When only one of them is set, ConnectUsingSettings() uses that one. The Chat API uses AppIdChat and Voice uses AppIdVoice.

The default AuthMode is AuthOnceWss: the client authenticates on the Name Server over WSS and then uses AppSettings.Protocol for the Master Server and Game Server. Set a different AppSettings.AuthMode before connecting if WSS causes issues in your setup.

ProtocolPorts replaces ServerPortOverrides and is a different type. Ports are defined per protocol and per server type, so changing the protocol without changing the ports no longer leaves the client with a mismatched combination. By default, the UDP overrides use the ports 27000-27002 and take precedence over the ports assigned by the server.

Operations and Arguments

The LoadBalancingPeer class is removed and its members are split in two:

• Methods starting with Op are part of RealtimeClient now.
• All other methods remain on the peer, which is RealtimeClient.RealtimePeer and replaces LoadBalancingClient.LoadBalancingPeer as the client's PhotonPeer instance.

SendOutgoingCommands() and DispatchIncomingCommands() can be called on the client directly. RealtimeClient.Service() calls both.

The argument types were renamed for consistency:

v4	v5
RaiseEventOptions	RaiseEventArgs
EnterRoomParams	EnterRoomArgs
OpJoinRandomRoomParams	JoinRandomRoomArgs

RaiseEventArgs is a struct, not a class, so it is copied by value and cannot be null.

JoinRandomRoomArgs.Lobby replaces the TypedLobby field and matches the naming of EnterRoomArgs.Lobby.

EnterRoomArgs.PlayerProperties is removed. Set the values as custom properties on RealtimeClient.LocalPlayer instead, from where the client picks them up when entering a room.

RealtimeClient.ChangeLocalID(int newId) lost its second parameter bool applyUserId, which was only used by the offline mode in PUN 2.

Callbacks and ConnectionHandler

The callback target containers, such as RealtimeClient.ConnectionCallbackTargets, are internal now. Register and unregister with AddCallbackTarget() and RemoveCallbackTarget(), which are unchanged.

The client no longer needs a ConnectionHandler created by your code. RealtimeClient.Handler is created and started automatically and gives you access to KeepAliveInBackground and similar values per client.

Logging changed considerably:

• SupportLogger is removed. The RealtimeClient logs this information itself, based on the level it is given.
• DebugLevel is renamed to LogLevel and the enum members use Pascal case, so DebugLevel.INFO becomes LogLevel.Info.
• Log output can use a per-client prefix and an optional timestamp.

See Logging for the available levels.

Removed Features

Inheriting from RealtimeClient and Player

Extending RealtimeClient (formerly LoadBalancingClient) is not recommended anymore. The few virtual methods it had are no longer virtual.

CreatePlayer still exists but is not virtual either. Reference the Player class instead of extending it.

SupportClass Helpers

SupportClass.StartBackgroundCalls(), StopBackgroundCalls() and StopAllBackgroundCalls() are removed. Use a Task, a Timer or Unity's InvokeRepeating instead.

SupportClass.DictionaryToString() is replaced by the ToStringFull() extension method, which is available for PhotonHashtable and other types.

Traffic Statistics

Most statistics moved to PhotonPeer.Stats, including the values that were on PeerBase before, such as BytesIn, BytesOut and timestampOfLastReceive. PhotonPeer.TrafficStatsEnabled and PhotonPeer.TrafficStatsReset() are removed.

Instead of resetting the counters, work with snapshots. TrafficStats.ToSnapshot() returns a TrafficStatsSnapshot that contains a timestamp. Comparing it to another snapshot or to the current TrafficStats gives you a TrafficStatsDelta.

Web Calls

WebRPC is removed. Call your backend directly from the client instead of routing the call through Photon.

WebFlags is removed and has no replacement, as this is configured per app on the server side.

Checklist

1. Update the assembly names: PhotonRealtime to Photon.Realtime, PhotonChat to Photon.Chat.
2. Replace the ExitGames namespaces with Photon.Client and Photon.Realtime.
3. Rename LoadBalancingClient to RealtimeClient, Hashtable to PhotonHashtable and the *Params argument types to *Args.
4. Move Op calls from the peer to the client and use RealtimeClient.RealtimePeer for the remaining peer calls.
5. Replace all connect calls with ConnectUsingSettings() and move AppId, version, region, protocol and lobby statistics into AppSettings.
6. Replace ServerPortOverrides with ProtocolPorts.
7. Remove subclasses of RealtimeClient and Player.
8. Replace the SupportClass background calls with a Task, Timer or InvokeRepeating, and DictionaryToString() with ToStringFull().
9. Delete your ConnectionHandler setup and use RealtimeClient.Handler.
10. Update logging: DebugLevel to LogLevel, and remove SupportLogger.
11. Read traffic statistics from PhotonPeer.Stats and use snapshots instead of resets.
12. Replace WebRPC with direct backend calls and remove WebFlags.

Back to top