Edgegap Hosting Plugin Guide
Mirror's inofficial Edgegap Hosting Plugin documentation.
Thanks to Edgegap's hosting plugin for Unity, Mirror users get 0.5 vCPU cloud hosting for free!
You can build & launch a game server into the cloud directly from your Unity Editor, without any Linux or Cloud usage whatsoever.
This is an early version.
If you encounter issues, please report them in our Discord's #edgegap channel.
Overview
Setup will take only a few minutes, with 4 basic steps:
Creating an Edgegap.com Account
Installing Unity Linux Build Support & Docker Desktop
Configuring the Unity Plugin
Building & Pushing our server to Edgegap
Open the Plugin in Unity / Mirror
Edgegap's Hosting plugin (version 2) is now always included in the latest Mirror version.
It requires at least Unity 2023 LTS, it won't work with older versions due to using UIToolkit.
The original source is on Github, but we applied a few fixes to the version in Mirror.
If you are on an older Mirror version, you can also download the Assets/Mirror/Hosting folder from our Github repository manually. If you see errors about missing 'Newtonsoft Json', add this package to your Package Manager:
You can also open the Packages/manifest.json file and add this line manually:
By default, this should work out of the box though.
Once you have it, check for "Edgegap -> Edgegap Hosting" in Unity's top menu:
Get a Token
The next step is to Get a Token from the Edgegap website.
Simply press the Get a Token button and either login to your existing Edgegap.com account, or press the Get Started link on the page to create a new account.
After confirming your email address, you'll be asked about naming Your Organization. You can enter anything, in this case we use "Your-Organization".
Afterwards you'll be asked to Begin the Application Tour. Skip it for now.
Next you'll automatically see the Token Created Successfully screen, because we initially clicked the Get Token button in the Unity plugin:
Press the Clipboard icon to copy the token, then paste it back into the Unity plugin and press Verify. Note that the token looks like "token 123456-abcdef-00000-...". The "token ..." part needs to remain in there.
After verifying successfully, enter an Application Name into the field and press Create Application:
It'll say Success and then show you the application details.
Next time you can enter your already created application name and press Load Existing App instead.
The final configuration step: we need to enter the Port and Protocol Type.
Open your scene in Unity (for example our Tanks demo), find the NetworkManager, find the Transport component, copy the Port into the plugin.
=> If you are using Kcp then the Protocol Type is UDP.
=> If you are using Telepathy, then it's TCP.
Almost done! Before we can Build and push, we need to install the Linux build support for Unity, and Docker!
Install Unity Linux Build Support
In your Unity Hub, select Installs, press the Configuration icon next to your Unity version and click Add Modules:
Find and install Linux Dedicated Server Build. You may add the others too just to be safe:
Press Continue, wait, restart Unity once, done.
Install Docker Desktop
Edgegap works with containers, which means we need to install Docker. We don't need to worry about it ever, we just need to install it once.
The easiest way is to simply install Docker Desktop:
Download it, install it, open it and leave it running. You can pretty much auto start it with your operating system each time.
Some users reported that they had to restart their computer once before they could use Docker. To be safe, consider restarting once!
Quick explanation about Docker if you care. You don't need to know this, so feel free to skip.
Basically Docker is a super easy way to configure a virtual machine for your game server build. Previously you would manually create a VM in say Google Cloud, configure a hard disk, open ports, install a Linux version, run apt-update, install dependencies, ...
With docker, we just have a text file. It says 'install ubuntu, copy our build into the VM, navigate to the folder, run unity. Again, you DO NOT need to worry about this. The plugin creates this automatically, something like this (again, don't worry about it):
Next, we need to log into Edgegap's docker registry.
We are working with Edgegap to automate this. For now you need to open a Terminal / Console:
On Windows, hit CTRL+R, enter CMD, hit enter to open it.
On Mac, open Finder, go to Applications -> Utilities -> Terminal.
On Linux, you probably know how to do it.
Don't be scared of the Terminal. It's just black background and white text where we'll enter exactly one command. This will be automated soon.
Grab your Username + Token from the Container Registry page on Edgegap.com:
https://app.edgegap.com/registry-management/repositories/list
You can find them under Credentials:
Now enter this simple terminal command. There won't be any others, promised!
Then enter your Username and Token (as password) that you see on the Edgegap.com -> Container Registry page.
If you can't seem to login, you can also try this command instead:
Docker Desktop remembers your login, so you won't have to do this again next time.
Alright, that's it for Docker.
Build and Push
Before we build the game server, select your NetworkManager and make sure that Auto Start Server in Headless Mode is enabled. Otherwise the server application may launch but not call NetworkManager.StartServer(), so no one would be able to connect.
Next, press Build and Push in the Unity plugin:
Note that Edgegap does not see your game's source code. They only see a finished Docker container.
You'll see a progress bar for a while:
Unity will create a Linux build, then create a Docker build, then upload the whole thing to Edgegap. Note that uploading will take a while depending on your internet connection. The progress bar halts while uploading, but you can check your operating system's bandwidth usage to see if it's still uploading:
If this all worked, then you'll see a log message:
If this failed, it'll show you errors. Here are a few common issues and workarounds:
Missing Linux Build Support: install it in your Unity hub. Make sure you do it for the Unity version that you are using in your project. This generally works once you have the Linux Build Support installed.
Incremental Build Failed: delete your previous Unity Linux build in the /Builds folder next to the /Assets folder, restart Unity try again. Delete your Library/ folder if you need to. This is a Unity bug that happens sometimes.
Docker authorization Failed: make sure Docker Desktop is running and make sure that you are logged in with the above Terminal command. Also make sure that image registry consists of the Container Registry's 'Project' + "/" + "your-game".
If you encounter other issues, talk in our #edgegap Discord channel. We want to find solutions for any possible issue and explain this here!
Deploying the Server
Now that we uploaded our server build to Edgegap, we need to Deploy (aka launch) it.
In the plugin, press Create New Deployment:
After a few seconds you'll see your running server in the list:
Note that our original port was 7777, but in the Deployment it says 30358. That's because one cloud server may launch multiple game servers. But there's only one port 7777, so it's using Port Mapping to find a free port for you.
Connect your Game Client
Finally, press Play in the Unity Editor (or launch your client build).
Enter the deployment's hostname and port in the NetworkManager HUD:
Enter the hostname(fa[...].edgegap.net) and the port (30358) separately!
Press the Client button to connect to it, and now you are online! 🚀
It's important to understand the magic that is happening here. Not only can you launch a game server with Two Clicks now. You can even launch thousands of servers with another click on Edgegap's website! 🤩
To reduce costs (if you are paying), you can press Stop Server in the plugin once you are done.
Optional: Grab the Server Status at Runtime
If you need to grab the server status from the above screenshot from your Game, you can use:
Troubleshooting Connection Issues
If your Server Status says Ready but you can't seem to connect, try this:
On the Edgegap website, go to Deployments -> select your Deployment -> select Container Logs, check the log files to see if your game server actually launched or if there are issues.
If it says "exec user process caused: no such file or directory": this can happen if you pushed an ARM build to Edgegap's x86 infrastructure. We already updated the plugin to properly cross compile from ARM so this generally should not happen anymore.
If everything seems fine but you still can't connect, please talk to an Edgegap employee in the Mirror Discord's #edgegap channel.
Big thanks to our Canadian 🇨🇦 friends at Edgegap for giving Mirror users 0.5 vCPU for free! While we hope for a larger free tier in the future, please keep in mind that they are the ones who are paying for the infrastructure. If you have the means, please pay them for more vCPUs!
Last updated
