Use case: Manage references between assets

Use the Unity Cloud Assets package to perform the following:

• Query the references of an asset.
• Create or delete references between assets.

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:

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

   Note

   Asset Manager roles define permissions that you have for a single Asset Manager project. Depending on your work, permissions might vary across different projects.

2. Create assets in Unity Cloud in 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 the references of an asset

To list the references of an asset, do the following:

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

public Dictionary<string, List<IAssetReference>> References { get; } = new();

public async Task ListReferencesAsync(AssetId assetId, string version, string id)
{
    References.Remove(id);

    var filter = new AssetReferenceSearchFilter();
    if (!string.IsNullOrEmpty(version))
    {
        filter.AssetVersion.WhereEquals(new AssetVersion(version));
    }

    try
    {
        var references = CurrentProject.QueryAssetReferences(assetId)
            .SelectWhereMatchesFilter(filter)
            .ExecuteAsync(default);

        var referencesList = new List<IAssetReference>();
        References.Add(id, referencesList);
        await foreach (var reference in references)
        {
            referencesList.Add(reference);
        }
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }
}

The code snippet generates the selected asset's reference list.

Add a reference between assets

To add a reference between assets, do the following:

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

public async Task CreateReferenceAsync(IAsset asset, AssetId referencedAssetId, string version, string label)
{
    IAssetReference assetReference = null;

    try
    {
        if (!string.IsNullOrEmpty(version))
        {
            assetReference = await asset.AddReferenceAsync(referencedAssetId, new AssetVersion(version), default);
        }
        else
        {
            assetReference = await asset.AddReferenceAsync(referencedAssetId, label, default);
        }
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }

    if (assetReference != null)
    {
        References["Source"].Add(assetReference);
        References["Target"].Add(assetReference);
        Debug.Log($"Reference created: {assetReference.ReferenceId}");
    }
}

The code snippet creates a new reference between a source asset and a target asset. A message in the console confirms the creation.

Remove a reference between assets

To remove a reference between assets, do the following:

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

public async Task RemoveReferenceAsync(IAsset asset, string referenceId)
{
    try
    {
        await asset.RemoveReferenceAsync(referenceId, default);
        References["Source"].RemoveAll(reference => reference.ReferenceId == referenceId);
        References["Target"].RemoveAll(reference => reference.ReferenceId == referenceId);
    }
    catch (Exception e)
    {
        Debug.LogError(e);
    }
}

The code snippet removes the reference between the source asset and the target asset. A message in the console confirms the deletion.

Add a UI for viewing and creating references

To create a UI for displaying asset references, follow these steps:

1. In the Project window of the Unity Editor, go to Assets > Scripts.
2. Select and hold the Assets/Scripts folder.
3. Go to Create > C# Script.
4. Name your script UseCaseManageAssetReferencesExampleUI.
5. Open the file and replace its contents with the following code sample:

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

public class UseCaseManageAssetReferencesExampleUI : IAssetManagementUI
{
    readonly AssetManagementBehaviour m_Behaviour;

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

    public void OnGUI() { }
}

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

enum SelectionMode
{
    Source,
    Target,
}

IAsset m_SelectedAsset;

SelectionMode m_SelectionMode;
Vector2 m_SourceScrollPosition;
Vector2 m_TargetScrollPosition;

IAsset m_SourceAsset;
string m_SourceVersion;

IAsset m_TargetAsset;
string m_TargetVersion;
string m_TargetLabel;

public void OnGUI()
{
    if (!m_Behaviour.IsProjectSelected)
    {
        m_SelectedAsset = null;
        m_SourceAsset = null;
        m_TargetAsset = null;
        return;
    }

    if (m_SelectedAsset != m_Behaviour.CurrentAsset)
    {
        m_SelectedAsset = m_Behaviour.CurrentAsset;

        OnCurrentAssetChanged();
    }

    GUILayout.BeginVertical();

    var selectionMode = (SelectionMode) GUILayout.SelectionGrid((int) m_SelectionMode, new[] {"Source", "Target"}, 2);
    if (m_SelectionMode != selectionMode)
    {
        m_SelectionMode = selectionMode;
        m_Behaviour.CurrentAsset = m_SelectionMode switch
        {
            SelectionMode.Source => m_SourceAsset,
            SelectionMode.Target => m_TargetAsset,
            _ => m_Behaviour.CurrentAsset
        };
    }

    GUI.enabled = m_SourceAsset != null && m_TargetAsset != null;

    if (GUILayout.Button("Create Reference"))
    {
        if (m_SourceAsset != null && m_TargetAsset != null)
        {
            _ = m_Behaviour.CreateReferenceAsync(m_SourceAsset,
                m_TargetAsset.Descriptor.AssetId, m_TargetVersion, m_TargetLabel);
        }
    }

    GUI.enabled = true;

    GUILayout.BeginHorizontal(GUILayout.ExpandWidth(true));

    DisplayAssetReference(m_SourceAsset, ref m_SourceVersion, SelectionMode.Source);
    DisplayAssetReference(m_TargetAsset, ref m_TargetVersion, SelectionMode.Target, DisplayTargetLabelSelection);

    GUILayout.EndHorizontal();

    GUILayout.EndVertical();
}

void DisplayAssetReference(IAsset asset, ref string version, SelectionMode selectionMode, Action labelSelection = null)
{
    if (asset == null)
    {
        GUILayout.Label("No asset selected");
        return;
    }

    if (!m_Behaviour.AssetProperties.TryGetValue(asset.Descriptor.AssetId, out var properties))
    {
        GUILayout.Label("Asset properties not loaded");
        return;
    }

    GUILayout.BeginVertical();

    GUILayout.Label($"{selectionMode} - {properties.Name}");

    GUILayout.Space(5);

    GUILayout.Label("Id: " + asset.Descriptor.AssetId);

    GUILayout.BeginHorizontal();
    GUILayout.Label("Ver.", GUILayout.Width(40));
    version = GUILayout.TextField(version);
    GUILayout.EndHorizontal();

    labelSelection?.Invoke();

    GUILayout.BeginHorizontal();

    if (GUILayout.Button("Refresh Ver.", GUILayout.Width(100)))
    {
        _ = m_Behaviour.ListReferencesAsync(asset.Descriptor.AssetId, version, selectionMode.ToString());
    }

    if (GUILayout.Button("Show All", GUILayout.Width(100)))
    {
        _ = m_Behaviour.ListReferencesAsync(asset.Descriptor.AssetId, string.Empty, selectionMode.ToString());
    }

    GUILayout.EndHorizontal();

    DisplayReferences(selectionMode, asset);

    GUILayout.EndVertical();
}

void DisplayReferences(SelectionMode selectionMode, IAsset asset)
{
    GUILayout.Label("References:");
    if (m_Behaviour.References.TryGetValue(selectionMode.ToString(), out var references))
    {
        switch (selectionMode)
        {
            case SelectionMode.Source:
                m_SourceScrollPosition = GUILayout.BeginScrollView(m_SourceScrollPosition);
                break;
            case SelectionMode.Target:
                m_TargetScrollPosition = GUILayout.BeginScrollView(m_TargetScrollPosition);
                break;
        }

        foreach (var reference in references)
        {
            GUILayout.Space(5);

            GUILayout.BeginHorizontal();
            GUILayout.Label($"Ref. {reference.ReferenceId}");
            if (GUILayout.Button("Remove", GUILayout.Width(80)))
            {
                _ = m_Behaviour.RemoveReferenceAsync(asset, reference.ReferenceId);
            }

            GUILayout.EndHorizontal();

            var isSource = reference.SourceAssetId == asset.Descriptor.AssetId;
            string assetVersion;
            string referencedId;
            string referencedVersion;
            if (isSource)
            {
                assetVersion = reference.SourceAssetVersion.ToString();
                referencedId = reference.TargetAssetId.ToString();
                referencedVersion = reference.TargetLabel ?? reference.TargetAssetVersion.ToString();
            }
            else
            {
                assetVersion = reference.TargetLabel ?? reference.TargetAssetVersion.ToString();
                referencedId = reference.SourceAssetId.ToString();
                referencedVersion = reference.SourceAssetVersion.ToString();
            }

            GUILayout.Label($"    Ver. {assetVersion}");
            GUILayout.Label($"     {(isSource ? "Depends on" : "Referenced by")}");
            GUILayout.Label($"    - id: {referencedId}");
            GUILayout.Label($"    - ver: {referencedVersion}");
        }

        GUILayout.EndScrollView();
    }
    else
    {
        GUILayout.Label("Loading...");
    }
}

void DisplayTargetLabelSelection()
{
    GUILayout.BeginHorizontal();
    GUILayout.Label("Label", GUILayout.Width(40));
    m_TargetLabel = GUILayout.TextField(m_TargetLabel);
    GUILayout.EndHorizontal();
}

void OnCurrentAssetChanged()
{
    switch (m_SelectionMode)
    {
        case SelectionMode.Source:
            if (m_Behaviour.CurrentAsset == null)
            {
                m_SourceAsset = null;
                m_SourceVersion = string.Empty;
            }
            else
            {
                m_SourceAsset = m_Behaviour.CurrentAsset;
                m_SourceVersion = m_SourceAsset.Descriptor.AssetVersion.ToString();
                _ = m_Behaviour.ListReferencesAsync(m_SourceAsset.Descriptor.AssetId, m_SourceVersion, SelectionMode.Source.ToString());
            }

            break;

        case SelectionMode.Target:
            if (m_Behaviour.CurrentAsset == null)
            {
                m_TargetAsset = null;
                m_TargetVersion = string.Empty;
                m_TargetLabel = string.Empty;
            }
            else
            {
                m_TargetAsset = m_Behaviour.CurrentAsset;
                m_TargetVersion = string.IsNullOrEmpty(m_TargetLabel) ? m_TargetAsset.Descriptor.AssetVersion.ToString() : string.Empty;
                _ = m_Behaviour.ListReferencesAsync(m_TargetAsset.Descriptor.AssetId, m_TargetVersion, SelectionMode.Target.ToString());
            }

            break;
    }
}

7. 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 UseCaseManageAssetReferencesExampleUI(m_Behaviour));

The code snippet displays the following UI elements:

• A selection grid to specify which entry to update on asset selection: the Source or Target.
• A list of references for the selected Source asset.
• A list of references for the selected Target asset.
• A UI button next to each reference to remove the reference.
• A UI button to create a reference between the selected Source and Target assets.