Individual Matchmaking

Personal matchmaking is used when a user wants to participate in a game alone.

Matchmaking operation flow in SDK¶

When implementing personal matchmaking with Hive SDK, the overall flow of operation is as shown in the diagram below.

Match request¶

Requesting matching for each user.

Before making the request, you must register the match information corresponding to matchId in the Hive console.

When requesting a match, you need to provide 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.) as arguments.

Here is an example code for a matching request.

using hive;
        int 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 <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        int 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::requestMatchMaking(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingData data) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

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

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        int 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
                    }
});

import HIVEService
let matchId: Int = 25                   // matchId registered in the console
let point: Int = 300                        // points used for the match
let extraData: String? = "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
        }
}

#import "HIVEService.h"
NSInteger 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.

MatchMakingData object structure¶

An object that is returned in response to the matching request and check matching status requests. It includes the information entered during the request and the matching result information.

MatchingResultTeamInfo object structure¶

This is the object that is passed when a team participates in a match and the matching status is matched. It includes the team index and information about the users belonging to the team.

MatchingResultPlayerInfo data structure¶

This is the object that is sent when a user participates in a personal match and the matching status is matched. It contains information about the user who participated in the match.

Check matching status¶

Checking the matching status of users participating in personal matches.

When calling the matching status check method, it returns one of the three matching statuses below.

1. Matching in progress (matchingStatus: matchingInProgress)
2. Matching successful (matchingStatus: matched)
3. Timeout (matchingStatus: timeout)

This is an example code for checking the matching status.

using hive;
        int 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 <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

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

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

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        int 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
                    }
});

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

#import "HIVEService.h"
NSInteger matchId = 25;          // matchId registered in the console

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

Matching in progress¶

If the matching status is In Progress, you need to repeatedly call the method to check the matching status to see if it has reached the Matched state.

It is recommended to call the repeat call cycle at intervals of 3 to 10 seconds. Depending on the characteristics of the app's implementation, it is also possible to extend the time interval.

Matching success¶

If the matching status is Matched, the developer's game will be launched. In other words, users connected through the Hive SDK who are matched can participate in the developer's game.

Timeout¶

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

Delete Matching¶

Deleting the existing match.

You must delete the match when it falls under one or more of the following cases.

• If the user cancels the match
• If the matching status is timeout (matchingStatus: timeout)

• If the game between users is completed normally

  ※ You must request to delete the match after updating the game results (rankings, scores, win/loss status, etc.) on the game server or game client

This is an example code for deleting a match.

using hive;
        int 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 <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        int matchId = 25;           // matchId registered in the console

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

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

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

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

#import "HIVEService.h"
NSInteger matchId = 25;          // matchId registered in the console

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

Error code¶