This document is about: SERVER 4
SWITCH TO

Clusters Sharding

This page is relevant only for Photon Enterprise Cloud customers.

Photon Cluster Definition

A Photon cluster is a combination of a Master Server and N- Game Servers registered to it. A single cluster can support up to 50K CCUs at the same time. Anything beyond that needs more sharding and new cluster(s). The Photon NameServer will automatically loadbalance players across clusters.

Working With Clusters

The response for "GetRegion" operation called on the name server will return the list of all available clusters across all regions. The result returned is an array of strings with special format: "{region}/{cluster}". Each entry has a region and cluster part separated by "/".

Example:

With two master servers running in region "EU" both will be returned as:

  • "EU/Default"
  • "EU/Cluster2"

When calling "Authenticate" operation, you have three options to select a cluster via request parameter "Region" (byte code 210):

The Default Cluster

If you specify the region only, you will always be routed to the default "first" cluster. This is the default behavior in current client SDKs. The other two options are not supported out of the box.

If you specify a string in a wrong format or a region/cluster combination that does not exist authentication will fail with error code "InvalidRegion" (byte code 32756).

Example:

  • "EU" -> will always route you to "EU/Default".

A Specific Cluster

You can pass both the region and the cluster explicitly and follow the same format seen above: "{region}/{cluster}". In this case, you will be connected to that specific cluster of that specific region of your choice.

If you specify a string in a wrong format or a region/cluster combination that does not exist authentication will fail with error code "InvalidRegion" (byte code 32756).

Examples:

  • "EU/Default" -> routes to "EU/Default".
  • "EU/Cluster2" -> routes to "EU/Cluster2".

A Random Cluster

This is like option 2 but instead of explicitly choosing a cluster you want the server to randomly pick one for you. In order to do this, you can set a wildcard or asterisk ('*') as a cluster.

If you specify a string in a wrong format or a region/cluster combination that does not exist authentication will fail with error code "InvalidRegion" (byte code 32756).

The "Authenticate" operation response contains a returned parameter value called "Cluster" (byte code is 196). This value will indicate to which cluster you have been routed to. For instance, you could use this information to tell other clients (e.g. friends) where to find you and join you for a match.

Example:

  • "EU/*" -> randomly routes to "EU/Default" or "EU/Cluster2".

Considerations

Since clusters are physically and logically separate entities you need to take into consideration the following points:

  • Application and lobby statistics are calculated by the Master Server per cluster.
  • By default a Photon region has a single cluster. But if you have too many CCUs cluster sharding becomes a must. To get an overall idea about a single region that has multiple clusters, you need to aggregate and calculate region statistics based on all clusters on that region.
  • Only players connected to the same cluster can interact. If you want friends to be able to play with eachother on the same region you have to send the cluster info around and you may have to switch from one cluster to another.
Back to top