跳轉至

團體配對

群組配對是在多個用戶希望作為同一隊伍一起參加遊戲時使用的。

群組匹配不僅可以在以群組為基礎的匹配請求時請求，還可以根據團隊成員的數量在群組和個人組成團隊時請求。

Note

團體配對僅支援於團體匹配中，無法用於個人匹配。

本指南解釋了用戶如何通過輸入創建小組時提供的 GroupCode 值來加入小組並請求匹配。

SDK中的配對操作流程

小組配對的進行順序如下。

  • 創建群組（房間）→ 成員群組參與 → 匹配請求

在使用 Hive SDK 实现组匹配时，匹配的整体流程取决于用户是组长还是组员。

從小組領導者的角度看配對過程流程

從小組成員的角度看配對過程流程


創建群組

您必須先創建一個群組才能使用群組配對。

如果多個用戶想要一起參加遊戲，創建的組將被匹配為同一隊伍。

在呼叫群組創建方法時，必須在 Hive 控制台中預先註冊與 matchId 相對應的匹配信息。

使用的參數為matchId、分數point（一個介於0到小於10^10的整數）以及額外信息extraData（包含256個字符內的信息，如暱稱、等級、國家等），用於比賽。

Note

用作参数的 matchId 的匹配单位必须设置为“team”。此外，创建该组的用户将成为组长。

這是一個創建群組的示例代碼。

API 參考: MatchMaking .createGroup 

using hive;

int matchId = 25;       // 在控制台中注册的 matchId
int point = 300;            // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息
MatchMaking.createGroup(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
            // 调用成功
    } else {
            // 调用失败。请查看下面的错误代码
    }
});


#include "HiveMatchMaking.h"

int MatchId = 25;                           // 在控制台中注册的 matchId
int Point = 300;                            // 比赛使用分数
FString ExtraData = TEXT("your extraData"); // 用于比赛的附加信息

FHiveMatchMaking::CreateGroup(MatchId, Point, ExtraData, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
    if (Result.IsSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}));

API 參考: MatchMaking ::createGroup

#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::createGroup(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMaking.createGroup

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台中注册的 matchId
val point = 300             // 用于比赛的积分
val extraData = "your extraData";   // 用于比赛的附加信息

MatchMaking.createGroup(matchId, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .createGroup

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // matchId 在控制台中注册
int point = 300;                // 用于比赛的积分
String extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.createGroup(matchId, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.createGroup

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 be used for the match

MatchMakingInterface.createGroup(matchId: matchId, point: point, extraData: extraData) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 參考: HIVEMatchMaking createGroup 

#import "HIVEService.h"
NSInteger matchId = 25;                 // 在控制台註冊的 matchId
NSInteger point = 300;                      // 用於比賽的點數
NSString *extraData = @"your extraData";    // 用於比賽的附加信息

[MatchMakingInterface createGroupWithMatchId:matchId
                                              point:point
                                          extraData:extraData
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

加入群組

您可以加入該群組。不是群組領導者的用戶可以加入該群組，以便被匹配為同一隊伍。


當呼叫群組參與方法時，使用的參數為 matchId、創建群組時發出的 GroupCode、用於匹配的分數 point（一個從 0 到小於 10^10 的整數），以及用於匹配的附加信息 extraData（包含 256 個字符以內的信息，如暱稱、等級、國家等）。

Note

A user who is not a group leader must request to join the group. The match unit for the matchId to be used as an argument must be set to 'team'.

這是一個關於團體參與的示例代碼。

API 參考: MatchMaking .joinGroup

using hive;

int matchId = 25;       // 在控制台中注册的 matchId
string groupCode = "5001789"; // 群组代码
int point = 300;            // 用于比赛的积分 
string extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 呼叫成功
    } else {
        // 呼叫失敗。請參見下面的錯誤代碼
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25;                           // 在控制台中注册的 matchId
FString GroupCode = TEXT("5001789");        // 组代码
int Point = 300;                            // 比赛使用分数
FString ExtraData = TEXT("your extraData"); // 用于比赛的附加信息

FHiveMatchMaking::JoinGroup(MatchId, GroupCode, Point, ExtraData, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
    if (Result.IsSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}));

API 參考: MatchMaking ::joinGroup

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台中注册的 matchId
string groupCode = "5001789";   // 群组代码
int point = 300;                // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息

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

API 參考: MatchMaking.joinGroup

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台註冊的 matchId
val groupCode = "5001789"   // 群組代碼
val point = 300             // 用於比賽的積分
val extraData = "your extraData";   // 用於比賽的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .joinGroup

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台中注册的 matchId
String groupCode = "5001789";   // 群组代码
int point = 300;                // 用于比赛的积分
String extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // 呼叫成功
    } else {
        // 呼叫失敗。請參見下面的錯誤代碼
    }
});

API 參考: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId: Int = 25                       // 控制台中注册的 matchId
let groupCode: String = "5001789"           // 组代码
let point: Int = 300                        // 用于比赛的积分
let extraData: String? = "your extraData"   // 用于比赛的附加信息

MatchMakingInterface.joinGroup(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 registered in the console
NSString *groupCode = @"5001789";           // group code
NSInteger point = 300;                      // points used for the match
NSString *extraData = @"your extraData";    // additional information to use for the match

[MatchMakingInterface joinGroupWithMatchId:matchId
                                          groupCode:groupCode
                                              point:point
                                          extraData:extraData
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

團體提款

我將離開這個群組。

如果任何一位小组成员处于“准备”状态，他们将无法退出。此外，如果小组领导者退出，剩下的成员之一将自动成为小组领导者。如果没有剩余成员，小组将自动被删除。

這是一個群組提款的範例代碼。

API 參考: MatchMaking .leaveGroup

using hive;
int matchId = 25;       // The matchId registered in the console
MatchMaking.leaveGroup(matchId, (ResultAPI result) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25; // 在控制台中注册的 matchId
FHiveMatchMaking::LeaveGroup(MatchId, FHiveMatchMakingOnResultDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
    if (Result.IsSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}));

API 參考: MatchMaking ::leaveGroup

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // matchId 在控制台中注册

MatchMaking::leaveGroup(matchId, [=](ResultAPI const & result) {
    if (result.isSuccess()) {
            // 呼叫成功
    } else {
            // 呼叫失敗。請參見下面的錯誤代碼
    }
});

API 參考: MatchMaking.deleteRequesting

import com.hive.MatchMaking
import com.hive.ResultAPI
val matchId = 25            // 在控制台中注册的 matchId
MatchMaking.leaveGroup(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;           // The matchId registered in the console
MatchMaking.leaveGroup(matchId, (result) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = 25            // The matchId registered in the console
MatchMakingInterface.leaveGroup(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 leaveGroupWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 呼叫成功
    } else {
        // 呼叫失敗。請參見下面的錯誤代碼
    }
}];

群組成員強制退出

小組領導可以強制移除特定成員。強制移除只能針對同一小組成員提出請求，並且在進行中的比賽中不能使用。

當呼叫群組成員強制退出方法時，使用您想要強制退出的成員的 targetPlayerId 作為參數。

以下是一段强制移除群组成员的示例代码。

API 參考: MatchMaking .kickGroupUser

using hive;

int matchId = 25;       // matchId registered in the console
long targetPlayerId = 123456789; // Player id of the member to be forcibly expelled

MatchMaking.kickGroupUser(matchId, targetPlayerId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMaking ::kickGroupUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25; // matchId 註冊在控制台
long long targetPlayerId = 123456789; // 強制驅逐的成員玩家 ID

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

API 參考: MatchMaking.kickGroupUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25 // 在控制台中注册的 matchId
val targetPlayerId = 123456789 // 强制导出的成员玩家 ID

MatchMaking.kickGroupUser(matchId, targetPlayerId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .kickGroupUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25; // matchId 註冊在控制台
long targetPlayerId = 123456789; // 強制驅逐的成員玩家 ID

MatchMaking.kickGroupUser(matchId, targetPlayerId, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.kickGroupUser

import HIVEService
let matchId = 25                    // 控制台中注册的 matchId
let targetPlayerId = 123456789      // 要强制驱逐的成员玩家 ID

MatchMakingInterface.kickGroupUser(matchId: matchId, targetPlayerId) { 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
NSNumber *targetPlayerId = 123456789;       // 要强制驱逐的成员的玩家 ID

[MatchMakingInterface kickGroupUserWithMatchId:matchId
                                          targetPlayerId:targetPlayerId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

根據群組用戶查詢群組資訊

根據群組內的用戶查詢群組信息。 它用於檢查參加該群組的其他用戶的信息或在匹配請求後檢查匹配結果。

建議定期檢查群組用戶的狀態。

以下是一段示例代码，用于根据组用户查询组信息。

API 參考: MatchMaking .getGroupInfoByUser

using hive;

int matchId = 25;       // matchId 在控制台中注册

MatchMaking.getGroupInfoByUser(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 呼叫成功
    } else {
        // 呼叫失敗。請參見下面的錯誤代碼
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25; // matchId registered in the console
FHiveMatchMaking::GetGroupInfoByUser(MatchId, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
        if (Result.IsSuccess()) {
            // call successful
        } else {
            // Call failed. See error code below
        }
}));

API 參考: MatchMaking ::getGroupInfoByUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25; // matchId 在控制台中注册

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

API 參考: MatchMaking.getGroupInfoByUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25 // matchId 在控制台中注册

MatchMaking.getGroupInfoByUser(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .getGroupInfoByUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25; // 在控制台中注册的 matchId

MatchMaking.getGroupInfoByUser(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.getGroupInfoByUser

import HIVEService
let matchId = 25                    // 在控制台中注册的 matchId

MatchMakingInterface.getGroupInfoByUser(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 參考: HIVEMatchMaking getGroupInfoByUser

#import "HIVEService.h"
NSInteger matchId = 25;                 // 在控制台中注册的 matchId

[MatchMakingInterface getGroupInfoByUserWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

根據群組代碼查詢群組資訊

根據群組代碼查詢有關該群組的信息。它用於檢查該群組是否存在。

以下是一个根据组代码检索组信息的示例代码。

API 參考: MatchMaking .getGroupInfoByGroupCode

using hive;

string groupCode = "5001789";   // group code

MatchMaking.getGroupInfoByGroupCode(groupCode, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

#include "HiveMatchMaking.h"

FString GroupCode = TEXT("5001789"); // group code

FHiveMatchMaking::GetGroupInfoByGroupCode(GroupCode, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
        if (Result.IsSuccess()) {
            // call successful
        } else {
            // Call failed. See error code below
        }
}));

API 參考: MatchMaking ::getGroupInfoByGroupCode

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

string groupCode = "5001789"; // group code

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

API 參考: MatchMaking.getGroupInfoByGroupCode

import com.hive.MatchMaking
import com.hive.ResultAPI

val groupCode = "5001789" // group code

MatchMaking.getGroupInfoByGroupCode(groupCode, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .getGroupInfoByGroupCode

import com.hive.MatchMaking;
import com.hive.ResultAPI;

String groupCode = "5001789"; // Group code

MatchMaking.getGroupInfoByGroupCode(groupCode, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.getGroupInfoByGroupCode

import HIVEService
let groupCode = "5001789" // Group code

MatchMakingInterface.getGroupInfoByGroupCode(groupCode: groupCode) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 參考: HIVEMatchMaking getGroupInfoByGroupCode

#import "HIVEService.h"
NSString *groupCode = @"5001789"; // 群組代碼

[MatchMakingInterface getGroupInfoByGroupCodeWithGroupCode:groupCode
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

成員資訊更新

群組中的成員可以更改他們的狀態或資訊。

在调用成员信息修改方法时，参数包括不包括组长的成员准备状态 ready，用于比赛的分数 point（一个从 0 到小于 10^10 的整数），以及用于比赛的附加信息 extraData（如昵称、等级、国家等信息，最多 256 个字符）。

Warning

群組中的所有成員必須處於準備狀態，才能讓群組領導者發出匹配請求。
對於群組領導者，準備值始終為真，將其更改為假將導致錯誤。

這是一個關於群組參與的示例代碼。

API 參考: MatchMaking .updateGroupUser

using hive;

int matchId = 25;       // matchId registered in the console
bool ready = true;          // readiness status
int point = 300;            // points used for the match 
string extraData = "your extraData";    // additional information to be used for the match

MatchMaking.updateGroupUser(matchId, ready, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25; // matchId registered in the console
bool Ready = true; // ready
int Point = 300; // points used for the match
FString ExtraData = TEXT("your extraData"); // additional information to be used for the match

FHiveMatchMaking::UpdateGroupUser(MatchId, Ready, Point, ExtraData, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
        if (Result.IsSuccess()) {
            // call successful
        } else {
            // Call failed. See error code below
        }
}));

API 參考: MatchMaking ::updateGroupUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台中注册的 matchId
bool ready = true;              // 准备状态
int point = 300;                // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息

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

API 參考: MatchMaking.updateGroupUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // matchId 註冊在控制台
val ready = true            // 準備狀態
val point = 300             // 用於比賽的點數
val extraData = "your extraData";   // 用於比賽的附加信息

MatchMaking.updateGroupUser(matchId, ready, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .updateGroupUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台中注册的 matchId
boolean ready = true;           // 准备状态
int point = 300;                // 用于比赛的积分
String extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.updateGroupUser(matchId, ready, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.updateGroupUser

import HIVEService
let matchId: Int = 25                       // 在控制台中注册的 matchId
let ready: Bool = true                      // 准备状态
let point: Int = 300                        // 比赛使用的积分
let extraData: String? = "your extraData"   // 用于比赛的附加信息

MatchMakingInterface.updateGroupUser(matchId: matchId, ready: ready, point: point, extraData: extraData) { result, data in
    if result.isSuccess() {
        // 呼叫成功
    }
    else {
        // 呼叫失敗。請參見下面的錯誤代碼
    }
}

API 參考: HIVEMatchMaking updateGroupUser

#import "HIVEService.h"
NSInteger matchId = 25;                 // matchId registered in the console
BOOL *ready = true;                         // group code
NSInteger point = 300;                      // points used for the match
NSString *extraData = @"your extraData";    // additional information to be used for the match

[MatchMakingInterface updateGroupUserWithMatchId:matchId
                                           ready:ready
                                           point:point
                                       extraData:extraData
                                      completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

匹配請求

請求配對。一旦小組中的所有成員都處於準備狀態，小組領導者可以發出配對請求。

請求比賽時，前提條件如下。

  • 在請求時，必須至少有 2 名小組成員。
  • 不是小組領導者（房間領導者）的成員必須將其「準備」狀態設置為真。
  • 如果存在現有的匹配，則必須在發出請求之前將其刪除。
  • 只有小組領導者（房間領導者）可以發出請求。
Warning

如果您在匹配请求正在进行时再次请求匹配，则现有的匹配将不会被中断，回调函数将返回错误值（MatchMakingResponseError）。 因此，请务必先通过 检查匹配状态 检查匹配状态，然后再请求匹配。

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

API 參考: MatchMaking .requestGroupMatching

using hive;
int matchId = 25;       // matchId registered in the console

MatchMaking.requestGroupMatching(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25; // matchId registered in the console
FHiveMatchMaking::RequestGroupMatching(MatchId, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
        if (Result.IsSuccess()) {
            // call successful
        } else {
            // Call failed. See error code below
        }
}));

API 參考: MatchMaking ::requestGroupMatching

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台中注册的 matchId

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

API 參考: MatchMaking.requestGroupMatching

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // matchId 在控制台中注册

MatchMaking.requestGroupMatching(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .requestGroupMatching

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台中注册的 matchId

MatchMaking.requestGroupMatching(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.requestGroupMatching

import HIVEService

let matchId = 25                    // 在控制台中註冊的 matchId

MatchMakingInterface.requestGroupMatching(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 參考: HIVEMatchMaking requestGroupMatching

#import "HIVEService.h"

NSInteger matchId = 25;                 // 在控制台中注册的 matchId

[MatchMakingInterface requestGroupMatchingWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

取消匹配請求 (刪除)

取消（刪除）比賽。如果比賽符合以下一項或多項條件，則必須刪除該比賽。

  • 如果用戶取消比賽
  • 如果比賽狀態為超時

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

    您必須在更新遊戲伺服器上的比賽結果（排名、分數、勝負狀態等）數據後請求刪除比賽。

以下是一個取消（刪除）匹配請求的示例代碼。

API 參考: MatchMaking .deleteGroupMatching

using hive;
int matchId = 25;       // matchId registered in the console

MatchMaking.deleteGroupMatching(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

#include "HiveMatchMaking.h"

int MatchId = 25; // matchId 在控制台中注册

FHiveMatchMaking::DeleteGroupMatching(MatchId, FHiveMatchMakingOnMatchMakingGroupDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingGroupData& MatchMakingGroupData) {
        if (Result.IsSuccess()) {
            // call successful
        } else {
            // Call failed. See error code below
        }
}));

API 參考: MatchMaking ::deleteGroupMatching

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // matchId 在控制台中注册

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

API 參考: MatchMaking.deleteGroupMatching

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // matchId 在控制台中注册

MatchMaking.deleteGroupMatching(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 參考: MatchMaking .deleteGroupMatching

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // matchId 在控制台中注册

MatchMaking.deleteGroupMatching(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 參考: MatchMakingInterface.deleteGroupMatching

import HIVEService

let matchId = 25                    // 在控制台中注册的 matchId

MatchMakingInterface.deleteGroupMatching(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 參考: HIVEMatchMaking deleteGroupMatching

#import "HIVEService.h"

NSInteger matchId = 25;                 // 在控制台中注册的 matchId

[MatchMakingInterface deleteGroupMatchingWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

MatchMakingGroupData 物件結構

這是根據群組配對提供的主要功能請求而交付的對象。

回應物件包括在請求期間輸入的信息、群組代碼、群組領導者信息、團隊成員信息和匹配結果信息。

字段名称 描述 类型
groupCode 创建组时生成的组代码 字符串
ownerPlayerId 请求创建组的玩家ID（组长） 长整型
requestGameIndex 匹配游戏索引 整型
requestMatchId 请求的比赛ID（以在Hive控制台中注册的格式） 整型
requestStatus 匹配请求状态（requested: 请求匹配，notRequested: 未请求（或没有进行中的匹配）） 字符串
requestTimeUtc 匹配请求时间（例如：2025-01-02T11:13:50.96） 字符串
matchingStatus 匹配进度状态（matchingInProgress: 匹配进行中，timeout: 在时间限制内未发生匹配，matched: 匹配成功） 字符串
matchingType 是否为团队参与或个人参与（如果matchingStatus为matched则存在）（team: 团队，player: 个人，unknown: 如果没有匹配确认） 字符串
matchingId 分配给成功匹配的ID（如果matchingStatus为matched则存在）（例如：539:21_2025-01-02T11:45:55.25_1） 字符串
memberInfoList 当前属于该组的成员玩家信息列表 MatchMemberInfo 数组
matchingTeamInfoList 如果匹配成功的团队信息列表 MatchingResultTeamInfo（如果matchingStatus为matched则存在） 数组

MatchMemberInfo 物件結構

這是參加團隊比賽時傳遞的物件。它包含屬於同一團隊（小組）的團隊成員的用戶信息。

字段名稱 描述 類型
playerId 群組成員的 playerId Long
ready 群組成員的準備狀態 Boolean
point 群組成員的分數 Int
extraData 群組成員提供的其他信息（如果用戶在請求時使用了 extraData，則存在） String

MatchingResultTeamInfo 物件結構

這是當一個隊伍參加比賽並且匹配成功（當 matchingStatus 為 matched 時）時所交付的物件。它包含隊伍索引和有關屬於該隊伍的用戶的信息。

字段名稱 描述 類型
teamIndex 團隊的唯一索引 Int
playerInfos 屬於該團隊的用戶信息列表 MatchingResultPlayerInfo Array

檢查匹配狀態

檢查用戶的匹配狀態。

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

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

您可以使用 按用户获取组信息 API 或 按组代码获取组信息 API 来检查匹配状态。

匹配進行中

如果匹配状态是进行中，您需要重复调用该方法以检查匹配状态，以查看是否已达到匹配。

建議在3到10秒的間隔內呼叫重複呼叫週期。根據應用程序的實現特點，也可以進一步增加時間間隔。

匹配成功

如果匹配状态为匹配成功，则开发者的游戏将被启动。这意味着通过 Hive SDK 连接的用户处于可以一起玩游戏的状态，匹配的用户可以参与开发者的游戏。

超時

如果狀態為超時（matchingStatus: timeout），您必須刪除現有的匹配並重新請求匹配。

錯誤代碼

錯誤代碼 訊息 描述
NEED_INITIALIZE MatchMakingNotInitialized 如果未完成SDK設置（AuthV4.setup）
INVALID_SESSION MatchMakingNeedSignIn 如果未完成AuthV4登錄
RESPONSE_FAIL MatchMakingResponseError 如果API調用因參數不正確、網絡問題而失敗，或者在已處於匹配請求狀態時發出匹配請求