Asset Bundle Compression

Unity supports three compression options for Asset Bundles: LZMA, LZ4, and Uncompressed.

LZMA Format

By default, when Asset Bundles are built, they are stored in a compressed format. The standard compressed format is a single LZMA stream of serialized data files, and needs to be decompressed in its entirety before use.

LZMA-Compressed bundles give the smallest possible download size, but has relatively slow decompression resulting in higher apparent load times.

LZ4 Format

Unity also supports LZ4 compression, which results in larger compressed file sizes, but does not require the entire bundle to be decompressed before use. LZ4 is a “chunk-based” algorithm, and therefore when objects are loaded from an LZ4-compressed bundle, only the corresponding chunks for that object are decompressed. This occurs on-the-fly, meaning there are no wait times for the entire bundle to be decompressed before use. The LZ4 Format was introduced in Unity 5.3 and was unavailable in prior versions.

Uncompressed Format

The third compression option is no compression at all. Uncompressed bundles are large, but are the fastest to access once downloaded.

Caching of Compressed Bundles

The WWW.LoadFromCacheOrDownload function downloads and caches asset bundles to disk and thus greatly speeds up loading afterwards. From Unity 5.3 onwards, cached data can also be compressed with the LZ4 algorithm. This saves 40%–60% of space compared to uncompressed bundles. Recompression happens during download and thus is almost unnoticeable by the end users. As data arrives from the socket, Unity will decompress it and recompress it in LZ4 format. This recompression occurs during the download streaming, which means the cache compression begins as soon as enough of the data is downloaded, and continues incrementally until the download is complete. After that, data is read from the cached bundle by decompressing chunks on-the-fly when needed.

Cache compression is enabled by default and is controlled by the Caching.compressionEnabled property. It affects bundles cached to disk and stored in memory.

AssetBundle load API overview

This table provides a comparison of memory and performance overheads when using different compression types and different loading methods.

* When downloading a bundle using WWW, WebRequest there is also an 8x64KB accumulator buffer which stores data from a socket.

Thus, use the following guidelines when using low-level loading API in your games:

1. Deploying asset bundles with your game as StreamingAssets - use BuildAssetBundleOptions.ChunkBasedCompression when building bundles and AssetBundle.LoadFromFileAsync to load it. This gives you data compression and the fastest possible loading performance with a memory overhead equal to read buffers.
2. Downloading asset bundles as DLCs - use default build options (LZMA compression) and LoadFromCacheOrDownload/WebRequest to download and cache it. Here you’ll have the best possible compression ratio and AssetBundle.LoadFromFile loading performance for further loads.
3. Encrypted bundles - choose BuildAssetBundleOptions.ChunkBasedCompression and use LoadFromMemoryAsync for loading (this is pretty much the only scenario where LoadFromMemory[Async] should be used).
4. Custom compression - use BuildAssetBundleOptions.UncompressedAssetBundle to build and AssetBundle.LoadFromFileAsync to load a bundle after it was decompressed by your custom compression algorithm.

You should generally always choose asynchronous functions - they don’t stall the main thread and they allow loading operations to be queued more efficiently. And absolutely avoid calling synchronous and asynchronous functions at the same time - this might introduce hiccups on the main thread.

Compatibility

The Asset Bundle container format was changed in order to support new compression type, and to provide basis for further improvements. Unity 5 still supports bundles created in Unity 4, however bundles created in earlier version (2.x, 3.x) are not supported.