Unreal integration
Coming soon
Unity integration
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.
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.
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 ParticipateInMatchAsync().
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.
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: Optional parameter that provides additional data for user participation. The default value is null.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
maxUsers (int): Designates the maximum number of users permitted in the matchmaking process.
isStarted (bool): Indicates if the matchmaking process has been initiated.
votingEnabled (bool): Defines whether voting is permitted during the matchmaking process.
oncePerUserVoting (bool): Dictates whether a user can only vote once throughout the matchmaking process.
createdBy (string): The identifier of the user who initiated the matchmaking process. This value is updated by the backend.
updatedBy (string): The identifier of the user who last updated the matchmaking data. This value is updated by the backend.
createdAt (long): The timestamp denoting the creation time of the match. This value is updated by the backend.
updatedAt (long): The timestamp marking the most recent update of the matchmaking data. This value is updated by the backend.
participants (list of strings): Contains user identifiers of all participants involved in the matchmaking process.
votes (list of Vote objects): Stores the votes cast during the matchmaking process.
participantsScore: A dictionary that maps participant identifiers to their respective scores during the matchmaking process.
participantsPayload: A dictionary that maps participant identifiers to their respective optional payload data during the matchmaking process.
Once the match fills up, it either begins automatically if matchFillBased is selected, or manually by invoking StartMatchAsync().
If votingEnabled is true, non-participating users can vote for participating users through VoteForMatchAsync(). To retrieve matches with voting enabled, use GetVoteOpenMatchesAsync().
If votingEnabled is false, participating users can submit their scores using SubmitMatchScoreAsync().
The match ends automatically if finishType is set to scoreSubmitBased once all users have submitted their scores, or it can be ended manually via FinishMatchAsync() in case the manual setting was submitted at the start.
The finished matches can be requested by calling the GetFinishedMatchesAsync() method.
participateMatchAchievements: A list of achievements with rewards given to users who participate in the match.
startMatchAchievements: A list of achievements with rewards given to the user who starts the match.
voteForMatchAchievements: A list of achievements with rewards given to the user who votes for other users.
winnerMatchAchievements: A list of achievements with rewards given to users who win the match.
finishMatchAchievements: A list of achievements with rewards given to all users who participate in the match upon its conclusion.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
try
{
// Create a match configuration
MatchmakingData matchConfig = new MatchmakingData
{
// fill matchConfig details
};
// Create optional participation payload
Dictionary<string, object> participatePayload = new Dictionary<string, object>
{
{"ExtraData1", "Value1"},
{"ExtraData2", "Value2"}
};
// Call the CreateMatchAsync method
var matchmakingResult = await MatchmakingModule.I.CreateMatchAsync(
matchConfig,
true,
participatePayload);
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchConfig is null: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID
string matchId = "your_match_id";
// Create optional participant payload
Dictionary<string, object> participantPayload = new Dictionary<string, object>
{
{"ExtraData1", "Value1"},
{"ExtraData2", "Value2"}
};
// Call the ParticipateInMatchAsync method
string participatedMatchId = await MatchmakingModule.I.ParticipateInMatchAsync(
matchId,
participantPayload);
// Use the participatedMatchId in your game logic
// ...
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID
string matchId = "your_match_id";
// Call the StartMatchAsync method
string startedMatchId = await MatchmakingModule.I.StartMatchAsync(matchId);
// Use the startedMatchId in your game logic
// ...
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID and participant ID
string matchId = "your_match_id";
string participantId = "your_participant_id";
// Call the VoteForMatchAsync method
string votedMatchId = await MatchmakingModule.I.VoteForMatchAsync(
matchId,
participantId);
// Use the votedMatchId in your game logic
// ...
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchId or ParticipantId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID and score
string matchId = "your_match_id";
long score = 10000; // your score
// Call the SubmitMatchScoreAsync method
string submittedScoreMatchId = await MatchmakingModule.I.SubmitMatchScoreAsync(
matchId,
score);
// Use the submittedScoreMatchId in your game logic
// ...
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID
string matchId = "your_match_id";
// Call the FinishMatchAsync method
string finishedMatchId = await MatchmakingModule.I.FinishMatchAsync(matchId);
// Use the finishedMatchId in your game logic
// ...
}
catch (ArgumentNullException ex)
{
Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the limit and optionally the startAfter match ID
int limit = 10;
string startAfter = "some_match_id"; // Or leave empty for the default value
// Call the GetJoinOpenMatchesAsync method
List<MatchmakingData> openMatches =
await MatchmakingModule.I.GetJoinOpenMatchesAsync(limit, startAfter);
// Iterate over the openMatches and use in your game logic
foreach (MatchmakingData match in openMatches)
{
// Your game logic here
// ...
}
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the limit and optionally the startAfter match ID
int limit = 10;
string startAfter = "some_match_id"; // Or leave empty for the default value
// Call the GetVoteOpenMatchesAsync method
List<MatchmakingData> openVoteMatches =
await MatchmakingModule.I.GetVoteOpenMatchesAsync(limit, startAfter);
// Iterate over the openVoteMatches and use in your game logic
foreach (MatchmakingData match in openVoteMatches)
{
// Your game logic here
// ...
}
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the limit and optionally the startAfter match ID
int limit = 10;
string startAfter = "some_match_id"; // Or leave empty for the default value
// Call the GetFinishedMatchesAsync method
List<MatchmakingData> finishedMatches =
await MatchmakingModule.I.GetFinishedMatchesAsync(limit, startAfter);
// Iterate over the finishedMatches and use in your game logic
foreach (MatchmakingData match in finishedMatches)
{
// Your game logic here
// ...
}
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}try
{
// Define the match ID
string matchId = "some_match_id";
// Call the GetFinishedMatchByIdAsync method
MatchmakingData finishedMatch =
await MatchmakingModule.I.GetFinishedMatchByIdAsync(matchId);
// Use the finishedMatch in your game logic
// ...
}
catch (OperationCanceledException ex)
{
Debug.Log("Operation was cancelled: " + ex.Message);
}
catch (Exception ex)
{
Debug.Log("Failed to get the match: " + ex.Message);
}Integration Guide