Guide to the Unity Matchmaking Backend

Quick heads up, if you’re using Unity 5.1.1f or any version before that, you must update to 5.1.1p2 or later here. I also heard that if you made your project using a beta version of Unity you may have to create a new project and copy your Assets over. Not confirmed, just some troubleshooting I saw.

Furthermore, if you haven’t read the Unity 5 Networking manual yet, please do so now because I won’t explain any of that stuff and will assume you understand the concepts there.

Here are some insights I have into getting matchmaking to work. It’s been a pain but I think I have it working perfectly now.

Setup

First off, head to the Unity Multiplayer Service page and sign up and create a project. Open up a notepad application and copy paste your cloud project id and UNET ID. These are not the same. The UNET ID is an integer below the cloud project id in very small text.

Now, go to your player settings (Edit->Project Settings->Player) and put in your cloud project id.

Open up a scene and create an empty GameObject. Add the components NetworkManager, NetworkManagerHUD, and a custom script, let’s call it NetworkCtrl. Set it up like the manual says.

Scripting

In your script, get a pointer to your NetworkManager and call it mgr.

The function mgr.StartMatchMaker() basically instantiates mgr.matchmaker. You cannot use mgr.matchmaker without calling StartMatchmaker.
Wherever you call this function, be sure it looks like this
PlayerPrefs.SetString ("CloudNetworkingId", "XXXX");
mgr.StartMatchMaker ();
mgr.matchMaker.SetProgramAppID ((AppID)XXXX);

where XXXX is your UNET ID. If you don’t add your UNET ID it will probably still work in the Unity Editor but you will probably run into problems on mobile.

Now you’re all set to write your own HUD. See my guide to writing your own HUD for details on this.

Troubleshooting

Using DestroyMatch to Remove Your Hosted Games

You may run into this issue where you host a match, then leave, then join a match and see your old match still there. To solve this, use DestroyMatch. To do this, have two longs m_networkID and m_nodeID. The OnMatchCreate function’s CreateMatchResponse parameter has a networkID field. Store that in m_networkID. Likewise, the OnMatchJoined function’s JoinMatchResponse parameter has a nodeID field. Store that in m_nodeID. Wherever you disconnect from a server you joined, be sure to call.

if (this.isHost) {
this.mgr.matchMaker.DestroyMatch ((NetworkID)this.m_networkId, OnDestroyMatch);
} else{
DropConnectionRequest dropReq = new DropConnectionRequest ();
dropReq.networkId = (NetworkID)this.m_networkId;
dropReq.nodeId = (NodeID)this.m_nodeId;
mgr.matchMaker.DropConnection (dropReq, OnConnectionDrop);

}

isHost is a bool I set to true in OnMatchCreate.
Host id {0} has already been deleted
For some reason this error goes away if you close the Profiler.

Host id Out of Bound
You need to update to 5.1.1p2 or later. Read the top of the guide again for the link to the update download.

Dictionary Element with Key Already Exists
This issue is related to cleanly deleting your hosted game. If you don’t call DestroyMatch properly you will run into this issue. Implement DestroyMatch by reading the “Using DestroyMatch to Remove Your Hosted Games” section under Troubleshooting.

ListMatch Received Invalid Request for appId=Invalid
This issue usually occurs when you forget to set the cloud project id or UNET ID. If this is occurring even when you’re properly setting these two ids, then it means you need to upgrade to 5.1.1p2 or higher.

SSLHandshakeException
This issue happens sometimes on mobile. I believe this has something to do with the WiFi you’re on. I tested it on public wifi and sometimes I get this error. I don’t think this is yours or Unity’s fault, but rather the setup of the public wifi denying access to trust anchors.

FileNotFoundException at CreateMatchRequest
Your room name right now shouldn’t contain any special characters like “<". If you're using something Device Name, it might come back as "” which will result in this error. What I do is System.Guid.NewGuid()