anchored-asset-paths#

Code

AA.001

Validator

latest+

Compatibility

core usd

Tags

🔑

Summary#

Asset references should use anchored paths

Description#

For reproducible results, asset references should use anchored paths (paths that begin with “./” or “../”) rather than absolute paths or search paths. Paths containing ../ should also be encapsulated and avoid to target locations above the asset root.

Why is it required?#

  • Ensures assets resolve consistently across different environments

  • Prevents dependency on environment-specific search paths

  • Makes assets self-contained and portable

Examples#

# Valid: Using anchored paths
def Material "MyMaterial"
{
    def Shader "diffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @./textures/diffuse.png@  # Anchored path
        token outputs:rgb
    }
}

# Invalid: Using search path
def Material "MyMaterial"
{
    def Shader "diffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @textures/diffuse.png@  # Search path
        token outputs:rgb
    }
}

# Invalid: Using absolute path
def Material "MyMaterial"
{
    def Shader "diffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @/projects/assets/textures/diffuse.png@  # Absolute path
        token outputs:rgb
    }
}


# Invalid: Using asset root path that targets a location above the asset root
# root.usda

def Material "MyMaterial"
{
    def Shader "diffuseTexture"
    {
        uniform token info:id = "UsdUVTexture"
        asset inputs:file = @../another/asset/textures/diffuse.png@  # Targets a location above the asset root
        token outputs:rgb
    }
}

How to comply#

  • Use anchored paths (starting with “./” or “../”) for all asset references

  • Encapsulate paths containing ../ to avoid targeting locations above the asset root

  • Organize assets in a relative directory structure

  • Avoid absolute paths or search paths that depend on resolver configuration

  • In Omniverse, use the “collect extension” to localize assets

  • In Omniverse, avoid using path-less material references such as OmniPBR or OmniGlass that rely on Omniverse’s default material search paths

For More Information#