What is the AYON USD Resolver?​

The AYON USD Resolver is a USD plugin that translates AYON Entity URIs into physical filepaths at runtime. This allows USD files to dynamically "point" to specific versions without needing to update the internal paths manually.

Common use cases include:

• Always Latest:

  ayon://AYLab_Demo/assets/chemistry_beaker01?product=usdAsset&version=latest&representation=usd

• Hero Versions:

  ayon://AYLab_Demo/assets/chemistry_beaker01?product=usdAsset&version=hero&representation=usd

This ensures your USD Assets and Shots are always up to date, letting the resolver handle the heavy lifting of path translation.

AYON Entity URI Structure

AYON uses Entity URIs for quick redirection and navigation. While they can point to tasks or folders, OpenUSD is primarily concerned with Representations.

Format:

ayon://{project_name}/{folder_path}?product={product_name}&version={version_number}&representation={representation_name}

• ayon://: The URI Scheme (also supports ayon+entity:).

• project_name: Case-insensitive project name.

• folder_path: Hierarchy path within the project.

• product_name: Name of the published product.

• version_number: Can be an integer (4), a padded string (v004), or a keyword (latest or hero).

• representation_name: The extension or representation (e.g., usd, abc, exr).

Enabling the Resolver

To enable the AYON USD Resolver, configure the following in your OpenUSD Addon Settings:

1. Binary Distribution: Enable this to allow AYON to download the prebuilt binaries automatically.

2. LakeFS Credentials: Set your access keys (contact your Admin or Ynput support to receive these).

3. Application Paths: Map the resolver paths to your specific DCC variant names.

Farm Rendering

Farm Rendering & New Builds

The AYON USD Resolver supports farm rendering. Recent builds for Houdini 21 and Maya 2026 include important bug fixes for initializing the resolver on Deadline farm render jobs.

When the resolver initializes correctly on the farm, you'll see log lines indicating the USD asset resolver is active for the application:

Example
From DL Log
Copy
2026-02-12 17:41:47: 0: STDOUT: >>> [ Initializing USD asset resolver for application: houdini/21 ]

Farm Rendering: Pinning Mode

For farm rendering, the AYON USD Resolver offers a Pinning Mode. This maps an Entity URI to a fixed filepath using a pinning file, bypassing the need to query the AYON server.

Key Benefits:

• Performance: Prevents overwhelming the AYON server. Without pinning, hundreds of farm workers might generate thousands of simultaneous queries; pinning reduces this to zero server communication during the render.

• Stability and Consistency: Pinning "freezes" the Entity URI to a specific physical path. This ensures every farm worker uses the exact same file versions throughout processing the render deadline job.

  This is vital when using "latest" or "hero" version keywords. The pinning file captures what "latest" was at the moment of submission, preventing a new publish from changing the versions mid-render and causing visual inconsistencies.

• Emergency Retargeting: Allows you to redirect a URI to a different version without ever opening or modifying the source USD file.

  Example: If a render fails because v005 is discovered to be broken, you can simply update the pinning file to retarget those URIs to v003. The farm will immediately begin pulling the working version.

Automated Pinning on Farm

By default, pinning mode is activated by enabling the “Generate USD Resolver Pinning file on publish” setting in the AYON USD Addon Settings. When this is active:

• Automatic Generation: Houdini generates a __render___pin.json file during the publish process.

• Job Injection: AYON automatically injects the necessary environment variables (ENABLE_STATIC_GLOBAL_CACHE and PINNING_FILE_PATH) into the Deadline job.

Manual Pinning (Debugging/Testing)

Manual debugging is useful for verifying that the resolver is correctly mapping paths or for testing retargeting. This requires an existing pinning file generated from a previous publish.

To test pinning mode locally on your workstation:

1. Locate the Pinning File:

   • Publish a USD render in Houdini. In the Details tab, find "Extract Skeleton Pinning JSON" to get the path to the __render___pin.json.

   • Alternatively, get the __render___pin.json path from the deadline job you have previously submitted.

2. Initialize Terminal: Select your project/asset context in the AYON Launcher, select Terminal, and Select your Houdini version.

   

3. Enable Pinning Mode in terminal: set the necessary environment variables (ENABLE_STATIC_GLOBAL_CACHE and PINNING_FILE_PATH)

   Example
   Windows
   Copy
   set ENABLE_STATIC_GLOBAL_CACHE=1
   set PINNING_FILE_PATH=H:/AYON/projects/Experiments/random/houdini/work/test_render/usd_renders/Expr_houdini_test_render_v013/renderGenericMain/__render___pin.json

4. Launch: Run houdinifx from that same terminal.

   Example
   Windows
   Copy
   houdinifx

Caching​

The AYON USD Resolver has a local caching mechanism to optimize its performance in daily use. Entity URIs traditionally resolve to static paths, so caching them in your local sessions is the best way to improve performance.

API and Technical References​

• AYON APIs and development resources

• AYON USD Resolver

FAQ

What is the __render___pin.json file next to my USD?

If you see this file next to a __render__.usd, it is a pinning map. It contains a list of every URI used in that file and its resolved path (marked by the ayon_resolver_pinning_data key). This ensures that what you saw in your LOPs viewer is exactly what the farm renders.