跳轉至

配對服務

配對是在網路遊戲中，將遊戲使用者連接在一起以便一起遊玩的過程，提供與相似水平的對手配對以獲得平衡的遊戲體驗。

開始

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

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()) {
        // 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";          // 在控制台注册的 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()) {
        // 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()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

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

錯誤代碼

錯誤代碼 訊息 描述
NEED_INITIALIZE MatchMakingNotInitialized 當SDK尚未設置時 (AuthV4.setup)
INVALID_SESSION MatchMakingNeedSignIn 當未登入時
RESPONSE_FAIL MatchMakingResponseError 在API調用時因錯誤的參數而失敗，因網絡問題而失敗，或在已經請求匹配的狀態下再次請求匹配時