マッチメイキング¶

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

始める¶

Hiveでマッチメイキングを使用する方法は大きく2つあります。

Hive SDK
Hive サーバーAPI

ここでは Hive SDK の方法を案内します。

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

マッチング方式とマッチング人数に関する詳細は、上記のコンソールガイドをご確認ください。

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

マッチメイキング機能を実装する際は、次の流れを参考にしてください。

マッチングリクエスト¶

マッチングをリクエストします。ユーザーごとにリクエストが必要であり、matchIdに該当するマッチ情報を事前にHiveコンソールに登録する必要があります。そして、マッチに使用するスコアpoint（0から10^10未満の整数）とマッチに使用する追加情報extraData（ニックネーム、レベル、国など256文字以内の情報）を引数としてリクエストします。

Note

すでにマッチングをリクエストした状態でマッチングを再リクエストすると、既存のマッチングは中断されませんが、エラーコールバック（MatchMakingResponseError）が渡されます。必ずマッチング状態確認でまずマッチング状態を確認してからマッチングをリクエストしてください。

次はマッチングリクエストの例コードです。

UnityアンリアルエンジンC++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()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

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

requestMatchMatking(), getRequestingStatus() メソッド呼び出しの結果として MatchMakingData オブジェクトを渡します。

MatchMakingDataオブジェクトの構成¶

フィールド名	説明	タイプ
matchPlayerId	リクエストしたユーザーの playerId	Long
matchGameIndex	マッチゲームインデックス	Int
matchId	リクエストしたマッチID	Int
requestStatus	マッチリクエストの状態 (`requested`: マッチングをリクエストした, `notRequested`: リクエストしていない（または、既にマッチングされて進行中のマッチがない）)	String
requestTimeUtc	マッチリクエストの時刻	String
requestPoint	マッチスコア	Int
requestExtraData	マッチリクエスト時に渡したその他の情報	String
matchingStatus	マッチ進行状況 (`matchingInProgress`: マッチング進行中, `timeout`: 制限時間内にマッチングが行われなかった, `matched`: マッチングが成立した)	String

マッチング状態の確認¶

ユーザーのマッチング状態を確認します。マッチング状態として次の3つのうち1つを返します。

マッチング進行中
マッチング成立
タイムアウト

マッチング進行中¶

状態が マッチング進行中の場合、繰り返しこのメソッドを呼び出して マッチング成功 状態になったかどうかを確認する必要があります。繰り返し呼び出しの間隔は3〜10秒ごとに呼び出すことを推奨します。アプリの実装特性に応じて、時間間隔をさらに延ばすことも可能です。

マッチング成立¶

状態が マッチング成功の場合、開発会社のゲームを実行します。つまり、Hive SDKがゲームを共にするユーザー同士をつなげたため、これらのユーザーは開発会社が実装したゲームを一緒に楽しむことになります。

タイムアウト¶

状態がタイムアウト(matchingStatus: timeout)の場合はマッチを削除し、マッチを再リクエストする必要があります。

以下はマッチング状態確認の例コードです。

UnityアンリアルエンジンC++KotlinJavaスウィフトObjective-C

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

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

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]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

マッチング削除¶

マッチングを削除します。以下のいずれかの条件に該当する場合、マッチングを削除する必要があります。

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

次はマッチング削除の例のコードです。

UnityアンリアルエンジンC++KotlinJavaスウィフトObjective-C

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

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

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呼び出し時に無効なパラメータで失敗した場合、ネットワークの問題で失敗した場合、すでにマッチングリクエストがされている状態でマッチングリクエストをした場合