unity-build-pipeline

Unity ビルドパイプライン

Unity 6.3 LTS のプレイヤービルドを設定、スクリプト化、自動化します。シーン、プラットフォームターゲット、スクリプティングバックエンド、ストリッピング、ヘッドレス／CI ビルドを扱います。対象は Unity 6.3 LTS (6000.3) です。

使用する場面

• Build Settings／Profiles の設定、プラットフォームとスクリプティングバックエンド（Mono と IL2CPP）の選択、マネージドストリッピングによるビルドサイズの縮小、BuildPipeline.BuildPlayer を使った再現可能なビルドのスクリプト化、CI／ヘッドレスビルドの構築に使用します。
• プロジェクトに ProjectSettings/EditorBuildSettings.asset または CI ビルドスクリプトがある場合に使用します。

使用しない場面： CI サービス設定のエンドツーエンドでの作成は DevOps の領域です。このスキルで扱うのは Unity 側のビルド API と設定です。コンソール／プラットフォームの認証に関する詳細は、プラットフォームの NDA の対象です。ストアへの提出には steam-publish／itch-publish を使用します。

基本的なワークフロー

1. ビルドするシーンを列挙します（File → Build Profiles/Settings → Scene List、または EditorBuildSettings.scenes）。リストに含まれ、有効になっているシーンのみがビルドに含まれます。シーン 0 が開始シーンです。
2. プラットフォームターゲットを選択し、 必要に応じてアクティブなビルドターゲットを切り替えます（BuildTarget／EditorUserBuildSettings）。
3. スクリプティングバックエンドを選択します（Player Settings）：Mono（反復が速く、デスクトップ向け）と IL2CPP（AOT C++。多くのプラットフォームで必須で、パフォーマンスに優れますが、リバースエンジニアリングは困難です）。IL2CPP にはプラットフォームの C++ ツールチェーンをインストールする必要があります。（補足：Unity では Mono を後継する最新の .NET ランタイムとして CoreCLR バックエンドを開発中ですが、これは 実験的 で、デスクトップ専用かつ本番利用可能な状態ではありません（Unity 6.7 時点）。そのため、6.3 LTS での選択肢は Mono と IL2CPP のままです。）
4. サイズ／パフォーマンスを調整します： Managed Stripping Level（Disabled → Minimal → Low → Medium → High）を設定し、リフレクション経由でのみ使用されるコードを link.xml で保護します。プラットフォームごとに Quality Settings を設定します。
5. BuildPipeline.BuildPlayer(BuildPlayerOptions) でビルドをスクリプト化し、 返された BuildReport を 確認します。Succeeded 以外の結果はパイプラインを失敗させる必要があります。
6. CI では -batchmode -quit -executeMethod を使ってヘッドレスで実行し、 終了コードを確認します。
7. ビルド結果が例外なく返っただけでなく、 実際に出力されたプレイヤーを起動して動作を確認します。

パターン

1. 結果を確認するスクリプト化されたビルド

using UnityEditor;
using UnityEditor.Build.Reporting;
using UnityEngine;

public static class BuildScript
{
    [MenuItem("Build/Windows x64")]
    public static void BuildWindows()
    {
        var options = new BuildPlayerOptions
        {
            scenes = new[] { "Assets/Scenes/Main.unity", "Assets/Scenes/Level1.unity" },
            locationPathName = "Builds/Windows/Game.exe",
            target = BuildTarget.StandaloneWindows64,
            options = BuildOptions.None,            // add BuildOptions.Development for a dev build
        };

        BuildReport report = BuildPipeline.BuildPlayer(options);
        BuildSummary summary = report.summary;

        if (summary.result != BuildResult.Succeeded)
            throw new System.Exception($"Build failed: {summary.totalErrors} errors");
        Debug.Log($"Build OK: {summary.totalSize} bytes in {summary.totalTime}");
    }
}

2. ヘッドレス／CI の呼び出し

# Exit code is 0 on success; -quit ensures the editor closes; -nographics for build servers.
Unity -batchmode -quit -nographics \
  -projectPath "/path/to/Project" \
  -executeMethod BuildScript.BuildWindows \
  -logFile -

3. link.xml でストリッピング対象のコードを保護する

<linker>
  <assembly fullname="MyGameRuntime" preserve="all"/>
</linker>

よくある問題

• エディターではシーンを読み込めるのに、ビルドに含まれていない — Build Settings のシーンリストに含まれていない（または無効になっている）ためです。SceneManager.LoadScene から参照できるのは、リストに含まれるシーンのみです。
• 新しいマシンで IL2CPP ビルドが失敗する — プラットフォームの C++ ツールチェーン（例：Windows のビルドツール、Android NDK）がインストールされていません。Mono にはこの要件はありません。
• MissingMethodException／TypeLoadException がビルドでのみ発生する — マネージドストリッピングによって、リフレクション経由でのみ使用されるコードが削除されています。ストリッピングレベルを下げるか、link.xml に preserve エントリーを追加します。
• 「BuildPlayer が返った」ことを成功とみなす — 必ず BuildReport.summary.result を確認してください。エラーがあっても返ることがあります。
• Addressables のコンテンツが古い、または見つからない — Addressables（com.unity.addressables）では、別途コンテンツビルド（Build → Addressables）が必要です。また、正しいロードパスを参照するプロファイルを設定します。プレイヤーのビルドだけでは Addressables は再ビルドされません。
• Development ビルドをリリースする — BuildOptions.Development はプロファイラー／デバッグ機能を有効にし、処理速度を低下させます。リリースには BuildOptions.None を使用します。

参考資料

• ターゲット切り替え、バージョンの設定、引数の解析、終了コードを含むマルチプラットフォーム CI ビルドスクリプトと、Addressables のコンテンツビルド呼び出しについては、references/ci-build-script.md を参照してください。
• 主なドキュメント：ScriptReference/BuildPipeline.BuildPlayer、Unity Manual のビルド関連セクション（プレイヤー設定、マネージドコードストリッピング）。将来導入予定の CoreCLR バックエンドについては、実験的機能に関する説明を参照してください。 https://docs.unity3d.com/6000.7/Documentation/Manual/scripting-backends-coreclr.html

関連スキル

• steam-publish / itch-publish — ビルドしたばかりのプレイヤーを配布します。
• unity-csharp-scripting — ビルドスクリプトで使用されるエディタースクリプトの規約です。