Skip to main content

Photon Bolt on Arbitrium

This guide is here to help create a headless server on Edgegap for a Unity project using Photon Bolt as its networking solution.

In this guide, we will be using a custom demonstration project as an example.

Preparing the Unity project#

Clone the Unity project#

The first step is to clone the Edgegap demo game project from git.
You can do so using this command in your command prompt:

git clone https://github.com/edgegap/photon-bolt-demo-game.git

This will create a folder containing the source Unity project, called demo-game.

Once the process is over, you can open Unity Hub and add the project by pressing the Add button in the Projects tab then finding the project's folder on your computer: img

To open the project, you will need to have the correct version of Unity installed. In our case, we will use Unity 2020.3.3. You can find it by visiting Unity's download archive: https://unity3d.com/get-unity/download/archive

img

After it is installed succesfully, you can now select the new Unity version in the proper drop-down menu of the project in Unity Hub: img

You can now open the Unity project to proceed to the next steps.

Setting up the game#

Setting up Photon Bolt#

Add Photon App ID and compile Bolt.#

For the game to communicate with Photon's services, you will need to add an App to your Photon dashboard. If you do not have an account with Photon just yet, you can easily create one on their website: https://id.photonengine.com/Account/

Once signed in, you will be able to create an app and give it a name. Every app is given it's unique App ID. You will need to copy and paste this ID in the Bolt Settings window within the Unity project:

img

img

Once the is ID entered, you can now close the Bolt Settings window. In the same Bolt menu as before, you will now have to execute two actions: Update Prefab Database then Compile Assembly respectively.

img

At this point, you should able to launch the game's StartScene scene without any error or warning being brought up in the debug console. However, you will not be able to start playing on a server just yet.

This is for the generic changes needed so your Photon Bolt works.
These changes will work both for the clients and servers of your game.

Preparing a headless server#

For your app to work with containers efficiently, you will need to make a few changes to your game to create a "headless server" build. For most projects, this will only require a few straightforward steps.

Requirements for the Unity project#

First, it is essential to note that Photon Bolt's headless server mode requires loading a scene holding a script called HeadlessServerManager.

The generic, unaltered script in question (taken from Bolt's documentation) looks like this:

using System;
using Bolt.Matchmaking;
using Bolt.Photon;
using UnityEngine;
using UnityEngine.SceneManagement;
namespace Bolt.Samples.HeadlessServer
{
public class HeadlessServerManager : Bolt.GlobalEventListener
{
public string Map = "";
public string GameType = "";
public string RoomID = "";
public override void BoltStartBegin()
{
// Register any Protocol Token that are you using
BoltNetwork.RegisterTokenClass<PhotonRoomProperties>();
}
public override void BoltStartDone()
{
if (BoltNetwork.IsServer)
{
// Create some room custom properties
PhotonRoomProperties roomProperties = new PhotonRoomProperties();
roomProperties.AddRoomProperty("t", GameType); // ex: game type
roomProperties.AddRoomProperty("m", Map); // ex: map id
roomProperties.IsOpen = true;
roomProperties.IsVisible = true;
// If RoomID was not set, create a random one
if (RoomID.Length == 0)
{
RoomID = Guid.NewGuid().ToString();
}
// Create the Photon Room
BoltMatchmaking.CreateSession(
sessionID: RoomID,
token: roomProperties,
sceneToLoad: Map
);
}
}
// Use this for initialization
void Start()
{
// Get custom arguments from command line
Map = GetArg("-m", "-map") ?? Map;
GameType = GetArg("-t", "-gameType") ?? GameType; // ex: get game type from command line
RoomID = GetArg("-r", "-room") ?? RoomID;
// Validate the requested Level
var validMap = false;
foreach (string value in BoltScenes.AllScenes)
{
if (SceneManager.GetActiveScene().name != value)
{
if (Map == value)
{
validMap = true;
break;
}
}
}
if (!validMap)
{
BoltLog.Error("Invalid configuration: please verify level name");
Application.Quit();
}
// Start the Server
BoltLauncher.StartServer();
DontDestroyOnLoad(this);
}
/// <summary>
/// Utility function to detect if the game instance was started in headless mode.
/// </summary>
/// <returns><c>true</c>, if headless mode was ised, <c>false</c> otherwise.</returns>
public static bool IsHeadlessMode()
{
return Environment.CommandLine.Contains("-batchmode") && Environment.CommandLine.Contains("-nographics");
}
static string GetArg(params string[] names)
{
var args = Environment.GetCommandLineArgs();
for (int i = 0; i < args.Length; i++)
{
foreach (var name in names)
{
if (args[i] == name && args.Length > i + 1)
{
return args[i + 1];
}
}
}
return null;
}
}
}

Usually, it will be held by an empty GameObject in an empty scene (which will only be used for headless server builds).

The script has been slightly altered for this demo to fit the project's structure, and it is currently placed in an empty GameObject in a scene located in Assets/Scenes/BoltHeadlessServer.

Adding headless server checks to your game#

The above script contains a static utility method called IsHeadlessMode, to be used to check if the running game is headless or not. If you are updating an existing project, you might want to add this check to remove or add features for the headless server, like preventing the instantiation of a player character.

Build settings#

In the Buid Settings of the project, add the BoltHeadlessServer scene at the very top, so it is the first to be loaded by the server.

Next, choose Linux as the target platform and check Server Build.

img

Now you can build your game under Linux with the above settings.

For client builds, do not forget to uncheck the BoltHeadlessServer scene and the IsServer option so your game functions properly.

For every step concerning the making of a headless server for Photon Bolt, more details are available in the official documentation: https://doc.photonengine.com/en-us/bolt/current/demos-and-tutorials/headless-server

Create a container for the server.#

If you aren't familiar with Docker or containers, you can learn more by checking out What is Docker?

To create a container from a Unity project, please refer to Unity on Docker.

Add your app to Arbitrium.#

You can now add your container to Arbitrium so it can be hosted everywhere your players are.

If you don't know how to add an app to Arbitrium, please refer to Getting Started.

However, you will need to make sure the name of your app is demo-game and that it has a version called v1. Else, you will need to update these values in the script located in Assets/Scripts/StaginController.cs.

Also, within the Assets/Scripts/StaginController.cs script, you will find a constant variable called API_TOKEN. You will need to create a token from your Arbitrium account and paste it as a string into this variable. That token will be used to authorize the API requests sent to Arbitrium.

Here is the script in question, with the token from Arbitrium in blue and the app parameters in red: img

Playing the demo game.#

Finally, you can start a demo game client build to play it. You can either build a client version of the game and launch or play it directly from the Unity interface. Just make sure to start it on the StartScene scene.

Once launched, an interface will show up. It contains a text field at the top, two large buttons and a label at the bottom left of the screen showing Bolt's current state.

img

You can copy your API Token from Arbitrium into the text field at the top. Once your Token is pasted, you can now press the Request Server button to send an API call to Edgegap to start a server.

A few seconds later, you should see the label at the bottom of the interface showing the number of available servers. You will now press the Connect to a random server button to join a game and start playing.