unreal-packaging

Unreal のパッケージ化とクック

UE5 プロジェクトを実行・配布可能なビルドにします。適切なビルド構成を選び、コンテンツをクックし、起動マップを設定して、エディターまたはコマンドラインからパッケージ化します。対象は UE 5.8 です。

使用する場面

• テスト用またはリリース用のビルドを作成する場合、Development と Shipping のどちらかを選ぶ場合、コンテンツをクックする場合、Packaging / Maps & Modes の設定を行う場合、または CI 用に RunUAT BuildCookRun でビルドを自動化する場合に使用します。
• プロジェクトに *.uproject と Config/Default*.ini があり、エディター内での実行ではなく、パッケージ化されたプレイヤーを作成する場合に使用します。

使用しない場面： ストアへの提出・リリース手順には steam-publish / itch-publish を使用します。エディターでのゲームプレイや反復作業はパッケージ化ではありません。

基本的なワークフロー

1. 起動マップを設定します。 Project Settings → Maps & Modes → Game Default Map は、パッケージ化したビルドが最初に読み込むマップです。ここが間違っている、または空になっていることが、「パッケージ化したゲームの画面が真っ暗になる」最も一般的な原因です。
2. ビルド構成を選びます。 Development（デフォルト。最適化されていますが、テスト用のログ／統計情報／コンソールは維持されます）と Shipping（すべての最適化を適用し、デバッグツールを削除します。リリース用）から選びます。DebugGame / Debug はエンジン／ゲームコードのデバッグ用であり、配布には使用しません。Blueprint のみのプロジェクトでは DebugGame は使用できません。
3. クックとパッケージ化の違いを理解します。 クックでは、アセットをターゲットプラットフォームの形式に変換し、.pak ファイルにまとめます。パッケージ化では、コンパイル済み実行ファイルとクック済みコンテンツを、単体で実行・配布できる一式のファイルにまとめます。パッケージ化の一環としてクックが実行されます。
4. エディターからパッケージ化します。 Platforms メニュー → プラットフォーム（例：Windows）を選択 → Binary Configuration を設定 → Package Project → 出力フォルダーを選択します。
5. または、コマンドラインからビルドします。 Unreal Automation Tool（RunUAT BuildCookRun）を使うと、繰り返し実行できる CI 向けのビルドを作成できます。
6. Packaging の設定を調整します（Project Settings → Packaging）。クックするマップ／ディレクトリ、完全な再ビルド、圧縮、すべてのマップをビルドするかどうかを設定します。
7. UnrealEditor-Cmd が使用できる場合は、パッケージ化の前にアセットを検証します。 UnrealEditor-Cmd <Project>.uproject -run=DataValidation（Windows では UnrealEditor-Cmd.exe）を実行し、報告された検証エラーをすべて修正してからクックします。
8. 検証します。 クックが成功しただけで済ませず、パッケージ化したビルドを実行します。実行ファイルを起動し、正しいマップが読み込まれて動作することを確認します。

パターン

1. エディターからのパッケージ化（メニュー操作）

Platforms (toolbar)
  -> Windows
     -> Binary Configuration -> Development | Shipping
     -> Content Management -> Package Project
  -> choose/confirm the staging output folder

2. UAT を使ったコマンドラインビルド（CI 向け）

# Cook + build + stage + pak + archive a Shipping Windows build.
RunUAT BuildCookRun \
  -project="C:/Path/MyGame.uproject" \
  -noP4 -platform=Win64 -clientconfig=Shipping \
  -cook -allmaps -build -stage -pak -archive \
  -archivedirectory="C:/Builds/MyGame"

RunUAT は Engine/Build/BatchFiles/ にあります（Windows では RunUAT.bat、macOS/Linux では RunUAT.sh）。マップの一部だけをクックするには、-allmaps を外し、-map=Map1+Map2 を渡します。

3. クックのみ（パッケージ化なし）。例：コンテンツの更新

RunUAT BuildCookRun -project="C:/Path/MyGame.uproject" -noP4 \
  -platform=Win64 -clientconfig=Development -cook -skipstage

注意点

• パッケージ化したビルドで、レベルが真っ暗、または空の状態で読み込まれる — Game Default Map が設定されていないか、そのマップがクックされていません。Maps & Modes で設定し、クック対象に含まれていることを確認します。
• Development ビルドを出荷している — Development ではログ／コンソール／統計情報が維持され、動作も遅くなります。出荷には Shipping を使用します。反対に、Shipping では UE_LOG / コンソールが削除されるため、Shipping のみで発生する問題をデバッグするには Development または Test が必要です。
• 参照先のマップ／アセットが実行時に見つからない — クックされていません。Packaging 設定のクック対象マップ／ディレクトリに追加するか、すべてのマップをクックします。
• プラットフォーム向けのビルドに失敗する — プラットフォームの SDK／ツールチェーンがインストールされていません（Windows のビルドツール、Android SDK/NDK、コンソールの SDK など）。プラットフォームの前提条件をインストールします。
• Blueprint Nativization を期待している — UE5 では削除されています。パフォーマンス向上のために当てにしないでください。代わりにプロファイリングを行い、処理負荷の高いロジックを C++（unreal-cpp-gameplay）に移します。
• 初回のクックが非常に遅い — 初回はシェーダーとすべてのアセットを最初からクックします。以降のクックは差分実行されます。初回のクックが遅くても、ハングしたと勘違いしないでください。

参考資料

• 主なドキュメント：「プロジェクトのパッケージ化」 （https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project）と Build Configurations／BuildCookRun のリファレンスです。

関連スキル

• steam-publish／itch-publish — パッケージ化したビルドをストアフロントで配布します。
• unreal-cpp-gameplay — BP のネイティブ化がなくなったため、ホットなロジックを C++ に移行します。