This sample demonstrates how to implement a Quick Match using PlayFab's services. This feature will allow the players to play a Match instantly, without the need of looking for a specific Match.
Before starting explaining how this feature works, lets see how the game was implemented.
Regarding the Quick Match feature, we can add the next information:
- Tic-Tac-Toe game: this is implemented in this project. Here we've the Quick Match button, where players can start a match.
- Tic-Tac-Toe Function App: we've implemented this here.
Before configuring this project, first ensure the following prerequisites have been completed:
- Read and complete the PlayFab configuration.
- Read and complete the Azure Function configuration.
- Read and complete the Cosmos DB configuration.
The P1's Quick Match implementation is a three part process:
- The first part consists of Step 01 to Step 03. Here the P1 creates a Matchmaking Ticket for starting a match against a random player, and then polls the PlayFab's services to get the Ticket status until a match has been assigned.
- The second part includes Steps 04 to 09. The Tic-Tac-Toe game, using the CreateSharedGroup Azure Function, creates a Shared Group using the PlayFab's Services, in order to have a storage where the Game's Data will be stored later. After creating it, the Azure Function returns the Shared Group Data to the Tic-Tac-Toe game for using it in further steps.
- The last part consists in the Step 10, where the Tic-Tac-Toe game starts the Start Match process.
The process starts when the P1 press the Quick match button.
Then, we use the Matchmaking Handler for creating a Matchmaking Ticket.
In this step, we use the PlayFab's API for creating the Matchmaking Ticket (link), setting all the necessary request's properties using the QueueConfiguration object we set when creating the current MatchmakingHandler class (check this here).
In the next step, we poll the ticket status using the EnsureGetMatchmakingTicketStatus method from the MatchmakingHandler class. This method uses the GetMatchmakingTicketStatus method from the same class, where we call the GetMatchmakingTicket PlayFab API's method for getting the Ticket's information, where the Ticket Status is included.
Something important to mention here is that the GetMatchmakingTicket API's method has a time-polling constraint of 10 polls per minute (i.e., one every 6 seconds). Due to this, we have added this condition in the EnsureGetMatchmakingTicketStatus method. You can read more about this here.
Once we've ensured there is a match, the Tic-Tac-Toe game determines if we're the first player to play (P1) using this method. In case it's true, we'll be in charge of creating the Shared Group the game will be using later for storing its information. For doing so, we'll be using the Create method from the Shared Group Handler class. This method allows us to perform a request to the CreateSharedGroup Azure Function, which purpose is explained here.
This is the implementation of the Create method:
public IEnumerator Create(string sharedGroupId)
{
var request = GetExecuteFunctionRequest(
"CreateSharedGroup",
new CreateSharedGroupRequest { SharedGroupId = sharedGroupId });
PlayFabCloudScriptAPI.ExecuteFunction(request,
(result) =>
{
// handle OnSuccess code.
},
(error) =>
{
// handle OnError code.
}
);
yield return WaitForExecution();
}NOTE: In this method we're using the GetExecuteFunctionRequest from a custom Request Handler class for creating the request we'll be sending to our Azure Function.
One of the Azure Functions we use in this process is the CreateSharedGroup Azure Function, which allows us to create a Shared Group in the PlayFab's service, add the current player as a Shared Group member, and update and return the Shared Group Data.
This is the implementation of the CreateSharedGroup Azure Function:
[FunctionName("CreateSharedGroup")]
public static async Task<TicTacToeSharedGroupData> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequestMessage req)
{
var context = await FunctionContext<CreateSharedGroupRequest>.Create(req);
var playerOne = context.CallerEntityProfile.Lineage.MasterPlayerAccountId;
// (1)
var sgdResponse = await SharedGroupDataUtil.CreateAsync(context.AuthenticationContext, context.FunctionArgument.SharedGroupId);
// (2)
await SharedGroupDataUtil.AddMembersAsync(context.AuthenticationContext, context.FunctionArgument.SharedGroupId, new List<string> { playerOne });
var sharedGroupData = new TicTacToeSharedGroupData
{
SharedGroupId = sgdResponse.SharedGroupId,
Match = new Match { PlayerOneId = playerOne }
};
// (3)
return await SharedGroupDataUtil.UpdateAsync(context.AuthenticationContext, sharedGroupData);
}In this Azure Function we use the next PlayFab's API methods, which we've implemented in the SharedGroupDataUtil class:
(1) Create Shared Group, implemented here.
(2) Add member to Shared Group, implemented here.
(3) Update Shared Group, implemented here.
The other function we're using in this process is the GetSharedGroup Azure Function, which allows us to retrieve the data stored in the Shared Group instance.
This is the implementation of the GetSharedGroup Azure Function:
[FunctionName("GetSharedGroup")]
public static async Task<TicTacToeSharedGroupData> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequestMessage req)
{
var context = await FunctionContext<GetSharedGroupRequest>.Create(req);
// (1)
return await SharedGroupDataUtil.GetAsync(context.AuthenticationContext, context.FunctionArgument.SharedGroupId);
}In this Azure Function we use the next PlayFab's API methods, which we've implemented in the SharedGroupDataUtil class:
(1) Get Shared Group, implemented here.
The P2 Quick Match follows a three part process:
- The first part consists in the Step 01 to Step 03. Here, P2 creates a Matchmaking Ticket for starting a match against a random player, and then polls the PlayFab's services to get the Ticket's status, until a match has been assigned.
- The second part includes the Steps 04 to 07. In this part, the Tic-Tac-Toe game triggers the JoinMatch Azure Function to add the player to the current match as P2, and returns an updated TicTacToeSharedGroupData object for use in further steps.
- The last part consists in the Step 08, where the Tic-Tac-Toe game starts the Start Match process.
This is implemented in the same way as the P1 process. You can check it here
This is implemented in the same way as for the P1 process. You can check it here.
The next step consists in joining into an existing Match. For doing this, we are using the JoinMatch method from the MatchHandler class. This allows us to perform request calls to the JoinMatch Azure Function (which we'll explain later).
Disclaimer: This function is meant to be used in a process where only two players are matched to play against, using the PlayFab's Matchmaking feature, where only one of these players will be calling it. In case you need a similar solution but for a situation where more than two players will (or could) be calling this function, we strongly recommend to check the JoinMatchLobby function of this project, as there we manage some situations that could be happening in those cases, as, for example, a race condition situation.
With this function we are able to join the P2 to an existing Shared Group.
This is the implementation of the JoinMatch Azure Function:
[FunctionName("JoinMatch")]
public static async Task<TicTacToeSharedGroupData> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequestMessage req)
{
var context = await FunctionContext<JoinMatchRequest>.Create(req);
var playerId = context.CallerEntityProfile.Lineage.MasterPlayerAccountId;
// (1)
await SharedGroupDataUtil.AddMembersAsync(context.AuthenticationContext, context.FunctionArgument.SharedGroupId, new List<string> { playerId });
return // TicTacToeSharedGroupData
}In this Azure Function we use the next PlayFab's API methods, which we've implemented in the SharedGroupDataUtil class:
(1) Add member to Shared Group, implemented here.