Regions
The Photon Cloud provides low latency gaming globally by hosting servers in various regions.
Clients get the list of regions from our Photon Name Servers. Over the lifetime of a project, new regions may be added or old ones may be deprecated and removed.
Each region is completely separate from the others and consists of a Master Server (for matchmaking) and Game Servers (hosting rooms).
The list of available regions differs per product (Fusion, Quantum, Chat etc.).
With the Region Allowlist, you can define which regions should be available per AppId (see below).
Below is the list of regions for this product.
Available Regions
The Photon Cloud consists of servers in several regions, distributed across multiple hosting centers over the world.
Some regional servers only support specific products and client SDKs. This means for example that Fusion clients can use the region Japan but Chat can not.
Each Photon Cloud region is identified by a "region token", which is a case insensitive, short string.
For example, "EU" or "eu" are both accepted and refer to the same Europe region.
Region | Hosted in | Token |
---|---|---|
Asia | Singapore | asia |
Australia | Sydney | au |
Canada, East | Montreal | cae |
Chinese Mainland (See Instructions) | Shanghai | cn |
Europe | Amsterdam | eu |
Hong Kong | Hong Kong | hk |
India | Chennai | in |
Japan | Tokyo | jp |
South Africa | Johannesburg | za |
South America | Sao Paulo | sa |
South Korea | Seoul | kr |
Turkey | Istanbul | tr |
United Arab Emirates | Dubai | uae |
USA, East | Washington D.C. | us |
USA, West | San José | usw |
USA, South Central | Dallas | ussc |
Region Allowlist
The Region Allowlist enables you to customize the available regions per application directly from the dashboard. Clients using the Best Region feature, will adapt automatically.
By using using more or less regions, you balance the quality of service (roundtrip times are better, when there is a region close to players) versus the matchmaking experience (less regions mean more players per region).
To define the regions per app, open the dashboard, click "Manage" for a chosen application and then click "Edit Allowlist".
You will find an input field to enter the list of allowed regions as follows:
- the available regions are listed above per SDK and sometimes separately for the Industries Circle.
- the allowlist must be a string of region tokens separated by semicolons. e.g. "eu;us".
- region tokens are case insensitive.
- undefined or unrecognized region tokens will be ignored from the list.
- empty ("") or malformed string (e.g. ";;;") means all available regions are allowed.
Within 10 minutes of a change (confirm and save), the Name Servers will send the filtered list to connecting clients.
To avoid conflicts on the client side, connect to the "Best Region" by ping or make sure to pick a region received with the regions list.
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?
Options are..
- 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.
- d) let all users connect to the same region if the higher latency is acceptable for your gameplay.
All Photon Cloud apps are working in all available regions without any extra charge.
Photon Cloud's dashboard lets you monitor the usage of your game in each region and easily upgrade or downgrade your subscription plan.
C# Realtime API
Photon Realtime (used by most Photon SDKs) can detect the Best Region to connect to and enables you to stick to that region.
To do so, clients always fetch the list of available regions from the Name Server on connect.
The servers response is used to setup the LoadBalancingClient.RegionHandler
which is also provided via the callback OnRegionListReceived(RegionHandler regionHandler)
, as defined in the IConnectionCallbacks
.
Typically, the next step is to call regionHandler.PingMinimumOfRegions()
to detect the current ping to each region. You need to pass a method to call on completion and in best case you can also pass the "best region summary" from a previous run (explained below).
After pinging the servers, the (new) results are summarized in the regionHandler.SummaryToCache
which should be saved on the device for later use.
Without the SummaryToCache
from a previous session, all regions will be pinged, which takes a moment longer.
If a previous result is available, the client will check:
a. if the region list changed (covers the case if the "previous best region" is still available)
b. if the ping is no longer acceptable (>= 1.5x slower than previously saved reference value)
If either applies, all regions are pinged and a new result gets picked.
Using Best Region works well with the server-side Region Filter in the Dashboard.
It enables you to change the list of regions available to players on demand.
To access the list of regions or to override previous results, refer to the API Reference for regions.
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 it is 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 allowlist to select the ones you want and drop the others or connect to an explicit region.
To debug, set the logging level to "Info" and clear the "current best region" (in PUN: PhotonNetwork.BestRegionSummaryInPreferences = null). Have a look at the details or send us the log via mail.
Connect to a specific Master Server
To connect your clients to a specific region, set the AppSettings.FixedRegion
to a valid Region token and call ConnectUsingSettings(settings)
.
The SDK will get the master server address for the requested region from the Name Server (1 in the figure "Connect to Photon Cloud regions") and automatically connect you to the master server in the chosen region (2 in the figure "Connect to Photon Cloud regions").
With a FixedRegion, the client will not fetch the region list and skip pinging regions for a Best Region result. This speeds up the connection time.
If you compile a FixedRegion into your build, it can not be changed without an update. In best case, use Best Region and the Region Allowlist instead.
How To Show A Region List
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.
This will automatically fetch a list of currently available region master server addresses (1 in the figure "Connect to Photon Cloud regions").
While we write about "the name server", the name server is geographically load-balanced across available regions. That keeps the time to request the master servers' addresses as low as possible.
C# Client SDKs
C#
loadBalancingClient.ConnectToNameServer()
After a successful connection, LoadBalancingClient.OpGetRegions()
gets called internally. The result of this sets up the loadBalancingClient.RegionHandler
and calls OnRegionListReceived
if your code implements it and registered for callbacks.
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. This can be done with RegionHandler.PingMinimumOfRegions()
.
When your client has determined a region, connect to the master server for that region (2 in the figure "Connect to Photon Cloud regions").
C#
loadBalancingClient.ConnectToRegionMaster("us")
Finally, join or create a room for your game (3 in the figure "Client Connect to Photon Cloud").
C++ Client SDKs
The Constructor of class
Client
has a couple of optional parameters.
The last one of them, calledregionSelectionMode
, takes one of the values fromLoadBalancing::RegionSelectionMode
and defaults toRegionSelectionMode::DEFAULT
.
Explicitly passRegionSelectionMode::SELECT
for that parameter.During the connection 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 callbackListener::onAvailableRegions()
.
If you have passedRegionSelectionMode::SELECT
forregionSelectionMode
, thenClient
won't automatically choose an item in that list of available regions, but pass the list to that callback.
Therefor in yourListener
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.The connection flow pauses entirely until you have chosen a region.
Pass your chosen region to
Client::selectRegion()
to continue the connection 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:
C++
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
The Constructor of class
EGLoadBalancingClient
has a couple of optional parameters.
The last one of them, calledregionSelectionMode
, takes one of the values fromEGRegionSelectionMode.h
and defaults toEGRegionSelectionMode_DEFAULT
.
Explicitly passEGRegionSelectionMode_SELECT
for that parameter.During the connection 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 callbackEGLoadBalancingListener::onAvailableRegions()
.
If you have passedEGRegionSelectionMode_SELECT
forregionSelectionMode
, thenEGLoadBalancingClient
won't automatically choose an item in that list of available regions, but pass the list to that callback.
Therefor in yourEGLoadBalancingListener
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.The connect flow pauses entirely until you have chosen a region.
Pass your chosen region to
EGLoadBalancingClient::selectRegion()
to continue the connection 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:
Objective-C
- (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.
{% endif %}
Using The Chinese Mainland Region
The Photon Name Server has to be local to China, as the firewall might block the traffic otherwise.
The Chinese Photon Name Server 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 using a separate AppId with it.
For example, use a compile condition (of your choice) to change the AppId and the Photon Name Server depending on the build.
Follow the instructions corresponding to your client SDK to make a special build for the Chinese market.
C# Client SDKs
C#
void ConnectToChina()
{
AppSettings chinaSettings = new AppSettings();
chinaSettings.UseNameServer = true;
chinaSettings.ServerAddress = "ns.photonengine.cn";
chinaSettings.AppIdRealtime = "ChinaRealtimeAppId"; // TODO: replace with your own Realtime AppId unlocked for China region
chinaSettings.AppVersion = "ChinaAppVersion"; // optional
loadBalancingClient.ConnectUsingSettings(chinaSettings);
}
C++ Client SDKs
- Pass "ns.photonengine.cn" for parameter
serverAdress
toClient::connect()
. - Make sure to keep parameter
serverType
on its default value ofServerType::NAME_SERVER
.
Objective-C Client SDKs
- Pass "ns.photonengine.cn" for parameter
serverAdress
toEGLoadBalancingClient::connect()
- Make sure to keep parameter
serverType
on its default value ofEGServerType_NAME_SERVER
.