Mirror Netcode
Mirror on Arbitrium
This guide will help you create a headless server on Edgegap for a Unity project using Mirror as its networking solution.
This guide will use the open-source sample project Tanks
, which is already available in your Mirror sample, location Assets/Mirror/Examples/Tanks.
The final sample can be found on our GitHub.
Build the game server
Once ready with your game, head to the Build
screen of the Unity Editor, under File -> Build Settings
in the top menus. Make sure to select the right presets depending on your version of Unity.
-
Prior to version 2021.2:
- Set
Target Platform
toLinux
; - Set
Architecture
tox86_64
; - Check the
Server Build
option.
- Set
-
Otherwise:
- Set
Platform
toDedicated Server
; - Set
Target Platform
toLinux
.
- Set
Then press build and select a new empty folder named linux_server
as the file destination. Transfer linux_server
folder to a second empty folder, which will be refered as the [SERVER BUILD]
folder in this document.
Containerizing the dedicated game server
We will create a docker image containing the dedicated game server in this part. You might also be interested in reading Unity Server in Docker.
If you need more informations about Docker with Edgegap, please refer to this documentation.
Dockerfile
FROM ubuntu:bionic
MAINTAINER <author_detail>
ARG debian_frontend=noninteractive
ARG docker_version=17.06.0-ce
RUN apt-get update && \
apt-get install -y libglu1 xvfb libxcursor1 ca-certificates && \
apt-get clean && \
update-ca-certificates
EXPOSE 3389/TCP
EXPOSE [GAME PORT]/TCP
EXPOSE [GAME PORT]/UDP
COPY linux_server/ /root/linux_server/
COPY boot.sh /boot.sh
WORKDIR /root/
ENTRYPOINT ["/bin/bash", "/boot.sh"]
Take note of the port you use for network communications, referred as the [GAME PORT]
. By default, the port used is 7777
. You can find this information in the Unity Editor, on the NetworkManager
game object, in the Transport
component.
- Copy the above lines and paste them in your Dockerfile, placed inside
[SERVER BUILD]
. Modify the[GAME PORT]
placeholders to your game port.
Having the [GAME PORT]
opened on both TCP and UDP allow you to use any transport you prefer in the NetworkManager
Mirror component.
Finally, create a file named boot.sh
at the root of the [SERVER BUILD]
folder. It will be executed when starting the image in a container.
- Copy the following two lines, make sure to replace the
[YOUR GAME]
placeholders with the name of the generated file.
xvfb-run --auto-servernum --server-args='-screen 0 640X480X24:32' /root/build/[YOUR GAME].x86_64 -batchmode -nographics
At this point, you should have the following hierarchy:
[SERVER BUILD] folder
Dockerfile
boot.sh
linux_server
folder
- Unity generated files
- Start a command prompt in the
[SERVER BUILD]
folder, and run the following Docker commands:
- Linux
- cmd
- Powershell
For ARM CPU (Mac M1, M2, etc.) user, see the dedicated page : ARM CPU
# build the image
docker build . -t <IMAGE_NAME>:<IMAGE_VERSION>
# login, a prompt will ask the password
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>
# add another tag to your image corresponding to the registry
docker image tag <IMAGE_NAME>:<IMAGE_VERSION> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
#push the image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
For ARM CPU (Mac M1, M2, etc.) user, see the dedicated page : ARM CPU
# build the image
docker build . -t <IMAGE_NAME>:<IMAGE_VERSION>
# login, a prompt will ask the password
docker login -u <REGISTRY_USERNAME> <REGISTRY_URL>
# add another tag to your image corresponding to the registry
docker image tag <IMAGE_NAME>:<IMAGE_VERSION> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
#push the image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
For ARM CPU (Mac M1, M2, etc.) user, see the dedicated page : ARM CPU
# build the image
docker build . -t <IMAGE_NAME>:<IMAGE_VERSION>
# login, a prompt will ask the password
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>
# add another tag to your image corresponding to the registry
docker image tag <IMAGE_NAME>:<IMAGE_VERSION> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
#push the image
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_VERSION>
After these commands, you should be able to see your uploaded image on the Edgegap website if you are using the Edgegap Container Registry. See this doc if you want to use the Edgegap registry. You can also use another private registry.
Deploying to Edgegap
Navigate to the Applications & Games
page of the website. Click on the Create New
button in the top right hand corner to access the application form.
Here are the fields and how to fill them properly:
- Application name : Can be any notable name you want to use to easily recognize your application among others.
- Image : Can be any specific image you want to use to easily recognize your application among others.
- Version name : You may want to use a version name to describe the scope of the version you are deploying. Examples may be “demo”, “production”, “v1”, “v2”
- Container :
- Registry : “[URL]”, where [URL] is the value from the credentials you can display on the Container Repository page.
- Image repository : “[PROJECT]/[YOUR GAME]”, where [PROJECT] and [YOUR GAME] are the values you used earlier when pushing the docker image.
- Tag : “[TAG]”, where [TAG] is the value you used earlier when pushing the docker image.
- Tick “Using a private repository”
- Private registry username : “[USERNAME]”, where [USERNAME] is the value from your credentials.
- Private registry token : “[TOKEN]”, where [TOKEN] is the value from your credentials.
- Requirements : Left as is.
- Ports :
- Click the
+ Add port
link to add a new port, and add the following entries :[GAME PORT]
-TCP/UDP
- disable Verifications- 3389 - TCP - disable Verifications
- Click the
Once your application has been created, you can press the Deploy
button to proceed with deploying your game server.
Choose the region you want to deploy in, and enter the number of random players you want to generate depending on your game. Check that everything is running smoothly by verifying the following:
- Latest Status should be set to
Ready
. - In the
Port Mapping
tab, you should be seeing the port you set in the application creation form:
Add sample HUD in your client application
- Set the
Port
value of theTransport
component of theNetworkManager
to the external port defined in thePort Mapping
tab of your deployment.
In this example, the port was set to 31887
. This primarily depends on the game you are developing and will most likely be set programmatically in the game’s codebase.
- Set the value of
Network Address
of theNetwork Manager
to your deployment'sHost
. This URL can be found in theDeployment Summary
on the dashboard or with the API.
In this example, the address was set to 0ace560706a5.pr.edgegap.net
. Again, this value will most likely be set programmatically during the client’s communication with the master server/API responsible for the matchmaking process.
With the correct information, you should be able to connect to the game server normally and be able to start playing right away.
You now have a Mirror project available to deploy on demand!
Bonus: Seat Sessions Management
With seat-based deployments, it's possible to use Mirror to create a system that automatically removes hanging Edgegap sessions once a player disconnects from the server, using NetworkManager
callback functions, and a NetworkBehaviour
script attached to the player prefab that uses a Remote Procedure Call (RPC) function and a Command function.
When the server starts, the NetworkManager
retrieves the list of session IDs
linked to its deployment from the Edgegap API and stores it. Afterwards, when a new player connects to the server, a client-side function is initiated via RPC
that will send the player's IP address
back to the server with a command
. With the player's IP, the server checks for a matching IP in each session's data; The server gets the session data using its cached ID with the Edgegap API. If a match is found, the session ID
is mapped to that player's NetworkConnectionToClient
.
Since new sessions can be added after the server starts, the list of session IDs is updated and the new sessions are checked if a match can't be found the first time around.
Finally, once a player disconnects from the server, the server uses that player's NetworkConnectionToClient
to retrieve their associated session ID
, then uses the Edgegap API to delete that session. This frees a socket in the deployment for a new player to join.
- PlayerNetworkBehaviour
- CustomNetworkManager
public class PlayerNetworkBehaviour : NetworkBehaviour
{
[ClientRpc]
public void RpcSendClientIpAddress()
{
StartCoroutine(FetchPublicIpAndSendToServer());
}
private IEnumerator FetchPublicIpAndSendToServer()
{
UnityWebRequest request = UnityWebRequest.Get("https://api.ipify.org?format=json");
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
string responseText = request.downloadHandler.text;
string clientIp = JObject.Parse(responseText)["ip"].ToString();
CmdSendIpAddressToServer(clientIp);
}
else
{
Debug.LogError("Failed to fetch public IP address.");
}
}
[Command]
public void CmdSendIpAddressToServer(string clientIp)
{
NetworkConnectionToClient conn = connectionToClient;
if (conn != null)
{
CustomNetworkManager.Instance.StoreClientIpAddress(conn, clientIp);
}
else
{
Debug.LogError("Connection not found.");
}
}
}
public class CustomNetworkManager : NetworkManager
{
private static readonly string edgegapUrl = "https://api.edgegap.com/v1";
private string apiToken;
private string deploymentId;
private Dictionary<NetworkConnectionToClient, string> connectionToSessionIdMap = new Dictionary<NetworkConnectionToClient, string>();
private Dictionary<NetworkConnectionToClient, bool> mappingInProgress = new Dictionary<NetworkConnectionToClient, bool>();
private ArrayList currentDeploymentSessions = new();
private ArrayList newSessions = new();
public static CustomNetworkManager Instance;
public override void Awake()
{
base.Awake();
Instance = this;
}
public override void OnStartServer()
{
base.OnStartServer();
deploymentId = System.Environment.GetEnvironmentVariable("ARBITRIUM_REQUEST_ID");
apiToken = System.Environment.GetEnvironmentVariable("API_TOKEN");
if (string.IsNullOrEmpty(apiToken))
{
Debug.LogError("Edgegap API token not found in environment variables.");
}
StartCoroutine(GetNewSessionList());
}
public override void OnServerAddPlayer(NetworkConnectionToClient conn)
{
base.OnServerAddPlayer(conn);
Debug.Log($"Adding player for connection: {conn.connectionId}");
// Get the PlayerNetworkBehaviour from the player object
PlayerNetworkBehaviour playerNetworkBehaviour = conn.identity.GetComponent<PlayerNetworkBehaviour>();
playerNetworkBehaviour.RpcSendClientIpAddress();
}
public void StoreClientIpAddress(NetworkConnectionToClient conn, string clientIp)
{
mappingInProgress[conn] = true; // Set mapping in progress to true
Debug.Log($"Stored IP address for connection {conn.connectionId}: {clientIp}");
// Start mapping the session to the connection
StartCoroutine(CheckCachedSessions(conn, clientIp));
}
private IEnumerator GetNewSessionList()
{
newSessions.Clear();
string url = $"{edgegapUrl}/status/{deploymentId}";
UnityWebRequest request = UnityWebRequest.Get(url);
request.SetRequestHeader("Authorization", apiToken);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
string responseText = request.downloadHandler.text;
Debug.Log("Deployment Status Response: " + responseText);
var json = JObject.Parse(responseText);
var sessions = json["sessions"] as JArray;
foreach (var session in sessions)
{
string sessionId = session["session_id"]?.ToString();
if (!currentDeploymentSessions.Contains(sessionId))
{
newSessions.Add(sessionId);
currentDeploymentSessions.Add(sessionId);
}
}
Debug.Log("New session list initialized");
}
}
private IEnumerator CheckCachedSessions(NetworkConnectionToClient conn, string clientAddress)
{
foreach (string sessionId in currentDeploymentSessions)
{
yield return GetSessionAndMap(conn, sessionId, clientAddress);
if (connectionToSessionIdMap.ContainsKey(conn))
{
break;
}
}
if (!connectionToSessionIdMap.ContainsKey(conn))
{
Debug.Log("Could not map player with current cached sessions");
yield return GetNewSessionList();
foreach (string sessionId in newSessions)
{
yield return GetSessionAndMap(conn, sessionId, clientAddress);
if (connectionToSessionIdMap.ContainsKey(conn))
{
break;
}
}
}
}
private IEnumerator GetSessionAndMap(NetworkConnectionToClient conn, string sessionId, string clientAddress)
{
Debug.Log($"Fetching session details for session ID: {sessionId}");
string url = $"{edgegapUrl}/session/{sessionId}";
UnityWebRequest request = UnityWebRequest.Get(url);
request.SetRequestHeader("Authorization", apiToken);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
Debug.Log("Session fetched successfully.");
string responseText = request.downloadHandler.text;
Debug.Log("Session Response: " + responseText);
var session = JObject.Parse(responseText);
var sessionUsers = session["session_users"] as JArray;
if (sessionUsers != null && sessionUsers.Count > 0)
{
Debug.Log($"Found {sessionUsers.Count} users in session.");
foreach (var user in sessionUsers)
{
string playerIp = user["ip"]?.ToString();
Debug.Log($"Player IP: {playerIp}, Connection IP: {clientAddress}");
if (playerIp == clientAddress)
{
connectionToSessionIdMap[conn] = sessionId;
Debug.Log($"Mapped session ID {sessionId} to connection {conn.connectionId} with IP {playerIp}");
// Additional confirmation logging
if (connectionToSessionIdMap.ContainsKey(conn))
{
Debug.Log($"Session ID {sessionId} successfully stored for connection {conn.connectionId} with IP {playerIp}");
}
else
{
Debug.LogError($"Failed to store session ID {sessionId} for connection {conn.connectionId} with IP {playerIp}");
}
break;
}
}
}
else
{
Debug.LogError("No users found in session.");
}
}
else
{
Debug.LogError($"Error fetching session: {request.error}");
Debug.LogError($"Response Code: {request.responseCode}");
Debug.LogError($"Response Text: {request.downloadHandler.text}");
}
mappingInProgress[conn] = false; // Set mapping in progress to false once done
}
public override void OnServerDisconnect(NetworkConnectionToClient conn)
{
base.OnServerDisconnect(conn);
Debug.Log($"Server disconnected client: {conn.connectionId}");
StartCoroutine(HandleDisconnect(conn));
}
private IEnumerator HandleDisconnect(NetworkConnectionToClient conn)
{
while (mappingInProgress.ContainsKey(conn) && mappingInProgress[conn])
{
Debug.Log($"Waiting for session mapping to complete for connection {conn.connectionId}...");
yield return new WaitForSeconds(0.1f);
}
if (connectionToSessionIdMap.TryGetValue(conn, out string sessionId))
{
Debug.Log($"Deleting session ID: {sessionId}");
StartCoroutine(DeleteSession(sessionId));
connectionToSessionIdMap.Remove(conn);
mappingInProgress.Remove(conn);
currentDeploymentSessions.Remove(sessionId);
}
else
{
Debug.LogWarning("No session ID found for this connection.");
}
}
private IEnumerator DeleteSession(string sessionId)
{
Debug.Log($"Sending request to delete session ID: {sessionId}");
string url = $"{edgegapUrl}/session/{sessionId}";
UnityWebRequest request = UnityWebRequest.Delete(url);
request.SetRequestHeader("Authorization", apiToken);
yield return request.SendWebRequest();
if (request.result == UnityWebRequest.Result.Success)
{
Debug.Log("Session deleted successfully.");
}
else
{
Debug.LogError($"Error deleting session: {request.error}");
Debug.LogError($"Response Code: {request.responseCode}");
Debug.LogError($"Response Text: {request.downloadHandler.text}");
}
}
}