Matchmaking¶

Matchmaking is the process of connecting game users in online games so that they can play together, providing a balanced gaming experience by matching them with opponents of similar skill levels.

Getting started¶

There are two main ways to use matchmaking at Hive .

Hive SDK\n2. Hive Server API

Here, we guide you on the Hive SDK method.

To use Hive SDK for matchmaking, you must first follow these steps.

For detailed information on the matching method and the number of matches, please refer to the console guide above.

Overall flow of the Matchmaking SDK¶

When implementing the matchmaking feature, please refer to the following flow.

Match request¶

Requesting a match. A request is needed for each user, and the match information corresponding to matchId must be registered in the Hive console in advance. You also need to request the score point (an integer from 0 to less than 10^10) and additional information extraData (information within 256 characters such as nickname, level, country, etc.) to be used in the match.

Note

When requesting a match again while already in the process of matching, the existing match will not be interrupted, but an error callback (MatchMakingResponseError) will be delivered. Be sure to check the matching status first using Check Matching Status before requesting a match.

This is an example code for a matching request.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .requestMatchMaking

using hive;
        string matchId = "25";      // matchId registered in the console
        int point = 300;            // points used for the match
        string extraData = "your extraData";    // additional information to use for the match
        MatchMaking.requestMatchMaking(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveMatchMaking.h"

FString matchId = "25";
int32 point = 300;
FString extraData = "your extraData";

FHiveMatchMaking::RequestMatchMaking(matchId, point, extraData, FHiveMatchMakingOnRequestMatchMakingDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    if (Result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API Reference: MatchMaking ::requestMatchMaking

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string matchId = "25";          // matchId registered in the console
        int point = 300;                // points used for the match
        string extraData = "your extraData";    // additional information to use for the match

        MatchMaking::requestMatchMaking(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingData data) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMaking.requestMatchMaking

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // The matchId registered in the console
        val point = 300             // Points used for the match
        val extraData = "your extraData";   // Additional information to use for the match
        MatchMaking.requestMatchMaking(matchId, point, extraData, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking .requestMatchMaking

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // matchId registered in the console
        int point = 300;                // points used for the match
        String extraData = "your extraData";    // additional information to be used for the match
        MatchMaking.INSTANCE.requestMatchMaking(matchId, point, extraData, (result, data) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId = "25"                  // matchId registered in the console
let point = 300                     // points used for the match
let extraData = "your extraData"    // additional information to use for the match
MatchMakingInterface.requestMatchMaking(matchId: matchId, point: point, extraData: extraData) { result, data in
        if result.isSuccess() {
        // call successful
        }
        else {
        // Call failed. See error code below
        }
}

API Reference: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSString *matchId = @"25";                  // matchId registered in the console
NSInteger point = 300;                      // points used for the match
NSString *extraData = @"your extraData";    // additional information to be used for the match

[MatchMakingInterface requestMatchMakingWithMatchId:matchId
                                              point:point
                                          extraData:extraData
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

The result of calling the requestMatchMatking() and getRequestingStatus() methods returns a MatchMakingData object.

Structure of the MatchMakingData object¶

Field Name	Description	Type
matchPlayerId	The playerId of the requested user	Long
matchGameIndex	Match game index	Int
matchId	The requested match ID	Int
requestStatus	Match request status (`requested`: Matching requested, `notRequested`: Not requested (or, no ongoing match that has already been matched))	String
requestTimeUtc	Match request time	String
requestPoint	Match score	Int
requestExtraData	Additional information provided during the match request	String
matchingStatus	Match progress status (`matchingInProgress`: Matching in progress, `timeout`: Matching not completed within the time limit, `matched`: Matching successful)	String

Check Matching status¶

Checking the user's matching status. It returns one of the following three matching statuses.

Matching in progress
Matching successful
Timeout

Matching in progress¶

If the status is Matching in Progress, you should repeatedly call this method to check if it has reached the Matching Successful status. It is recommended to call at intervals of 3 to 10 seconds. Depending on the characteristics of the app implementation, it is also possible to increase the time interval further.

Matching success¶

If the status is match successful, the developer's game will be launched. In other words, since the Hive SDK has connected users who will play the game together, these users will enjoy the game implemented by the developer together.

Timeout¶

If the status is a timeout (matchingStatus: timeout), you need to delete the match and request the match again.

The following is an example code for checking the matching status.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .getRequestingStatus

using hive;
        string matchId = "25";      // The matchId registered in the console
        MatchMaking.getRequestingStatus(matchId, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::GetRequestingStatus(matchId, FHiveMatchMakingOnGetRequestingStatusDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API Reference: MatchMaking ::getRequestingStatus

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string matchId = "25";          // Registered matchId in the console

        MatchMaking::getRequestingStatus(matchId, [=](ResultAPI const & result, MatchMakingData data) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMaking.getRequestingStatus

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // The matchId registered in the console
        MatchMaking.getRequestingStatus(matchId, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking.INSTANCE .getRequestingStatus

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // The matchId registered in the console
        MatchMaking.INSTANCE.getRequestingStatus(matchId, (result, data) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMakingInterface.getRequestingStatus

import HIVEService
let matchId = "25"          // The matchId registered in the console
MatchMakingInterface.getRequestingStatus(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    } else {
        // Call failed. See error code below
    }
}

API Reference: HIVEMatchMaking getRequestingStatus

#import "HIVEService.h"
NSString *matchId = @"25";          // Registered matchId in the console

[MatchMakingInterface getRequestingStatusWithMatchId:matchId
                                          completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

Delete Matches¶

Deleting the match. The match must be deleted if it meets one or more of the following conditions.

If the user cancels the match
If the match status is timed out
If the game between users is completed normally
- After updating the game results (rank, score, win/loss, etc.) data on the game server, a request to delete the match should be made

This is an example code for deleting a match.

UnityUnreal EngineC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .deleteRequesting

using hive;
        string matchId = "25";      // The matchId registered in the console
        MatchMaking.deleteRequesting(matchId, (ResultAPI result) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnDeleteRequestingDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API Reference: MatchMaking ::deleteRequesting

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        string matchId = "25";          // Registered matchId in the console

        MatchMaking::deleteRequesting(matchId, [=](ResultAPI const & result) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMaking.deleteRequesting

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // The matchId registered in the console
        MatchMaking.deleteRequesting(matchId, object : MatchMaking.MatchMakingResultListener {
                    override fun onMatchMakingResult(result: ResultAPI) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // Registered matchId in the console
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = "25"          // The matchId registered in the console
MatchMakingInterface.deleteRequesting(matchId: matchId) { result in
    if result.isSuccess() {
        // call successful
    } else {
        // Call failed. See error code below
    }
}

API Reference: HIVEMatchMaking deleteRequesting

#import "HIVEService.h"
NSString *matchId = @"25";          // Registered matchId in the console

[MatchMakingInterface deleteRequestingWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

Error codes¶

Error Code	Message	Description
NEED_INITIALIZE	MatchMakingNotInitialized	If the SDK Setup is not done (AuthV4.setup)
INVALID_SESSION	MatchMakingNeedSignIn	If not signed in
RESPONSE_FAIL	MatchMakingResponseError	If the API call fails due to incorrect parameters, due to network issues, or if a matching request is made while already in a matching request state