个人匹配

个人匹配用于用户想要单独参与游戏时。

SDK中的 matchmaking 操作流程¶

在使用 Hive SDK 实现个人配对时，操作的整体流程如下面的图所示。

匹配请求¶

请求为每个用户匹配。

在发出请求之前，您必须在Hive控制台中注册与matchId对应的比赛信息。

在请求匹配时，您需要提供分数 point（一个从 0 到小于 10^10 的整数）和额外信息 extraData（256 个字符以内的信息，例如昵称、等级、国家等）作为参数。

Warning

如果在已有匹配进行时再次请求匹配，回调函数将返回错误值（MatchMakingResponseError），而不会停止现有匹配。因此，请务必在请求匹配之前先使用检查匹配状态检查匹配状态。

这是一个匹配请求的示例代码。

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .requestMatchMaking

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 "HiveMatchMaking.h"

int MatchId = 25;                           // 在控制台注册的 matchId
int Point = 300;                            // 用于比赛的积分
FString ExtraData = TEXT("your extraData"); // 用于比赛的附加信息

FHiveMatchMaking::RequestMatchMaking(MatchId, Point, ExtraData, FHiveMatchMakingOnMatchMakingDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    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;

        int 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 = "你的额外数据";   // 用于比赛的附加信息
        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;
        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
                    }
});

API 参考: MatchMakingInterface.requestMatchMaking

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

API 参考: HIVEMatchMaking requestMatchMaking

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

调用requestMatchMatking()和getRequestingStatus()方法的结果返回一个MatchMakingData对象。

MatchMakingData对象结构¶

在响应匹配请求和检查匹配状态请求时返回的对象。它包括请求期间输入的信息和匹配结果信息。

字段名称	描述	类型
requestPlayerId	请求比赛的用户的玩家ID	Long
requestGameIndex	比赛游戏索引	Int
requestMatchId	请求的比赛ID（在Hive控制台中注册的格式）	Int
requestStatus	比赛请求状态（`requested`：已请求比赛，`notRequested`：未请求（或没有已匹配的进行中的比赛））	String
requestTimeUtc	比赛请求时间（例如：2025-01-02T11:13:50.96）	String
requestPoint	比赛分数	Int
requestExtraData	在比赛请求期间提供的额外信息（如果在请求期间使用了extraData，则存在）	String
matchingStatus	比赛进度状态（`matchingInProgress`：匹配进行中，`timeout`：在时间限制内未发生匹配，`matched`：匹配成功）	String
matchingType	是否为团队参与或个人参与（如果matchingStatus为matched，则存在）（`team`：团队，`player`：个人，`unknown`：如果没有匹配确认）	String
matchingId	分配给成功匹配的ID（如果matchingStatus为matched，则存在）（例如：539:21_2025-01-02T11:45:55.25_1）	String
matchingPlayerInfoList	匹配用户的信息列表 MatchingResultPlayerInfo（如果matchingStatus为matched，则存在，个人参与时存在）	Array
matchingTeamInfoList	团队信息列表 MatchingResultTeamInfo（如果matchingStatus为matched，则存在，团队参与时存在）	Array

MatchingResultTeamInfo 对象结构¶

这是在团队参加比赛并且匹配状态为匹配时传递的对象。它包括团队索引和属于该团队的用户信息。

字段名称	描述	类型
teamIndex	团队的唯一索引	Int
playerInfos	属于团队的用户信息列表 MatchingResultPlayerInfo	Array

Note

在请求个人匹配时，既可以选择个人匹配，也可以选择团队匹配，根据比赛结果，将提供相应的 matchingPlayerInfoList 或 matchingTeamInfoList。

MatchingResultPlayerInfo 数据结构¶

这是在用户参与个人比赛并且匹配状态为匹配时发送的对象。它包含有关参与比赛的用户的信息。

字段名称	描述	类型
playerId	匹配用户的 playerId	Long
point	匹配用户的点数	Int
extraData	匹配用户提供的附加信息（如果用户在请求时使用了 extraData，则存在）	String

检查匹配状态¶

检查参与个人比赛的用户的匹配状态。

调用匹配状态检查方法时，它返回以下三种匹配状态之一。

匹配进行中 (matchingStatus: matchingInProgress)
匹配成功 (matchingStatus: matched)
超时 (matchingStatus: timeout)

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

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .getRequestingStatus

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 "HiveMatchMaking.h"

int MatchId = 25;       // 控制台中注册的 matchId
FHiveMatchMaking::GetRequestingStatus(MatchId, FHiveMatchMakingOnMatchMakingDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    if (Result.IsSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请查看下面的错误代码
    }
}));

API 参考: MatchMaking ::getRequestingStatus

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

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

        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;
        int matchId = 25;           // 控制台中注册的 matchId
        MatchMaking.INSTANCE.getRequestingStatus(matchId, (result, data) -> {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参见下面的错误代码
                    }
});

API 参考: MatchMakingInterface.getRequestingStatus

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

API 参考: HIVEMatchMaking getRequestingStatus

#import "HIVEService.h"
NSInteger matchId = 25;          // 在控制台注册的 matchId

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

匹配进行中¶

如果匹配状态为进行中，您需要重复调用该方法检查匹配状态，以查看它是否已达到匹配状态。

建议在3到10秒的间隔内调用重复调用周期。根据应用程序实现的特性，也可以延长时间间隔。

匹配成功¶

如果匹配状态为匹配，则开发者的游戏将被启动。换句话说，通过Hive SDK 连接的用户如果匹配成功，可以参与开发者的游戏。

超时¶

如果匹配状态是超时（matchingStatus: timeout），您需要删除现有的匹配并重新请求匹配。

删除匹配¶

正在删除现有匹配项。

当比赛符合以下一个或多个情况时，您必须删除比赛。

如果用户取消匹配
如果匹配状态超时 (matchingStatus: timeout)
如果用户之间的游戏正常完成

※ 在更新游戏服务器或游戏客户端上的比赛结果（排名、分数、胜负状态等）后，您必须请求删除比赛

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

Unity虚幻引擎C++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .deleteRequesting

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 "HiveMatchMaking.h"

int MatchId = 25;       // 控制台中注册的 matchId
FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnResultDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
    if (Result.IsSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}));

API 参考: MatchMaking ::deleteRequesting

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

        int 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;
        int matchId = 25;           // 控制台中注册的 matchId
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请查看下面的错误代码
                    }
});

API 参考: MatchMakingInterface.deleteRequesting

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

API 参考: HIVEMatchMaking deleteRequesting

#import "HIVEService.h"
NSInteger matchId = 25;          // 在控制台中注册的 matchId

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

错误代码¶

错误代码	消息	描述
NEED_INITIALIZE	MatchMakingNotInitialized	如果SDK设置未完成（AuthV4.setup）
INVALID_SESSION	MatchMakingNeedSignIn	如果未完成AuthV4登录
RESPONSE_FAIL	MatchMakingResponseError	- 由于API调用期间参数不正确而失败 - 由于网络问题而失败 - 在已经处于匹配请求状态时请求再次匹配 - 请求删除未请求的匹配