Master Server Kit Setup

From gamevanilla wiki
Revision as of 08:40, 17 June 2020 by David (Talk | contribs) (Deploying to a production server)

Jump to: navigation, search


The best way to introduce the functionality provided by Master Server Kit is to play with the included demo.

You can launch it on your computer in order to be prompted with the intro screen:


You can register a new user:


And log in with an existing user:


You can also log in as a guest.

Once successfully logged into the master server, you will enter the lobby screen:


From this screen, you can perform the following actions by clicking on the appropriate buttons:

  • Find games: Lists all the available games on the master server.
  • Create a new game: Creates a new game (which will be public or private depending on the contents of the password input field). While the demo always creates 2-player games, the kit supports any number of players. We plan to extend the demo with the option to create games with different capacities in a future update.
  • Play now: Joins an available game or creates a new one automatically if none was found.
  • Join game: Joins the corresponding game.
  • Chat: Chat with all the other players connected.

You can see this functionality is fundamentally equivalent to the one provided by Unity Multiplayer Services's matchmaking, with the difference that everything is running on a dedicated server here.

If you try to join a private game you will be prompted with this dialog, where you need to introduce the game's password:


Once you have successfully joined a game, you will enter the game screen:


This screen is just a placeholder for demonstration purposes; you would implement your authoritative game logic here. You can chat with the other players in the game/match/room and also have the option to exit the game and return to the lobby. When no players are left in a game server, it is automatically shut down by the master server.

How to build the demo

The best way to understand how Master Server Kit is structured and how it works is to build the accompanying demo and run it locally on your machine. In order to do that, you will need to generate four binaries:

  • The master server: This server is responsible for authenticating existing players, registering new players into the system and managing the available games. You can think of it as the "brain" in Master Server Kit, acting like a centralized lobby.
  • The zone server: This server is responsible for managing the game server instances in a given zone. Zones are a useful abstraction that allow you to distribute the game server load across different machines (which is useful for load balancing or region-based matchmaking), meaning you can have several zone servers running different subsets of all the available game servers.
  • The demo's game server: This server is responsible for managing the server-side game logic of a single game/match/room of your game.
  • The demo's game client: This is the binary that your players will launch in order to play your game.

You should generally be able to use the provided master server and zone server mostly with no changes for your game, although you always have the option of extending or customizing them if needed because the kit comes with its complete source code included. The game server and game client are where you come in: it is your responsibility to program the multiplayer logic specific to your game server and client. The demo provides an example game server and client that you can use as an official reference for your own game.

In order to build the demo so that it can run locally on your development machine, follow these steps:

  • Import Master Server kit into your project. It is highly recommended you use the latest stable version of Unity.
  • Make sure the Run In Background option in Build Settings/Player Settings/Resolution and Presentation is enabled. This is very important when testing everything locally on your development machine to make sure the servers keep running even when they do not have the system focus.


It is also a good idea to make sure the Display Resolution Dialog option in Build Settings/Player Settings/Standalone Player Options is disabled for convenience, but this is not strictly required.

  • Change the Api Compatibility Level option in Build Settings/Player Settings from .NET 2.0 Subset to .NET 2.0 (this is only needed by the default SQLite database implementation) as follows:


If you decide you want to use a different database implementation and remove the files related to SQLite from your project, you will be able to use the .NET 2.0 Subset option as is usual in most Unity projects.


If you want to completely remove SQLite from your project, you will need to delete the following files: the SQLiteDatabaseProvider.cs file and the DLLs needed by SQLite (Mono.Data.Sqlite.dll, System.Data.dll, sqlite3.dll, sqlite3.def,

  • Configure your server settings as appropriate in the appropriate components located in the MasterServer, ZoneServer, GameServer and GameClient_Start scenes. By default they point to localhost (, which is just fine for testing things locally on your development machine. You will need to change the value of the Path to binary field in the Zone Server component so that it contains the absolute path on your system where the game server binary is located. In our computer running Windows that would be GameServer.exe. Please note that if you are using Mac OS the actual binary file is not but instead.
  • Select the Build All option located in the Window/Master Server Kit menu. This will generate the four binaries automatically. By default, the binaries will be located at the root of your Unity project in a folder named Builds.


This menu option is provided via an editor script located in Demo/Scripts/Editor/Builder.cs. You can change the build target specified in this script if you are targeting a different platform than Windows (which is the default).

  • Launch the master server, the zone server and any number of game clients (in that order). You should now be able to test the demo. The game servers will be automatically spawned and destroyed by the zone server as players create and leave new games rooms in the lobby (this is precisely the reason behind the existence of the Path to binary field, so that the zone server knows which binary to launch when a new game room is created).

You can also generate the builds manually from the build settings by selecting the appropriate scenes for each binary:


More specifically, you will need:

  • The MasterServer scene for the master server.
  • The ZoneServer scene for the zone server.
  • The GameServer scene for the demo's game server.
  • All the scenes located in the Demo/Scenes/GameClient folder for the demo's game client.

By default, the players' data is stored in a SQLite database, but the kit also provides implementations for MongoDB and LiteDB (you can find more information here). You do not generally need to worry about the details of interacting with the database, as this is something handled by the kit.

Deploying to a production server

When deploying the server binaries to a production environment, we recommend building the master server, zone server and game server as Linux headless. This allows you to launch them as command line programs with no graphics, which is particularly convenient for servers (where no graphics are required).


Please note the Headless Mode setting only exists for Linux builds and you need to disable the Development Build option in order to be able to enable it.

Master Server Kit is known to work on a Digital Ocean VPS, but any well-respected cloud service able to run Unity instances should be fine. Please note that we do not provide technical support for deployment issues. If you are using AWS, a kind user provided us with this helpful tip to get the kit working on this platform: "The trick was to set the server IP addresses to the internal IP address of the server, so not but the private IP address".

In order to get the servers deployed to a Digital Ocean VPS, you can follow these steps:

  • Set up your Digital Ocean server. You can follow the official tutorial here. Not all the steps are strictly necessary; for example, you can do everything as the root user at the beginning, but at some point it is recommended to create an administration user with more limited privileges for security reasons.
  • Update the firewall rules on your server to allow remote connections to the ports used by the kit. Ours look something like this (with the default configuration):
   To                   Action     From
   --                   ------     ----
   OpenSSH              ALLOW      Anywhere
   8000                 ALLOW      Anywhere
   9000:9100/tcp        ALLOW      Anywhere
   9000:9100/udp        ALLOW      Anywhere
   OpenSSH (v6)         ALLOW      Anywhere (v6)
   8000 (v6)            ALLOW      Anywhere (v6)
   9000:9100/tcp (v6)   ALLOW      Anywhere (v6)
   9000:9100/udp (v6)   ALLOW      Anywhere (v6)
  • Configure your server settings in the appropriate components located in the MasterServer, ZoneServer, GameServer and GameClient_Start scenes. Change the IP address fields to point to the public IP address of your server. You will also need to change the value of the Path to binary field in the Zone Server component so that it contains the path on your server where the game server binary is located. In our server, that would be game_server.x86_64.
  • Build the server binaries (master server, zone server and game server) for Linux 64-bit in headless mode.
  • Zip the server binaries and upload them to your Digital Ocean server. For example, by using the scp command:
   scp root@DIGITAL_OCEAN_IP:~/
  • Log into your Digital Ocean server and go to the location where you uploaded the .zip file containing the server binaries. Unzip it (you may need to install the unzip utility on your server):
  • Give execution permission to the extracted binary files:
   chmod +x master_server.x86_64
   chmod +x zone_server.x86_64
   chmod +x game_server.x86_64
  • Finally, run the master server and zone server in the background (so they keep running 24/7).
   ./master_server.x86_64 &
   ./zone_server.x86_64 &

The game server instances will be spawned and destroyed automatically by the zone server as appropriate.

With non-root users, you may need to use the sudo command as appropriate at some of the steps mentioned above.