Provides methods to work with Photon's regions (Photon Cloud) and can be use to find the one with best ping. More...

Public Member Functions
	RegionHandler (ushort masterServerUdpPort=0)
	Creates a new RegionHandler. More...

void	Abort ()
	Calling this will stop pinging the regions and suppress the onComplete callback. More...

string	GetResults ()
	Provides a list of regions and their pings as string. More...

bool	PingAvailableRegions (Action< RegionHandler > onCompleteCallback)
	Starts the process of pinging the available regions. More...

bool	PingMinimumOfRegions (Action< RegionHandler > onCompleteCallback, string previousSummary)
	Starts the process of pinging a subset of the available regions. More...

void	SetRegions (OperationResponse opGetRegions, RealtimeClient client=null)
	Initializes the regions of this RegionHandler with values provided from the Name Server (as OperationResponse for OpGetRegions). More...

Public Attributes
int	BestRegionSummaryPingLimit = 90
	If the region from a previous BestRegionSummary now has a ping higher than this limit, all regions get pinged again to find a better. Default: 90ms. More...

Static Public Attributes
static Type	PingImplementation
	The implementation of PhotonPing to use for region pinging (Best Region detection). More...

Properties
bool	Aborted `[get]`
	True if the pinging of regions is being aborted. More...

string	AvailableRegionCodes `[get]`
	Comma separated string of regions available to this client. More...

Region	BestRegion `[get]`
	When PingMinimumOfRegions was called and completed, the BestRegion is identified by best ping. More...

List< Region >	EnabledRegions `[get]`
	A list of region names for the Photon Cloud. Set by the result of OpGetRegions(). More...

bool	IsPinging `[get]`
	True if the available regions are being pinged currently. More...

string	SummaryToCache `[get]`
	This value summarizes the results of pinging currently available regions (after PingMinimumOfRegions finished). More...

Detailed Description

Provides methods to work with Photon's regions (Photon Cloud) and can be use to find the one with best ping.

When a client uses a Name Server to fetch the list of available regions, the RealtimeClient will create a RegionHandler and provide it via the OnRegionListReceived callback, as soon as the list is available. No pings were sent for Best Region selection yet.

Your logic can decide to either connect to one of those regional servers, or it may use PingMinimumOfRegions to test which region provides the best ping. Alternatively the client may be set to connect to the Best Region (lowest ping), one or more regions get pinged. Not all regions will be pinged. As soon as the results are final, the client will connect to the best region, so you can check the ping results when connected to the Master Server.

Regions gets pinged 5 times (RegionPinger.Attempts). Out of those, the worst rtt is discarded and the best will be counted two times for a weighted average.

Usually UDP will be used to ping the Master Servers. In WebGL, WSS is used instead.

It makes sense to make clients "sticky" to a region when one gets selected. This can be achieved by storing the SummaryToCache value, once pinging was done. When the client connects again, the previous SummaryToCache helps limiting the number of regions to ping. In best case, only the previously selected region gets re-pinged and if the current ping is not much worse, this one region is used again.

Constructor & Destructor Documentation

◆ RegionHandler()

Photon.Realtime.RegionHandler.RegionHandler ( ushort masterServerUdpPort = 0 )

inline

Creates a new RegionHandler.

Parameters

masterServerUdpPort If non-zero, this port will be used to ping Master Servers on.

Member Function Documentation

◆ GetResults()

string Photon.Realtime.RegionHandler.GetResults ( )

inline

Provides a list of regions and their pings as string.

◆ SetRegions()

void Photon.Realtime.RegionHandler.SetRegions	(	OperationResponse	opGetRegions,
		RealtimeClient	client = `null`
	)

inline

Initializes the regions of this RegionHandler with values provided from the Name Server (as OperationResponse for OpGetRegions).

◆ PingAvailableRegions()

bool Photon.Realtime.RegionHandler.PingAvailableRegions ( Action< RegionHandler > onCompleteCallback )

inline

Starts the process of pinging the available regions.

Uses PingMinimumOfRegions without a summary.

Parameters

onCompleteCallback Provide a method to call when all ping results are available. Aborting the pings will also cancel the callback.

Returns: If pining the regions gets started now. False if the current state prevent this.

◆ PingMinimumOfRegions()

bool Photon.Realtime.RegionHandler.PingMinimumOfRegions	(	Action< RegionHandler >	onCompleteCallback,
		string	previousSummary
	)

inline

Starts the process of pinging a subset of the available regions.

Parameters

onCompleteCallback	Provide a method to call when all ping results are available. Aborting the pings will also cancel the callback.
previousSummary	A BestRegionSummary from an earlier RegionHandler run. This makes a selected best region "sticky" and keeps ping times lower.

Returns: If pining the regions gets started now. False if the current state prevent this.

◆ Abort()

void Photon.Realtime.RegionHandler.Abort ( )

inline

Calling this will stop pinging the regions and suppress the onComplete callback.

IsPinging becomes false immediately, so a new ping run (or a new RegionHandler) can start right away, even if the aborted pinger threads are still winding down.

Member Data Documentation

◆ PingImplementation

Type Photon.Realtime.RegionHandler.PingImplementation

static

The implementation of PhotonPing to use for region pinging (Best Region detection).

Defaults to null, which means the Type is set automatically.

◆ BestRegionSummaryPingLimit

int Photon.Realtime.RegionHandler.BestRegionSummaryPingLimit = 90

If the region from a previous BestRegionSummary now has a ping higher than this limit, all regions get pinged again to find a better. Default: 90ms.

Pinging all regions takes time, which is why a BestRegionSummary gets stored. If that is available, the Best Region becomes sticky and is used again. This limit introduces an exception: Should the pre-defined best region have a ping worse than this, all regions are considered.

Property Documentation

◆ EnabledRegions

List<Region> Photon.Realtime.RegionHandler.EnabledRegions

get

A list of region names for the Photon Cloud. Set by the result of OpGetRegions().

Implement IConnectionCallbacks and register for the callbacks to get OnRegionListReceived callbacks. You can also put a "case OperationCode.GetRegions:" into your OnOperationResponse method to notice when the result is available.

◆ AvailableRegionCodes

string Photon.Realtime.RegionHandler.AvailableRegionCodes

get

Comma separated string of regions available to this client.

◆ BestRegion

Region Photon.Realtime.RegionHandler.BestRegion

get

When PingMinimumOfRegions was called and completed, the BestRegion is identified by best ping.

◆ SummaryToCache

string Photon.Realtime.RegionHandler.SummaryToCache

get

This value summarizes the results of pinging currently available regions (after PingMinimumOfRegions finished).

This value should be stored in the client by the game logic. When connecting again, use it as previous summary to speed up pinging regions and to make the best region sticky for the client.

◆ IsPinging

bool Photon.Realtime.RegionHandler.IsPinging

get

True if the available regions are being pinged currently.

◆ Aborted

bool Photon.Realtime.RegionHandler.Aborted

get

True if the pinging of regions is being aborted.

Abort

Quantum 3 3.1.0

Public Member Functions

Public Attributes

Static Public Attributes

Properties

Detailed Description

Constructor & Destructor Documentation

◆ RegionHandler()

Member Function Documentation

◆ GetResults()

◆ SetRegions()

◆ PingAvailableRegions()

◆ PingMinimumOfRegions()

◆ Abort()

Member Data Documentation

◆ PingImplementation

◆ BestRegionSummaryPingLimit

Property Documentation

◆ EnabledRegions

◆ AvailableRegionCodes

◆ BestRegion

◆ SummaryToCache

◆ IsPinging

◆ Aborted