The Matchmaking Module acts as the central management system for all matchmaking procedures within the PLAY. It boasts an array of functionalities designed to facilitate the initiation, participation, voting, and termination of matches.
The primary functionality of the matchmaking module is to allow PvP matchmaking for synchronous gameplay.
Additional functionality referred to as "Voting" throughout this document allows for a matchmaking system wherein the winner is determined by votes cast by other players.
Therefor the Matchmaking module can be utilized for either PvP synchronous gameplay matches, or for the voting approach - the two styles do not have both be utilized.
Using the MatchmakingModule
type (string): Identifies the match's type. Currently, only "default" is supported.
finishType (string): Describes how a match concludes, either through manual input or based on score submission.
startType (string): Outlines how a match commences, either manually or based on match filling.
Lifecycle of a Match
Initially, all getter methods return empty lists, implying no current match.
Here's a step-by-step overview of a match's lifecycle:
A match is created with the settings provided via CreateMatchAsync(). By default, the user who created the match becomes a participant if participateInOnCreate is set to true.
GetJoinOpenMatchesAsync() returns the newly created match.
Other users join the match using
Additional Features
The backend currently supports several features that the Unity SDK does not:
participateFee: An array of currencies. Users need to pay with these provided currencies to participate in the match.
voteFee: An array of currencies. Users need to pay with these provided currencies to vote for other users.
createMatchAchievements: A list of achievements with rewards given to the user who creates the match.
Should you require any of the above features or have requests for additional features, please inform the PLAY team.
CreateMatchAsync
The CreateMatchAsync method within the MatchmakingModule class is designed to asynchronously create a matchmaking match, based on the provided match configuration.
This method offers an asynchronous operation, returning a Task<MatchmakingData>, which represents the created match.
MatchmakingData matchConfig: The configuration for the match to be created. This cannot be null.
bool participateInOnCreate: Optional parameter that determines whether the user participates in the match upon its creation. The default value is true.
Dictionary<string, object> participatePayload
ArgumentNullException: Thrown when matchConfig is null.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the CreateMatchAsync method:
Ensure to handle the possible exceptions for a smooth user experience. Always make sure matchConfig is not null before passing it to the method.
ParticipateInMatchAsync
The ParticipateInMatchAsync method in the MatchmakingModule class allows a user to asynchronously participate in a matchmaking match, identified by the provided match ID.
The method performs an asynchronous operation, returning a Task<string> that signifies the ID of the match that the user has participated in.
string matchId: The ID of the match to participate in. This value cannot be null or empty.
Dictionary<string, object> participantPayload: Optional parameter that provides additional data for user participation. The default value is null.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the ParticipateInMatchAsync method:
Be sure to handle possible exceptions to ensure a seamless user experience. Always confirm that matchId is not null or empty before passing it to the method.
StartMatchAsync
The StartMatchAsync method in the MatchmakingModule class allows for asynchronously starting a matchmaking match, identified by the provided match ID.
The method provides an asynchronous operation, returning a Task<string> that represents the ID of the match that has been started.
string matchId: The ID of the match to start. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the StartMatchAsync method:
Always handle possible exceptions to ensure a seamless user experience. Make sure that matchId is not null or empty before passing it to the method.
VoteForMatchAsync
The VoteForMatchAsync method in the MatchmakingModule class enables the casting of a vote asynchronously for a matchmaking match, identified by the provided match ID and participant ID.
The method conducts an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the vote has been cast.
string matchId: The ID of the match to vote for. This value cannot be null or empty.
string participantId: The ID of the participant casting the vote. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
ArgumentNullException: Thrown when matchId or participantId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the VoteForMatchAsync method:
Always handle possible exceptions to ensure a seamless user experience. Ensure both matchId and participantId are not null or empty before passing them to the method.
SubmitMatchScoreAsync
The SubmitMatchScoreAsync method in the MatchmakingModule class enables a user to asynchronously submit the score for a matchmaking match, identified by the provided match ID.
The method provides an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the score has been submitted.
string matchId: The ID of the match for which the score is being submitted. This value cannot be null or empty.
long score: The score to be submitted for the match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the SubmitMatchScoreAsync method:
Always handle possible exceptions to ensure a seamless user experience. Make sure matchId is not null or empty before passing it to the method.
FinishMatchAsync
The FinishMatchAsync method in the MatchmakingModule class allows a user to asynchronously finish a matchmaking match, identified by the provided match ID.
The method executes an asynchronous operation, returning a Task<string> that represents the ID of the match that has been finished.
string matchId: The ID of the match to finish. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.
Here's an example usage of the FinishMatchAsync method:
Always handle possible exceptions to ensure a seamless user experience. Confirm that matchId is not null or empty before passing it to the method.
GetJoinOpenMatchesAsync
The GetJoinOpenMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of open matches that a user can join.
The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can join.
int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for joining.
Here's an example usage of the GetJoinOpenMatchesAsync method:
Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.
GetVoteOpenMatchesAsync
The GetVoteOpenMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of open matches that a user can vote on. Some matches may have voting enabled, allowing users to vote for match participants.
The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can vote on.
int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for voting.
Here's an example usage of the GetVoteOpenMatchesAsync method:
Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.
GetFinishedMatchesAsync
The GetFinishedMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of finished matches.
The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of finished matches.
int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the finished matches for the current app.
Here's an example usage of the GetFinishedMatchesAsync method:
Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.
GetFinishedMatchByIdAsync
The GetFinishedMatchByIdAsync method in the MatchmakingModule class allows for asynchronously retrieving data of a finished match by its ID. If the match does not exist or is from another application, the method throws an exception.
The method executes an asynchronous operation, returning a Task<MatchmakingData> that represents the data of the finished match.
string matchId: The ID of the finished match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
Task<MatchmakingData>: A task that represents the asynchronous operation. The task result contains the MatchmakingData of the finished match.
Here's an example usage of the GetFinishedMatchByIdAsync method:
Always handle possible exceptions to ensure a seamless user experience. You can modify the matchId parameter to retrieve the data of any specific finished match by its ID.