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

การจับคู่

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

เริ่มต้น

วิธีการใช้การจับคู่ที่ Hive มีอยู่ 2 แบบใหญ่ๆ

  1. Hive SDK
  2. Hive Server API

ที่นี่เราจะแนะนำวิธีการใช้ Hive SDK


หากต้องการใช้การจับคู่ด้วย Hive SDK ให้ทำตามขั้นตอนต่อไปนี้ก่อน

  1. Hive ศูนย์แอปคอนโซลลงทะเบียนโปรเจกต์
  2. Hive คอนโซลการจับคู่สร้างแมตช์

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

กระบวนการทั้งหมดของ SDK การจับคู่

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

การขอจับคู่

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

Note

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

ต่อไปนี้คือตัวอย่างโค้ดการขอแมตช์

API Reference: MatchMaking .requestMatchMaking

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

FString matchId = "25";
int32 point = 300;
FString extraData = "your extraData";

FHiveMatchMaking::RequestMatchMaking(matchId, point, extraData, FHiveMatchMakingOnRequestMatchMakingDelegate::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;

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

API Reference: MatchMakingInterface.requestMatchMaking

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

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 {
        // การเรียลล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}];

ส่งวัตถุ MatchMakingData เป็นผลลัพธ์จากการเรียกใช้เมธอด requestMatchMatking(), getRequestingStatus()

โครงสร้างของอ็อบเจ็กต์ MatchMakingData

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

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

ตรวจสอบสถานะการจับคู่ของผู้ใช้ จะส่งคืน 1 ใน 3 รายการต่อไปนี้

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

กำลังดำเนินการจับคู่

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

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

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

หมดเวลา

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


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

API Reference: MatchMaking .getRequestingStatus

using hive;
        string matchId = "25";      // matchId ที่ลงทะเบียนในคอนโซล
        MatchMaking.getRequestingStatus(matchId, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // การเรียกสำเร็จ
                    } else {
                            // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::GetRequestingStatus(matchId, FHiveMatchMakingOnGetRequestingStatusDelegate::CreateLambda([this](const FHiveResultAPI& Result, const FHiveMatchMakingData& MatchMakingData) {
    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";          // ค่าที่ลงทะเบียนในคอนโซล 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;
        String matchId = "25";          // matchId ที่ลงทะเบียนในคอนโซล
        MatchMaking.INSTANCE.getRequestingStatus(matchId, (result, data) -> {
                    if (result.isSuccess()) {
                            // การเรียกสำเร็จ
                    } else {
                            // การเรียลล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
                    }
});

API Reference: MatchMakingInterface.getRequestingStatus

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

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

using hive;
        string matchId = "25";      // matchId ที่ลงทะเบียนในคอนโซล
        MatchMaking.deleteRequesting(matchId, (ResultAPI result) => {
                    if (result.isSuccess()) {
                            // การเรียกสำเร็จ
                    } else {
                            // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
                    }
});

#include "HiveMatchMaking.h"

FString MatchId = "25";

FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnDeleteRequestingDelegate::CreateLambda([this](const FHiveResultAPI& 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";          // 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 Reference: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        String matchId = "25";          // matchId ที่ลงทะเบียนในคอนโซล
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // การเรียกสำเร็จ
                    } else {
                            // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
                    }
});

API Reference: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = "25"          // matchId ที่ลงทะเบียนในคอนโซล
MatchMakingInterface.deleteRequesting(matchId: matchId) { result in
    if result.isSuccess() {
        // การเรียกสำเร็จ
    } else {
        // การเรียกล้มเหลว ดูรหัสข้อผิดพลาดด้านล่าง
    }
}

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