CCD + Addressables walkthrough

This section demonstrates how to set up an actual Unity game project with Cloud Content Delivery (CCD) and Addressables, allowing you to easily integrate a pipeline of assets from Unity Editor into CCD.

The Addressables Asset System isn’t required for using CCD.

Using a very simple mobile game called Loady Dungeons, you will learn how to:

After reading this walkthrough, you will know how to effectively serve content to your users, and how to use the Addressable Asset system in Unity with CCD.

This walkthrough uses Unity 2021.3.18f1.

Download 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.

Test the project

  1. Open Unity Editor.

  2. Open the Loady Dungeons project.

  3. Open the MainMenu scene.

  4. Click on the Game tab.

  5. In the Aspect dropdown, click +.

    1. 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.
    2. Click OK.
    3. Deselect Low Resolution Aspect Ratios.
  6. Press the Editor's Play button to try the game.

Playing the game in its initial state means you can't load the first level. Progressing through this walkthrough fixes this limitation by associating the required assets to use CCD with Addressables.

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 game assets as addressable

Addressable assets provide an easy way to handle asset management overload by loading assets by address. Now that you have the Addressables package installed, it’s time to mark your game assets 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.

  4. Open the Addressables Groups window from Window > Asset Management > Addressables > Groups.

  5. Create the following new groups using Create > Group > Packed Assets:

    • 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. Drag the entire contents from the Hats folder (not the folder itself) in the Project window (Prefabs > Hats) 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. You can select all the assets, right-clickSimplify Addressable Names to automatically rename them.

    For the scene asset Level_00, rename its Addressable field from Assets/Scenes/Level_00.unity to Level_00.

    • 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 profiles and building AssetBundles

  1. At this stage, create a new Addressables profile to save all the associated settings related to development of the game to this development profile:

    1. Click Window > Asset Management > Addressables > Groups.
    2. Select Profile > Manage Profiles from the dropdown.
    3. In the resulting Addressables Profiles window, select Create > Profile.
    4. A profile named New Profile appears. Right-click it and select Rename Profile. Name it “Development Profile”.
  2. Right-click Development Profile > Set Active. This sets the Development Profile as the current profile in use.

  3. Now, build your AssetBundle, which is an archive file that contains non-code assets for your game. This is so that the Editor’s play mode uses our AssetBundles instead of local assets.

    1. Click 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.

Get started with CCD

Now you are ready to hook this game into the Cloud Content Delivery (CCD) service, ultimately leveraging Addressables and AssetBundles. The benefit of CCD is that it is a managed cloud service that hosts and delivers content to your application’s users worldwide without having to reinstall a new version of the application.

To get started with CCD:

  1. Go to the Unity Cloud Dashboard.

  2. Sign in using your Unity ID.

  3. From the projects dropdown, click Create Project.

    1. Name it “Loady Dungeons Workshop”.
    2. Click Create project.
  4. Open the Loady Dungeons Workshop project and take note of the Project ID.

  5. Select the Environments tab.

  6. If you don't already have a development environment, create one.

  7. From the Dashboard landing page, locate and select Cloud Content Delivery.

The Command-line interface (optional)

If you prefer to 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

See CCD Command-line interface (CLI).

Buckets

At this point, it is time to create buckets to assist in the different stages of creation for this project.

Create buckets

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

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

  3. Click Create Bucket.

    1. Name the bucket “Loady Dungeons Sample”.

    2. Give the bucket an optional description.

    3. Choose whether this bucket is:

      • 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.
    4. To restrict read access to this bucket, select Enable Bucket Privacy. Private buckets only allow users with an access token to read the content.\

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

    5. Select Next.

    6. Make sure both production and development environments are checked.

    7. Select Create.

The Loady Dungeons Sample bucket should now appear on the Cloud Content Delivery Buckets page in the Unity Cloud Dashboard, for both development and production environments. You can switch between environments using the environments dropdown at the top of the page. Take note of the buckets’ Bucket ID in both environments because you need to use them later in your remote load path.

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, click 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. If you didn’t take note of your Project ID earlier, find it by clicking on your user name in the corner of the Unity Cloud Dashboard, then Account > Project Management > Loady Dungeons Workshop.
      • Replace BUCKET_ID in the path with the ID of the bucket you want to use, the Loady Dungeons Sample bucket created in your development environment in this example. If you didn’t take note of its BUCKET_ID earlier, find it in 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.

  6. Select Hats.

  7. In the Inspector panel, set:

    1. Build Path: RemoteBuildPath
    2. Load Path: RemoteLoadPath
    3. Repeat for Level 00, Level 01, Level 02, and Level 03

    This sets the build path and load paths for these four sets of assets to the paths we specified for the Development Profile.

  8. Still in the Groups window, click on the Build dropdown, then select New Build > Default Build Script. This saves the AssetBundles at the RemoteBuildPath location.

  9. To use the build we just made as the basis for a playtest, click on the Play Mode Script > Use Existing Build.

  10. Click 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, we want to upload this content into the Development bucket we set up in CCD earlier.

  1. Select the Loady Dungeons Sample bucket in your development environment from the CCD section of the Unity Cloud Dashboard.
  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 from earlier.
  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.

Notice that CCD automatically applies the automatically created latest badge to this release, marking 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+ facilitates building, uploading and releasing Addressable content.

You need to upgrade the Addressables versions and install the CCD Management package through the Package Manager.

  1. Select Window > Package Manager.
  2. Search for Addressables, select the version 1.19.15+, then Install.
  3. Search for CCD Management, select the version 2.0.1+, then Install.

Generate AssetBundles

  1. In your Unity Editor project, click 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 change the Remote dropdown to use Cloud Content Delivery.

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

    1. In the next list of options, choose the Loady Dungeons Sample bucket created earlier.
    2. In the subsequent list, choose the Latest badge.
  5. Return to the Addressables Groups window.

  6. Select Hats.

  7. In the Inspector panel, under Content Packaging & Loading:

    1. Set Build and Load Paths: Remote
    2. Repeat for Level 00, Level 01, Level 02, and Level 03

    This sets the build path and load paths for these four sets of assets to the paths pairs specified for the Development Profile. See Profile for more information on path pairs.

  8. In the Groups window, click on 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 playtest, click on the Play Mode Script > Use Existing Build.

  10. Select the Play button in Unity Editor to test the game.

  11. Select Start in the game. Notice how 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’ve uploaded 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. If not already there, 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, notice that CCD automatically applies the automatically created latest badge to this release, marking 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:

  1. You can have a different player build per environment. Your Development build would have debug symbols and the bucket_id variable set to your bucket from the development environment, and your Production build would have debug symbols disabled and the bucket_id variable set to your bucket from the production environment, but they would use the same content.
  2. Use static properties in a profile variable or TransformInternalId to dynamically change the bucket the catalog is reaching out to at runtime. For more about the static profile variables and transforming internal IDs in Addressables, see Transforming resource URLs.

Test the game:

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

You’ve now successfully moved the release and all its assets from Development to Production, ready to deploy to your users.

Using Addressables with private buckets

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 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.