Requirements:
You should already have a dedicated room server built and dockerized
Your server should be functional using brainCloud's built-in hosting
Note that this is not an exhaustive Edgegap tutorial. For more information - check out
Updated for brainCloud 6.1: starting with brainCloud 6.1, room servers are launched as Edgegap deployments. Edgegap has retired its session system, so there is no session type or socket count to configure any more - earlier versions of this guide asked you to choose a Seat session type and a number of session sockets, and those steps no longer apply.
Existing Edgegap customers on a brainCloud server older than 6.1: to ship a new build of your room server, update the container image behind your existing Edgegap application version. Do not create a new application version until your app is running on brainCloud 6.1 - older brainCloud servers launch through Edgegap's session API, which cannot launch a version created through Edgegap's current portal, so every launch of a new version fails.
1 - Set up an Application in the Edgegap Portal
First, you must set up your server on the Edgegap portal - which is called an application within Edgegap.
To do so, simply:
Login to Edgegap
Go to the Applications section
Click Create Application
Fill out the page of details regarding your app, the container image, etc.
Then choose Create Version
Then fill in the Port options according to how you have built your server
No session settings are needed - brainCloud creates one Edgegap deployment per lobby launch.
2 - Set up a Token to use to access Edgegap from brainCloud
Login to Edgegap (if you aren't already logged in)
Choose your team in the bottom-left corner - and then click Tokens
Create a new token for brainCloud - and keep it handy - or just be ready to go back to the page to retrieve it.
3 - Set up the Edgegap server type in brainCloud
Login to the brainCloud Portal
Choose your app - and then navigate to App > Design > Servers > My Servers
Click [+ Add New Server]
Enter a name
Choose Edgegap Server for Server Type
Then fill in the Edgegap-specific information
Edgegap App Name - as entered in the Edgegap portal (required)
Edgegap Version Name - the version to be launched (required for a new server). If an existing server config has no version name, brainCloud launches the version most recently created in Edgegap, which changes whenever you add a version - so we recommend always setting it explicitly.
Edgegap API Key - this is the token retrieved in step 2 (required). Note that brainCloud doesn't require the "token " prefix at the beginning of the token. The web UI will automatically strip it off for you.
Beacons - choose the regions to ping when doing geo matchmaking. If exactly one region is selected, servers are always placed in that region; otherwise Edgegap places each server based on the lobby members' IP addresses.
Click [Save & Close]
4 - Connect the Edgegap server to the appropriate Lobby types
Login to the brainCloud Portal
Navigate to App > Design > Multiplayer > Lobbies
Choose a lobby that you would like to launch servers on Edgegap, and edit it to launch the new Edgegap Server type you just created.
5 - Modify your server to terminate the Edgegap deployment
Important note: When your server shuts down, its Edgegap deployment has to be terminated. This is not done automatically, so your server must do it when it wants to shut down, in one of two ways:
Call the SysRoomSessionEnded S2S operation with the SERVER_ID and SERVER_CONTEXT values your server was launched with (see the environment variables below). brainCloud then stops the Edgegap deployment for you.
Or delete the deployment yourself, by sending a DELETE web request to the Edgegap API as documented here.
For the second option: when Edgegap servers deploy, there are environment variables that are injected which provide the URL to call as well as the authorization token to provide with it to delete the deployment.
The environment variable for the deployment delete url is named ARBITRIUM_DELETE_URL and the environment variable for the authorization token is named ARBITRIUM_DELETE_TOKEN.
This is example C++ code for Unreal implementation of this call:
FString deploymentDeleteUrl = getenv("ARBITRIUM_DELETE_URL");
FString authToken = getenv("ARBITRIUM_DELETE_TOKEN");
if (!deploymentDeleteUrl.IsEmpty()) {
UE_LOG(DedicatedServerLog, Log, TEXT("EdgeGap server shutting down sending request to delete url: %s"), *deploymentDeleteUrl);
TSharedRef<IHttpRequest> HttpRequest = FHttpModule::Get().CreateRequest();
HttpRequest->SetURL(deploymentDeleteUrl);
HttpRequest->SetVerb("DELETE");
HttpRequest->SetHeader("authorization", *authToken);
// HttpRequest->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
HttpRequest->OnProcessRequestComplete().BindUObject(this, &ADedicatedDemoGameMode::OnDeploymentDeleteResponse);
// Send the request
HttpRequest->ProcessRequest();
}
---
Your app should now be ready to use the new Lobby type and server.
When your lobby starts, brainCloud will send the connection details (IP:PORT) to your application once the Edgegap deployment is ready, then your application would connect to it. If Edgegap reports that the deployment failed (for example, because the container image could not be pulled), the lobby launch fails right away with reason code 40738 (EDGEGAP_ERROR) and Edgegap's status in the message, instead of waiting for the launch to time out.
From there - your Edgegap-based room server can send information to brainCloud just like any other Room Server -- that is, via the S2S API.
Your server will be launched with the following ENVs which can be used to establish the S2S connection.
SERVER_HOST <-- "api.braincloudservers.com"
SERVER_PORT <-- 443
APP_ID <-- "55555"
SERVER_NAME <-- "arena2v2"
SERVER_SECRET <-- "aaaa-bbbb-cccc-ddd-eee"
LOBBY_ID <-- "55555:arena2v2:123"
SERVER_ID <-- unique id of this server instance
SERVER_CONTEXT <-- server context to pass to SysRoomSessionEnded
PRE_READY_LAUNCH <-- "true" if the server was launched before the lobby was ready
Any custom environment variables defined on the server config in brainCloud are passed in as well.
Handy references for S2S:
Our S2S API docs - https://docs.braincloudservers.com/api/s2s/
Our S2S libraries - https://github.com/orgs/getbraincloud/repositories?q=s2s
Impersonating a user (via S2S or otherwise) - https://help.getbraincloud.com/en/articles/3631086-how-do-impersonate-a-user-using-the-braincloud-api
Reach out to brainCloud support if you have further questions!