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

การจับคู่

การจับคู่ คือกระบวนการเชื่อมต่อผู้ใช้เกมในเกมออนไลน์เพื่อให้พวกเขาสามารถเล่นด้วยกัน โดยให้ประสบการณ์การเล่นเกมที่สมดุลโดยการจับคู่กับคู่ต่อสู้ที่มีระดับทักษะใกล้เคียงกัน.

เริ่มต้น

มีสองวิธีหลักในการใช้การจับคู่ใน Hive:

  1. Hive SDK\n2. Hive Server API

คู่มือนี้จะมุ่งเน้นไปที่การใช้ SDK ของ Hive


ในการใช้การจับคู่กับ SDK ของแบรนด์ Hive คุณต้องทำตามขั้นตอนเหล่านี้ก่อน:

  1. ลงทะเบียนโปรเจคใน Hive Console App Center
  2. สร้างการแข่งขันใน Hive Console Matchmaking

สำหรับข้อมูลรายละเอียดเกี่ยวกับวิธีการจับคู่และจำนวนผู้เล่น โปรดดูที่คู่มือคอนโซลด้านบน

โฟลว์โดยรวมของ SDK การจับคู่

โปรดดูตามกระบวนการต่อไปนี้เมื่อดำเนินการฟีเจอร์การจับคู่

การขอจับคู่

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

Note

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

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

API Reference: MatchMaking .requestMatchMaking

using hive;
        string matchId = "25";      // Registered matchId in the console
        int point = 300;            // Score used for the match 
        string extraData = "your extraData";    // Additional information to be used in 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;

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

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

เอกสาร API: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId = "25"                  // Registered matchId in the console
let point = 300                     // Score used for the match
let extraData = "your extraData"    // Additional information to be used in 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"
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]) {
        // การเรียกสำเร็จ
    } else {
        // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}];

requestMatchMaking(), getRequestingStatus() การเรียกใช้เมธอดจะส่งคืนวัตถุ MatchMakingData

โครงสร้างของวัตถุ MatchMakingData

ชื่อฟิลด์ คำอธิบาย ประเภท
matchPlayerId รหัสผู้เล่นของผู้ใช้ที่ทำการร้องขอ Long
matchGameIndex ดัชนีเกมการแข่งขัน Int
matchId รหัสการแข่งขันที่ร้องขอ Int
requestStatus สถานะการร้องขอการแข่งขัน (requested: การแข่งขันที่ร้องขอ, notRequested: ไม่ได้ร้องขอ (หรือไม่มีการแข่งขันที่กำลังดำเนินการ)) String
requestTimeUtc เวลาที่ร้องขอการแข่งขัน String
requestPoint คะแนนการแข่งขัน Int
requestExtraData ข้อมูลเพิ่มเติมที่ให้ระหว่างการร้องขอการแข่งขัน String
matchingStatus สถานะความก้าวหน้าของการแข่งขัน (matchingInProgress: การจับคู่กำลังดำเนินการ, timeout: การจับคู่ไม่เสร็จสิ้นภายในเวลาที่กำหนด, matched: การจับคู่สำเร็จ) String

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

ตรวจสอบสถานะการจับคู่ของผู้ใช้ มันจะส่งคืนหนึ่งในสามสถานะต่อไปนี้:

  1. กำลังจับคู่
  2. การจับคู่สำเร็จ
  3. หมดเวลา

กำลังจับคู่

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

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

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

หมดเวลา

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


นี่คือตัวอย่างโค้ดสำหรับตรวจสอบสถานะการจับคู่

API Reference: MatchMaking .getRequestingStatus

using hive;
        string matchId = "25";      // Registered matchId 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;

        string 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 Reference: MatchMaking.getRequestingStatus

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = "25"          // Registered matchId in the console
        MatchMaking.getRequestingStatus(matchId, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking.INSTANCE .getRequestingStatus

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // Registered matchId in the console
        MatchMaking.INSTANCE.getRequestingStatus(matchId, (result, data) -> {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMakingInterface.getRequestingStatus

import HIVEService
let matchId = "25"          // Registered matchId 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"
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";      // Registered matchId 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;

        string matchId = "25";          // Registered matchId in the console

        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"          // Registered matchId in the console
        MatchMaking.deleteRequesting(matchId, object : MatchMaking.MatchMakingResultListener {
                    override fun onMatchMakingResult(result: ResultAPI) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // Registered matchId 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"          // Registered matchId 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"
NSString *matchId = @"25";          // ลงทะเบียน matchId ในคอนโซล

[MatchMakingInterface deleteRequestingWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // การเรียกสำเร็จ
    } else {
        // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}];

รหัสข้อผิดพลาด

รหัสข้อผิดพลาด ข้อความ คำอธิบาย
NEED_INITIALIZE MatchMakingNotInitialized หากการตั้งค่า SDK ยังไม่ได้ทำ (AuthV4.setup)
INVALID_SESSION MatchMakingNeedSignIn หากผู้ใช้ยังไม่ได้ลงชื่อเข้าใช้
RESPONSE_FAIL MatchMakingResponseError หากการเรียก API ล้มเหลวเนื่องจากพารามิเตอร์ไม่ถูกต้อง ปัญหาเครือข่าย หรือหากมีการส่งคำขอจับคู่ในขณะที่อยู่ในสถานะคำขอจับคู่แล้ว