CCD and Addressables walkthrough#

You can use the Addressable Asset system in Unity with CCD to effectively serve content to your users. This page demonstrates how to set up an actual Unity game project with Cloud Content Delivery (CCD) and Addressables, which allows you to easily integrate a pipeline of assets from Unity Editor into CCD.

This workflow gives you instructions on how to do the following tasks with the Loady Dungeons sample project in Unity:

1. Configure Addressables in the Editor.
   1. Configure game assets as addressable.
   2. Configure an Addressables profile.
2. Connect your project to CCD.
3. Create buckets for your project.
4. Generate AssetBundles and upload content either manually or with the CCD Management package.
5. Promote the release.
6. Test your game.

Prerequisites#

For this workflow, you need to install the Loady Dungeon sample project. This project comes with the Addressables Assets package pre-installed, but you can also install the package from the Asset Manager.

Download and test the project#

The first thing you need to do to follow along with this walkthrough is to download the latest version of our sample game from GitHub, Loady Dungeons.

You can then test the project in the Unity Editor:

1. Open the Loady Dungeons project in the Unity Editor.
2. Open the MainMenu scene and click on the Game tab.
3. In the Aspect dropdown, select the + icon.
4. Create a new aspect of Type "Aspect Ratio", with a Width and Height of 9 and 16, respectively. This makes the game preview look more like it's running on a phone.
5. Select OK.
6. Deselect Low Resolution Aspect Ratios.
7. Select the Editor Play button to try the game.

Install the Addressable Assets package#

In order to mark assets as addressable, you need to install the Addressables package directly in Unity Editor.

This project already has an Addressables package pre-installed, but if you are following along with a custom project or want to upgrade to a newer verified version, install the Addressables package through the Package Manager:

1. Select Window > Package Manager.
2. Search for the latest version of Addressables verified for the version of Unity Editor you’re using. This example uses version 1.16.19.
3. Select the version you need, then Install.

Configure Addressables in the Editor#

Configure game assets as addressable#

Addressable assets provide an easy way to handle asset management overload by loading assets by address. To load game assets by address, you need to mark them as Addressable:

1. Open the Scenes folder in the Project window.

2. Select the following assets:

   • Level_00
   • Level_01
   • Level_02
   • Level_03

3. In the Inspector window, select Addressable for each asset.

4. Select Window > Asset Management > Addressables > Groups to open the Addressables Groups window.

5. Select Create > Group > Packed Assets and create the following new groups:

   • Level 00
   • Level 01
   • Level 02
   • Level 03
   • Hats

6. Drag the Scenes assets from the default group into their corresponding groups. For example, drag the Level_01 scene from the default group into the new Level 01 group you created.

7. In the Project window (Prefabs > Hats), drag the entire contents from the Hats folder (not the folder itself) into the Hats group.

8. Select each of the assets from the Addressables Groups window, and rename their lengthy Addressable field to something simpler in the Inspector window.

   Note: To automatically rename them, select all the assets, right-click, and select Simplify Addressable Names.

   • Rename scene asset Level_00’s Addressable field to Level_00
   • Rename scene asset Level_01’s Addressable field to Level_01
   • Rename scene asset Level_02’s Addressable field to Level_02
   • Rename scene asset Level_03’s Addressable field to Level_03
   • Rename prefab asset Hat00’s Addressable field to Hat00
   • Rename prefab asset Hat01’s Addressable field to Hat01
   • Rename prefab asset Hat02’s Addressable field to Hat02
   • Rename prefab asset Hat03’s Addressable field to Hat03

Configure an Addressables profile#

To save all of the associated settings related to development of the game, you can create a new Addressables profile:

1. Select Window > Asset Management > Addressables > Groups.
2. From the dropdown, select Profile > Manage Profiles.
3. In the Addressables Profiles window, select Create > Profile to create a New Profile.
4. Right-click the new profile and select Rename Profile. Name it Development Profile.
5. Right-click Development Profile and select Set Active. This sets the Development Profile as the current profile in use.
6. Build your AssetBundle, which is an archive file that contains non-code assets for your game.
7. Set the Editor’s play mode to use your AssetBundles instead of local assets:
   1. Select Window > Asset Management > Addressables > Groups.
   2. Select Build > New Build > Default Build Script from the dropdown.
   3. Select Play Mode Script > Use Existing Build from the dropdown.

Connect your project to CCD#

After you set up your Addressables in the Unity Editor, you can connect the game project to the Cloud Content Delivery (CCD) service, ultimately leveraging the Addressables and AssetBundles. CCD is managed cloud service that hosts and delivers content to your application’s users worldwide without the need to reinstall a new version of the application.

To get started with CCD:

1. Sign in to the Unity Cloud Dashboard with your Unity ID.

2. From the projects page, select New button.

   1. Name the project Loady Dungeons Workshop.
   2. Select Create project.

3. Open your new Loady Dungeons Workshop project and take note of the Project ID.

4. Select the Environments tab. If you don't already have a development environment, create one.

5. From the Products page in the dashboard, locate and open Cloud Content Delivery.

The Command-line interface (optional)#

You can also use the optional command-line interface (CLI) to manage your project:

1. Download the CLI for your operating system.
2. Make sure to include the CLI’s folder in your computer’s Environment Variables.
3. Open the command line and navigate to your project’s folder.
4. Type the following command to make sure the CLI is successfully configured: ucd help.

For more information, refer to CCD Command-line interface (CLI).

Create buckets#

You can create buckets to assist in the different stages of creation for this project.

1. From the CCD landing page, select Buckets on the left.

2. Select Loady Dungeons Workshop from the projects dropdown (if not already selected).

3. Select Create Bucket to create a new bucket.

4. Name the bucket Loady Dungeons Sample and give the bucket an optional description.

5. Select the permissions for this bucket from the following:

   • Open to all: Anyone can modify content in this bucket.
   • Promotion only: Owners and managers can modify content through promotion. No one can upload to or delete content from this bucket.

6. To restrict read access to this bucket, select Enable Bucket Privacy. Private buckets only allow users with an access token to read the content.

   Note: You cannot change the bucket privacy settings after you create the bucket.

7. Select Next and make sure both production and development environments are selected.

8. Select Create.

When you create the Loady Dungeons Sample bucket. it appears on the Cloud Content Delivery Buckets page in the Unity Cloud Dashboard, for both development and production environments. You can use the environments dropdown to switch between environments at the top of the page. Take note of the Bucket IDs of the buckets in both environments because you need to use them later in your remote load path.

Use Addressables with private buckets#

If you want to read the data from private buckets, you need to have a valid Bucket Access Token.

As of Addressables 1.19.4, you can use the WebRequestOverride feature to add a Bucket Access Token as a header to the request, which the following example demonstrates:

void Start()
{
	textComponent = GetComponent<Text>();
	Addressables.WebRequestOverride = webRequest =>
	{
		webRequest.SetRequestHeader("Authorization", "Basic "+token);
		//  Debug.Log($"Fetching: {webRequest.url}");
	};
	Addressables.LoadAssetAsync<TextAsset>("Assets/one.txt").Completed += handle =>
	{
		textComponent.text = handle.Result.text;
		// Debug.Log($"Text is now: {handle.Result.text}");
	};
}

In this example, token is the base64 encoded Bucket Access Token value.

Generate AssetBundles and upload content manually#

Generate AssetBundles#

An AssetBundle is an archive file that contains platform-specific non-code assets that Unity can load at run time.

To generate AssetBundles:

1. In your Unity Editor project, select Window > Asset Management > Addressables > Groups.

2. In the Profile dropdown, make sure that Development Profile is selected. If it isn’t, select it now.

3. In the Profile dropdown, select Manage Profiles.

4. With Development Profile selected, set the following:

   • RemoteBuildPath: AssetBundles/[BuildTarget], where [BuildTarget] is the default subfolder.

   • RemoteLoadPath: https://PROJECT_ID.client-api.unity3dusercontent.com/client_api/v1/buckets/BUCKET_ID/release_by_badge/latest/entry_by_path/content/?path=

     • Replace PROJECT_ID with the ID of your project. To find your Project ID, click on your username in the corner of the Unity Cloud Dashboard, then select Account > Project Management > Loady Dungeons Workshop.
     • Replace BUCKET_ID in the path with the ID of the bucket you want to use. In this example, select the Loady Dungeons Sample bucket created in your development environment. To find the BUCKET_ID, go to your list of buckets in the Unity Cloud Dashboard.
     • The latest in the path refers to the badge called Latest, an automatically generated badge assigned to the most recent release.

5. Return to the Addressables Groups window and select Hats.

6. In the Inspector panel, set the build path and load paths for these four sets of assets to the paths we specified for the Development Profile:

   • Build Path: RemoteBuildPath
   • Load Path: RemoteLoadPath
   • Repeat for Level 00, Level 01, Level 02, and Level 03

7. In the Groups window, select the Build dropdown, then select New Build > Default Build Script. This saves the AssetBundles at the RemoteBuildPath location.

8. To use the build you made as the basis for a play test, select Play Mode Script > Use Existing Build.

9. Select the Play button in Unity Editor to test the game. Press Start in the game. Notice how the game is now stuck.

Upload the content#

At this point, you can upload this content into the Development bucket you set up in CCD earlier.

1. In your Unity Cloud Dashboard, go to your development environment in the CCD section and select the Loady Dungeons Sample bucket.
2. Select Upload using the dashboard if the bucket is empty, or Upload Content if the bucket already contains entries.
3. Drag and drop, or select the Browse button, to upload content from the folder where you built your AssetBundles to your CCD Development bucket. Your files are in the folder specified as the RemoteBuildPath.
4. Select Upload 5 Files (four levels and Hats).
5. After the upload process, select Refresh Page to update the status of the bucket's information. The entries appear as Unreleased Changes. This means that the entries are present in the bucket but have not yet been wrapped up in a Release.
6. To make a release, select Create Release. This takes the AssetBundles you uploaded to the Loady Dungeons Sample bucket in your development environment and binds them into a Release. Follow the onscreen prompts to finish the process.

CCD automatically applies the automatically created latest badge to this release, which marks it as the newest release created in this bucket.

Generate AssetBundles and upload content with CCD Management package#

The CCD Management package with Addressables 1.19.15+ allows you to build, upload and release Addressable content.

Generate AssetBundles#

1. In your Unity Editor project, select Window > Asset Management > Addressables > Groups.
2. In the Profile dropdown, make sure that Development Profile is selected.
3. In the Profile dropdown, select Manage Profiles.
4. In the Profiles window, select Development Profile, then select Cloud Content Delivery from the Remote dropdown.

   Note: At this point if you don't already have the CCD Management package installed, Unity Editor prompts you to add it. Select the Install CCD Management SDK Package button to install it.

5. In the next list of options, select the Loady Dungeons Sample bucket and in the subsequent list, select the Latest badge.
6. Return to the Addressables Groups window and select Hats.
7. In the Inspector panel, under Content Packaging & Loading set the build path and load paths for these four sets of assets to the paths pairs specified for the Development Profile. For more information on path pairs, refer to the Profiles overview.
   • Set Build and Load Paths: Remote
   • Repeat for Level 00, Level 01, Level 02, and Level 03
8. In the Groups window, select the Build dropdown, then select New Build > Default Build Script. This saves the AssetBundles at the RemoteBuildPath location.
9. To use the build we made as the basis for a play test, select Play Mode Script > Use Existing Build.
10. Select the Play button in Unity Editor to test the game.

When you select Start in the game, the game is now stuck.

Upload the content#

To generate, upload, and release this content into the Loady Dungeons Sample bucket we set up in CCD earlier:

1. In your Unity Editor project, click Window > Asset Management > Addressables > Groups.
2. Select Build & Release.

The CCD Management package uses the default build script behavior to generate the Addressable bundles. Then, the management package uploads all groups associated with the path pair that is connected to the Loady Dungeons Sample bucket and latest badge that we set up earlier to those remote targets. Finally, the management package creates a release for those remote targets and updates their badge to latest.

Promote the release#

After you upload your assets to the Loady Dungeons Sample bucket in your development environment and you tie those assets into a release, you can put these latest changes out for public consumption. That’s why we also created the bucket in your production environment. The buckets in your production environment contain releases ready for your players. This means moving the release from the bucket in your development environment to the one in your production environment by a process called promotion.

To promote the release from the bucket in your development environment to the one in your production environment:

1. In the Unity Cloud Dashboard, go to the Loady Dungeons Workshop CCD project, make sure the development environment is selected in the environments dropdown, and select the Loady Dungeons Sample bucket.
2. Select Promote Release.
3. In the Target Environment dropdown, select production.
4. In the Target Bucket dropdown, select Loady Dungeons Sample.
5. Add optional release notes.
6. Select Next and follow the onscreen prompts.
7. Select Promote Release.

Again, CCD automatically applies the automatically created latest badge to this release, which marks it as the newest release created in this bucket.

Before you test the game, you need to modify the profile variables to point to the correct bucket. There are two ways to do this:

• You can have a different player build per environment. Both builds use the same content, but for the Deployment build, you need to enable debug symbols and set the bucket_id variable to your bucket from the development environment. For your Production build, you need to disable debug symbols and set the bucket_id variable to your bucket from the production environment.
• You can use static properties in a profile variable or TransformInternalId to dynamically change the bucket the catalog reaches out to at runtime. For more information about the static profile variables and how to transform internal IDs in Addressables, refer to Change resource URLs.

Test your game#

1. In Unity Editor, select the Editor's Play button.
2. Select Start in game.
3. Select Play in game. You can now play the game within Unity Editor.

In this workflow, you successfully move the release and all its assets from Development to Production, ready to deploy to your users as a functional game.