Tutorial 2 - Ticket MatchMaker

このチュートリアルでは、Diarkis のチケット方式マッチメイキングを実装します。各クライアントがチケットを発行するだけで、サーバーが同じチケットタイプを持つクライアントを自動的にグループ化します。ホストを選ぶ必要も、ルームを検索する必要もありません。

終了時には以下のことが身についています:

• DiarkisInterface から DiarkisMatchMaker モジュールを取得する方法

• DiarkisEventHandler にマッチメイキング用コールバックを登録する方法

• チケットの発行・キャンセルと各レスポンスの処理

• SDK からメンバーリストとオーナー情報を取得して表示に反映する方法

• チケット内でブロードキャストメッセージを送受信する方法

Tutorial 1 の接続フローが前提です。このシーンは Start() で自動接続するため、手動の接続ステップはありません。

チケット方式とは

Diarkis のマッチメイキングには主に 2 つの方式があります。

方式	概要
Ticket（チケット方式）	各クライアントがチケットを発行し、サーバーが条件の合うクライアントをグループ化する
Host/Search	誰かがホストとなってルームを作り、他のクライアントがそのルームを検索して参加する

チケット方式ではホストを意識する必要がありません。クライアントは SendIssueTicket() を呼ぶだけで、サーバーがグループ化を管理します。

ticketType（byte 0〜255）はマッチングのカテゴリを表します。同じ ticketType を持つチケット同士だけがグループ化されるので、ランクマッチ・カジュアルマッチなどモードごとに異なる値を使います。

マッチングの流れ

重要な非対称性: チケットを発行したクライアントは OnMMTicketIssueResponse でチケット参加を確認しますが、OnMMTicketJoin は受け取りません。OnMMTicketJoin は既存のチケットに後から参加した側（2 人目以降）にのみ届きます。コードはこの両方のケースに対応しています。

シーンのセットアップ

Tutorials/Scenes/Tutorial2-TicketMatchMaker.unity を開き、接続先を環境に合わせて変更してください。

private const string HOST       = "127.0.0.1:7000";
private const string CLIENT_KEY = "";

Play モードに入るとシーンが自動接続します。Network State ラベルが緑色になり「接続済み」と表示されると、Issue Ticket ボタンが有効になります。

Tip — 同一マシンで 2 クライアントをテストする場合: Edit > Project Settings > Player の Run In Background を有効にしてください。これを有効にしないと、フォーカスのない Unity インスタンスはネットワークイベントを処理せず、UI がウィンドウをアクティブにしたときしか更新されません。

コードの解説

MatchMaker モジュールの取得

DiarkisInterface diarkis = DiarkisNetworkManager.GetDiarkisInterface(INTERFACE_NAME);
_matchMaker = diarkis.MatchMaker;

機能モジュールはすべて DiarkisInterface を通じて取得します。Tutorial 4 の diarkis.Room も同じパターンです。

イベントの登録

DiarkisEventHandler handler = diarkis.EventHandler;

handler.OnUDPConnect(OnConnect, this);
handler.OnUDPDisconnect(OnDisconnect, this);
handler.OnUDPFail(_ => SetNetworkState("接続失敗", ColorRed), this);
handler.OnHttpError(_ => SetNetworkState("HTTP 認証エラー", ColorRed), this);

handler.OnMMTicketIssueResponse(OnIssueTicketResponse, this);
handler.OnMMTicketJoin(OnTicketJoin, this);
handler.OnMMTicketMemberJoin(args => OnTicketMemberJoin(args), this);
handler.OnMMTicketMemberLeave(args => OnTicketMemberLeave(args), this);
handler.OnMMTicketComplete(OnTicketComplete, this);
handler.OnMMTicketCancel(_ => OnTicketCancelled(), this);
handler.OnMMTicketBroadcast(OnTicketBroadcast, this);

このチュートリアルで登録するイベントの一覧です。

イベント	発火タイミング	コールバックシグネチャ
OnMMTicketIssueResponse	サーバーがチケット発行を応答	Action<DiarkisMMResponseEventArgs>
OnMMTicketJoin	既存チケットに参加した（参加者側のみ）	Action<DiarkisMMTicketJoinEventArgs>
OnMMTicketMemberJoin	他のプレイヤーがチケットに参加	Action<DiarkisMMTicketJoinEventArgs>
OnMMTicketMemberLeave	プレイヤーがチケットから離脱	Action<DiarkisMMResponseEventArgs>
OnMMTicketComplete	必要人数が揃いマッチング成立	Action<DiarkisMMResponseEventArgs>
OnMMTicketCancel	チケットがキャンセルされた	Action<DiarkisMMResponseEventArgs>
OnMMTicketBroadcast	ブロードキャストメッセージを受信	Action<DiarkisMMSyncEventArgs>

OnDestroy での UnregisterCallbacks(this) はお忘れなく。オーナーパターンの詳細は Tutorial 1 を参照してください。

SendIssueTicket() — チケットの発行

private void OnTicketClicked()
{
    byte ticketType = GetTicketType();
    SetStatus("チケット待機中...");
    _matchMaker.SendIssueTicket(ticketType);
}

SendIssueTicket は非同期です。結果は OnMMTicketIssueResponse で届きます。

OnIssueTicketResponse — チケットに参加した（発行者側）

private void OnIssueTicketResponse(DiarkisMMResponseEventArgs args)
{
    if (!args.IsSuccess())
    {
        SetStatus($"チケット発行失敗 (code: {args.GetErrorCode()})");
        return;
    }
    // 発行者は OnMMTicketJoin を受け取らないため、ここで UI を更新する
    SetStatus("チケット参加済み");
    RefreshTicketUI();
    RefreshButtons();
}

OnMMTicketIssueResponse の成功が、発行者がチケット待機状態に入ったことの確認です。OnMMTicketJoin は後から参加した側（2 人目以降）にのみ届きます。どちらのパスも RefreshTicketUI() を呼んでメンバーリストとオーナー表示を更新します。

メンバーリストとオーナーの更新

イベント引数からメンバー情報を読み取るのではなく、各イベント後に SDK から直接取得します。

private void RefreshTicketUI()
{
    byte ticketType = GetTicketType();

    if (_ownerIDValueText != null)
        _ownerIDValueText.text = _matchMaker.GetTicketOwnerUID(ticketType) ?? "";

    if (_memberListText != null)
    {
        var members = _matchMaker.GetMembers(DiarkisMatchMakerType.Ticket, ticketType);
        _memberListText.text = members != null && members.Count > 0
            ? string.Join("\n", members)
            : "";
    }
}

GetTicketOwnerUID() と GetMembers() は常にサーバー側の最新状態を反映しているため、参加・離脱・完了のすべてのコールバックからこのヘルパーを呼んでいます。

OnTicketComplete — マッチング成立

private void OnTicketComplete(DiarkisMMResponseEventArgs args)
{
    if (!args.IsSuccess())
    {
        SetStatus($"チケット完了失敗 (code: {args.GetErrorCode()})");
        return;
    }
    SetStatus("マッチング成立！");
}

OnMMTicketComplete はチケット内の全クライアントに同時に届きます。これをゲームセッション開始のシグナルとして使います。

SendTicketBroadcast — チケット内メッセージ

マッチング待機中にチケット内のメンバー全員へメッセージを送れます。SendTicketBroadcast は送信者自身にも届くため、ペイロードに自分の UID を含めることで送受信側を区別します。

private void OnMessageClicked(string message)
{
    // "uid:message" 形式でエンコードして送信者を識別できるようにする
    string myUID = GetMyUID();
    byte[] payload = Encoding.UTF8.GetBytes($"{myUID}:{message}");
    _matchMaker.SendTicketBroadcast(GetTicketType(), new ArraySegment<byte>(payload));
}

private void OnTicketBroadcast(DiarkisMMSyncEventArgs args)
{
    // "uid:message" を分解して自分か他者かを判別する
    DiarkisByteVector payload = args.GetPayload();
    string raw = Encoding.UTF8.GetString(/* payload のバイト列 */);
    int sep = raw.IndexOf(':');
    string senderUID = raw[..sep];
    string message   = raw[(sep + 1)..];

    string prefix = senderUID == GetMyUID() ? "[自分]" : $"[{senderUID}]";
    AddChatLine($"{prefix} {message}");
}

ペイロードはバイト配列です。形式はゲームに合わせて自由に決めてください。このサンプルでは UID プレフィックス付き UTF-8 テキストを使っています。

TicketState によるボタン制御

MatchMakerTicketState でクライアントの現在位置を把握し、ボタンと入力フィールドの有効/無効を切り替えます。

MatchMakerTicketState state = _matchMaker.GetTicketState(ticketType);

bool notStarted = state == MatchMakerTicketState.None;
bool inTicket   = state == MatchMakerTicketState.TicketJoined;
bool complete   = state == MatchMakerTicketState.TicketComplete;

_ticketButton.interactable    = notStarted && _connected;
_cancelButton.interactable    = inTicket;
_ticketTypeInput.interactable = !inTicket;  // チケット中は変更不可

Cancel と Leave の違い

この 2 つのメソッドは似ていますが、使うタイミングが異なります。

メソッド	呼ぶタイミング	呼べるのは誰か
SendTicketCancel	マッチング待機中（チケット未完了）	チケットオーナーのみ — 全メンバーのチケットをキャンセルする
SendTicketLeave	チケット完了後、ルームが生成された後	任意のメンバー — 他のメンバーに影響せずルームから退出する

このチュートリアルの Cancel ボタンは SendTicketCancel を呼び、オーナーが待機中のチケットをキャンセルします。非オーナーのメンバーがマッチング後のルームから抜けたい場合は、代わりに SendTicketLeave を使います。

バックフィル（上級）

このチュートリアルでは使用しませんが、バックフィルの概要を紹介します。

チケットが完了してゲームセッションが始まった後、プレイヤーが途中で離脱することがあります。バックフィルを使うと、チケットオーナーがサーバーに空きスロットへの新規プレイヤー補充をリクエストできます。マッチメイキングプロセス全体をやり直す必要はありません。

// プレイヤーが抜けた後、オーナーが代替プレイヤーをリクエスト
_matchMaker.SendTicketBackfill(ticketType);
// → 補充が見つかると OnTicketBackfillComplete が届く

// 補充待ちをやめる場合
_matchMaker.SendTicketCancelBackfill(ticketType);

マッチメイキングのロジック自体はサーバー側で処理されます。クライアントはリクエストを送り、OnTicketBackfillComplete コールバックを待つだけです。

次は Tutorial 3 - Host/Search MatchMaker で、明示的なホスト/サーチャーロールを使うマッチメイキングを学びます。