Manage builds with profiles

You'll deliver your Addressables content either locally or remotely, so you will need to specify consistent local and remote storage locations.

You might also need to separate your content into different build environments. These environments are meant to be a reflection of your production pipeline, such as Development, Test, and Production, with each environment existing in a different remote location on your content delivery network (CDN). This workflow enables you to place Addressables content in the Development location without affecting the previous version of content that QA is testing, or the Production version that users interact with.

Profiles are a configurable data structure with customizable variables that you’ll manage in the Unity Editor without writing scripts. The variables are text that can represent many things, but typically they represent file locations where local and remote Addressables are stored during project development and where the application loads them from.

By default, Addressables is configured with a set of variables and a Default profile with values for them. The default profile describes build paths, where content will be stored during each build, and load paths from which content will be loaded during runtime.

To check out the default profile in the Addressables Profile window, select Window > Asset Management > Addressables > Profiles from the main menu.

In this window, there are five variables, which are as follows:

• Local.BuildPath: the location on your development workstation to store your player build.
• Local.LoadPath: the location on your target platform from where Addressables content that is packaged with your application is loaded from at runtime.
• Remote.BuildPath: the location on your development workstation where Addressables content that is meant to be packaged on a CDN will be written to.
• Remote.LoadPath: the location on your target platform where Addressables content is loaded at runtime. This is usually a web address.
• BuildTarget: The target platform for the player build. This value changes depending on the target platform you select in Unity Editor's Build Settings.

This default set of variables is assumed to exist with those exact names so they can be used by the Default Build Script.

Profile notation

Addressables Profiles use both square and curly brackets to denote values that come from other profile variables or either static variables in your scripts:

• Square Brackets [ ] denote that values of other profile variables should replace everything within the brackets (including the brackets) at the time that the content gets built.
• Curly Braces { } denote the values of public static fields from your game scripts should replace everything within the brackets (including the brackets) at time of Addressables’ runtime initialization.

You'll create a profile for each environment to specify how variables differ. You can have many profiles but they all share the same structure, the list of variables. The values of these variables differ between profiles, allowing you to set up different configurations.

To create a new profile, follow these instructions:

1. From the Profiles window, select Create > Profile.

2. Select the New Profile profile, right-click it, and select Rename Profile.

3. Rename New Profile “Development”.

4. To make a profile active so that it's used for your build, right-click it and select Set Active. In the Profiles window, a check mark next to a profile’s name indicates that it is the currently active profile.

Note: You can also change the active profile and access the Addressables Profiles window through the Profile dropdown at the top of the Addressables Groups window.

5. Repeat steps 2 and 3 to add “Test” and “Production” profiles.

You might have noticed that the new profiles you just created have the same variables as the Default profile. This is because new profiles are based on your current active profile, and you haven’t yet defined how they differ.

The number of variables and their names will be the same across all profiles, but the values of these variables differ allowing you to set up different configurations across profiles.

Let's create a new variable that you can use in your profiles:

1. From the Profiles window, select Create > Variable (All Profiles).

2. In the dialog, select the Variable Name box and enter "RemoteHost".

3. In the dialog, select the Default Value box and enter “DEFAULT” and then select the Save button.

To rename a variable, right-click it in the Profiles window and select Rename Variable (All Profiles).

To delete a variable, right-click it in the Profiles window and select Delete Variable (All Profiles).

Build and Load Path variables

There is a special type of variable called a Build and Load Path variable (also known as a path pair variable) that is actually two variables in one. Build and Load Path variables are treated as one in the Editor in order to restrict how you can edit them. One variable always represents the build path, and the other represents the load path:

• .BuildPath: the location on your development workstation where built content is written to.
• .LoadPath: the location on your Player target platform where built content is loaded at runtime.

For consistency, the two paths share the name of the Build and Load Path variable as a prefix.

To create a Build and Load Path variable, follow these instructions:

1. From the Profiles window, select Create > Build and Load Path Variables (All Profiles).

2. In the dialog, select the Prefix Name box and enter “Testing”.

3. In the dialog, select the Build Path Value box and enter “here”, then select the Load Path Value box and enter “there”.

4. Select the Save button.

5. Right-click Remote variable and select Delete Path Pair (All Profiles).

6. Right-click Testing variable and select Rename Path Prefix (All Profiles) and rename it to “Remote”. Note that renaming the Build and Load Path variable also changes the prefix for the BuildPath and LoadPath.

Due to their nature as variables that represent paths, Build and Load Path variables have a location type dropdown in the Profiles window that constrains these variables and values into specific structures for convenience. From this dropdown, you can select the following types:

• Built-in: the recommended location where built content that is meant to be packaged with your application.
• Editor hosted: the recommended location to use if you are using the Unity Editor as a means of mocking a CDN through private hosting.
• Cloud Content Delivery: integrates into Unity Gaming Services’ Cloud content delivery network.
• Custom: defined by the developer.

When you create a Build and Load Path variable, the location type defaults to Custom. If you choose anything other than Custom, the Addressables system determines what the contents of the path variables are, for consistency.

Edit profile variable values

As you navigate from one profile to the next, notice that the values of the profile variables stay the same. This is because variables are populated across all profiles with the same default values when they are created.

To change profile variable values so that they differ from profile to profile, follow these instructions:

1. From the Profiles window, select the Development profile.

2. Select RemoteHost and enter “DEV”.

3. From the Profiles window, select the Test profile.

4. Select RemoteHost and enter “QA”.

5. From the Profiles window, select the Production profile.

6. Select RemoteHost and enter “PROD”.

Now when you select different profiles, the name of the new variable RemoteHost will be the same across all profiles, but it will have different values.

Now that you're familiar with profiles and variables, let's use the profiles in Loady Dungeons to try a scenario similar to one that you might encounter in your own game.

Suppose that you have a CDN that will host your Addressables content for Loady Dungeons. You need to send content to build environments for development (DEV), quality assurance testing (QA), and product release (REL). You have set up the CDN buckets on your web server to use the same base URL (https://your_CDN_URL.com/), but the rest of the URL differs across all of your team's Unity applications, for each build environment (DEV, QA, and REL), and for each target platform.

Here are some of the paths you need to generate in your profiles:

• A development build for Windows needs to go to https://unity.com/LoadyDungeons/DEV_StandaloneWindows64/.
• A QA build for a version of LoadyDungeons that targets the Android platform needs to point at the URL https://unity.com/LoadyDungeons/QA_Android/ to get the correct Addressables content.
• A release build on iOS needs to be located at https://unity.com/LoadyDungeons/PROD_iOS/.

As you can see, you have planned a consistent pattern in these URLs, so you can create a ruleset in your Addressables profiles.

In our scenario, let's say that you don't have an CDN integrated with Unity Editor that can automatically upload after a build, so you will upload built content manually. Your builds are saved to a folder on your local disk named "ServerData" under the Unity project, where you have a subfolder for each build target.

Let's use the square bracket notation to configure the profile path pair variables, so that Loady Dungeons's profiles can build and locate the content at the correct locations.

Mini-challenge: Rewrite the Remote path pair

Given that the name of your application, LoadyDungeons, is stored in the public static field UnityEditor.PlayerSettings.productName, try writing the new Remote path pair on your own before you proceed to the instructions below.

Configure the Remote path pair

The pattern of the Remote path pair in the default profiles doesn't match the pattern your organization is using, so let's change it across all the profiles. To configure your new path pair, follow these instructions:

1. Create QA and Release profiles if you haven't already.

2. In the Profiles window, locate the Remote variable.

3. Select the BuildPath value and enter “ServerData/[BuildTarget]”.

4. Select the LoadPath value and enter “https://unity.com/{UnityEditor.PlayerSettings.productName}/[RemoteHost]_[BuildTarget]”.

5. Make sure that the values of the Remote path pair are the same across all profiles, and that the value of the RemoteHost variable is the only thing that changes between the profiles. Make adjustments as needed.

Next, let's check your work. You'll write a script that will display your profile variables and their values, and run it from the Unity Editor.

To write your test script, follow these instructions:

1. In the Project window, in Assets, right-click and select Create > Folder and name the folder “Editor". Here, you can store scripts that won't be included in the build.

2. Select the Editor folder, right-click Create > C# script, and name it “ProfileVariableTester.cs”.

3. Remove all lines of code in this file.

4. Near the top of the script, add the Addressables namespaces:

using System.Collections.Generic;
using UnityEditor;
using UnityEditor.AddressableAssets;
using UnityEditor.AddressableAssets.Settings;
using UnityEngine;

5. Add in the file with the following code:

class ProfileVariables
{
    public int count;
    public List<string> names;
    public List<string> values;
    public List<string> editorValues;

    public ProfileVariables(List<string> names)
    {
        this.count = names.Count;
        this.names = names;
        values = new List<string>(count);
        editorValues = new List<string>(count);
    }

    public override string ToString()
    {
        string message = string.Empty;
        for (int i = 0; i < count; i++)
        {
            message += $"{names[i]} = '{values[i]}' -> '{editorValues[i]}'\n";
        }

        return message;
    }
}

This is a structure which will keep track of how our profile variables will change

6. In the ProfileVariableTester class add the following code below the previous class:

public class ProfileVariableTester
{
    [MenuItem("LoadyProfiles/Test Profile Variable")]
    private static void TestProfileVariable()
    {
        AddressableAssetSettings addressableAssetSettings = AddressableAssetSettingsDefaultObject.Settings;
        AddressableAssetProfileSettings profileSettings = addressableAssetSettings.profileSettings;
        string activeProfileID = addressableAssetSettings.activeProfileId;

        var variables = new ProfileVariables(profileSettings.GetVariableNames());
        
        for (int i = 0; i < variables.count; i++)
        {
            string variableName = variables.names[i];
            var value = profileSettings.GetValueByName(activeProfileID, variableName);
            variables.values.Add(value);

            var editorValue = profileSettings.EvaluateString(activeProfileID, value);
            variables.editorValues.Add(editorValue);
        }
        Debug.Log(variables);
    }
}

7. From the main menu, select Loady Profiles > Test Profile Variable.

All the profile variables will appear in the Console window. The log shows the variable name, the variable value with notation, and the variable value with the notation resolved. When you build and run Loady Dungeons, the application will use the paths to save and load content.

You can retrieve variable values from Addressables API at runtime using the same notation in your application scripts. However, the concept of profiles does not exist at runtime, so default behavior does not provide a way to resolve values such as Local.LoadPath.

To check whether the value of Remote.LoadPath and other curly brace notated values are actually transforming to the correct value, follow these instructions:

1. Open the ProfileVariableTester.cs and add the following code, add the Addressables namespaces:

using UnityEngine.AddressableAssets.Initialization;

2. In the ProfileVariables class, add the following field:

public List<string> runtimeValues;

3. Locate the ProfileVariables constructor. At the end of its scope, add this line of code:

runtimeValues = new List<string>(count);

4. In the ToString method, locate the following line of code:

message += $"{names[i]} = '{values[i]}' -> '{editorValues[i]}'\n";

Change the above line of code to the following:

message += $"{names[i]} = '{values[i]}' -> '{editorValues[i]}' -> '{runtimeValues[i]}'\n";

5. In the TestProfileVariable method, locate the for loop and add the following line of code at the end its scope:

var runtimeValue = AddressablesRuntimeProperties.EvaluateString(editorValue);
variables.runtimeValues.Add(runtimeValue);

This will make it so that the script processes the string with the additional curly bracket notation. The result is added to the list of runtime values, which are later printed in ToString.

6. From the main menu, select Loady Profiles > Test Profile Variable. The log printed in the Console window now resolves the curly brace notation for Local.LoadPath. This is the same path that the Addressables system will use at startup.

7. Open up your OS file system and find the Loady Dungeons project. Using the runtime value of Local.LoadPath, find the directory. This is where your Addressables content is built for the Editor.

You’ve successfully discovered how to configure the Addressables system to resolve local and remote content paths for different build profiles. In the next tutorials, you will learn how to use profiles with Addressables groups and how to control the shape of build content with groups.