配對¶
配對是將遊戲用戶在在線遊戲中連接在一起的過程，以便他們可以一起遊玩，通過將他們與相似技能水平的對手匹配來提供平衡的遊戲體驗。
開始使用¶
在 Hive 中使用配對的主要方式有兩種：
- Hive SDK
- Hive 伺服器 API
本指南将重点介绍使用 Hive SDK。
要使用 Hive SDK 的配對功能，您必須首先遵循以下步驟：
有關配對方法和玩家人數的詳細資訊，請參考上面的控制台指南。
配對 SDK 的整體流程¶
實施配對功能時，請參考以下流程。
匹配請求¶
已發出配對請求。每位用戶需要發出請求，並且必須在 Hive 控制台中提前註冊對應於 matchId 的配對信息。您還需要提供將在比賽中使用的分數 point（一個從 0 到小於 10^10 的整數），以及額外信息 extraData（暱稱、等級、國家等，限制為 256 個字符）作為請求的參數。
Note
如果您在已有匹配请求的情况下再次请求匹配，现有的匹配将不会被取消，但会发送错误回调（MatchMakingResponseError）。在再次请求匹配之前，请务必先检查匹配状态。
以下是匹配请求的示例代码。
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"; // 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
}
});
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 Reference: 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 对象。
配對數據對象的結構¶
| 字段名称 | 描述 | 类型 |
|---|---|---|
| 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），您需要刪除匹配並再次請求匹配。
這是一個檢查匹配狀態的示例代碼。
API 參考: MatchMaking .getRequestingStatus
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 .deleteRequesting
API 參考: MatchMaking ::deleteRequesting
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 參考: HIVEMatchMaking deleteRequesting
錯誤代碼¶
| 錯誤代碼 | 訊息 | 描述 |
| NEED_INITIALIZE | MatchMakingNotInitialized | 如果SDK設置尚未完成（AuthV4.setup） |
| INVALID_SESSION | MatchMakingNeedSignIn | 如果用戶尚未登入 |
| RESPONSE_FAIL | MatchMakingResponseError | 如果API調用因參數不正確、網絡問題而失敗，或在已處於匹配請求狀態時發出匹配請求 |