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

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

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

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

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

คำขอจับคู่

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

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

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

Warning

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

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

API Reference: MatchMaking .requestMatchMaking

using hive;
        int matchId = 25;       // matchId registered in the console
        int point = 300;            // points used for the match
        string extraData = "your extraData";    // additional information to use for 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 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 Reference: 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 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 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) 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 รหัสที่กำหนดให้กับแมตช์ที่สำเร็จ (มีอยู่หาก 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
                    }
});

API Reference: MatchMaking ::getRequestingStatus

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

        int matchId = 25;           // Registered matchId in the console

        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 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 วินาที ขึ้นอยู่กับลักษณะการทำงานของแอปพลิเคชัน ยังสามารถขยายช่วงเวลาได้อีกด้วย

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

หากสถานะการจับคู่เป็น 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
                    }
});

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 Reference: 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 registered in the console

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