PlayFab Multiplayer guide

Idea

I wanted to integrate a multiplayer mode into the game and decided to use PlayFab for that.

The cool thing about PlayFab is that your server.exe file can be hosted on multiple locations all around the world.
This should guarantee a good ping for everyone, no matter where you are. But the servers will not run all the time.
They are in some kind of standby mode and will only activate themselves when somebody tries to connect.

For PlayFab you have to integrate their SDK into your unity project and build the server.exe file.
Which you can then upload to their servers.

For the game you deliver to the end user I wanted to achieve the following:

  • ping all PlayFab server locations and get the one with the best ping
  • if no server is active at that location, get one out of standby
  • if one is active, check if there is still room for some more players.
    If so connect to it. If not get another server out of standby

The code and examples I found on the web were outdated and didn’t work anymore.
Or they simply didn’t implement the workflow I had in mind. Therefore I decided to create my own solution for Unity 3D.

You can find it here:
https://github.com/BenjaminKobjolke/PlayFabUnity

Notes

I will only cover the topics that I stated before.
PlayFab has a lot more features but I am not interested in those right now.

This guide does not contain information about the actual implementation of multiplayer code.
I think you already got your multiplayer code ready and that’s when you searched the web for PlayFab integration.
If not then I suggest you use mirror as your network / multiplayer libary. Firstgeargames sells a collection of mirror tutorials. You can get them for $5. So please do yourself a favor and get those 🙂


Guide

Create an account at developer.playfab.com
Also create your first game on that webpage.
Then there is one important thing you have to activate “Allow client to start games”.
First go to “Title settings”.

Next we will get our server ready.
Start the unity project which you will find in the \unity folder.
I used Unity 2021.1.1f1. But it will probably work with an older version too.
I added the PlayFabSDK (Assets\PlayFabSDK) and the PlayFab Editor Extension (Assets\PlayFabEditorExtensions) to the project. I leave it up to you if you want to upgrade them to the latest versions. You can find them here: https://github.com/PlayFab/UnitySDK

Open the PlayFab Extension window

Login with your PlayFab account

Set your title at “Title ID”.
The “Developer Secret Key” should be automatically set.

Enable all API-Features

Open the Scenes/Server scene.
The scene is already setup to work with PlayFab.
You will find a “PlayFabServer” object with two scripts attached:

PlayFabServerConnection.cs
This script does all the “magic”. You should not need to edit this one, except to remove the Debug.Logs.

Server.cs
This is the example you should use as a template for your multiplayer game.
Our server wants a few infos about your game at runtime:

  • when a player connects: OnPlayerConnectedPlayfab?.Invoke(playerId);
  • when a player disconnects: OnPlayerConnectedPlayfab?.Invoke(playerId);
  • when a game starts: OnGameStartingPlayfab?.Invoke();

There server wants this information so it can shutdown again if no players connect to it.
Because on PlayFab you get billed for CPU usage. So it can save you real money to shut down your servers.

Server.cs contains some tests with the above mentioned functions

We will come back to those tests later.

Now build the server.

Be sure to only select the Server scene and also to check “Server Build”.
This will create a console application.
Build to a folder called “Server”.
When the build is done it should look like this.

Now zip this folder into Server.zip
Then copy it here: playfab\localtest\Server.zip
The folder should look like this:

We are now testing the server before uploading it to playfab.com
Open MultiplayerSettings.json
There are two things you need to adjust.

LocalFilePath
Obviously where the zip is located.

StartGameCommand
This is tricky. This is the path to the exe file after the local test tool extracted the zip file.
Depending how you zipped the project you might need to add “Server\\” or not.

Then open a cmd prompt in that folder and start LocalMultiplayerAgent.exe
A lot of debug logs will pass by.

The important things are the logs that match our tests in Server.cs (mentioned earlier).
The tests look like this:

The tests will connect a few players and then disconnect them again.
After 60 seconds of “no players connected” the server will terminate.

Now you are ready to upload that Server.zip to playfab.com!

Go to Multiplayer – New build

Change the setting to this and wait until your zip was uploaded (there is no progress bar, just be patient until it shows in the “asset package” field).

I selected a single core machine because I think our Server.exe does not gain anything from more cores.
The Start Command is again tricky, like in the json file before. Depending on your ZIP-File you will need to add “\Server”.
The port setting is relevant to the network library you use. For mirror this is usually 7777.

Then at the bottom you can select the regions for the servers.
If you don’t have a paid playfab account the regions you can select are limited.
I will set it like this:

Finally hit “Save”.

You will see that your server is “deploying”

This can take a while.

In the meantime we will setup a test client.
Please copy the build id of your build, we will need it soon.

Go back to unity and open the Client scene.
You will find the PlayFabClient object and it contains two scripts.

PlayFabClientConnection.cs
Add your build id here

That’s basically all we need to do for the client.
How check back at playfab.com if your server was deployed:

There is another thing we have to change on the playfab webpage before we can start our client.
PlayFab uses a “CloudScript” file so you can add extra functionality to your server/client.
And we need to add some functions for our client to work properly.
Go to “Automation” – “Revisions” and select “Upload a new revision”.

You will find the file to upload here: playfab\CloudScript.js
The functions that I added can be found at the bottom of the file

The only thing you might want to change is the maximum amount of players you want to be able to connect to one server.

Save and deploy the new file.

Again back to unity.
For the client you do not need to build, you can just hit play in unity.

The console will first show you the regions, sorted by the least latency.

Then it will request to power up a new server in the best region

And finally it will get the IP address and the port of that server

You will get that information in Client.cs and could then connect to the server with the network libary of your choice.

At the playfab webpage you can also see that a server was now powered on

If you start the unity client again (fast enough before the server shuts down again) the logs will look different

Because now the server is already running.

If you start servers too often you might get this:
“MultiplayerServerTooManyRequests – NoHostsAvailableInRegion – No Hosts available in regions ‘NorthEurope’, please retry.” The reason is that you earlier set the maximum amount of servers per region. If you need more serves you can edit your build at the playfab webpage.

And that’s it!