An AssetBundle is an archive file that contains platform-specific non-code Assets (such as Models, Textures, Prefabs, Audio clips, and even entire Scenes) that Unity can load at run time. AssetBundles can express dependencies between each other; for example, a Material in one AssetBundle can reference a Texture in another AssetBundle. For efficient delivery over networks, you can compress AssetBundles with a choice of built-in algorithms depending on use case requirements (LZMA and LZ4).
AssetBundles can be useful for downloadable content (DLC), reducing initial install size, loading assets optimized for the end-user’s platform, and reduce runtime memory pressure.
An AssetBundle built for any of the standalone platforms can only be loaded on that platform. For example, a bundle built on iOS is not compatible with Android.
One reason for this is that ShadersA program that runs on the GPU. More info
See in Glossary, Textures and other types of data are built into platform-specific formats based on the BuildTarget.
When you build or rebuild AssetBundles, you typically build all of the project’s AssetBundles together using a single API call. It is usually best not to build or rebuild them individually, because when built together, the Unity Editor makes decisions about how to reference or embed content in each AssetBundle which can depend on what is included in other AssetBundles. The exception to this is if you’re an advanced user who understands the references and dependencies among the AssetBundles in your project, in which case you can sometimes build just a subset of your project’s AssetBundles.
Because the APIs that you use to load AssetBundles are designed to be simple, they abstract away the details of how data is represented inside AssetBundles. However it can be useful to understand the structure, especially if you use tools to extract or examine the contents of an AssetBundle.
The AssetBundle is a container file format, similar to a zip file. It has a binary-format header and embeds additional files inside it. These additional files consist of two types:
The AssetBundle file always includes a serialized AssetBundle object. This object acts like a directory for the contents of the AssetBundle. This is the object you interact with via code to load Assets from a specific AssetBundle archive, and it is also used internally when loading Assets from AssetBundles with the Addressables API.
When an AssetBundle is built, the objects that are included are serialized using the definition from the version of the Unity Editor you used to build it, as well as the C# types defined in the Project that is built. The information for each type is recorded inside the AssetBundle in a structure called the Type Tree. This type information contributes somewhat to the size of the AssetBundle, but it is critical to enabling loading those objects when the version of the player does not match the Editor version at the time of the build. For many Unity features the types are quite stable and only change in minor ways between versions so the backward compatibility support works well. However in cases where Unity features change substantially it may not be possible to load the old data in a way that achieves the expected results in the newer version. In that case, you must rebuild the AssetBundle using the new version of Unity.
Unity does not support forward-compatibility, so loading an AssetBundle built with a new version of Unity into a Player that was built with an older version of Unity is likely to have trouble loading the content.
Note: By default the version of the Unity Editor that was used to build the file is included inside the AssetBundle header. This information can be useful when investigating backward compatibility issues. However, it can also result in AssetBundles being rebuilt unnecessarily, and cause unnecessary client downloads if a project is rebuilt after doing a minor upgrade of the Editor. To avoid this, you can exclude the Editor version, see BuildAssetBundleOptions.AssetBundleStripUnityVersion.
AssetBundles do not contain assemblies and are not used to distribute new C# classes or changes to existing classes. Rather, it is the Player Build that contains the compiled assemblies. This means to release code changes, you must rebuild and redistribute the main build of your game or app.
However, you can use AssetBundles to distribute new objects that are instances of the classes compiled into your Player build, such as new items for a game.
For example, AssetBundles can include ScriptableObject Assets. When you load that Asset from the AssetBundle Unity finds the matching class definition, based on the assembly name, namespace and class name. It creates an object that is an instance of that class and sets the fields of the object using the serialized values.
If the object was serialized based on an older definition of the class then Unity will use its backward compatibility support to match up whatever fields it can, based on the field names and other info recorded in the Type Tree.
Scripts often use Conditional Compilation to specify platform-specific code. For example, using scripting symbols like UNITY_STANDALONE, UNITY_IOS and UNITY_ANDROID. If fields on a class or struct are not compiled on some targets then the serialization of objects inside the AssetBundle will not include those fields (and they will not be included in the Type Tree). This is another reason that AssetBundles must be rebuilt for each platform that you target.
There are two supported APIs to build AssetBundles for Unity:
BuildPipeline.BuildAssetBundles
, AssetBundle
and UnityWebRequestAssetBundle
. This is the functionality described in this section of the Manual. However this method is quite low-level, for example it requires that you understand Asset dependencies, determine bundle assignments yourself and write your own build script.Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.