Introduction to content directories
Understand what content directories are, how they compare to AssetBundles, and when to use them.
阅读时间6 分钟最后更新于 11 天前
A content directory is a way of creating separate content builds to distribute along with a Player build. They're a replacement for the AssetBundle system, with additional benefits that include implicit de-duplication, reduced load times, and a lower memory overhead. Content directories are compatible with the Addressables package, which provides a user interface for organizing the content in your project.
A content build supplements the content that's included in the Player build. This allows you to create smaller, faster builds, and reduces asset duplication by minimizing the amount of content in a build.
重要
Content directory builds only support local content builds, and don't support remote content distribution.
Structure of the build process
When you use content directories in your project, you structure the build process in the following way:
-
Player build: Only contains the core code and content required to start your application. The recommended approach is to create a starting scene that performs an initial load of content from a content directory. You build a Player from the Editor or through scripts.
-
Content build: Build one or more content directories to distribute the content of your application along with the Player. A content folder contains the following:
- The built content of your project. The content of your project is the assets needed to create the gameplay of your application.
- A manifest file () which contains a record of the information needed to load the content.
BuildManifest
Content directory builds are incremental. Unity rebuilds only the content that changed since the previous build, which makes an incremental build much faster than a clean build. Iterating on content in a content directory is also faster than iterating on the same content built into the Player, because you rebuild only the content directory instead of the whole Player.
Creating content directories
Content directories use ScriptableObject instances called root assets to define the content included in a build. You can then use the API to load and unload individual assets synchronously, or asynchronously with and keywords. For more information, refer to Create content directories.
Loadable<T>asyncawaitThe content directory system automatically removes any duplicated content in a build and handles dependencies because they're tracked per asset. However, because each build is self-contained, if two content directory builds both reference the same asset, then each build includes its own copy of that asset. For more information on avoiding asset duplication, refer to Duplication of assets in content directories.
Comparison to AssetBundles
Content directories are a replacement for the AssetBundle system.
提示
If you use the Addressables package, you can use the content directory system, and convert existing projects to use the content directory system. For more information on the different options, refer to the Addressables documentation on Choose a content build system.
The following table describes the differences between AssetBundles and content directories:
Feature | Content directories | AssetBundles |
|---|---|---|
| Organization | Uses root assets to organize the content in your application. | Must assign assets to explicit AssetBundles. |
| Layout | Granular file layout with hash-based names, optionally in a Unity archive. | Individual Unity archive files for each defined AssetBundle. Referenced content can be duplicated in multiple AssetBundles. |
| On demand references | Uses | Uses string paths to load references. |
| Dependencies | Dependencies are tracked per asset. Unity automatically removes duplicated content in a build, and handles dependencies automatically. | Dependencies are tracked per AssetBundle. Loading an asset requires loading its AssetBundle, and recursively loading all the dependent AssetBundles, even if the loaded asset itself doesn't reference them. |
| Remote content delivery | Local content only. | Supports local and remote content. |
| Build manifests | Build information is stored in | Stored in |
| Code stripping | Use | Use |
| Build callbacks | Invokes a subset of the Player build callbacks, including | Invokes the same subset of callbacks, except for AssetBundles built with Addressables or the Scriptable Build Pipeline package, which invoke fewer. For more information, refer to Use build callbacks. |
Replacing AssetBundle code
The method forced callers to define the name of each AssetBundle, and to explicitly assign assets and scenes to them via script or the Inspector. Therefore, some AssetBundles might only exist to avoid asset duplication, such as to share assets that are referenced from more than one AssetBundle. This isn't a recommended pattern in content directories, and it's best practice to create one root asset to hold all assets in your project.
BuildAssetBundleIf your existing project relies on loading many assets by string, then consider using a that acts as an asset list instead of defining many root assets. A single asset list can expose all the assets that you need to load by string, or you can split content into multiple asset lists.
ScriptableObjectFor more information on creating content directories, refer to Create content directories.
Using AssetBundles and content directories in the same project
It's best practice to choose one content build system, and avoid using a mixture of content directories and AssetBundles in your project. If you use a mixture of the two systems, then any shared dependencies between AssetBundles and content directories are built twice, which increases build size and might lead to asset duplication.
However, you can use both build systems in existing projects that have both local and remote content. Because the content directory system doesn't currently have a remote content distribution mechanism, you can continue to use AssetBundles for its remote content capability, but use content directories for local content to gain the benefit of improved performance.
Limitations
Content directories have the following limitations:
- You can only use content directories to create local content builds that you distribute with the Player build of your application. If you want to distribute content builds remotely, or download content after the user installs a Player, then you must create your own mechanism for distributing content directories, or use the AssetBundle system.
- You can't use the API with content directories. Assets that use this API need to be modified in order for them to load correctly with content directories. To resolve asset issues, use Project Auditor.
BuildUsage - A clean build might be slower than an AssetBundle build.
- Circular references between assets cause Unity to load those assets together as a single unit rather than individually, which increases load times and memory use. Unity prints a warning to the Console when it detects a circular reference, and fails the build if the combined size of the assets in a single cycle exceeds 64 MB. To identify which assets are involved, open the file that Unity writes to the build report folder.
circularrefs.json