USD Toolkit › Composition arcs explained

USD composition arcs: sublayers, references & payloads

Guide · Updated 6 July 2026

The single most powerful - and most confusing - idea in OpenUSD is composition: a final stage is assembled from many layers and external files, combined by a handful of composition arcs. If you have ever opened a .usda and wondered how subLayers, references and payload differ, this is the map. These are exactly the arcs a dependency inspector follows to find every asset a layer needs.

subLayers - stacking whole layers

A layer's subLayers list pulls in other entire layers beneath it, like a stack of transparencies. Opinions in the layers listed higher win over those lower down. This is how a shot layer sits on top of a sequence layer, which sits on top of a show-wide base - each contributing and overriding as needed. subLayers compose the layer's whole namespace, not a single prim.

references - bringing a prim in

A references arc pulls the prims from another layer onto a specific prim in your stage, optionally re-rooting them. This is how you place an asset: reference @assets/tree.usd@ onto a prim called tree_01, again onto tree_02, and you have two instances that both track the source. References are the workhorse of set assembly.

payloads - references you can defer

A payload is a special kind of reference that USD can unload. Heavy assets - a fully-modelled hero character, a dense set - are brought in behind payloads so a big stage opens quickly with them deferred, and an artist loads only the pieces they need. Functionally a payload composes like a reference; the difference is that it is load-controlled.

Reference vs payload: both graft another layer's prims onto a target prim. A reference is always composed; a payload can be left unloaded for speed. Use payloads for the heavy things.

inherits, specializes & variants

Two more arcs shape opinions rather than pull files. inherits lets many prims share a common "class" so a change in one place propagates to all of them (think of a shared look). specializes is similar but composes at the weakest strength, so it provides fallback opinions that anything else can override. variantSets package alternatives - a model variant, an LOD, a shading option - that you switch between by selecting a variant. They don't usually add external files, but they change what the composed stage looks like.

value clips - animation across files

For long or heavy animation, clips (value clips) let a prim read its per-frame values from a sequence of external files rather than baking everything into one layer. An inspector treats each clip asset as another dependency to collect.

Reading the arcs in a layer

You don't have to trace this by hand. Open a .usda in USD Toolkit and it lists every external asset path grouped by the arc it arrived on - subLayer, reference, payload, clip and asset attributes - flags each as portable (relative) or absolute, and builds a collect-files list of everything the layer needs. That is exactly what you want before moving a layer between machines or handing it to another studio, where an absolute path like /mnt/local/tex.exr would break.

Resolve a .usda now Explore Houdini Studio Hub →