unity-build-size

Unity ビルドサイズ

Unity プレイヤーのビルドをサイズ制限内に収めます。制限対象を測定し、サイズを大きく左右する少数のアセットと設定を調整して、再ビルドし、実行できることを確認します。対象は Unity 6.3 LTS (6000.3) です。スクリプトは glTFast 6.20.0 のプロジェクトで動作確認済みです。既存のプロジェクトでは、ProjectSettings/ProjectVersion.txt に記載されたバージョンを使用してください。

以下のスクリプトのパスは、このスキルのフォルダーからの相対パスです。どちらのスクリプトも読み取り専用で、Python 3.10 以降の標準ライブラリのみを使用します。

1. 制限対象を特定する

ビルドには複数のサイズがあり、誤ったサイズを調整するとユーザーの時間を無駄にします。どのファイルがどの程度制限されているのかを確認し、該当するリファレンスのみを読みます。

対象	一般的な制限対象	参照先
ブラウザー（itch.io、ポータル、自社サイト）	Build/ 内の各ファイル（itch.io：ファイルごとに 200 MB）と圧縮ダウンロードサイズ	references/platform-web.md
Android（APK、AAB、Google Play）	Google Play が AAB から算出するダウンロードサイズ	references/platform-android.md
iOS（App Store、TestFlight）	デバイスごとのシンボルを除去したダウンロードサイズ	references/platform-ios.md
Windows、macOS、Linux（zip、jam、Steam）	アーカイブ、インストール先のフォルダー、または Steam のパッチサイズ	references/platform-desktop-steam.md

ユーザーが数値を指定しているものの、対象ファイルが不明な場合は、その点だけを質問します。厳密な制限がない場合は、ユーザーが費用を負担するサイズ（ダウンロードサイズ、インストール後のサイズ、パッチサイズ）を選び、何を測定したかを明記します。変更を加える前に、そのファイルの現在のサイズを記録します。これが比較の基準になります。

2. 配布物を測定する

ビルドを 1 回実行するか、この Editor セッションで最後に作成したビルドを使い、Build Report を要約します。

python scripts/build_report.py ~/Library/Logs/Unity/Editor.log --top 20

ログのパス：Windows は %LOCALAPPDATA%\Unity\Editor\Editor.log、Linux は ~/.config/unity3d/Editor.log、バッチモードでは -logFile のパスです。カテゴリから、どの種類のデータがサイズを占めているかが分かります。アセット一覧から、どのファイルかが分かります。サイズは非圧縮の MiB 単位なので、ダウンロードサイズではありません。必ず手順 1 で測定したファイルと比較してください。

Unity CLI がインストールされている場合（unity --version）、ビルドを実行してログを保存できます。 unity build . --profile "<Build Profile name>" --output-path <output path> --log-file build.log を実行してから、 build_report.py build.log を実行します。Unity CLI がない場合は、Editor の Build Profiles ウィンドウまたはプロジェクトのビルドスクリプトを使用します。

3. プロジェクト内で原因を特定する

# --platform: the one you ship, as Standalone, Android, iPhone or WebGL
python scripts/check_unity_build_size.py path/to/Project --platform WebGL --max-texture-size 2048

適切な --platform を指定しないと、そのプラットフォームのテクスチャオーバーライドは検査されません。各 WARNING にはファイル名、設定、ビルドサイズの推定値、および fix: の行が表示されます。NOTE は補足情報です。このチェッカーでは、ビルドがどのアセットを参照するかは分からないため、Build Report と照合してください。ビルドに含まれるシーンで使用されないアセットは、サイズに影響しません。

4. まず最も大きいカテゴリを修正する

変更は小さなものから、一度に1つのカテゴリだけ行います。そうすれば、次の測定で各修正による効果を確認できます。

• 埋め込み画像を含む glTF/GLB（gltf-embedded-texture）：glTFast はこれらを圧縮せずに出力し、修正に使える Texture Importer もありません。チェッカーの fix: コマンドを実行するか、画像を別の場所に移動してください。最初に対応する前に、references/gltf-textures.md をお読みください。
• テクスチャ（uncompressed-texture、texture-max-size）：必要に応じてプラットフォームごとに、Compression を Normal Quality にし、Max Size を小さくします（下記のパターンを参照）。Format を明示的に指定したオーバーライドは Compression を無視するため、その Format を Automatic または圧縮形式に設定してください。DXT/ETC 形式でダウンロードサイズを抑えるには、品質を多少犠牲にして Use Crunch Compression を有効にすると、ファイルをさらに小さくできます。
• オーディオ（pcm-audio）：音楽や環境音には Vorbis、短い効果音には ADPCM を使用し、ステレオにする利点がない場合は Force To Mono を有効にします。
• リソースと StreamingAssets：Resources フォルダー内のすべてのファイルは、読み込まれるかどうかにかかわらずビルドに含まれます。Assets/StreamingAssets はバイト単位でそのままコピーされます。使われていないものは移動してください。
• メッシュ、アニメーション、ライトマップ：FBX/OBJ には Model Importer の Mesh Compression を使用します（glTF の場合はソースを削減し、gltf-heavy-geometry を確認してください）。クリップではアニメーション圧縮を使用します。ライトマップがテクスチャカテゴリの大部分を占める場合は、Lighting ウィンドウで Max Lightmap Size を小さくし、Lightmap Compression を設定します。
• シーン：ビルドに使用するプロファイルの Scene List からテスト用シーンを削除します。
• コードとエンジンのサイズ：ネイティブライブラリ、.wasm、またはマネージ DLL がリストの大部分を占める場合は、プラットフォームリファレンスの設定を適用してください。ストリッピングレベルと link.xml については、unity-build-pipeline を参照してください。
• パッケージング：プラットフォームリファレンスでは、プレーヤーの圧縮、ストア向けパッケージング、出荷時に含めてはいけないデバッグフォルダーについて説明しています。

5. 再ビルドして比較し、検証する

1. 空の出力フォルダーにビルドします（古いファイルや残ったデバッグフォルダーがあると、サイズが不正確になります）。
2. build_report.py とチェッカーを再実行し、手を加えたカテゴリのサイズが減っていることを確認します。手順1で測定した対象ファイルも再度測定し、修正前と修正後の数値を報告してください。
3. プレーヤーが実際に利用する方法でビルドを起動し、ゲームプレイまで進んで、サイズを縮小したアセットを確認します。起動方法はプラットフォームリファレンスに記載されています（Web ビルドにはサーバーが必要です）。対象環境で実行できない場合は、自分のプラットフォーム向けにビルドして起動し、どのプラットフォームでテストしたかを記載してください。
4. CI では、build_report.py build.log --budget-mb 400 は予算を超えると終了コード 1 を返し、比較可能な完全なサイズがログにない場合も終了コード 1 を返します。これは非圧縮時の合計を確認するため、上限が出荷ファイルに適用される場合は、そのファイルを別途確認してください。

注意点

• テクスチャ設定に問題がないように見えるのに、ビルドがまだ非常に大きい → テクスチャは .glb／.gltf モデル内にあります。チェッカーを実行してください。修正方法は references/gltf-textures.md に記載されています。
• Build Report のテクスチャが、.meta の設定から想定されるサイズを大幅に上回っている → Build Profiles ウィンドウの Asset Import Overrides により、Texture Compression が Force Uncompressed（または Force No Crunch）に設定されています。これはチェッカーでは検出できない、ローカルでの反復作業用の一時的な設定です。リリースビルドの前に解除してください (Build Profiles リファレンス).
• 同じフォルダーにある複数のモデルに .gltf の修正を適用する → gltf-transform は書き出す画像にテクスチャスロット名 （baseColor_1.png など）を付け、既存の画像を上書きするため、すべてのモデルに最後のモデルのテクスチャが適用されます。チェッカーの fix: の行に、最初にモデルを専用フォルダーへ移動する必要がある場合が示されます。その指示に従ってください。
• glTF の画像を外部に移動した後、法線マップの見た目がおかしい → sRGB が有効な状態で取り込まれています。ベースカラー、エミッシブ、スペキュラ・グロシネスのペア以外は、すべてのマップで sRGB (Color Texture) をオフにしてください。
• LZ4HC で zip は小さくなったのに、Steam のパッチが非常に大きい → Steam はダウンロードを独自に圧縮し、Unity の圧縮済みプレイヤーデータは、小さな変更を多くのチャンクに分散させます。Steam と Android では、Compression Method を Default のままにしてください。プラットフォームのリファレンスを参照してください。
• Web ビルドが想定サイズの数倍になっている → 開発ビルドです。Unity は開発ビルドを圧縮しません。
• Addressables のコンテンツが Build Report のアセット一覧にない → ローカルグループはバンドルとしてビルドされ、プレイヤーの StreamingAssets/aa にコピーされます。プレイヤーの Build Report には、バンドル内のアセットは一覧表示されません。Addressables Build Report ウィンドウを使用してください。現在の Addressables のバージョンでは Library/ にビルドされるため、残っている Assets/StreamingAssets/aa は古いものであり、そのまま同梱されます。Addressables の変更履歴では、これを削除することが推奨されています (変更履歴).
• アトラスにまとめたスプライトに uncompressed-texture 警告が表示される → Sprite Atlas 内のスプライトには、アトラスの設定が適用されます。アトラスを確認してください。
• Max Size を下げた後、テクスチャがぼやけて見える → そのテクスチャは上限を超える画面ピクセル数を占めています。Max Size を上げ、目立ちにくい要素の設定を下げてください。
• チェッカーが Git LFS pointer モデルを報告する → クローンにはポインターファイルがあります。何かを計測する前に git lfs pull を実行してください。

パターン：テクスチャ制限を一括設定する（Editor スクリプト）

まずコミットしてください。これはインポート設定を変更するため、差分をレビューします。任意の Editor フォルダー内に配置してください。チェッカーと同様、小さなテクスチャは対象外となるため、ピクセルアートや UI アイコンの設定は維持されます。

using UnityEditor;
using UnityEngine;

public static class TextureBudget
{
    const int MaxSize = 2048;
    const int MinEdgeToCompress = 1024;

    [MenuItem("Tools/Build Size/Compress Large Textures")]
    static void CompressLargeTextures()
    {
        AssetDatabase.StartAssetEditing();   // one reimport pass instead of one per texture
        try
        {
            foreach (string guid in AssetDatabase.FindAssets("t:Texture2D", new[] { "Assets" }))
            {
                string path = AssetDatabase.GUIDToAssetPath(guid);
                if (AssetImporter.GetAtPath(path) is not TextureImporter importer)
                    continue;   // sub-assets of models (glTFast) have no TextureImporter
                importer.GetSourceTextureWidthAndHeight(out int width, out int height);
                if (Mathf.Max(width, height) < MinEdgeToCompress)
                    continue;

                bool changed = false;
                if (importer.maxTextureSize > MaxSize) { importer.maxTextureSize = MaxSize; changed = true; }
                if (importer.textureCompression == TextureImporterCompression.Uncompressed)
                {
                    importer.textureCompression = TextureImporterCompression.Compressed;
                    changed = true;
                }
                if (changed)
                {
                    importer.SaveAndReimport();
                    Debug.Log($"Compressed {path}");
                }
            }
        }
        finally
        {
            AssetDatabase.StopAssetEditing();
        }
    }
}

これはデフォルト設定を変更します。この設定は、オーバーライドがないすべてのプラットフォームに適用されます。特定のプラットフォームだけを対象にする場合は、importer.GetPlatformTextureSettings("Android") を使用し、overridden = true、 maxTextureSize、textureCompression を設定してから、importer.SetPlatformTextureSettings(settings) を呼び出してください。

オプションのヘルパー

このスキルはファイルと Editor のログだけで動作します。以下がインストールされている場合、手順を短縮できます。

• Unity CLI（unity、試験運用版）：ログを保持してビルドし（手順 2）、unity build run で最後のビルドを起動します。Web ビルドもローカルサーバー上で起動できます (Unity CLI ドキュメント).
• Unity 公式のエージェントスキル（Unity-Technologies/skills）： optimize-web と optimize-audio は、起動中の Editor を通じて Player とオーディオの設定を適用し、 project-auditor-fixes は Project Auditor を実行します。Editor 側の変更にはこれらを使用し、その前後ではこのスキルの計測・比較のサイクルを維持してください。

リソース

• scripts/check_unity_build_size.py --help：プロジェクトのチェックです。ツール向けの --json と、警告がある場合に失敗する --strict を指定できます。
• scripts/build_report.py --help：Build Report の概要です。--top、--json、--budget-mb を指定できます。
• references/gltf-textures.md：glTFast の埋め込み画像、サイズ表、2 つの修正方法、容量の大きいジオメトリについて説明します。
• Unity マニュアル：ビルドのファイルサイズを削減する、予約済みフォルダー名、ビルドに追加ファイルを含める。

関連スキル

• unity-build-pipeline：ビルドスクリプト、CI、スクリプティングバックエンド、マネージドストリッピング、Addressables のセットアップ。
• performance-optimization：ランタイムメモリとフレーム時間。
• create-game-assets：インポート前に適切なサイズのテクスチャを作成します。
• steam-publish / itch-publish：パッケージ化したビルドをアップロードします。