Use case: Manage the versions of an asset

Use the Unity Cloud Assets package to perform the following:

Search the versions of an asset.
Freeze a version.
Create an editable version from a frozen version.

Note

To manage assets, you need the Asset Manager Admin role at the organization level or the Asset Manager Contributor add-on role at the project level. Asset Manager Contributors can manage assets only for the specific projects to which they have access.

Before you start

Before you start, do the following:

Verify you have the required permissions. Read more about verifying permissions.

Note

Asset Manager roles define the permissions that you have for a single Asset Manager project. Depending on your work, permissions may vary across projects.
Set up a Unity scene in the Unity Editor with an Organization and Project browser. Read more about setting up a Unity scene.
Create assets in Unity Cloud any of the following ways:
- Add assets using the Asset SDK.
- Add a single asset or multiple assets through the dashboard.

How do I...?

List an asset's versions

To list an asset's versions, follow these steps:

Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
Add the following code to the end of the class:


public Dictionary<AssetVersion, AssetProperties> VersionProperties { get; } = new();

public AssetVersion? CurrentVersion => CurrentAsset?.Descriptor.AssetVersion;

VersionQueryBuilder m_CurrentQuery;

public async Task SetCurrentAsset(AssetVersion assetVersion)
{
    if (CurrentAsset != null)
    {
        CurrentAsset = await CurrentAsset.WithVersionAsync(assetVersion, CancellationToken.None);
        Debug.Log($"Current asset set to version: {CurrentAsset.Descriptor.AssetVersion}");
    }
}

public async Task SearchVersions(string sortingField, SortingOrder sortingOrder)
{
    m_CurrentQuery = CurrentProject.QueryAssetVersions(CurrentAsset.Descriptor.AssetId)
        .OrderBy(sortingField, sortingOrder);

    await PopulateVersions(m_CurrentQuery);
}

async Task PopulateVersions(VersionQueryBuilder query)
{
    if (query == null) return;

    var results = query.ExecuteAsync(CancellationToken.None);

    var currentVersion = CurrentVersion;

    VersionProperties.Clear();
    await foreach (var asset in results)
    {
        var properties = await asset.GetPropertiesAsync(CancellationToken.None);
        VersionProperties.Add(asset.Descriptor.AssetVersion, properties);

        if (currentVersion.HasValue && asset.Descriptor.AssetVersion == currentVersion.Value)
        {
            CurrentAsset = asset;
        }
    }
}

The code snippet does the following:

Creates a query to search the versions of an asset.
Fills a list of versions.

Freeze a version

To freeze the editable version of an asset, follow these steps:

Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
Add the following code to the end of the class:


public async Task FreezeVersion(AssetVersion assetVersion)
{
    var asset = await CurrentAsset.WithVersionAsync(assetVersion, CancellationToken.None);

    await asset.FreezeAsync(new AssetFreeze
    {
        ChangeLog = "Use case coding example submission.",
        Operation = AssetFreezeOperation.CancelTransformations
    }, CancellationToken.None);
    await asset.RefreshAsync(CancellationToken.None);

    var properties = await asset.GetPropertiesAsync(CancellationToken.None);
    Debug.Log($"Version frozen with sequence number: {properties.FrozenSequenceNumber}");

    await PopulateVersions(m_CurrentQuery);
}

The code snippet does the following:

Freezes the specific asset.
Refreshes each listed version.
Displays a success message in the console.

Create a new version

To create a new version of an asset, follow these steps:

Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
Add the following code to the end of the class:


public async Task CreateVersion(AssetVersion assetVersion)
{
    var version = await CurrentAsset.WithVersionAsync(assetVersion, CancellationToken.None);
    var asset = await version.CreateUnfrozenVersionAsync(CancellationToken.None);
    await PopulateVersions(m_CurrentQuery);

    Debug.Log($"New version created with version: {asset.Descriptor.AssetVersion}");
}

The code snippet does the following:

Creates a new version of the asset from the specific frozen version.
Refreshes the current list of versions for the asset.
Displays a success message in the console.

Delete an unfrozen version

To delete an unfrozen version of an asset, follow these steps:

Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
Add the following code to the end of the class:


public async Task DeleteVersion(AssetVersion assetVersion)
{
    await CurrentProject.DeleteUnfrozenAssetVersionAsync(CurrentAsset.Descriptor.AssetId, assetVersion, CancellationToken.None);
    await PopulateVersions(m_CurrentQuery);

    Debug.Log($"Asset version {assetVersion} has been deleted.");
}

The code snippet does the following:

Deletes the specific unfrozen version of the asset.
Refreshes the current list of versions for the asset.
Displays a success message in the console.

Add a UI for managing versions

To create a UI for managing the versions of an asset, follow these steps:

In your Unity Project window, go to Assets > Scripts.
Select and hold the Assets/Scripts folder.
Go to Create > C# Script.
Name your script UseCaseVersionSearchExampleUI.
Open the UseCaseVersionSearchExampleUI script you created in the previous step and replace the contents of the file with the following code sample:


using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Unity.Cloud.Assets;
using Unity.Cloud.Common;
using UnityEngine;

public class UseCaseVersionSearchExampleUI : IAssetManagementUI
{
    readonly AssetManagementBehaviour m_Behaviour;

    public UseCaseVersionSearchExampleUI(AssetManagementBehaviour behaviour)
    {
        m_Behaviour = behaviour;
    }

    public void OnGUI() { }
}

In the same script, replace the OnGUI function with the following code:


string m_SortingField = "versionNumber";
SortingOrder m_SortingOrder = SortingOrder.Descending;
AssetId m_CurrentAssetId;

public void OnGUI()
{
    if (m_Behaviour.CurrentAsset == null) return;

    if (m_Behaviour.CurrentAsset.Descriptor.AssetId != m_CurrentAssetId)
    {
        m_CurrentAssetId = m_Behaviour.CurrentAsset.Descriptor.AssetId;
        SearchAssetVersions();
    }

    GUILayout.Space(15f);

    GUILayout.BeginVertical();

    GUILayout.Label("Sorting Field:");
    m_SortingField = GUILayout.TextField(m_SortingField);

    GUILayout.Label("Sorting Order:");
    m_SortingOrder = (SortingOrder) GUILayout.SelectionGrid((int) m_SortingOrder, new[] {"Ascending", "Descending"}, 2);

    if (GUILayout.Button("Search"))
    {
        SearchAssetVersions();
    }

    GUILayout.Space(15f);

    GUILayout.Label("Versions: ");

    if (m_Behaviour.VersionProperties.Count == 0)
    {
        GUILayout.Label("Loading...");
    }
    else
    {
        foreach (var kvp in m_Behaviour.VersionProperties)
        {
            DisplayVersion(kvp.Key, kvp.Value);
        }
    }

    GUILayout.EndVertical();

    DisplayCurrentVersion();
}

void SearchAssetVersions()
{
    if (string.IsNullOrEmpty(m_SortingField)) return;

    _ = m_Behaviour.SearchVersions(m_SortingField, m_SortingOrder);
}

void DisplayVersion(AssetVersion version, AssetProperties properties)
{
    var versionStr = properties.State switch
    {
        AssetState.Frozen => $"Ver. {properties.FrozenSequenceNumber}",
        AssetState.Unfrozen => $"WIP from Ver. {properties.ParentFrozenSequenceNumber}",
        AssetState.PendingFreeze => "Pending",
        _ => ""
    };

    var labels = properties.Labels.Select(x => x.LabelName).ToArray();
    if (labels.Length > 0)
    {
        versionStr += $" ({string.Join(", ", labels)})";
    }

    GUILayout.BeginHorizontal();

    GUILayout.Label(versionStr, GUILayout.ExpandWidth(true));

    GUI.enabled = m_Behaviour.CurrentVersion != version;

    if (GUILayout.Button("Select", GUILayout.Width(60)))
    {
        _ = m_Behaviour.SetCurrentAsset(version);
    }

    GUI.enabled = true;

    GUILayout.EndHorizontal();
}

void DisplayCurrentVersion()
{
    if (m_Behaviour.CurrentVersion == null)
    {
        GUILayout.Label("! No version selected. !");
        return;
    }

    var version = m_Behaviour.CurrentVersion.Value;

    if (!m_Behaviour.VersionProperties.TryGetValue(version, out var properties))
    {
        GUILayout.Label("! Version properties not loaded. !");
        return;
    }

    GUILayout.BeginVertical();

    GUILayout.Label($"Version: {version}");
    if (properties.ParentFrozenSequenceNumber > 0)
    {
        GUILayout.Label($"Parent Sequence Number: {properties.ParentFrozenSequenceNumber}");
    }

    GUILayout.Label($"State: {properties.State}");

    if (properties.State == AssetState.Unfrozen)
    {
        GUILayout.BeginHorizontal();
        
        if (GUILayout.Button("Delete version"))
        {
            _ = m_Behaviour.DeleteVersion(version);
        }
        
        if (GUILayout.Button("Freeze version"))
        {
            _ = m_Behaviour.FreezeVersion(version);
        }
        
        GUILayout.EndHorizontal();
    }
    else
    {
        GUILayout.Label($"Frozen Sequence Number: {properties.FrozenSequenceNumber}");

        if (GUILayout.Button("Create new version"))
        {
            _ = m_Behaviour.CreateVersion(version);
        }
    }

    GUILayout.EndVertical();
}

Open the AssetManagementUI script that you created as described in Get started with Asset SDK and replace the contents of the Awake function with the following code:


m_UI.Add(new OrganizationSelectionExampleUI(m_Behaviour));
m_UI.Add(new ProjectSelectionExampleUI(m_Behaviour));
m_UI.Add(new AssetSelectionExampleUI(m_Behaviour));
m_UI.Add(new UseCaseVersionSearchExampleUI(m_Behaviour));

The code snippet does the following:

Provides fields to specify the sorting field and order for the list of versions.
Provides a UI button to refresh the list of versions.
Displays the list of versions with a Select button next to each version.
When you select a version, the UI displays information on this version and provides buttons to freeze, delete, or create a new version based on the frozen state of the selected version.

Going further

Read more about further examples of managing versions.