USD Asset Resolver

Asset Resolver Settings

To access the USD Asset Resolver Settings dialog, go to Windows > Settings/Preferences > Preferences > USD, then under Asset Resolver, click USD Asset Resolver Settings.

This dialog lets you manage how USD resolves asset paths in Maya. It defines where and how the resolver searches for assets, including project tokens, user-defined paths, and environment variables.

Note:

Asset Resolver is currently not available on MacOS.

Include Maya Project Tokens: Enable this option to let the USD Asset Resolver use the directories defined in Maya’s project window as search tokens. When on, your current Maya project folders automatically become tokenized search locations.
Mapping File: Specifies a mapping file that contains data used by the resolver, such as search paths and tokens. Use the Browse button to navigate and select the file. You can also create custom mapping files to match your specific environment setup.

Example of a USD mapping file:

   #usda 1.0
   (
        customLayerData = {
            string[] searchPaths = ["E:/Assets/Kitbash3d/Source"]
            string[] tokenMappingPairs = ["assets", "E:/Assets/Kitbash3d/Source/library/assets"]
            string[] pathMappingPairs = ["assetA/assetA.usd", "assetA/assetA_v002.usd"]
            string[] regexMappingPairs= ["\b[a-z]{4}\b", "path"]
        }
   )

Note:

Use searchPaths and tokenMappingPairs for standard workflows. The other methods (pathMappingPairs and regexMappingPairs) are experimental.

User Paths: Define your own custom search paths for the Asset Resolver.

Double-click a row to edit a path.
Hover over a row to display Browse and Delete buttons.

Add: Click the + button to add a new blank row where you can enter a custom search path.
Add via Browse: Opens a file browser to select a directory and add it to the list. If multiple paths are selected, the Browse button is disabled.
Move Up/Move Down: Reorder user-defined paths to control their search priority relative to extension and environment variable paths.

Important:

The order of search paths affects performance. Place paths that are used most often at the top of the list for faster resolution. Avoid using broad or root-level paths (for example, C:), as they can significantly slow down searches.

User Paths Only: Enable this option to restrict the Asset Resolver to search only within user-defined paths. When on, paths from extensions and environment variables are ignored.
Extensions & Environment Variables Paths: Lists paths added automatically through mapping file or environment variables. These entries are read-only and cannot be reordered, but you can copy them for reference. The Asset Resolver automatically gathers search paths from the following environment variables:
- ADSK_AR_SEARCH_PATH
- PXR_AR_DEFAULT_SEARCH_PATH
- ADSK_AR_MAPPING_FILE
  
  ADSK_AR_SEARCH_PATH and PXR_AR_DEFAULT_SEARCH_PATH define search paths used to resolve relative asset references. ADSK_AR_MAPPING_FILE points to a system-wide default mapping file that can include both tokens and search paths. On Windows, these variables use semicolon-separated path strings. These variables use semicolon-separated path strings on Windows and colon-separated strings on Linux.

Note:

Changes made in the Asset Resolver Settings do not affect USD stages already loaded in the current scene. To apply the updated settings, start a new scene or session.

How tokens and environment variables work in Asset Resolver

The Asset Resolver supports tokens and environment variables to make asset paths more flexible and portable across systems. For example, if an asset is referenced as:

 <assets>/trees/tree1.usda

and the mapping file defines a token called assets that points to the correct folder location, the resolver automatically finds the referenced file.

Similarly, environment variables can also be used in USD paths. If an environment variable named assets exists (defined either in your operating system or in the DCC session), the resolver can locate the file when the path is written as:

 {assets}/trees/tree1.usda
 ${assets}/trees/tree1.usda
 %assets%/trees/tree1.usda

Note:

The USD Exporter currently does not export assets with tokenized or environment variable paths. To author this kind of assets, you need to build custom tooling, such as custom scripts, prim writers, or chasers.

Using tokens, search paths, and environment variables directly in USD files

When authoring USD files, you can reference assets using tokens, search paths and environment variables recognized by the Asset Resolver.

Token example

subLayers = [
    @<library_>/file.usda@
]

In this example, <library_> represents a predefined token that resolves to a specific folder when the USD file is loaded.

Search path example

subLayers = [
    @folder/file.usda@
]

In this example, the Asset Resolver uses search paths to resolve the full path of the relative path folder/file.usda. These search paths can come from:

A mapping file.
User defined paths.
Either of the following two environment variables:
- ADSK_AR_SEARCH_PATH
- PXR_AR_DEFAULT_SEARCH_PATH

The Asset Resolver checks each search path in the order shown in the Asset Resolver Settings dialog, and stops at the first match. For instance, if the search paths are:

  C:/assets1/
  C:/assets2/

The Asset Resolver tries:

  C:/assets1/folder/file.usda

If not found, then it tries

  C:/assets2/folder/file.usda

Environment variable example

subLayers = [
    @$cyber_district/file.usda@
]

In this example, $cyber_district represents an environment variable whose value is used by the Asset Resolver to resolve the path.

Note:

On Windows, environment variables are not case-sensitive, while on other operating systems they are case-sensitive. Tokens are case-sensitive on all operating systems.