ข้ามไปที่เนื้อหา

การจับคู่ส่วนตัว

การจับคู่ส่วนบุคคลจะถูกใช้เมื่อผู้ใช้ต้องการเข้าร่วมเกมคนเดียว

กระบวนการจับคู่ใน SDK

เมื่อดำเนินการจับคู่ส่วนบุคคลด้วย Hive SDK โฟลว์การทำงานโดยรวมจะแสดงในแผนภาพด้านล่าง

ขอจับคู่

กำลังขอการจับคู่สำหรับผู้ใช้แต่ละคน.

ก่อนที่จะทำการร้องขอ คุณต้องลงทะเบียนข้อมูลการแข่งขันที่ตรงกับ matchId ในคอนโซล Hive.

เมื่อขอการแข่งขัน คุณต้องระบุคะแนน point (จำนวนเต็มตั้งแต่ 0 ถึงน้อยกว่า 10^10) และข้อมูลเพิ่มเติม extraData (ข้อมูลภายใน 256 ตัวอักษร เช่น ชื่อเล่น ระดับ ประเทศ ฯลฯ) เป็นอาร์กิวเมนต์

Warning

หากคุณขอให้จับคู่ซ้ำอีกครั้งในขณะที่มีการจับคู่กำลังดำเนินอยู่ ฟังก์ชัน callback จะส่งค่าผิดพลาด (MatchMakingResponseError) โดยไม่หยุดการจับคู่ที่มีอยู่ ดังนั้นโปรดตรวจสอบสถานะการจับคู่ก่อนโดยใช้ ตรวจสอบสถานะการจับคู่ ก่อนที่จะขอให้จับคู่

นี่คือตัวอย่างโค้ดสำหรับคำขอที่ตรงกัน

API Reference: MatchMaking .requestMatchMaking

using hive;
        int matchId = 25;       // matchId ที่ลงทะเบียนในคอนโซล
        int point = 300;            // คะแนนที่ใช้สำหรับการแข่งขัน
        string 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("ข้อมูลเพิ่มเติมของคุณ");  // ข้อมูลเพิ่มเติมที่ใช้สำหรับการแข่งขัน

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 Reference: MatchMaking ::requestMatchMaking

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

        int matchId = 25;           // matchId ลงทะเบียนในคอนโซล
        int point = 300;                // คะแนนที่ใช้สำหรับการแข่งขัน
        string extraData = "ข้อมูลเพิ่มเติมของคุณ"; // ข้อมูลเพิ่มเติมที่จะใช้สำหรับการแข่งขัน

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

API Reference: 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 ที่ลงทะเบียนในคอนโซล
        int point = 300;                // คะแนนที่ใช้สำหรับการแข่งขัน
        String extraData = "ข้อมูลเพิ่มเติมของคุณ"; // ข้อมูลเพิ่มเติมที่จะใช้สำหรับการแข่งขัน
        MatchMaking.INSTANCE.requestMatchMaking(matchId, point, extraData, (result, data) -> {
                    if (result.isSuccess()) {
                            // การเรียกสำเร็จ
                    } else {
                            // การเรียลล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
                    }
});

API Reference: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId: Int = 25                   // matchId ที่ลงทะเบียนในคอนโซล
let point: Int = 300                        // คะแนนที่ใช้สำหรับการแข่งขัน
let extraData: String? = "your extraData"   // ข้อมูลเพิ่มเติมที่ใช้สำหรับการแข่งขัน
MatchMakingInterface.requestMatchMaking(matchId: matchId, point: point, extraData: extraData) { result, data in
        if result.isSuccess() {
        // การเรียกสำเร็จ
        }
        else {
        // การเรียล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
        }
}

API Reference: HIVEMatchMaking requestMatchMaking 

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

[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 รหัสผู้เล่นของผู้ใช้ที่ขอแมตช์ Long
requestGameIndex ดัชนีเกมแมตช์ Int
requestMatchId รหัสแมตช์ที่ขอ (รูปแบบที่ลงทะเบียนใน Hive console) Int
requestStatus สถานะการขอแมตช์ (requested: ขอแมตช์แล้ว, notRequested: ไม่ได้ขอ (หรือ ไม่มีแมตช์ที่กำลังดำเนินการที่ได้ถูกจับคู่แล้ว)) String
requestTimeUtc เวลาที่ขอแมตช์ (เช่น: 2025-01-02T11:13:50.96) String
requestPoint คะแนนแมตช์ Int
requestExtraData ข้อมูลเพิ่มเติมที่ให้ในระหว่างการขอแมตช์ (มีอยู่ถ้าใช้ extraData ในระหว่างการขอ) String
matchingStatus สถานะความก้าวหน้าของแมตช์ (matchingInProgress: กำลังจับคู่, timeout: ไม่มีการจับคู่เกิดขึ้นภายในเวลาที่กำหนด, matched: การจับคู่สำเร็จ) String
matchingType ว่ามีการเข้าร่วมเป็นทีมหรือการเข้าร่วมเป็นรายบุคคล (มีอยู่ถ้าสถานะการจับคู่คือ matched) (team: ทีม, player: บุคคล, unknown: ถ้าไม่มีการยืนยันการจับคู่) String
matchingId รหัสที่กำหนดให้กับแมตช์ที่สำเร็จ (มีอยู่ถ้าสถานะการจับคู่คือ matched) (เช่น: 539:21_2025-01-02T11:45:55.25_1) String
matchingPlayerInfoList รายการข้อมูลของผู้ใช้ที่จับคู่ MatchingResultPlayerInfo (มีอยู่ถ้าสถานะการจับคู่คือ matched, ปรากฏในกรณีการเข้าร่วมเป็นรายบุคคล) Array
matchingTeamInfoList รายการข้อมูลทีม MatchingResultTeamInfo (มีอยู่ถ้าสถานะการจับคู่คือ 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 Reference: 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;       // หมายเลขการแข่งขันที่ลงทะเบียนในคอนโซล
FHiveMatchMaking::GetRequestingStatus(MatchId, FHiveMatchMakingOnMatchMakingDataDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    if (Result.IsSuccess()) {
        // เรียกสำเร็จ
    } else {
        // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}));

API Reference: 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;           // The matchId registered in the console
        MatchMaking.INSTANCE.getRequestingStatus(matchId, (result, data) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

เอกสาร 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 Reference: HIVEMatchMaking getRequestingStatus

#import "HIVEService.h"
NSInteger matchId = 25;          // matchId ลงทะเบียนในคอนโซล

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

กำลังจับคู่

หากสถานะการจับคู่คือ กำลังดำเนินการ คุณต้องเรียกใช้วิธีการซ้ำเพื่อเช็คสถานะการจับคู่เพื่อดูว่ามันได้ถึงสถานะ จับคู่แล้ว หรือไม่

แนะนำให้เรียกวงจรการโทรซ้ำที่ช่วงเวลา 3 ถึง 10 วินาที ขึ้นอยู่กับลักษณะการใช้งานของแอปพลิเคชัน ยังสามารถขยายช่วงเวลาได้อีกด้วย

การจับคู่สำเร็จ

หากสถานะการจับคู่เป็น Matched เกมของนักพัฒนาจะถูกเปิดตัว กล่าวอีกนัยหนึ่ง ผู้ใช้ที่เชื่อมต่อผ่าน Hive SDK ที่ถูกจับคู่สามารถเข้าร่วมเกมของนักพัฒนาได้

หมดเวลา

หากสถานะการจับคู่เป็นการหมดเวลา (matchingStatus: timeout), คุณต้อง ลบ การจับคู่ที่มีอยู่และขอการจับคู่ใหม่อีกครั้ง.


ลบที่ตรงกัน

กำลังลบการแข่งขันที่มีอยู่

คุณต้องลบการแข่งขันเมื่อมันตกอยู่ภายใต้กรณีหนึ่งหรือมากกว่าดังต่อไปนี้

  • หากผู้ใช้ยกเลิกการจับคู่
  • หากสถานะการจับคู่หมดเวลา (matchingStatus: timeout)

  • หากเกมระหว่างผู้ใช้เสร็จสิ้นตามปกติ

    ※ คุณต้องขอให้ลบการแข่งขันหลังจากอัปเดตผลการแข่งขัน (อันดับ, คะแนน, สถานะชนะ/แพ้, ฯลฯ) บนเซิร์ฟเกมหรือไคลเอนต์เกม

นี่คือตัวอย่างโค้ดสำหรับการลบการแข่งขัน

API Reference: 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;       // หมายเลขการแข่งขันที่ลงทะเบียนในคอนโซล
FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnResultDelegate::CreateLambda([this](const FHiveResultAPI& Result) {
    if (Result.IsSuccess()) {
        // เรียกสำเร็จ
    } else {
        // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}));

API Reference: 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()) {
                            // 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;
        int matchId = 25;           // The matchId registered in the console
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

เอกสาร 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 Reference: 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
- ล้มเหลวเนื่องจากปัญหาเครือข่าย
- ขอให้จับคู่ใหม่ในขณะที่อยู่ในสถานะการขอจับคู่แล้ว
- ขอให้ลบการจับคู่ที่ไม่ได้ร้องขอ