Unity

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:

1. 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.

2. GetJoinOpenMatchesAsync() returns the newly created match.

3. Other users join the match using ParticipateInMatchAsync().

4. Once the match fills up, it either begins automatically if matchFillBased is selected, or manually by invoking StartMatchAsync().

5. If votingEnabled is true, non-participating users can vote for participating users through VoteForMatchAsync(). To retrieve matches with voting enabled, use GetVoteOpenMatchesAsync().

6. If votingEnabled is false, participating users can submit their scores using SubmitMatchScoreAsync().

7. 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.

8. 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 when matchConfig is null.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the CreateMatchAsync method:

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);
}

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 when matchId is null or empty.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the ParticipateInMatchAsync method:

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);
}

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 when matchId is null or empty.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the StartMatchAsync method:

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);
}

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 when matchId or participantId is null or empty.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the VoteForMatchAsync method:

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);
}

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 when matchId is null or empty.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the SubmitMatchScoreAsync method:

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);
}

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 when matchId is null or empty.

• OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the FinishMatchAsync method:

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);
}

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 of MatchmakingData objects, which are the open matches available for joining.

Example

Here's an example usage of the GetJoinOpenMatchesAsync method:

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);
}

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 of MatchmakingData objects, which are the open matches available for voting.

Example

Here's an example usage of the GetVoteOpenMatchesAsync method:

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);
}

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 of MatchmakingData objects, which are the finished matches for the current app.

Example

Here's an example usage of the GetFinishedMatchesAsync method:

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);
}

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 the MatchmakingData of the finished match.

Example

Here's an example usage of the GetFinishedMatchByIdAsync method:

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);
}

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.