配对¶

matchmaking 是在在线游戏中将游戏用户连接在一起以便他们可以一起玩的过程，通过将他们与技能水平相似的对手匹配来提供平衡的游戏体验。

开始使用¶

在Hive中使用匹配的主要方式有两种：

Hive SDK\n2. Hive 服务器 API

本指南将重点介绍使用 Hive SDK。

要使用 Hive SDK 的匹配功能，您必须首先遵循以下步骤：

有关匹配方法和玩家数量的详细信息，请参考上面的控制台指南。

匹配 SDK 的整体流程¶

在实现匹配功能时，请参考以下流程。

匹配请求¶

发起匹配请求。每个用户需要发出请求，且与matchId对应的匹配信息必须提前在Hive控制台中注册。您还需要提供将在匹配中使用的分数point（一个从0到小于10^10的整数），以及额外信息extraData（昵称、等级、国家等，限制为256个字符）作为请求的参数。

Note

如果您在已有匹配请求的情况下再次请求匹配，现有的匹配将不会被取消，但会发送错误回调（MatchMakingResponseError）。在再次请求匹配之前，请务必先检查匹配状态。

以下是匹配请求的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .requestMatchMaking

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

API 参考: MatchMaking ::requestMatchMaking

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

        string matchId = "25";          // 注册的 matchId 在控制台中
        int point = 300;                // 用于比赛的分数
        string extraData = "your extraData";    // 比赛中使用的附加信息

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

API 参考: MatchMaking.requestMatchMaking

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // 在控制台注册的 matchId
        val point = 300             // 用于比赛的分数
        val extraData = "your extraData";   // 用于比赛的附加信息
        MatchMaking.requestMatchMaking(matchId, point, extraData, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // 调用成功
                            } else {
                                    // 调用失败。请参见下面的错误代码
                            }
                    }
})

API 参考: MatchMaking .requestMatchMaking

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // 控制台中注册的 matchId
        int point = 300;                // 用于比赛的分数
        String extraData = "your extraData";    // 用于比赛的附加信息
        MatchMaking.INSTANCE.requestMatchMaking(matchId, point, extraData, (result, data) -> {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参阅下面的错误代码
                    }
});

API 参考: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId = "25"                  // 注册的 matchId 在控制台中
let point = 300                     // 用于比赛的分数
let extraData = "your extraData"    // 用于比赛的附加信息
MatchMakingInterface.requestMatchMaking(matchId: matchId, point: point, extraData: extraData) { result, data in
        if result.isSuccess() {
        // 调用成功
        }
        else {
        // 调用失败。请参见下面的错误代码
        }
}

API 参考: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSString *matchId = @"25";                  // 控制台中注册的 matchId
NSInteger point = 300;                      // 用于比赛的分数
NSString *extraData = @"your extraData";    // 用于比赛的附加信息

[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() 方法调用返回一个 MatchMakingData 对象。

MatchMakingData对象的结构¶

字段名称	描述	类型
matchPlayerId	请求用户的玩家ID	Long
matchGameIndex	匹配游戏索引	Int
matchId	请求的匹配ID	Int
requestStatus	匹配请求状态 (`requested`: 匹配请求， `notRequested`: 未请求（或没有进行中的匹配）)	String
requestTimeUtc	匹配请求时间	String
requestPoint	匹配得分	Int
requestExtraData	在匹配请求期间提供的附加信息	String
matchingStatus	匹配进度状态 (`matchingInProgress`: 匹配进行中， `timeout`: 在时间限制内未完成匹配， `matched`: 匹配成功)	String

检查匹配状态¶

检查用户的匹配状态。它返回以下三种状态之一：

匹配进行中
匹配成功
超时

匹配进行中¶

如果状态为匹配进行中，您应该重复调用此方法以检查状态是否已更改为匹配成功。建议每3到10秒调用一次此方法。根据应用程序的实现特性，您还可以进一步延长时间间隔。

匹配成功¶

如果状态是 匹配成功，启动开发者的游戏。这意味着 Hive SDK 已经将将要一起玩游戏的用户连接起来，让他们能够享受开发者开发的游戏。

超时¶

如果状态是超时 (matchingStatus: timeout)，您需要删除匹配并再次请求匹配。

这是一个检查匹配状态的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .getRequestingStatus

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

API 参考: 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()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参见下面的错误代码
                    }
});

API 参考: MatchMaking.getRequestingStatus

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // 注册的 matchId 在控制台中
        MatchMaking.getRequestingStatus(matchId, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // 调用成功
                            } else {
                                    // 调用失败。请参见下面的错误代码
                            }
                    }
})

API 参考: MatchMaking.INSTANCE .getRequestingStatus

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

API 参考: MatchMakingInterface.getRequestingStatus

import HIVEService
let matchId = "25"          // 在控制台注册的 matchId
MatchMakingInterface.getRequestingStatus(matchId: matchId) { result, data in
    if result.isSuccess() {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}

API 参考: HIVEMatchMaking getRequestingStatus

#import "HIVEService.h"
NSString *matchId = @"25";          // 控制台中注册的 matchId

[MatchMakingInterface getRequestingStatusWithMatchId:matchId
                                          completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}];

删除匹配项¶

此过程会删除一个比赛。如果满足以下一个或多个条件，则应删除比赛：

用户已取消比赛。
比赛状态为超时。
用户之间的游戏已正常完成。
- 在游戏服务器上更新游戏结果（排名、分数、胜负状态等）后，您应该请求删除比赛。

这是一个删除匹配项的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .deleteRequesting

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

API 参考: MatchMaking ::deleteRequesting

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

        string matchId = "25";          // 在控制台中注册的 matchId

        MatchMaking::deleteRequesting(matchId, [=](ResultAPI const & result) {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参见下面的错误代码
                    }
});

API 参考: MatchMaking.deleteRequesting

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // 在控制台注册的 matchId
        MatchMaking.deleteRequesting(matchId, object : MatchMaking.MatchMakingResultListener {
                    override fun onMatchMakingResult(result: ResultAPI) {
                            if (result.isSuccess) {
                                    // 调用成功
                            } else {
                                    // 调用失败。请参见下面的错误代码
                            }
                    }
})

API 参考: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // 注册的 matchId 在控制台中
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参见下面的错误代码
                    }
});

API 参考: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = "25"          // 在控制台中注册的 matchId
MatchMakingInterface.deleteRequesting(matchId: matchId) { result in
    if result.isSuccess() {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}

API 参考: HIVEMatchMaking deleteRequesting

#import "HIVEService.h"
NSString *matchId = @"25";          // 控制台中注册的 matchId

[MatchMakingInterface deleteRequestingWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}];

错误代码¶

错误代码	消息	描述
NEED_INITIALIZE	MatchMakingNotInitialized	如果SDK设置未完成（AuthV4.setup）
INVALID_SESSION	MatchMakingNeedSignIn	如果用户未登录
RESPONSE_FAIL	MatchMakingResponseError	如果API调用因参数错误、网络问题而失败，或在已处于匹配请求状态时发起匹配请求