Create content directories

Define ScriptableObject root assets, which contain the assets of your project to build into a content directory.

読み終わるまでの所要時間 8 分

最終更新 2日前

A content directory is the output of the content build process, similar to the folder that contains the

.bundle

files and manifest when using AssetBundles. You don't assign assets to a content directory in the Unity Editor, but create a

ScriptableObject

instance which acts as a root asset. Unity includes the root asset and everything it references, directly or indirectly, in the content directory. For more information, refer to Reference content in a content directory.

ヒント

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.

Root asset overview

A root asset is a

ScriptableObject

asset in your project that you use to define which content to include in a content build.

If you're moving from the AssetBundle system, root assets don't need to mirror AssetBundles, because the content directory system automatically handles asset dependencies for you. For example, if you previously had ten AssetBundles, you don't need ten root assets because the content in a content directory can be loaded and unloaded independently without having to load other content in the root asset. One root asset for all content suits most projects, and if necessary, you can create more for specific content such as optional content packs.

Unity loads root assets into memory automatically when you register a content directory with

ContentLoadManager.RegisterContentDirectory

, so it's best practice to avoid direct references to large assets.

For an example, refer to Create a ScriptableObject to define the root asset.

Differences between the AssetBundle and content directory creation process

Content directories are designed to be a replacement for the AssetBundle system. The concept of assigning assets to be built in separate content builds remains the same, but the process differs as follows:

Workflow	AssetBundles	Content directories
Creation	Create named AssetBundles in the Editor, or `.meta` files.	Create `ScriptableObject` instances and pass their paths as root assets in the build script.
Assigning assets	Assign each asset to a specific AssetBundle.	Reference assets from the `ScriptableObject` instances.
Building	Run `BuildPipeline.BuildAssetBundles` .	Run `BuildPipeline.BuildContentDirectory` with an output folder path and `rootAssetPaths` .
Loading content	Each dependent AssetBundle loaded explicitly with `AssetBundle.LoadFromFile` and similar methods.	All content available with `ContentLoadManager.RegisterContentDirectory` .
Loading individual assets	Use `AssetBundle.LoadAsset` .	Use `Loadable<T>` .
Loading scenes	Load through `SceneManager` by path.	Load through `SceneManager` by `LoadableSceneId` .
Unloading	Call `AssetBundle.Unload` to unload an entire AssetBundle. The `unloadAllLoadedObjects` parameter controls whether Unity also destroys objects already loaded from it.	Call `Release` on each `Loadable<T>` . Unity reference counts each asset and unloads it when the last reference is released.

重要

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.

Content directory creation overview

To create content directories, perform the following steps:

Create a ScriptableObject root asset.
Create the root asset in the Unity Editor.
Build the content directory.
Optionally verify the build process.

Create a ScriptableObject root asset

The following is an example which defines a root asset for an optional content pack. It uses three ways to include content in the build:

A
```
Loadable<GameObject>
```
for a bonus prefab you load on demand at runtime.
A
```
LoadableSceneId
```
for a bonus level scene.
A direct reference to a lightweight metadata
```
ScriptableObject
```
.

For more information on how to reference assets, refer to Reference content in a content directory.

Save the following as

ContentPackRootAsset.cs

anywhere in the

Assets

folder of your project.


using UnityEngine;    using Unity.Loading;        // Defines the name of the menu options as they appear in the Editor.    [CreateAssetMenu(fileName = "ContentPackRootAsset", menuName = "Content/Content Pack Root Asset")]    public class ContentPackRootAsset : ScriptableObject    {        // Loadable: included in the build; load when needed with bonusPrefab.Load().        public Loadable<GameObject> bonusPrefab;        // Scene reference: included in the build; load with SceneManager when the directory is registered.        public LoadableSceneId bonusLevel;        // Direct reference to another lightweight ScriptableObject is fine here, such as metadata.        public ContentPackMetadata metadata;    }

Also save the following as

ContentPackMetadata.cs

anywhere in the

Assets

folder of your project.


using UnityEngine;    using Unity.Loading;    // Lightweight metadata asset that the root asset references directly.    [CreateAssetMenu(fileName = "ContentPackMetadata", menuName = "Content/Content Pack Metadata")]    public class ContentPackMetadata : ScriptableObject    {        public string description;        // Stored as a string because Unity doesn't serialize System.DateTime.        public string expirationDate;        public int difficulty;    }

If you have a large amount of content, you don't have to define all

Loadable<T>

references on a single root asset. You can create a hierarchy of

ScriptableObject

instances where the root asset holds direct references to other

ScriptableObject

instances, each of which tracks a different category of content. Only the top-level

ScriptableObject

in the hierarchy needs to be the root asset passed to

BuildPipeline.BuildContentDirectory

because Unity follows tracked references from the root asset wherever they lead. For more information, refer to Build the content directory.

For examples of other ways to organize a root asset and the

ScriptableObject

instances it references, including lookup by key and designs that populate themselves, refer to ScriptableObject designs for content directories.

Create the root asset in the Editor

After Unity compiles the script, right-click in the Project window and select Create > Content > Content Pack Root Asset (from
```
[CreateAssetMenu]
```
).
Give the root asset a name (for example
```
ContentPackRootAsset
```
) and place it at a stable path such as
```
Assets/ContentPacks/ContentPackRootAsset.asset
```
.
Select the asset and assign your content pack prefabs, scene, and
```
ContentPackMetadata
```
asset in the Inspector.

The

.asset

path is what you pass to the build API, for example:


var parameters = new BuildContentDirectoryParameters{    outputPath = "Builds/ContentPack",    rootAssetPaths = new[] { "Assets/ContentPacks/ContentPackRootAsset.asset" }};BuildPipeline.BuildContentDirectory(parameters);

Unity then follows references from the root asset and includes the metadata asset, bonus prefab, and bonus level scene in the content directory build.

Build the content directory

The following is an example of an Editor script that uses the previous steps to call the build API and create a content directory. To use this script, place it in the

Assets/Editor

folder of your project, or add a

#if UNITY_EDITOR

define:


using UnityEditor;    using UnityEditor.Build.Reporting;    public static class BuildContentPackRootAsset    {        [MenuItem("Build/Content Directories/Content Pack")]        public static void Build()        {            var parameters = new BuildContentDirectoryParameters            {                // Folder for the built content directory (created if it does not exist).                // Typically should be outside the Assets folder.                outputPath = "Builds/ContentPack",                // Project paths to ScriptableObject root assets for this pack.                // Unity includes each root and every asset they reference (direct, Loadable, scenes).                rootAssetPaths = new[]                {                    "Assets/ContentPacks/ContentPackRootAsset.asset"                },                // Optional build flags (for example BuildContentOptions.CleanBuildCache).                // See BuildContentOptions in the Scripting Reference.                options = BuildContentOptions.None,            };            // Uses the active build target from Build Profiles.            BuildReport report = BuildPipeline.BuildContentDirectory(parameters);            if (report.summary.result == BuildResult.Succeeded)                UnityEngine.Debug.Log($"Content directory built to: {parameters.outputPath}");        }    }

You can then create a content build from the menu item the script adds under Build. Unity adds the content directory to the

Builds

folder of your project, as defined by

outputPath

. For more information on the optional build flags, refer to the

BuildContentOptions

API documentation.

A content directory build produces the following files, which Unity names with a hash of their own content:

```
.cf
```
content files: Hold the serialized Unity objects from scenes or assets.
```
.resS
```
files: Hold streamed texture and mesh data.
```
.resource
```
files: Hold audio and video data.
Build manifest: Records the information Unity needs to load the content, including the list of content files, their dependencies, and the loadable objects and scenes. Its file name is the content hash with a
```
.json
```
extension.

The build also produces

BuildManifestHash.txt

, which has a fixed name and records the hash of the build manifest so that Unity can find the current manifest.

To pack the content files, resource files, and build manifest into a Unity archive instead of writing them individually, set

BuildContentOptions.UseArchive

, or set

BuildContentDirectoryParameters.compression

to a compressed setting, which produces an archive automatically. The archive has a fixed name of

content0.archive

, and only

BuildManifestHash.txt

remains as an individual file alongside it.

For a low-level description of these files, refer to ContentDirectory format in the UnityDataTools documentation.

To create another content directory, run

BuildContentDirectory

again with a different

outputPath

and different

rootAssetPaths

Verify the build

To verify the build process was successful, you can check the build result as follows:

In a build script, check
```
BuildReport.summary.result
```
. For example, the previous build script logs a message when
```
report.summary.result
```
equals
```
BuildResult.Succeeded
```
.
In the Editor, open the Build Analysis window (Window > Analysis > Build Analysis), which displays the build result as Success, Failed, or Cancelled. To confirm that a specific asset is included in the build, inspect the Assets tab.

When the build succeeds, Unity writes the content directory to the folder under

outputPath

, including a build manifest file. Distribute every file in this folder along with the Player build. To package the output into a Player build from a script, refer to Create a custom build script.

ドキュメント

Development

User Acquisition

Monetization

産業

Unity Engine

User Manual

Script Reference

Unity Engine

Create content directories

Root asset overview

Differences between the AssetBundle and content directory creation process

Workflow

AssetBundles

Content directories

Content directory creation overview

Create a ScriptableObject root asset

Create the root asset in the Editor

Build the content directory

Verify the build

Additional resources