Regions

Photon Cloud provides you with global connectivity to allow low latency gaming all around the world.

The initial connection of clients goes to a Photon Nameserver, which provides the list of available regions. Typically, clients connect with "Best Region" selection enabled, which will detect the region with the lowest ping and connect to it (see below).

Each region is completely separate from the others and consists of a Master Server (for matchmaking) and Game Servers (hosting rooms).

The full list of available regions is below. In the Dashboard, you can define which regions should be available for the clients.

Best Region Considerations

"Best Region" option is not deterministic. Sometimes it may be "random" due to little variations or exact same ping calculations.

Theoretically, you could:

• have the same exact ping to multiple regions from the same device. So its random, if you end up with different regions on clients connected to the same network.
• different ping values for the same region on different devices (or different retries on the same device) connected to the same network.

For instance, in the case of "us" and "usw" (or "ru" and "rue"), you could either make use of the online regions whitelist to select the ones you want and drop the others or connect to an explicit region.

Available Regions

Photon Cloud has servers in several regions, distributed across multiple hosting centers over the world.

Each Photon Cloud region is identified by a "region token".

To pass the region token with the "Connect" method of your client, call:

    loadBalancingClient.ConnectToRegionMaster(regionString);

List of available regions and tokens:

Dashboard Regions Filtering

You can filter the list of available Photon Cloud regions per application on the fly directly from the dashboard.

Go to the dashboard and then click "Manage" for a chosen application and then click "Edit". You will find an input field where you can enter the list of whitelisted regions as follows:

• the allowed list should be a string of region tokens seprated by semicolon. e.g. "eu;us".
• region tokens are case insensitive and are defined here.
• undefined or unrecognized region tokens will be ignored from the list.
• empty ("") or malformed string (e.g. ";;;") means empty list.
• empty list means all available regions are allowed.

Once you confirm and save, the operation GetRegions will return only the filtered list of regions. Thus clients should select from that list but it's fully possible clients connect to any available region explicitly. Take into consideration that dashboard updates propagation can take up to 10 minutes.

How To Choose A Region

Users in the US have the lowest latency if connected to the Photon Cloud US region. Easy.

But what if you have users from all over the world?

You can

• a) let the game client ping the different Photon Cloud regions and pre-select the one with the best ping, read our how-to
• b) distribute client builds tied to a region, so users from different regions connect to different Photon Cloud regions or
• c) let the user choose a matching region from within your game`s UI.

Alternatively you can d) let all users connect to the same region if the higher latency is acceptable for your gameplay, e.g. with any "not-so-realtime" games.

All Photon Cloud apps are working in all available regions without any extra charge. See pricing.

Photon Cloud's dashboard lets you monitor the usage of your game in each region and easily upgrade or downgrade your subscription plan. Go to your dashboard.

How To Start Your Game With Lowest Latency

Connect to the nearest Master Server

Direct connections to a master server using the generic region master server address are deprecated. Instead use the method to connect to a region master as provided by the SDK you are using!

If you know the closest region for your client to connect to you can connect to it passing only the region.

    loadBalancingClient.ConnectToRegionMaster("us");

For other platforms follow the link to the respective SDK and API from the SDKs list.

The SDK will get the master server address for the requested region for you from the name server (1 in the figure "Connect to Photon Cloud regions") and then automatically connect you to the master server in the chosen region (2 in the figure "Connect to Photon Cloud regions").

How To Select A Region At Runtime

If you want to select the region at runtime - e.g. by showing a list of available regions to your players and let them choose -, you need to connect to the name server first. You can then query the name server for a list of currently available region master server addresses (1 in the figure "Connect to Photon Cloud regions").

While we write of "the name server", the name server is actually geographically load balanced across available regions. That keeps the time to request the master servers' addresses as low as possible.

C# Client SDKs

    loadBalancingClient.ConnectToNameServer()

On successful connection you get the list of available regions.

    loadBalancingClient.OpGetRegions()

With the list of master servers you could now ping all to figure out the best region to connect to for lowest latency gameplay, or let your players choose a region.

When your client has determined the region, connect to the master server for that region (2 in the figure "Connect to Photon Cloud regions").

    loadBalancingClient.ConnectToRegionMaster("us")

Finally, join or create a room for your game (3 in the figure "Client Connect to Photon Cloud").

C++ Client SDKs

1. Make sure that you connect to Photon Cloud. Cloud regions are not supported by Photon Server.

2. The Constructor of class Client has a couple of optional parameters. The last one of them, called regionSelectionMode, takes one of the values from LoadBalancing::RegionSelectionMode and defaults to RegionSelectionMode::DEFAULT. Please explicitly pass RegionSelectionMode::SELECT for that parameter.

3. During the connect flow that is triggered by your call to Client::connect(), the client receives a list of available regions from the name server. Listener declares an optional callback Listener::onAvailableRegions(). If you have passed RegionSelectionMode::SELECT for regionSelectionMode, then Client won't automatically choose an item in that list of available regions, but pass the list to that callback. Therefor in your Listener implementation you should override the empty default implementation of that callback with a meaningful implementation that selects a region based on whatever criteria you can come up with.

4. The connect flow pauses entirely until you have chosen a region.

5. Pass your chosen region to Client::selectRegion() to continue the connect flow.

Note: Client::selectRegion() is only expected to be called after you have received a call to Listener::onAvailableRegions() (call selectRegion() either directly from within this callback or later, after the callback has returned). Otherwise the Client won`t be at the correct stage of the connection-flow for region selection.

An example implementation of Listener::onAvailableRegions() can be found in the source code of demo_loadBalancing inside the Client SDK:

void NetworkLogic::onAvailableRegions(const ExitGames::Common::JVector<ExitGames::Common::JString>& availableRegions, const ExitGames::Common::JVector<ExitGames::Common::JString>& availableRegionServers)
{
    EGLOG(ExitGames::Common::DebugLevel::INFO, L"%ls / %ls", availableRegions.toString().cstr(), availableRegionServers.toString().cstr());
    mpOutputListener->writeLine(L"onAvailableRegions: " + availableRegions.toString() + L" / " + availableRegionServers.toString());
    // select first region from list
    mpOutputListener->writeLine(L"selecting region: " + availableRegions[0]);
    mLoadBalancingClient.selectRegion(availableRegions[0]);
}

Note that selectRegion() is only supposed to be called during the connect-flow after the call to onAvailableRegions() has been received. Calling it at any other time or state or calling it multiple times for a single call to onAvailableRegions() is not supported and produces undefined behavior.

Objective-C Client SDKs

1. Make sure that you connect to Photon Cloud. Cloud regions are not supported by Photon Server.

2. The Constructor of class EGLoadBalancingClient has a couple of optional parameters. The last one of them, called regionSelectionMode, takes one of the values from EGRegionSelectionMode.h and defaults to EGRegionSelectionMode_DEFAULT. Please explicitly pass EGRegionSelectionMode_SELECT for that parameter.

3. During the connect flow that is triggered by your call to EGLoadBalancingClient::connect(), the client receives a list of available regions from the name server. EGLoadBalancingListener declares an optional callback EGLoadBalancingListener::onAvailableRegions(). If you have passed EGRegionSelectionMode_SELECT for regionSelectionMode, then EGLoadBalancingClient won't automatically choose an item in that list of available regions, but pass the list to that callback. Therefor in your EGLoadBalancingListener implementation you should override the empty default implementation of that callback with a meaningful implementation that selects a region based on whatever criteria you can come up with.

4. The connect flow pauses entirely until you have chosen a region.

5. Pass your chosen region to EGLoadBalancingClient::selectRegion() to continue the connect flow.

Note: EGLoadBalancingClient::selectRegion() is only expected to be called after you have received a call to EGLoadBalancingListener::onAvailableRegions() (call selectRegion() either directly from within this callback or later, after the callback has returned). Otherwise the Client won`t be at the correct stage of the connection-flow for region selection.

An example implementation of EGLoadBalancingListener::onAvailableRegions() can be found in the source code of demo_loadBalancing_objc inside the Client SDK:

- (void) onAvailableRegions:(EGArray*)availableRegions :(EGArray*)availableRegionServers
{
    NSString* r = [availableRegions componentsJoinedByString:@", "];
    NSString* s = [availableRegionServers componentsJoinedByString:@", "];
    EGLOG(EGDbgLvl::INFO, L"onAvailableRegions: %ls / %ls", [r UTF32String], [s UTF32String]);
    [mOutputListener writeLine:@"onAvailableRegions: %@ / %@", r, s];
    // select first region from list
    [mOutputListener writeLine:@"selecting region: %@", availableRegions[0]];
    [mLoadBalancingClient selectRegion:availableRegions[0]];
}

Note that selectRegion() is only supposed to be called during the connect-flow after the call to onAvailableRegions() has been received. Calling it at any other time or state or calling it multiple times for a single call to onAvailableRegions() is not supported and produces undefined behavior.

Using The Chinese Mainland Region

The Photon NameServer has to be local to China, as the firewall might block the traffic otherwise. The Chinese Photon NameSever is "ns.photonengine.cn".

Connecting with clients from outside of China mainland will most likely not produce good results. Also, connecting from the Photon servers to servers outside of China mainland (e.g. for Custom Authentication, WebHooks, WebRPCs) might not be reliable.

Also for legal reasons, you need a separate build for China and we recommend to use a separate AppId with it. For example, use a compile condition (of your choice) to change the AppId and the Photon NameServer depending on the build.

Follow the instructions corresponding to your client SDK to make a special build for the Chinese market.

C# Client SDKs

1. Set the AppId to the application that has China region unlocked. If you want to use same project and have different builds you can do something like this:

       // TODO: replace compile condition with your own
   #if CHINA
       loadBalancingClient.AppID = "ChinaRealtimeAppId"; // TODO: replace with your own AppId
   #else
       loadBalancingClient.AppID = "nonChinaRealtimeAppId"; // TODO: replace with your own AppId
   #endif

2. Open "LoadBalancingClient.cs" file and set the NameServerHost to "ns.photonengine.cn":
3. Use LoadBalancingClient.ConnectToRegionMaster("CN") to connect to Chinese Mainland region.

C++ Client SDKs

• Pass "ns.photonengine.cn" for parameter serverAdress to Client::connect().
• Make sure to keep parameter serverType on its default value of ServerType::NAME_SERVER.

Objective-C Client SDKs

• Pass "ns.photonengine.cn" for parameter serverAdress to EGLoadBalancingClient::connect()
• Make sure to keep parameter serverType on its default value of EGServerType_NAME_SERVER.

 To Document Top