個人マッチメイキング

個人マッチメイキングは、ユーザーが一人でゲームに参加したいときに使用されます。

SDKにおけるマッチメイキング操作の流れ¶

Hive SDKを使用して個人マッチメイキングを実装する際の全体的な操作の流れは、以下の図に示されています。

マッチリクエスト¶

各ユーザーに対してマッチングをリクエストしています。

リクエストを行う前に、HiveコンソールでmatchIdに対応するマッチ情報を登録する必要があります。

マッチをリクエストする際には、スコア point（0から10^10未満の整数）と追加情報 extraData（ニックネーム、レベル、国などの256文字以内の情報）を引数として提供する必要があります。

Warning

もしマッチが進行中のときに再度マッチをリクエストすると、コールバック関数は既存のマッチを停止することなくエラー値（MatchMakingResponseError）を返します。したがって、マッチをリクエストする前に、まずマッチングステータスの確認を使用してマッチングステータスを確認してください。

ここにマッチングリクエストのための例のコードがあります。

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

APIリファレンス: 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
                    }
});

#include "HiveMatchMaking.h"

int MatchId = 25;                           // コンソールに登録されたmatchId
int Point = 300;                            // マッチに使用されるポイント
FString ExtraData = TEXT("your extraData"); // マッチに使用する追加情報

FHiveMatchMaking::RequestMatchMaking(MatchId, Point, ExtraData, FHiveMatchMakingOnMatchMakingDataDelegate::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;

        int matchId = 25;           // matchId registered in the console
        int point = 300;                // points used for the match
        string extraData = "your extraData";    // additional information to be used for the match

        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;
        int 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: 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 リファレンス: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSInteger 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オブジェクト構造¶

マッチングリクエストおよびマッチングステータス確認リクエストに対する応答として返されるオブジェクトです。リクエスト中に入力された情報とマッチング結果情報が含まれています。

フィールド名	説明	タイプ
requestPlayerId	マッチをリクエストしたユーザーのプレイヤーID	Long
requestGameIndex	マッチゲームインデックス	Int
requestMatchId	リクエストされたマッチID（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	成功したマッチに割り当てられたID（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

一致状況を確認¶

個人マッチに参加しているユーザーのマッチング状況を確認しています。

一致状況チェックメソッドを呼び出すと、以下の3つの一致状況のいずれかが返されます。

マッチング中 (matchingStatus: matchingInProgress)
マッチング成功 (matchingStatus: matched)
タイムアウト (matchingStatus: timeout)

これは一致状況を確認するためのサンプルコードです。

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

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
                    }
});

#include "HiveMatchMaking.h"

int MatchId = 25;       // コンソールに登録されたmatchId
FHiveMatchMaking::GetRequestingStatus(MatchId, FHiveMatchMakingOnMatchMakingDataDelegate::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;

        int 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;
        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リファレンス: HIVEMatchMaking getRequestingStatus

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

[MatchMakingInterface getRequestingStatusWithMatchId:matchId
                                          completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

一致中¶

マッチングステータスが進行中の場合、マッチングステータスがマッチ済みの状態に達したかどうかを確認するために、メソッドを繰り返し呼び出す必要があります。

リピートコールサイクルは3秒から10秒の間隔で呼び出すことをお勧めします。アプリの実装の特性に応じて、時間間隔を延長することも可能です。

一致成功¶

マッチングステータスがマッチ済みの場合、開発者のゲームが起動します。言い換えれば、Hive SDKを通じて接続されたユーザーがマッチングされると、開発者のゲームに参加できます。

タイムアウト¶

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

一致を削除¶

既存のマッチを削除しています。

次のいずれかのケースに該当する場合、試合を削除しなければなりません。

ユーザーがマッチをキャンセルした場合
マッチングステータスがタイムアウトの場合 (matchingStatus: timeout)
ユーザー間のゲームが正常に完了した場合

※ ゲームサーバーまたはゲームクライアントでゲーム結果（ランキング、スコア、勝敗状況など）を更新した後、試合の削除をリクエストする必要があります

これはマッチを削除するための例のコードです。

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

API リファレンス: 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
                    }
});

#include "HiveMatchMaking.h"

int MatchId = 25;       // コンソールに登録されたmatchId
FHiveMatchMaking::DeleteRequesting(MatchId, FHiveMatchMakingOnResultDelegate::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;

        int 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;
        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リファレンス: HIVEMatchMaking deleteRequesting

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

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

エラーコード¶

エラーコード	メッセージ	説明
NEED_INITIALIZE	MatchMakingNotInitialized	SDKのセットアップが行われていない場合 (AuthV4.setup)
INVALID_SESSION	MatchMakingNeedSignIn	AuthV4のサインインが行われていない場合
RESPONSE_FAIL	MatchMakingResponseError	- API呼び出し中の不正なパラメータによる失敗 - ネットワークの問題による失敗 - すでにマッチングリクエスト状態にあるときに再度マッチングを要求した - リクエストされていないマッチングの削除を要求した