マッチメイキング¶

マッチメイキングは、オンラインゲームでゲームユーザーを接続し、一緒にプレイできるようにするプロセスであり、同様のスキルレベルの対戦相手とマッチングすることによってバランスの取れたゲーム体験を提供します。

始めに¶

Hiveでマッチメイキングを使用する主な方法は2つあります:

Hive SDK\n2. Hive サーバーAPI

このガイドでは、Hive SDKの使用に焦点を当てます。

Hive SDKを使用してマッチメイキングを行うには、まず以下の手順に従う必要があります:

マッチング方法とプレイヤー数に関する詳細情報については、上記のコンソールガイドを参照してください。

マッチメイキングSDKの全体的な流れ¶

マッチメイキング機能を実装する際は、以下のフローを参照してください。

マッチリクエスト¶

マッチリクエストが行われます。各ユーザーはリクエストを行う必要があり、matchIdに対応するマッチ情報は事前にHiveコンソールに登録されている必要があります。また、マッチで使用されるスコアpoint（0から10^10未満の整数）や、リクエストのパラメータとして追加情報extraData（ニックネーム、レベル、国など、256文字以内）を提供する必要があります。

Note

既存のマッチリクエストがある状態で再度マッチをリクエストすると、既存のマッチはキャンセルされず、エラーコールバック（MatchMakingResponseError）が送信されます。再度マッチをリクエストする前に、必ずマッチの状態を確認してください。

以下はマッチリクエストのための例コードです。

UnityC++KotlinJavaスウィフトObjective-C

APIリファレンス: 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 {
                            // 呼び出し失敗。以下のエラーコードを参照してください
                    }
});

APIリファレンス: 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リファレンス: 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リファレンス: 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リファレンス: 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 リファレンス: 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	リクエストユーザーのプレイヤーID	Long
matchGameIndex	マッチゲームインデックス	Int
matchId	リクエストされたマッチID	Int
requestStatus	マッチリクエストのステータス (`requested`: マッチがリクエストされた, `notRequested`: リクエストされていない（または進行中のマッチなし）)	String
requestTimeUtc	マッチリクエストの時間	String
requestPoint	マッチスコア	Int
requestExtraData	マッチリクエスト中に提供された追加情報	String
matchingStatus	マッチ進行状況のステータス (`matchingInProgress`: マッチング進行中, `timeout`: 制限時間内にマッチングが完了しなかった, `matched`: マッチング成功)	String

マッチステータスの確認¶

ユーザーのマッチステータスを確認します。次の3つのステータスのいずれかを返します:

マッチング中
マッチング成功
タイムアウト

一致中¶

ステータスがマッチング中の場合、このメソッドを繰り返し呼び出して、ステータスがマッチング成功に変更されたかどうかを確認する必要があります。このメソッドは3秒から10秒の間隔で呼び出すことをお勧めします。アプリの実装特性に応じて、時間間隔をさらに延長することもできます。

一致成功¶

ステータスが一致成功の場合、開発者のゲームを起動します。これは、Hive SDKがゲームを一緒にプレイするユーザーを接続し、開発者が開発したゲームを楽しむことを可能にすることを意味します。

タイムアウト¶

ステータスがタイムアウトの場合（matchingStatus: timeout）、マッチを削除し、再度マッチをリクエストする必要があります。

マッチステータスを確認するための例のコードはこちらです。

UnityC++KotlinJavaスウィフトObjective-C

API リファレンス: 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 リファレンス: 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()) {
                            // 成功しました
                    } else {
                            // 呼び出しに失敗しました。以下のエラーコードを参照してください
                    }
});

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";          // Registered matchId 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
MatchMakingInterface.getRequestingStatus(matchId: matchId) { result, data in
    if result.isSuccess() {
        // 呼び出し成功
    } else {
        // 呼び出し失敗。以下のエラーコードを参照してください
    }
}

APIリファレンス: HIVEMatchMaking getRequestingStatus

#import "HIVEService.h"
NSString *matchId = @"25";          // コンソールに登録された matchId

[MatchMakingInterface getRequestingStatusWithMatchId:matchId
                                          completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 成功した呼び出し
    } else {
        // 呼び出しに失敗しました。以下のエラーコードを参照してください
    }
}];

一致の削除¶

このプロセスはマッチを削除します。次のいずれかの条件が適用される場合は、マッチを削除する必要があります：

ユーザーがマッチをキャンセルしました。
マッチのステータスはタイムアウトです。
ユーザー間のゲームは正常に完了しました。
- ゲームサーバーでゲーム結果（ランキング、スコア、勝敗ステータスなど）を更新した後、マッチの削除をリクエストする必要があります。

ここにマッチを削除するためのコードの例があります。

UnityC++KotlinJavaスウィフトObjective-C

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リファレンス: 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()) {
                            // 成功した呼び出し
                    } else {
                            // 呼び出しに失敗しました。以下のエラーコードを参照してください
                    }
});

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;
        String matchId = "25";          // コンソールに登録されたmatchId
        MatchMaking.INSTANCE.deleteRequesting(matchId, (result) -> {
                    if (result.isSuccess()) {
                            // 呼び出し成功
                    } else {
                            // 呼び出し失敗。以下のエラーコードを参照してください
                    }
});

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リファレンス: 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呼び出しが不正なパラメータ、ネットワークの問題、またはすでにマッチングリクエスト状態にあるときにマッチリクエストが行われた場合に失敗する