Matchmaking¶

Matchmaking is the process of connecting game users in online games so 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 in Hive:

1. Hive SDK
2. Hive Server API

This guide will focus on using the Hive SDK.

To use matchmaking with the Hive SDK, you must first follow these steps:

1. Register a project in the Hive Console App Center
2. Create a match in the Hive Console Matchmaking

For detailed information on matching methods and the number of players, please refer to the console guides above.

Overall Flow of the Matchmaking SDK¶

Refer to the following flow when implementing matchmaking features.

Match Request¶

A match request is made. Each user needs to make a request, and the match information corresponding to matchId must be registered in the Hive console in advance. You also need to provide the score point (an integer from 0 to less than 10^10) to be used in the match, as well as additional information extraData (nickname, level, country, etc., limited to 256 characters) as parameters for the request.

Below is an example code for a match request.

using hive;
        string matchId = "25";      // Registered matchId in the console
        int point = 300;            // Score used for the match 
        string extraData = "your extraData";    // Additional information to be used in 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;

        string matchId = "25";          // Registered matchId in the console
        int point = 300;                // Score used for the match
        string extraData = "your extraData";    // Additional information to be used in 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"          // Registered matchId in the console
        val point = 300             // Score used for the match
        val extraData = "your extraData";   // Additional information to be used in 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;
        String matchId = "25";          // Registered matchId in the console
        int point = 300;                // Score used for the match
        String extraData = "your extraData";    // Additional information to be used in 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 = "25"                  // Registered matchId in the console
let point = 300                     // Score used for the match
let extraData = "your extraData"    // Additional information to be used in 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"
NSString *matchId = @"25";                  // Registered matchId in the console
NSInteger point = 300;                      // Score used for the match
NSString *extraData = @"your extraData";    // Additional information to be used in 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
    }
}];

requestMatchMaking(), getRequestingStatus() method calls return a MatchMakingData object.

Structure of the MatchMakingData Object¶

Checking Match Status¶

Check the user's match status. It returns one of the following three statuses:

1. Matching in progress
2. Matching successful
3. Timeout

Matching in Progress¶

If the status is matching in progress, you should repeatedly call this method to check if the status has changed to matching successful. It is recommended to call this method at intervals of 3 to 10 seconds. Depending on the app's implementation characteristics, you can also extend the time interval further.

Matching Successful¶

If the status is matching successful, launch the developer's game. This means that the Hive SDK has connected the users who will play the game together, allowing them to enjoy the game developed by the developer.

Timeout¶

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

Here is an example code for checking match status.

using hive;
        string matchId = "25";      // Registered matchId 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;

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

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // Registered matchId 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;
        String matchId = "25";          // Registered matchId 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"          // Registered matchId 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"
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
    }
}];

Deleting Matches¶

This process deletes a match. You should delete a match if one or more of the following conditions apply:

• The user has canceled the match.
• The match status is timeout.
• The game between users has been completed normally.
  • You should request to delete the match after updating the game results (rankings, scores, win/loss status, etc.) on the game server.

Here is an example code for deleting a match.

using hive;
        string matchId = "25";      // Registered matchId 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;

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

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // Registered matchId 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;
        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
                    }
});

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

#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¶