跳转至

匹配制作

匹配制作是在在线游戏中将游戏用户连接在一起以便一起游戏的过程，提供与相似水平的对手匹配以实现平衡的游戏体验。

开始

Hive使用匹配的方式主要有两种。

  1. Hive SDK
  2. Hive 服务器 API

这里介绍Hive SDK的使用方法。


要使用Hive SDK进行配对，您需要首先遵循以下步骤。

  1. Hive 控制台应用中心注册项目
  2. Hive 控制台匹配制作创建匹配

有关匹配方式和匹配人数的详细信息，请查看上面的控制台指南。

匹配制作 SDK 整体流程

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

匹配请求

请求匹配。每个用户都需要请求，并且必须事先在 Hive 控制台注册与 matchId 相对应的比赛信息。然后请求比赛所需的分数 point（0 到 10^10 之间的整数）和比赛所需的附加信息 extraData（昵称、等级、国家等 256 字符以内的信息）。

Note

如果在已经请求匹配的状态下再次请求匹配，现有匹配不会中断，但会传递错误回调（MatchMakingResponseError）。请务必先通过 检查匹配状态 确认匹配状态后再请求匹配。

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

API 参考: MatchMaking .requestMatchMaking

using hive;
        string matchId = "25";      // 控制台注册的 matchId
        int point = 300;            // 匹配使用积分 
        string extraData = "your extraData";    // 匹配使用的附加信息
        MatchMaking.requestMatchMaking(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请查看下面的错误代码
                    }
});

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

requestMatchMatking(), getRequestingStatus() 方法调用的结果传递 MatchMakingData 对象。

MatchMakingData 对象的构成

字段名 说明 类型
matchPlayerId 请求的用户 playerId Long
matchGameIndex 匹配游戏索引 Int
matchId 请求的匹配 ID Int
requestStatus 匹配请求状态 (requested: 已请求匹配, notRequested: 未请求(或, 已匹配且正在进行的匹配不存在)) String
requestTimeUtc 匹配请求时间 String
requestPoint 匹配分数 Int
requestExtraData 匹配请求时传递的其他信息 String
matchingStatus 匹配进行状态 (matchingInProgress: 匹配进行中, timeout: 在限制时间内未完成匹配, matched: 匹配成功) String

匹配状态确认

检查用户的匹配状态。匹配状态将返回以下三种中的一种。

  1. 匹配进行中
  2. 匹配成功
  3. 超时(Timeout)

匹配进行中

状态为 匹配进行中 时，需要反复调用此方法以确认是否已达到 匹配成功 状态。建议重复调用的周期为每3~10秒调用一次。根据应用的实现特性，也可以适当延长时间间隔。

匹配成功

状态为 匹配成功 时，启动开发商的游戏。也就是说，Hive SDK 将游戏中的用户相互连接，因此这些用户将一起享受开发商实现的游戏。

超时

如果状态为超时(matchingStatus: timeout)，则需要删除匹配并重新请求匹配。


以下是匹配状态检查示例代码。

API 参考: MatchMaking .getRequestingStatus

using hive;
        string matchId = "25";      // 控制台注册的 matchId
        MatchMaking.getRequestingStatus(matchId, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请参见下面的错误代码
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::GetRequestingStatus(matchId, FHiveMatchMakingOnGetRequestingStatusDelegate::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;

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

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

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

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]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

删除匹配

删除匹配。当符合以下一个或多个情况时，必须删除匹配。

  • 当用户取消匹配时
  • 匹配状态超时的情况
  • 用户之间的游戏正常完成的情况
    • 在游戏服务器更新游戏结果（排名、分数、胜负等）数据之后，必须请求删除匹配

以下是匹配删除示例代码。

API 参考: MatchMaking .deleteRequesting

using hive;
        string matchId = "25";      // 控制台注册的 matchId
        MatchMaking.deleteRequesting(matchId, (ResultAPI result) => {
                    if (result.isSuccess()) {
                            // 调用成功
                    } else {
                            // 调用失败。请查看下面的错误代码
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnDeleteRequestingDelegate::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;

        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调用时由于参数错误而失败，因网络问题而失败，或在已请求匹配的状态下再次请求匹配