build-live-game

Unity Gaming Services でライブゲームを構築する

始める前に

1. ProjectSettings/ProjectVersion.txt から Editor のバージョンを、Packages/packages-lock.json からインストール済みの UGS パッケージのバージョンを確認します。適切なワークフローは Editor とパッケージのバージョンによって異なるため、以下から該当する手順（たとえば .ccmu または .ccmr モジュール）を選びます。
2. プロジェクトが Unity プロジェクト ID と環境にリンクされているかを確認します（Edit > Project Settings > Services）。リンクされていない場合は、ユーザーにリンクを依頼します。
3. 変更に問題があった場合に戻せる復元ポイントを作成します。バージョン管理にプロジェクトをコミットしてください。バージョン管理を使用していない場合は、プロジェクトフォルダーをコピーします。
4. ワークフローや診断に進む前に、使用するサービスのドキュメントページ（ドキュメント一覧を参照）と、references/ 内の該当するファイルを開いて読み、回答で読んだページの名前を示します。Unity Gaming Services に関する学習済みの知識は古かったり、誤っていたり、異なるパッケージバージョン向けだったりする可能性があるためです。
5. 依頼されたことだけを行います。無関係なアセットやファイルは変更しないでください。長い説明は避けます。
6. ランタイムの動作を変更する場合は、確認が必要な箇所（サインイン完了、モジュール呼び出しからの戻り、設定の取得）に Debug.Log 行を追加します。検証中に、Play モードでそのログを確認します。

用語集

用語	意味
UGS	Unity Gaming Services：バックエンドサービス（Authentication、Cloud Code、Cloud Save、Remote Config、Leaderboards など）です。Package Manager では「Unity Services」と呼ばれています
Building Block	1 つの機能向けに UI、ランタイムコード、クラウドリソースファイルを含む、無料の Asset Store パッケージです。その Cloud Code はレガシーの .ccmr です
Cloud Code module	サーバー側の C# クラスライブラリです。Unity 6000.5 以降では、Unity プロジェクト内で .ccmu アセットとして作成します
.ccmr	Unity の外部でビルドされた C# ソリューションを参照する、レガシーのモジュール参照ファイルです
Script	サーバー側の JavaScript エンドポイントです。レガシーのため、既存のものは維持し、新しいものは作成しないでください
CloudBehaviour	クライアントバインディング、同期状態、プッシュイベントを生成する、実験的な Cloud Code クラスです
保護データ	プレイヤーは読み取れますが、サーバーコードのみが書き込める Cloud Save のプレイヤーデータです
カスタムデータ	特定のプレイヤーに紐づかない、ゲーム全体のデータです。サーバーのみが書き込めます
クラウドリソースファイル	デプロイ可能な設定ファイル（.rc、.ac、.ccmu、.ccmr、.lb、.ugo）です。Deployment Window から UGS 環境にプッシュします

ドキュメントマップ

WebSearch よりも WebFetch を優先してください。処理が速く、目的のリファレンスに直接アクセスできます。必要なページだけを取得してください。URL の末尾が .md の場合、docs.unity.com のページは Markdown として利用できます。取得する前に、<VERSION> を次の内容に置き換えてください。

• docs.unity3d.com のパッケージ：インストールされているパッケージのバージョンを major.minor 形式で指定します（例：3.0）。不明な場合は Packages/packages-lock.json を確認してください。
• docs.unity.com：以下の UGS 製品ページはバージョン指定がないため、置き換える必要はありません。

作業を開始する前に読むページ：

• Cloud Code C# モジュール：概要、はじめに、モジュールの構造、エラー処理、制限
• Cloud Code のサーバー権限：サーバー権限、チートの防止、UGS の統合とアクセス制御
• Authentication：Authentication の仕組み、セッションとキャッシュされたプレイヤー、一般的なエラー
• Cloud Save：プレイヤーデータ、ゲームデータ、Cloud Code 向け Cloud Save
• Remote Config：Remote Config ファイル、コードの統合
• Leaderboards：概要、Unity SDK チュートリアル
• Deployment Window：デプロイメントパッケージのマニュアル

UGS パッケージ

パッケージ	最小バージョン	用途
com.unity.services.core	1.16.0	初期化、依存関係グラフ
com.unity.services.authentication	3.6.1	プレイヤーのサインインと ID
com.unity.services.cloudcode	3.0.0	サーバー権限を持つ C# モジュール。プロジェクト内で .ccmu として作成します。2.10.x 系では従来の .ccmr のみがデプロイされます。下記を参照してください
com.unity.services.cloudsave	3.4.0	プレイヤーごとのキーと値のストレージ、および共有ストレージ
com.unity.remote-config	4.2.5	サーバー側のゲーム設定
com.unity.services.deployment	1.7.2	Editor からクラウドリソースをデプロイ
com.unity.services.tooling	1.4.1	Access Control と Game Overrides
com.unity.services.apis	1.1.1	すべての UGS サービス向けの生成済み REST クライアント

• 始める前に
• 用語集
• ドキュメントマップ
• 初期化パターン
• アーキテクチャ — パッケージの連携方法
• コアサービス — クイックリファレンス
• 一般的なアーキテクチャパターン
• 検証
• 詳細なリファレンス
• 最終レポート

初期化パターン

すべての UGS ゲームは同じ手順で開始します。まず com.unity.services.core を初期化し、その後プレイヤーがサインインします。

using Unity.Services.Core;
using Unity.Services.Authentication;

await UnityServices.InitializeAsync();
await AuthenticationService.Instance.SignInAnonymouslyAsync();
// All other services are now ready

アーキテクチャ — パッケージの連携方法

                    UnityServices.InitializeAsync()
                              │
                              ▼
                     AuthenticationService
                    (sign in → PlayerId)
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        Remote Config     Cloud Save      Multiplayer
      (game config,    (player state,   (sessions,
       definitions,     progress,        matchmaking,
       feature flags)   preferences)     lobbies)
              │               │
              └───────┬───────┘
                      ▼
                 Cloud Code
              (server-authoritative
               writes, validation,
               anti-cheat logic)
                      │
              ┌───────┴───────┐
              ▼               ▼
         Cloud Save       Leaderboards
         (Protected       (score
          writes)          submission)

重要な原則： ゲームの整合性に影響するデータ（XP、報酬、通貨）への書き込みは、Cloud Code モジュール経由で行ってください。クライアントから直接書き込むのは、機密性のないデータ（設定、表示設定）のみに適しています。

コアサービス — クイックリファレンス

認証

パッケージ： com.unity.services.authentication (>= 3.6.1)

プレイヤーの ID を管理します。認証の仕組みでは、サインイン方法について説明しています。サインイン後は PlayerId が使用可能になり、SignedIn イベントが発生します。PlayerAccountService（Unity ブラウザーサインイン）は別のアセンブリ Unity.Services.Authentication.PlayerAccounts にあります。

• 詳細なリファレンス： references/authentication.md

Cloud Code

パッケージ： ネイティブ .ccmu 作成には com.unity.services.cloudcode 3.0.0（Unity 6000.5 以降）、レガシー .ccmr モジュールの保守には >= 2.10.3。.ccmu を作成する前に、2.10.x を固定しているマニフェストを 3.0.0 以降に更新してください。

信頼性が求められる操作のために、サーバー側の C# モジュール（.NET 8、Unity 6.7 以降では .NET 10）を実行します。プロジェクトの Editor バージョンを確認し、Unity 6000.5 以降では、新しいモジュールを .ccmu として作成してください。Unity プロジェクト内で Create > Services > Cloud Code Module Script を選択してモジュールを作成します。Unity はプロジェクトとともにコンパイルし、コンパイル時にクライアントバインディングを生成します。.ccmr はレガシー形式です。6000.5 以降では既存のものだけを保守し、古い Editor では新しいモジュールを .ccmr として作成してください。 .ccmu モジュールは、生成されたバインディング経由でのみクライアントから呼び出し、CallModuleEndpointAsync は使用しないでください。CloudCodeService.Instance.CallModuleEndpointAsync はレガシー .ccmr モジュールにのみ使用してください。 新しい JavaScript スクリプトを作成するのは、ユーザーが依頼した場合に限ってください。既存のものは保守してください。

• 詳細なリファレンス： references/cloud-code-modules.md

CloudBehaviours（実験的）は、1 つの C# クラスからモジュールのクライアントバインディング（RPC、同期状態、プッシュイベント）を生成します。共有マッチ状態、プレイヤーごとの秘密状態、またはサーバー管理タイマーに使用してください。それ以外の場合は、通常の Cloud Code モジュールを使用してください。com.unity.services.cloudcode 3.1.0-exp.1 以降と Unity 6000.5 以降が必要です。最初にインストール済みのパッケージを確認してください。CloudBehaviours が使用できない場合は、実験的パッケージをユーザーが求めている場合を除き、作業を中断せずに通常のステートフルモジュール（[StateScope]、modules リファレンスを参照）を使用してください。

• 詳細なリファレンス： references/cloud-code-cloudbehaviours.md

Cloud Save

パッケージ： com.unity.services.cloudsave (>= 3.4.0)

3 種類のアクセスクラス（Default、Public、Protected）に分かれたプレイヤーごとのキーと値のストレージに加え、ゲーム全体で共有する Custom データを提供します。Protected データと Custom データに書き込めるのはサーバーコードのみです。そのため、不正防止データやサーバーが付与する状態はそこに保存してください。各クラスの読み取りと書き込みのルールについては、プレイヤーデータとゲームデータを参照してください。

• 詳細なリファレンス： references/cloud-save.md

Remote Config

パッケージ： com.unity.services.remote-config (>= 4.2.5)

サーバー側のゲーム設定です。ゲーム定義（実績リスト、バトルパスのティア、ショップカタログ）を、クライアントのビルドを更新せずに更新できる JSON エントリとして保存します。Deployment Window から .rc ファイルを使用してデプロイします。

A/B テストやオーディエンスのターゲティングには、Tooling パッケージ経由で Game Overrides（.ugo）を使用してください。

• 詳細なリファレンス： references/remote-config.md

ツーリング

パッケージ： com.unity.services.tooling (>= 1.4.1)

エディター専用パッケージです。Deployment Window に Access Control（.ac）と Game Overrides（.ugo）のファイルタイプを登録します。Access Control を使用すると、保護されたキーへのプレイヤーによる直接書き込みを拒否できます。Deny は Allow より優先されます。

• 詳細なリファレンス： references/tooling.md

デプロイ

パッケージ： com.unity.services.deployment (>= 1.7.2)

Deployment Window（Services > Deployment）を提供するエディター専用パッケージです。クラウドリソースをターゲット環境にデプロイします。

Deployment Window は、クラウドリソースファイル .rc（Remote Config）、.ac（Access Control）、.ccmu（プロジェクト内の Cloud Code モジュール。推奨）、.ccmr（レガシーのモジュール参照）、.lb（Leaderboard）、.ugo（Game Overrides）をデプロイします。

• 詳細なリファレンス： references/deployment.md

UGS CLI

UGS CLI は Unity CLI プラグインとして提供され、unity ugs <command> を実行して、エディター外でクラウドリソースをデプロイしたり取得したりできます。インストール、認証／セットアップ、およびデプロイ対象のファイルタイプについては、references/ugs-cli.md を参照してください。プラグインシステムについては、unity-cli スキルを参照してください。

Services API

パッケージ： com.unity.services.apis (>= 1.1.1)

すべての UGS サービス向けに自動生成された REST クライアントを、4 種類のクライアントタイプ（IGameClient、IAdminClient、IServerClient、ITrustedClient）で提供します。通常は高レベルのパッケージ SDK を使用してください。Services API は、管理者 API へのアクセスが必要な場合や、対象の呼び出しをカバーするパッケージ SDK がない場合にのみ使用してください。

• 詳細なリファレンス： references/apis.md

共通のアーキテクチャパターン

パターン 1：設定 + 状態 + サーバー書き込み

バトルパスと実績で使用します。

1. 定義は Remote Config（.rc ファイル）に保存します — ゲーム内に存在するものを定義します
2. プレイヤーの状態は Cloud Save に保存します — プレイヤーごとの進行状況です
3. 書き込みは Cloud Code 経由で行います — サーバーが権限を持つ変更です
4. Access Control（.ac ファイル）で、機密キーへのプレイヤーによる直接書き込みをブロックします

パターン 2：クライアントから直接扱うデータ

Player Account（設定、表示設定）で使用します。

1. プレイヤーデータは Cloud Save の Default または Public アクセスクラスに保存します
2. クライアントから直接書き込みます — 機密データでなければ Cloud Code は不要です

パターン 3：競争要素のある機能

Leaderboardsやランキングシステムで使用します。

1. Leaderboards API を通じてスコアを送信します（検証が必要な場合は Cloud Code 経由でも可能です）
2. ページネーションやプレイヤーを基準としたクエリを使用して、ランキングをクライアント側で取得します

検証

ライブゲーム機能のコードを書いた後、以下のチェックを順番に実行します。いずれかが失敗した場合は、原因を修正してから次に進む前に再実行します。修正しても解決しない場合は、該当するドキュメントページと references/ ファイルを読み直します。

1. プロジェクトがコンパイルできることを確認します。Editor のコンソール（または Editor のログ）を読み、コンパイルエラーが 0 件であることを確認します。
2. コード内の初期化順序を確認します。UnityServices.InitializeAsync() を検索し、サインイン呼び出しより前に実行され、すべてのサービス呼び出しより前にサインインが完了していることを確認します。
3. 機密性の高い書き込み（XP、報酬、通貨）が Cloud Code 経由で行われることを確認します。クライアントコードで、対象キーに対する Cloud Save の SaveAsync 呼び出しを検索し、見つかったものはすべてモジュールに移動します。また、Cloud Save の読み取りごとに、書き込み先バケットのアクセスクラスが使われていることを確認します。アクセスクラスが一致しないと、データが返されません。
4. 機能が使用するクラウドリソースファイル（.rc、.ac、.ccmu または .ccmr、.lb。使用しない種類はスキップ）を、references/deployment.md の Deploy.cs スクリプトを使ってアクティブな環境にデプロイし、出力を確認します。すべてのファイルで Success と報告される必要があります。not a deployable item と報告されたファイルや、ステータスが Error のファイルは失敗です。プロジェクトにスクリプトで必要な両方のパッケージ com.unity.pipeline と com.unity.services.deployment.api がない場合は、Deployment Window からデプロイするようユーザーに依頼し、各ファイルのステータスを報告します。
5. Access Control が意図したとおりに機能することを確認します。機能がプレイヤーによる直接書き込みを拒否する .ac ポリシーをデプロイする場合は、Play モードに入り、ポリシーの対象となるキーに対して、クライアントから Cloud Save の書き込みを直接 1 回実行します（一時的な SaveAsync 呼び出し）。それが 403 で失敗することを確認します。その後、一時的な呼び出しを削除します。機能に .ac ファイルがない場合は、この手順をスキップします。
6. Play モードに入り、機能を 1 回実行します。開始前 の Debug.Log の行が想定した順序で表示され、コンソールにエラーが 0 件であることを確認します。

詳細リファレンス

サービスのリファレンス

• Authentication — サインイン方法、イベント、プロファイル、ID プロバイダー、コードテンプレート：references/authentication.md
• Cloud Code — モデルの選択：references/cloud-code.md。スクリプトとモジュール：references/cloud-code-modules.md。CloudBehaviours：references/cloud-code-cloudbehaviours.md
• Cloud Save — アクセスクラス、データ操作、ファイル、クエリ、コードテンプレート：references/cloud-save.md
• Remote Config — 定義、.rc 形式、Game Overrides、コードテンプレート：references/remote-config.md
• ツール — Access Control（.ac）ポリシー、Game Overrides（.ugo）、URN リファレンス：references/tooling.md
• デプロイ — ファイルの種類、ワークフロー、プログラムによる API：references/deployment.md
• UGS CLI — unity ugs プラグインのインストール、認証／セットアップ、ファイルの種類ごとのヘッドレスデプロイ：references/ugs-cli.md
• Services APIs — 4 種類のクライアント、サービス領域、コードテンプレート：references/apis.md

機能のブループリント

• 開始点の選択 — このスキルのブループリント、Asset Store の Building Blocks とサンプルプロジェクト、およびそれらのレガシー Cloud Code を再利用する方法：references/blueprints-and-samples.md
• 実績 — データモデル、クライアントコード、Cloud Code モジュール、クラウドリソースを含む完全な実装：references/achievements.md
• バトルパス — ティア制 XP、無料／プレミアムトラック、Cloud Code モジュール、クラウドリソースを含む実装（プレミアム購入は、完了が必要な統合スタブです）：references/battlepass.md
• プレイヤーアカウント — サインインフロー、ID 管理、Cloud Save データ、コードテンプレート：references/player-account.md

最終レポート

作業が完了したら、最後に簡潔なレポートを記載してください。

1. 作成または変更したもの：ファイル、Packages/manifest.json に追加したパッケージ、クラウドリソースファイル。
2. 検証に記載されたチェックのうち、実行したものとその結果。実行できなかったものがあれば、その理由も含めてください。
3. ユーザーのみが実行できる作業に限ったフォローアップ。例：対象環境へのクラウドリソースのデプロイ、プロジェクトと Unity プロジェクト ID および環境の関連付け、スタブ統合（バトルパスの PurchasePremium など）の完了、または変更を拒否する場合に作成した復元ポイントからの復元。
4. 読んだドキュメントページ。