Version: jp

sdk

note

Unity マッチメイキングは現在、クローズドベータテスト中です。このサービスの詳細については、マッチメイキングに関するドキュメントを参照してください。チュートリアル、FAQ、API 情報が含まれます。

Multiplay を使用してマルチプレイヤーゲームをホストすることに興味をお持ちですか？詳細についてはお問い合わせください。

ベータ版の SDK とサンプル#

マッチ関数 SDK は、マッチ関数の外部サンプルに含まれる、C# アセンブリのセットです。

note

マッチ関数で現在サポートされている .NET ランタイムのバージョンは、3.0 と 3.1 です。

マッチ関数の外部サンプルには、次の DLL ファイルが含まれます。

コア SDK のアセンブリ

Unity.Services.Matchmaking.Functions.Contracts.dll
Unity.Services.Matchmaking.Matchmaker.Contracts.dll

ヘルパーアセンブリ（ConfigurableMatchFunction を参照）

Unity.Services.Matchmaking.Functions.Base.dll

マッチ関数のオーサリングとテストを支援するテストシミュレーションライブラリ

Unity.Services.Matchmaking.TicketGenerator.dll

関数のスレッドセーフ#

caution

リソースの活用を最大化するために、マッチ関数が複数のスレッドで同時に実行されることがあります。そのため、関数がスレッドセーフな方法で記述されていることが重要です。

スレッドセーフでない例を次に示します。

public class MyCustomMatchFunction : ConfigurableMatchFunction<CustomConfig>
{
  readonly ILogger<MyCustomMatchFunction> _logger;
  static List<Proposal> _proposals;

  public MyCustomMatchFunction(ILogger<MyCustomMatchFunction> logger)
  {
    _logger = logger;
  }

  protected override async Task<IEnumerable&lt;Proposal>&gt; ExecuteAsync(FunctionContext functionContext, ITicketData ticketQuery, CustomConfig functionConfig)
  {
    // 初期化
    _proposals = new List<Proposal>();

    // 申請をビルドするためのコード
    _proposals.Add(proposal);

    return _proposals;
  }
}

これがスレッドセーフでない理由は、別のスレッドが ExecuteAsync を実行している場合、両方のスレッドが同じ申請のリスト（_proposals）を観察することになるため、それに変更を加えると最終的にマッチメーカーにまったく同じリストが戻される結果になることがあります。一般的に、非同期のメソッドからスレッドセーフでない方法でメンバー変数にアクセスすることは避けてください。

各マッチ関数が完全に独立して実行されるように、このロジックをこのように記述することをお勧めします。

public class MyCustomMatchFunction : ConfigurableMatchFunction<CustomConfig>
{
  readonly ILogger<MyCustomMatchFunction> _logger;

  public MyCustomMatchFunction(ILogger<MyCustomMatchFunction> logger)
  {
    _logger = logger;
  }

  protected override async Task<IEnumerable&lt;Proposal>&gt; ExecuteAsync(FunctionContext functionContext, ITicketData ticketQuery, CustomConfig functionConfig)
  {
    // 初期化
    var proposals = new List<Proposal>();

    // 申請をビルドするためのコード
    proposals.Add(proposal);

    return proposals;
  }
}

この例では、各関数が独自の申請のリストで初期化を実行し、その他の同時スレッドがデータを変更できないようにしています。

コントラクト#

マッチ申請#

/// <summary>
/// マッチ関数がチケットのコレクションを一緒にグループ化できるようにするための最初のクラスコンテナ
/// </summary>
public class Proposal
{
  /// <summary>
  /// 常に生成される申請 ID
  /// </summary>
  public Guid Id { get; }

  /// <summary>
  /// 一緒にグループ化するチケット
  /// </summary>
  public List<Ticket> Tickets { get; set; }

  /// <summary>
  /// マッチスケジューラーに戻されるカスタム情報
  /// </summary>
  public ProposalProperties Properties { get; set; }
}

ProposalProperties#

public class ProposalProperties
{
  /// <summary>
  /// 接続を事前に指定することで接続の割り当てをバイパスするマッチメイキングのバックエンドメカニズム。
  /// </summary>
  /// <remarks>
  /// これはバックエンドにマッチメイキングからプレイヤーを削除するよう指示し、
  /// 代わりにそれらのプレイヤーを既存のセッションやサーバーなどの別の場所にリダイレクトするのに便利です。
  /// </remarks>
  public string ConnectionOverride { get; set; }

  /// <summary>
  /// エラーメッセージを作成することで接続の割り当てをバイパスするマッチメイキングのバックエンドメカニズム。
  /// </summary>
  /// <remarks>
  /// これはバックエンドにマッチメイキングからプレイヤーを削除するよう指示し、
  /// 代わりにそれらのプレイヤーに各チケットの割り当てでエラーメッセージを表示するのに便利です。
  /// </remarks>
  public string AssignmentError { get; set; }

  /// <summary>
  /// スコアベースのマッチ評価を実行するために、ScoreEvaluator と組み合わせて使用されます。デフォルト値は 0 です。
  /// </summary>
  public double Score { get; set; }

  /// <summary>
  /// チケットとセッションサービスに指定されるカスタム割り当てとマッチ情報。
  /// </summary>
  /// <remarks>
  /// * [非推奨] このプロパティはマッチメーカー v2.x.x では非推奨です（ただし引き続きサポートされます）。
  /// * 契約の互換性はマッチメーカー 2.x.x のすべてのバージョンで維持されます。
  /// * AssignmentProperties が指定されると、ディレクターが JObject を
  /// チケットごとの TicketProperties と SessionProperties にコピーします。このシナリオでは、MatchProperties
  /// は伝送されず、各チケットとセッションサービスが前と同じ
  /// プロパティを受け取ります。
  /// * このプロパティは、マッチメーカー v3.x.x 以降で削除される予定です。
  /// </remarks>
  public JObject AssignmentProperties { get; set; }

  /// <summary>
  /// チケットごとのプロパティ。キーはチケット ID で、値は割り当て中にチケットにアタッチする
  /// JObject です。意図されているチケットにのみ
  /// 指定されます。
  /// </summary>
  /// <remarks>
  /// マッチ関数に TicketProperties が設定されると、AssignmentProperties は
  /// 無視されます。
  /// </remarks>
  public IDictionary<string, JObject> TicketProperties { get; set; }

  /// <summary>
  /// セッションサービス/DGS にのみ指定されるプロパティ。
  /// </summary>
  /// <remarks>
  /// マッチ関数に SessionProperties が設定されると、AssignmentProperties は
  /// 無視されます。
  /// </remarks>
  public JObject SessionProperties { get; set; }

  /// <summary>
  /// チケットとセッションサービスの両方に指定されるプロパティ。
  /// そのマッチのグローバルまたは共有プロパティを配置する場所と
  /// 考えてください。
  /// </summary>
  /// <remarks>
  /// マッチ関数に MatchProperties が設定されると、AssignmentProperties は
  /// 無視されます。
  /// </remarks>
  public JObject MatchProperties { get; set; }

  /// <summary>
  /// ターゲット割り当てプロバイダーに関連するプロパティ。
  /// </summary>
  /// <remarks>
  /// * [非推奨] <see cref="DgsAllocationProperties"/> に置き換わりましたが、引き続き 2.x.x でサポートされます。
  /// </remarks>
  public List<AllocationPropertiesBase> AllocationProperties { get; set; }

  /// <summary>
  /// 専用ゲームサーバーを割り当てるために必要なプロパティ。
  /// </summary>
  /// <remarks>
  /// 各 DGS プロバイダーが割り当てを実行するには、特定のデータが必要です。
  /// マッチ関数はこのデータをサポート対象の各プロバイダーに提供します。
  /// チケット割り当てサービスは、指定されたデータを使用して割り当てを設定することで、
  /// 割り当てを実行するプロバイダーを選択します。
  /// </remarks>
  public IList<DgsAllocationProperties> DgsAllocationProperties { get; set; }
}

IMatchFunction と ConfigurableMatchFunction#

IMatchFunction は、マッチ関数の動作を定義するために実装する必要があるコアインターフェースです。ただし、次のヘルパークラスはオプションでその関数に運用設定を挿入およびロードすることができるため、ConfigurableMatchFunction<TConfig> で開始することをお勧めします。

public class MyCustomMatchFunction : ConfigurableMatchFunction<CustomConfig>
{
  // マッチ関数のコンテキストに渡されるロガー。
  readonly ILogger<MyCustomMatchFunction> _logger;

  public MyCustomMatchFunction(ILogger<MyCustomMatchFunction> logger)
  {
    _logger = logger;
  }

  // マッチ関数のメインメソッド。カスタム設定オブジェクトが自動的にチケットクエリインターフェースと一部の
  // コンテキスト情報（プールと cancellationToken）と一緒に渡されます。
  protected override async Task<IEnumerable&lt;Proposal>&gt; ExecuteAsync(FunctionContext functionContext, ITicketData ticketQuery, CustomConfig functionConfig)
  {
    // ticketQuery インターフェースを使用してチケットを照会します。
    // 申請のリストをビルドして返します。
  }
}

サンプル#

次のマッチ関数のサンプルが含まれています。Samples-download には各サンプルの説明と共に readme が含まれます。

AvoidParties
ClanAlliance
ClanAllianceExtended
Simple
SimpleBackfill
Team-Qos
Timeout

Csproj に関するメモ#

アップロードプロセス中に関数が正しくロードされるには、アップロードしている .zip ファイルにコア SDK ライブラリを含めないでください。この回避策の詳細については、マッチメーカーのリリースノートを参照してください。

<ItemGroup>
  <Reference Include="Unity.Services.Matchmaking.Functions.Contracts, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null">
    <HintPath>..\external\Unity.Services.Matchmaking.Functions.Contracts.dll</HintPath>
      <Private>false</Private>
  </Reference>
  <Reference Include="Unity.Services.Matchmaking.Matchmaker.Contracts, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null">
    <HintPath>..\external\Unity.Services.Matchmaking.Matchmaker.Contracts.dll</HintPath>
      <Private>false</Private>
  </Reference>
</ItemGroup>