unity-build-size

Unity build size

Bring a Unity player build under a size limit: measure the thing that is limited, fix the few assets and settings that dominate it, rebuild, and prove the result runs. Targets Unity 6.3 LTS (6000.3); the scripts were exercised against glTFast 6.20.0 projects. Keep an existing project's version from ProjectSettings/ProjectVersion.txt.

Script paths below are relative to this skill's folder. Both scripts are read-only, standard-library Python 3.10+.

1. Pin what is limited

A build has several sizes, and fixing the wrong one wastes the user's time. Find out which file is limited and by how much, then read only the matching reference:

Target	What is usually limited	Read
Browser (itch.io, portals, own site)	each file in Build/ (itch.io: 200 MB per file) and the compressed download	references/platform-web.md
Android (APK, AAB, Google Play)	the download Play computes from the AAB	references/platform-android.md
iOS (App Store, TestFlight)	the thinned download per device	references/platform-ios.md
Windows, macOS, Linux (zip, jam, Steam)	the archive, the installed folder, or Steam patch size	references/platform-desktop-steam.md

If the user names a number but not the file it applies to, ask that one question. With no hard limit, pick what the user pays for (download, installed size, patch size) and say which one you measured. Write down the current size of that file before you change anything: it is the baseline you compare against.

2. Measure what ships

Build once (or use the last build of this Editor session) and summarize the Build Report:

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

Log paths: Windows %LOCALAPPDATA%\Unity\Editor\Editor.log, Linux ~/.config/unity3d/Editor.log, batch mode the -logFile path. Categories say what kind of data dominates; the asset list says which files. The sizes are uncompressed and in MiB, so they are not the download size: always compare against the file you measured in step 1.

When the Unity CLI is installed (unity --version), it can make the build and keep its log: unity build . --profile "<Build Profile name>" --output-path <output path> --log-file build.log, then run build_report.py build.log. Without it, use the Editor's Build Profiles window or the project's build script.

3. Find the causes in the project

# --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

Without the right --platform, that platform's texture overrides are not checked. Each WARNING names a file, the setting, an estimated build cost and a fix: line; NOTEs are context. The checker cannot know which assets a build references, so cross it with the Build Report: an asset no shipped scene uses costs nothing.

4. Fix the biggest category first

Smallest change first, one category at a time, so the next measurement shows what each fix bought.

• glTF/GLB with embedded images (gltf-embedded-texture): glTFast ships them uncompressed, and they have no Texture Importer to fix. Run the checker's fix: command, or move the images out; read references/gltf-textures.md before the first one.
• Textures (uncompressed-texture, texture-max-size): Compression Normal Quality and a lower Max Size, per platform if needed (Pattern below). An override with an explicit Format ignores Compression, so set that Format to Automatic or a compressed one. For download size on DXT/ETC formats, Use Crunch Compression shrinks the files further at some quality cost.
• Audio (pcm-audio): Vorbis for music and ambience, ADPCM for short effects, Force To Mono where stereo adds nothing.
• Resources and StreamingAssets: everything in a Resources folder ships whether or not it is loaded; Assets/StreamingAssets is copied byte for byte. Move out what nothing uses.
• Meshes, animation, lightmaps: Model Importer Mesh Compression for FBX/OBJ (glTF: reduce the source, gltf-heavy-geometry), animation compression on clips, and in the Lighting window a lower Max Lightmap Size and Lightmap Compression when lightmaps top the Textures category.
• Scenes: remove test scenes from the Scene List of the profile you build.
• Code and engine size: when native libraries, .wasm or managed DLLs top the list, apply the platform reference's settings; stripping levels and link.xml belong to unity-build-pipeline.
• Packaging: the platform reference covers player compression, store packaging and the debug folders that must not ship.

5. Rebuild, compare, prove

1. Build into an empty output folder (a stale folder or a leftover debug folder skews the size).
2. Rerun build_report.py and the checker; the categories you touched must have dropped. Measure the limited file from step 1 again and report before and after as numbers.
3. Launch the build the way players get it, reach gameplay, and look at the assets you shrank. The platform reference says how (a Web build needs a server). When you cannot run the target, build for your own platform and launch that, and say which one you tested.
4. For CI, build_report.py build.log --budget-mb 400 exits 1 over budget, and also when the log has no complete size to compare. It checks the uncompressed total, so check the shipped file separately when the limit is on that file.

Gotchas

• Texture settings look fine but the build is still huge → the textures sit inside .glb/.gltf models. Run the checker; references/gltf-textures.md has the fixes.
• Textures in the Build Report are far larger than their .meta settings allow → the Build Profiles window's Asset Import Overrides set Texture Compression to Force Uncompressed (or Force No Crunch). They are a local iteration shortcut the checker cannot see; clear them before a release build (Build Profiles reference).
• Running a .gltf fix for several models in one folder → gltf-transform names the images it writes after the texture slot (baseColor_1.png) and overwrites existing ones, so every model ends up with the last one's textures. The checker's fix: line says when to move a model into its own folder first; follow it.
• Normal maps look wrong after moving glTF images out → they came in with sRGB on. Turn sRGB (Color Texture) off for every map except base color, emissive and the specular-glossiness pair.
• LZ4HC made the zip smaller and the Steam patch huge → Steam compresses downloads itself, and Unity's compressed player data spreads small changes across many chunks. On Steam and Android, leave Compression Method on Default; see the platform reference.
• The Web build is several times the expected size → it is a development build, which Unity never compresses.
• Addressables content is missing from the Build Report's asset list → local groups are built as bundles and copied into the player's StreamingAssets/aa; the player Build Report does not list the assets inside them. Use the Addressables Build Report window. Current Addressables versions build into Library/, so a leftover Assets/StreamingAssets/aa is stale and ships anyway; the Addressables changelog recommends deleting it (changelog).
• An uncompressed-texture warning on a sprite you packed → a sprite in a Sprite Atlas ships with the atlas's settings; check the atlas instead.
• Textures look soft after lowering Max Size → that texture fills more screen pixels than the limit; give it a higher Max Size and lower something less visible.
• The checker reports a Git LFS pointer model → the clone has pointer files; run git lfs pull before measuring anything.

Pattern: texture limits in bulk (Editor script)

Commit first: this changes import settings, and the diff is the review. Place under any Editor folder. It skips small textures, as the checker does, so pixel art and UI icons keep their settings.

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();
        }
    }
}

This changes the default settings, which apply to every platform without an override. For one platform, use importer.GetPlatformTextureSettings("Android"), set overridden = true, maxTextureSize and textureCompression, then importer.SetPlatformTextureSettings(settings).

Optional helpers

This skill works with files and the Editor log alone. When they are installed, these save steps:

• Unity CLI (unity, experimental): builds with a kept log (step 2) and unity build run to launch the last build, including a Web build on a local server (Unity CLI docs).
• Unity's official agent skills (Unity-Technologies/skills): optimize-web and optimize-audio apply Player and audio settings through a live Editor, project-auditor-fixes runs Project Auditor. Use them for the Editor-side changes, and keep this skill's measure-and-compare loop around them.

Resources

• scripts/check_unity_build_size.py --help: the project check. --json for tools, --strict to fail on warnings.
• scripts/build_report.py --help: Build Report summary; --top, --json, --budget-mb.
• references/gltf-textures.md: glTFast embedded images, size table, the two fixes, heavy geometry.
• Unity manual: Reducing the file size of a build, Reserved folder names, Include additional files in a build.

Related skills

• unity-build-pipeline: build scripts, CI, scripting backend, managed stripping, Addressables setup.
• performance-optimization: runtime memory and frame time.
• create-game-assets: making textures at the right size before import.
• steam-publish / itch-publish: uploading the packaged build.