unity-cli

Unity CLI

コマンドラインを通じて、Unity プロジェクトのワークフローと自動化を効率化します。

このスキルを使用する場合

• 環境に Unity CLI をインストールし、動作を確認する
• CI/CD パイプラインや自動ビルドの認証を設定する
• Unity プロジェクトをプログラムで作成、管理する
• ビルド、テスト、プロジェクト初期化のワークフローを自動化する
• クラウドセーブ、ライセンス、組織の設定を行う
• Unity CLI を GitHub Actions、Jenkins、その他の CI システムに統合する

このスキルを使用しない場合

• インタラクティブなゲーム開発ワークフローの場合 → unity-gamedev-skill-pack を使用します
• グラフィックスやレンダリングのタスクの場合 → threejs-* またはエンジン固有のスキルを使用します
• ゲーム内の UI デザインの場合 → game-studio-harness または open-design-game-ui-* を使用します
• VFX やアニメーションの場合 → game-vfx または video-motion-previs を使用します

手順

ステップ 1：自動化の目的を把握する

以下を特定します。

• 目的：ビルドの自動化、プロジェクトのセットアップ、CI/CD への統合、クラウド操作、ライセンスのいずれか
• 環境：ローカル開発、GitHub Actions、Jenkins、GitLab CI、またはカスタムランナー
• 範囲：単一のプロジェクト、モノレポ、または組織全体の自動化
• 認証：サービスアカウント、個人用トークン、またはインタラクティブログイン

ステップ 2：前提条件を確認する

以下を確認します。

dotnet --version
which unity-cli || which unity

インストールされていない場合は、ステップ 3 に進みます。

ステップ 3：Unity CLI をインストールする

ローカルへのインストール：

bash .agent-skills/unity-cli/scripts/setup.sh --install

Docker（CI/CD）：

CLI が事前にインストールされた公式 Unity Docker イメージを使用します。

docker pull unityci/editor:<version>-<platform>-<architecture>

手動（システム全体）：

Unity CLI のインストールのドキュメントに従い、PATH に追加します。

ステップ 4：認証する

インタラクティブログイン：

unity-cli manage licensing --authenticate

CI/CD トークン（推奨）：

export UNITY_SERIAL=<serial>
export UNITY_EMAIL=<email>
export UNITY_PASSWORD=<password>

unity-cli manage licensing --validate

サービスアカウントでは、平文のパスワードの代わりに個人用アクセストークンを使用します。

ステップ 5：一般的なワークフローを実行する

新しいプロジェクトを作成する：

unity-cli project create --name myproject --template 3d

Editor のインストールを管理する：

# List available Editor versions
unity-cli install --list

# Install exact Editor version with specific modules
unity-cli install 2023.2.10f1 -m android ios webgl --accept-eula --yes

# Open project with auto-detected Editor version
unity-cli open ./MyGame

検証可能な出力（JSON/TSV）でビルドする：

# Machine-readable build output
unity-cli build --project /path/to/project \
  --platform WebGL \
  --output /path/to/build \
  --format json > build-result.json

# Parse results in CI
cat build-result.json | jq '.success'

Pipeline パッケージを呼び出す（localhost API）：

# Requires: com.unity.pipeline experimental package installed
# Requires: Editor running with --api-port flag

# Example: Evaluate C# in running Editor
curl -X POST http://localhost:14000/eval \
  -H "Authorization: Bearer $PIPELINE_TOKEN" \
  -d '{"code": "Debug.Log(Application.version)"}'

セットアップを検証する：

unity-cli doctor

エビデンスを伴うテストを実行する：

unity-cli test --project /path/to/project \
  --results-file test-results.xml \
  --format json > test-output.json

ステップ 6：CI/CD に統合する

GitHub Actions ワークフローの例：

name: Unity Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: bash .agent-skills/unity-cli/scripts/setup.sh --ci
      - run: unity-cli build --project . --platform WebGL --output ./dist
      - uses: actions/upload-artifact@v3
        with:
          name: build
          path: ./dist

Jenkins、GitLab CI、その他のランナーについては、references/ci-cd-patterns.md を参照してください。

ステップ 7：失敗のトラブルシューティングを行う

ライセンスの検証に失敗する場合：

unity-cli manage licensing --validate --verbose

依存関係が見つからずビルドに失敗する場合：

unity-cli project validate --project /path/to/project

CLI が見つからない場合：

bash .agent-skills/unity-cli/scripts/setup.sh --diagnose

よくある問題と解決方法については、references/troubleshooting.md を参照してください。

例

例 1：WebGL ビルド用に CI/CD をセットアップする

GitHub Actions ワークフローで、ゲームを WebGL 向けにビルドする必要があります。このスキルを使用して、指定したバージョンの Editor をインストールし、プロジェクトを検証して、構造化された出力でビルドし、結果を解析します。

例 2：本番環境でゲームのビルドを検証する

AI エージェントが、ビルドの成功を確認し、出力パスを取得する必要があります。JSON 形式のビルド出力を使用して成功または失敗を解析し、エージェントが構造化された結果に基づいて判断できるようにします。

例 3：Pipeline パッケージ経由で実行中の Editor にクエリする

Editor の実行中に、CI ジョブでビルド情報を確認する必要があります。com.unity.pipeline パッケージをインストールし、--api-port を指定して Editor を起動してから、スクリプトからカスタム CLI コマンドをクエリします。

ベストプラクティス

1. CI/CD ではトークンを使用し、 リポジトリ内のファイルに平文のパスワードを記載しないでください。
2. ビルド前に検証します。 — project validate で設定エラーを早期に検出します。
3. ビルドにバージョンを付けます。 — リリースに明示的なタグを付け、CI の出力とソースを対応付けます。
4. ビルドアーティファクトをキャッシュします。 — 実行間で Editor のキャッシュを再利用し、CI を高速化します。
5. まずローカルでテストします。 — CI にコミットする前に、マシン上で CLI コマンドが動作することを確認します。
6. 公式 Docker イメージを使用します。 — ビルド済みのイメージを使うと、OS 依存関係の差異を避けられます。
7. CLI を最新の状態に保ちます。 — バグ修正や新機能を利用できるよう、定期的に最新の安定版へ更新します。

参考資料

• Unity CLI のドキュメント
• references/commands.md — コマンドの詳細リファレンス
• references/ci-cd-patterns.md — GitHub Actions、Jenkins、GitLab CI の例
• references/production-workflows.md — エビデンス付きの検証可能なゲーム制作ワークフロー
• references/troubleshooting.md — よくあるエラーと解決方法
• scripts/setup.sh — インストールと検証の自動化