Master Server

The master server is a meeting place for game servers that are actively seeking clients, and player clients who want to connect to them. As such, the master server is essentially a basic lobby server, but with some special features. Its purpose is also to hide IP address and port details, and to perform technical tasks around setting up network connections which otherwise would be impossible, like acting as a proxy server to let clients behind a firewall act as a game server.

If you only have one single game server running on a server with a public IP adress, for your clients to connect to, there is no need to use the master server. In such a case, just let the clients connect to your server directly using its public address. But when you have several game servers running in parallel and the players should be able to select one of the game servers from a list, the master sever is the a great tool.

Since the release of uLobby, this master server is not the recommended choice. We recommend using uLobby for building a better and more advanced lobby. But if you have a plan for hosting the game servers outside the datacenter, using some of the player's computers as game servers, it is smart to use the master server and the included proxy feature.

Basic interaction

When there are several game server for a game, each individual running game server provides a game type to the master server. All game servers with a matching game type are gathered together so that compatible clients easily can view them. When a client connects to the master server and queries it for a matching game type, a list with basic information about the servers is shown to the player. This information about a game server is contained in the uLink.HostData class, and helps the player to decide which game server to connect to. For example, the player can see the game's name, player count and whether or not a password is needed to join. The server uses MasterServer.RegisterHost() to transmit this data to the master server, and the client uses MasterServer.RequestHostList() to read it.

When calling RegisterHost() from your game server, you need to pass at least three arguments, namely a string denoting the previously mentioned game type, a string containing the name of the new game, and a comment string describing the game. RequestHostList() takes as an argument the game type string of the hosts you want to connect to. All the registered hosts with a matching type will then be sent to the requesting client. This is performed as an asynchronous operation and the actual host list can be retrieved with PollHostList() which returns the list if it has arrived.

Registering a game

Once the master server has been started, it is possible to register a game server. Please set the correct IP and port to the master server before calling it. Use the loopback adress 127.0.0.1 to connect to a master server started on the local computer. Default port number is 23466.

uLink.MasterServer.ipAddress = "127.0.0.1";
uLink.MasterServer.port = 23466;

If the ipAdress is not set, the game server will register in the default master server, which is the public master server hosted by UnityPark. This server is available just to make it easy for all uLink customers to test and learn how to use a master server. Do not use it for commercial games, there is no guarantee that this master server will be available at all times.

Use the code outlined in the following script example. When a button is pressed by the user that started the game server, the game server host is registered in the master server.

function OnGUI()
{
    if (GUILayout.Button ("Start Server"))
    {
        uLink.Network.InitializeServer(32, 25002);
        uLink.MasterServer.RegisterHost("MyUniqueGameType", "JohnDoes game",
            "l33t game for all");
    }
}

Listing available games

The client makes a call to the master server to get a list of available games. This example code prints out some of the available information in the host list returned by the master server.

function Awake()
{
    uLink.MasterServer.RequestHostList("MadBubbleSmashGame");
}


function OnGUI()
{
    var data : uLink.HostData[] = uLink.MasterServer.PollHostList();
    // Go through all the hosts in the host list
    for (var element in data)
    {
        GUILayout.BeginHorizontal();    
        var name = element.gameName + " " + element.connectedPlayers +
            " / " + element.playerLimit;
        GUILayout.Label(name);    
        GUILayout.Space(5);
        var hostInfo;
        hostInfo = "[";
        for (var host in element.ip)
            hostInfo = hostInfo + host + ":" + element.port + " ";
        hostInfo = hostInfo + "]";
        GUILayout.Label(hostInfo);    
        GUILayout.Space(5);
        GUILayout.Label(element.comment);
        GUILayout.Space(5);
        GUILayout.FlexibleSpace();
        if (GUILayout.Button("Connect"))
        {
            print("Connecting directly to host");
            uLink.Network.Connect(element.ip, element.port);            
        }
        GUILayout.EndHorizontal();    
    }
}

Starting the master server

The master server is a completely separate entity. It must be hosted on a machine with a public IP address. It can be hosted on Linux (with Mono installed), Windows and Mac OS, and anyone can have their own master server.

On Windows, start the master server by running uLinkMasterServer.exe that was installed together with uLink. The default installation path on Windows is the following.

C:/Users/Public/Documents/uLink Tools/MasterServer

The master server can be started as a console application with a number of options. You can use the -help command switch to get more information about the configuration options available.

Detecting LAN servers

When using uLink, it is possible for a client to send a request to all hosts on the local area network (LAN) and ask if they are uLink servers. This can be done on one selected port or for a complete port range. This is useful for LAN games and makes it possible to detect running game servers without using the master server. You may ask why the API for detecting local servers is a part of the master server API when you don't use a master server for the operation. The answer is that uLink gathers all server detection features in one single place, to make life easier for the programmer.

You can read more about this in the API reference for MasterServer.DiscoverLocalHosts().

You can't detect LAN servers in a web player due to the security restrictions.

Storing favorite servers

In some games it is important for players to be able to store their favorite servers that they have used before. There is a built-in list in uLink for storing such favorite servers. You can read more in the API reference for MasterServer.AddKnownHostData().

GUI example

The following picture shows one way to combine the features in the master server API and build a feature-rich menu in the game client.

Master Server GUI
Master Server GUI

At the top of the picture there are three menu buttons. When you press the Internet button a request goes out to a known master server and populates the list with all the available games servers that has enlisted themselves. The client knows the public address to the master server, either because it is pre-configured in the client by a developer, or because it is made available to the player who enters it into the client.

The player can mark any server as a favorite by clicking the star icon to the right, which will add the server to the list of the player's favorite servers.

To connect to a game server, the player just have to click the Join button to the right.

The second button in the top row is named LAN. When a player presses this button another list is shown, containing all servers for the given game in the player's local area network.

Pressing the Favorite button brings up a list of all servers on the internet and in the LAN that the player has marked as favorites. This list can be stored on disk by the Unity web player and by the Unity stand-alone client, which makes it easy for players to return to their favorite game server whenever they want to.

The values in the list are updated live. This means that things like the ping time or the number of connected players will be updated continually as long as the player is viewing the list. New servers will pop up and stopped servers will be removed from the list automatically.

The code for this master server GUI is available in the SNOWBOX sample game included with uLink.

Host list filters

The master server API has a feature for filtering the list of available servers. This is very convenient to use when the list of servers is long. The client programmer can use this API to filter the list of available game servers based on the number of connected players, max number of players, game type, level and more. You can read more about this in the uLink API for the class uLink.HostDataFilter.

Proxy server

The proxy server can be used when the uLink game server must be hosted in one of the player's machines and that machine has no public IP address. The game server can be running in a Unity web player with this setup.

UnityPark does not recommend hosting the game server in a player's machine for commercial games, since that setup has several security risks. However, the feature is available in uLink and can be used when needed.

The proxy server is popular because it removes the cost for hosting all the game servers, but at the same time, it increases the latency and also increases the bandwidth need for the host where the proxy server is running.

It is also popular when there are problems with P2P games using NAT punchthrough. Some home routers and/or firewalls can refuse NAT punchthrough and cause a variety of problems like lost connections. When using the proxy server, those problems are avoided.

Proxy sequence explained

The proxy server is a feature that is part of the stand-alone uLink master server. It can be activated when starting the master server. This is the sequence of events when the proxy server is used:

  • The proxy server feature must be activated in the master server when it starts. Choose a range for proxy socket ports and make sure these ports are open for incoming UDP traffic in the firewall (if the master server host is located behind a firewall).
uLinkMasterServer.exe -proxy 41000:42000
  • Player 1 wants to play the game. No game servers can be found in the master server.
  • Player 1 starts the game anyway and will become the uLink server for this game session. The game server registers itself in the master server including information that it needs a proxy server to connect to. When a host list is requested from the master server, it will inform that this game server only accepts connections via a proxy. Make sure the useProxy property has been set to true before registering the game server in the master server:
uLink.Network.useProxy = true;
  • Player 2 wants to play the game. One game server can be found in the master server. You can write code in the client to detect that the property useProxy is true in the received instance of the class HostData.
  • Player 2 requests to join this game server. The request goes to the master server. Write code that calls one of the connect methods that takes HostData as the first argument.
uLink.Network.Connect(HostData data, ... )
  • The master server gets the request and starts a proxy session dedicated for this player only. This proxy session will have a UDP-socket with a unique UDP port number.
  • The game server (hosted in the machine for player 1) will get a message from the master server to connect to the proxy session. It makes the connection. This is handled automatically by uLink.
  • Player 2 client will get a message from the master server to connect to the proxy session. It makes the connection. This is handled automatically by uLink.
  • The two players are now playing the game. All network traffic between the players are going through the proxy session.

When more players join this game server, they need to connect using the same procedure as player 2. A new proxy session with a unique port number is started for every player.

NAT punchthrough not included

Currently there is no functionality in uLink to perform NAT punchthrough. MuchDifferent have no plans for releasing this feature due to reliability issues.