個人符合
個人配對用於用戶想要單獨參加遊戲時。
SDK中的配對操作流程¶
在使用 Hive SDK 实现个人配对时，操作的整体流程如下面的图所示。
匹配請求¶
請求每個用戶的匹配。
在發送請求之前，您必須在 Hive 控制台中註冊與 matchId 相對應的比賽資訊。
在请求匹配时，您需要提供分数 point（一个从 0 到小于 10^10 的整数）和额外信息 extraData（256 个字符以内的信息，例如昵称、等级、国家等）作为参数。
Warning
如果您在比賽已經進行中時再次請求比賽，回調函數將返回錯誤值（MatchMakingResponseError），而不會停止現有的比賽。 因此，請務必在請求比賽之前先使用 檢查匹配狀態 檢查匹配狀態。
這裡是一個匹配請求的示例代碼。
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 = "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;
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 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
}
}
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)
這是一個檢查匹配狀態的示例代碼。
API 參考: MatchMaking .getRequestingStatus
#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()) {
// 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 {
// 调用失败。请参见下面的错误代码
}
}
})
匹配進行中¶
如果匹配状态为进行中，您需要反复调用该方法检查匹配状态，以查看它是否已达到匹配状态。
建議在3到10秒的間隔內調用重複調用週期。根據應用程序實現的特性，也可以延長時間間隔。
匹配成功¶
如果匹配状态为匹配，则开发者的游戏将被启动。换句话说，通过Hive SDK 连接的用户如果被匹配，可以参与开发者的游戏。
超時¶
如果匹配状态是超时（matchingStatus: timeout），您需要删除现有的匹配并再次请求匹配。
刪除匹配¶
刪除現有的匹配。
當比賽符合以下一個或多個情況時，您必須刪除該比賽。
- 如果用戶取消比賽
- 如果匹配狀態超時 (matchingStatus: timeout)
-
如果用戶之間的遊戲正常完成
※ 您必須在遊戲伺服器或遊戲客戶端更新比賽結果（排名、分數、勝/負狀態等）後請求刪除比賽
這是一個刪除匹配的示例代碼。
API 參考: MatchMaking .deleteRequesting
API 參考: MatchMaking ::deleteRequesting
API 參考: MatchMaking.deleteRequesting
API 參考: HIVEMatchMaking deleteRequesting
錯誤代碼¶
| 錯誤代碼 | 訊息 | 描述 |
| NEED_INITIALIZE | MatchMakingNotInitialized | 如果尚未完成SDK設置（AuthV4.setup） |
| INVALID_SESSION | MatchMakingNeedSignIn | 如果尚未完成AuthV4登錄 |
| RESPONSE_FAIL | MatchMakingResponseError | - 由於API調用期間參數不正確而失敗 - 由於網絡問題而失敗 - 在已處於匹配請求狀態時請求再次匹配 - 請求刪除未請求的匹配 |