コンテンツにスキップ

個人マッチメイキング

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

SDKにおけるマッチメイキング操作フロー

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

マッチリクエスト

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

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

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

Warning

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

こちらはマッチングリクエストのための例のコードです。

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

API リファレンス: MatchMaking ::requestMatchMaking

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
        using namespace std;
        using namespace hive;

        int 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;
        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つの一致するステータスのいずれかが返されます。

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

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

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

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 registered in the console

[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)

  • ユーザー間のゲームが正常に完了した場合

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

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

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

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

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 registered in the console

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

エラーコード

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