Unity
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.
Using the MatchmakingModule
Properties:
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.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.
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 ifparticipateInOnCreate
is set to true.GetJoinOpenMatchesAsync()
returns the newly created match.Other users join the match using
ParticipateInMatchAsync()
.Once the match fills up, it either begins automatically if
matchFillBased
is selected, or manually by invokingStartMatchAsync()
.If
votingEnabled
is true, non-participating users can vote for participating users throughVoteForMatchAsync()
. To retrieve matches with voting enabled, useGetVoteOpenMatchesAsync()
.If
votingEnabled
is false, participating users can submit their scores usingSubmitMatchScoreAsync()
.The match ends automatically if
finishType
is set toscoreSubmitBased
once all users have submitted their scores, or it can be ended manually viaFinishMatchAsync()
in case themanual
setting was submitted at the start.The finished matches can be requested by calling the
GetFinishedMatchesAsync()
method.
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.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.
Should you require any of the above features or have requests for additional features, please inform the PLAY team.
CreateMatchAsync
Description
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.
Parameters
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.CancellationToken cancellationToken
: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.
Exceptions
ArgumentNullException
: Thrown whenmatchConfig
is null.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Exceptions
ArgumentNullException
: Thrown whenmatchId
is null or empty.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Exceptions
ArgumentNullException
: Thrown whenmatchId
is null or empty.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Exceptions
ArgumentNullException
: Thrown whenmatchId
orparticipantId
is null or empty.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Exceptions
ArgumentNullException
: Thrown whenmatchId
is null or empty.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Exceptions
ArgumentNullException
: Thrown whenmatchId
is null or empty.OperationCanceledException
: Thrown when the operation is cancelled via thecancellationToken
.
Example
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
Description
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.
Parameters
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.
Returns
Task<List<MatchmakingData>>
: A task that represents the asynchronous operation. The task result contains a list ofMatchmakingData
objects, which are the open matches available for joining.
Example
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
Description
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.
Parameters
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.
Returns
Task<List<MatchmakingData>>
: A task that represents the asynchronous operation. The task result contains a list ofMatchmakingData
objects, which are the open matches available for voting.
Example
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
Description
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.
Parameters
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.
Returns
Task<List<MatchmakingData>>
: A task that represents the asynchronous operation. The task result contains a list ofMatchmakingData
objects, which are the finished matches for the current app.
Example
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
Description
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.
Parameters
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.
Returns
Task<MatchmakingData>
: A task that represents the asynchronous operation. The task result contains theMatchmakingData
of the finished match.
Example
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.
Last updated