Introduction to content directories

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. You can also use this mechanism to add optional content to your game, such as expansion packs or DLCs.

Important: 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 sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary that performs an initial load of content from a content directory. You build a Player from the Editor or through scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary.
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 assetsAny media or data that can be used in your game or project. An asset may come from a file created outside of Unity, such as a 3D Model, an audio file or an image. You can also create some asset types in Unity, such as an Animator Controller, an Audio Mixer or a Render Texture. More info
  See in Glossary needed to create the gameplay of your application.
- A manifest file (BuildManifest) which contains a record of the information needed to load the content.

The content directory system only rebuilds changed content, which helps reduce iteration time while developing a project.

Creating content directories

Content directories use ScriptableObject instances called root assets to define the content included in a build. You can then use the Loadable<T> API to load and unload individual assets synchronously, or asynchronously with async and await keywords. For more information, refer to Create content directories.

Comparison to AssetBundles

Content directories are a replacement for the AssetBundle system. The following table describes the differences between the two systems:

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 `Loadable<T>` and `LoadableSceneId` to put content into a build that needs to be loaded on demand. Unity automatically includes assets referenced by `Loadable` in the build. For more information, refer to Reference content in a content directory	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 `ScriptsOnlyCache.yaml`, the build manifest, and import data tracked inside the Asset Database. For more information, refer to Build cache location reference	Stored in `.manifest` files and `AssetBundleManifest`.
Code stripping	Use `BuildPlayerOptions.previousBuildMetadataLocations` to control code stripping. For more information, refer to How code stripping affects content.	Use `BuildPlayerOptions.assetBundleManifestPath` to control code stripping.
Build callbacks	Uses `IPreprocessBuildWithContext` and `IPostprocessBuildWithContext`. These callbacks are called for the Player build, content directory builds, and AssetBundles built with `BuildPipeline.BuildAssetBundles`. To check which type of build is happening, investigate the `BuildReport.summary.buildType`. `IPostprocessBuildWithContext` is called after all Player and content builds regardless of if they were successful, failed, or cancelled.	Uses `IPreprocessBuildWithReport` and `IPostprocessBuildWithReport`.

Tip: If you use the Addressables system, content directories are compatible.

Replacing AssetBundle code

The BuildAssetBundle method forced callers to define the name of each AssetBundle, and to explicitly assign assets and scenes to them via script or the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary. 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.

If your existing project relies on loading many assets by string, then consider using a ScriptableObject 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.

For more information on creating content directories, refer to Create content directories.

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.
Root assets must be ScriptableObject instances.
You can’t use the BuildUsage 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.
A clean build might be slower than AssetBundle build time.
Circular references are discouraged and print a warning to the Console.
Loadable references are only supported in the content directory system.

Additional resources

Use content directories to load assets at runtime

Create content directories