跳轉至

個人符合

個人配對用於用戶想要單獨參加遊戲時。

SDK中的配對操作流程

在使用 Hive SDK 實現個人配對時，操作的整體流程如下圖所示。

匹配請求

請求每個用戶的匹配。

在發出請求之前，您必須在 Hive 控制台中註冊與 matchId 相對應的比賽信息。

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

Warning

如果您在比賽已經進行中時再次請求比賽，回調函數將返回錯誤值（MatchMakingResponseError），而不會停止現有的比賽。 因此，在請求比賽之前，請務必先使用 檢查匹配狀態 檢查匹配狀態。

這裡是一個匹配請求的示例代碼。

API 參考: MatchMaking .requestMatchMaking

using hive;
        int 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"

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


檢查匹配狀態

檢查參加個人比賽的用戶的匹配狀態。

當調用匹配狀態檢查方法時，它會返回以下三種匹配狀態之一。

  1. 匹配進行中 (matchingStatus: matchingInProgress)
  2. 匹配成功 (matchingStatus: matched)
  3. 超時 (matchingStatus: timeout)

這是一個檢查匹配狀態的示例代碼。

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()) {
                            // 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;
        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 registered in the console

[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)

  • 如果用戶之間的遊戲正常完成

    ※ 在更新遊戲伺服器或遊戲客戶端上的比賽結果（排名、分數、勝負狀態等）後，您必須請求刪除該比賽

這是一個刪除匹配的示例代碼。

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調用期間參數不正確而失敗
- 由於網絡問題而失敗
- 在已處於匹配請求狀態時請求再次匹配
- 請求刪除未請求的匹配