/unity-build-size

name: unity-build-size
description: >
  Finds and shrinks what makes a Unity 6.3 LTS build too big: Build Report reading, uncompressed
  textures, glTFast models, PCM audio and per-platform levers. Use when an APK, AAB, WebGL build
  or Steam depot is over a size limit or the download is too big. Not for frame rate
  (`performance-optimization`), build scripts or stripping (`unity-build-pipeline`) or store
  uploads (`steam-publish`).

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](references/platform-web.md) | | Android (APK, AAB, Google Play) | the download Play computes from the AAB | [references/platform-android.md](references/platform-android.md) | | iOS (App Store, TestFlight) | the thinned download per device | [references/platform-ios.md](references/platform-ios.md) | | Windows, macOS, Linux (zip, jam, Steam) | the archive, the installed folder, or Steam patch size | [references/platform-desktop-steam.md](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; `NOTE`s 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](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