Add a reference in the Outliner

References are one mechanism that can be used to create a USD set, which is a single complex asset compiled from individual USD assets. References let you load the same layer file multiple times into a single scene in different locations, reusing scene description. This lets you load scene description (ie. a model, asset) from an external location without copying it into the contents of the layer referencing it. In the following example, shot_sets.usd is referencing the file book.usd.

Tip: Payloads (a type of referencing that can be loaded/unloaded as you please) persist in memory. For example, i f you unload a payload and save your Maya scene file, when you reopen your Maya scene file, the state of your payload will persist.

Important: Referencing is not instancing. Marking a prim as instanceable simply indicates that it can be instanced. USD decides if it is instanced or not as your scene is composed.

Note: References are not given a type. In USD, references are typically a type-less def, which contains no information. This is useful when you reference a prim from another file, because a type-less def can easily take on a prim's type without interference.

Important: If you create multiple USD stages from the same USD file, only one of those files will be brought into your Maya scene. This is due to the fact that if two Maya proxyShape nodes share the exact same stage, it will not be brought in twice.

Add a USD reference to a prim in the Outliner

Right-click the prim you want to add a reference to.
Select Add Reference.
In the Add Reference to USD Prim file dialog that appears, select your reference file.

Important: The reference appears in the Viewport, but it does not appear in the Outliner. When the layer that contains the prim is printed, the reference is added to the prim.

Tip: Select Clear All References to remove the references from the Viewport.
The prim you added the reference to receives an arc badge to indicate the newly attained composition arc. See USD Arc badges in the Outliner.

Add a Maya reference to a prim in the Outliner

Add a Maya reference to a USD prim to enable working with original Maya data in your USD scene. Select a Maya scene file to add as a reference. Using the Outliner contextual menu, you can add a Maya reference prim, which holds a Maya reference file that you can create and build out the scope of. Once a Maya reference file is added, a Maya transform node will appear in the Outliner at your selected prim, containing your newly added Maya reference. Use the dialog to build out the scope of your Maya reference.

Do one of the following:
- Select a prim in the Outliner > right-click > Choose Add a Maya Reference... (located under Edit as Maya Data and Duplicate as Maya Data options)
- Select a stage/proxyShape node in the Outliner > right-click > Add New Prim > Add a Maya Reference...
The Add Maya Reference to USD Menu appears with the following Maya reference options once you select a Maya scene file:
- Maya Reference Prim Name: MayaReference1 (or iterated if not the first reference). You can edit this prepopulated field name to your choosing. Ensure that the reference prim name is unique.
- Group: If enabled, your Maya reference will be grouped under a new prim, under your currently selected USD prim for the Maya reference.
  - Prim Name: This is the prim name that your new Maya reference will be grouped under. Ensure that the group prim name is unique.
  - Prim Type: Choose from this dropdown to select the type of prim for your grouping under, between Xform (transform node) or Scope prim types.
  - Prim Kind: Choose from this dropdown to select the kind classification for your prim. See the kind hierarchy to learn more about selection by kind. Choose from (empty), group (default), assembly, component or subcomponent.
- Define in Variant: Select this checkbox to define the Maya Reference in a USD variant. This will enable your prim to have 2 variants you can switch between in the Outliner; the Maya reference and its USD cache. Tip: Enable this setting so you can switch between the Maya reference and its USD cache in the Outliner. In this option, choose the name for your variant set and variant as needed.
- Edit as Maya Data: Select this checkbox to enable editing the MayaReference prim as a Maya Reference. By default, this is enabled so your prim is pulled upon creation.
The following occurs:
- There is a new Maya node at the top of the reference. Underneath this node is all its children, also with the typical maya reference badge icon. These data nodes are all Maya data so Outliner branch lines are colored to reflect Maya daya (grey).
- The Maya reference node when pulled to USD will be named as per your MayaNamespace + RN.
- The Maya Reference in the USD hierarchy is editable, but locked.

Important: if you are unable to view your Maya reference node in the Outliner, ensure that you have Reference Nodes enabled in the Display menu of the Outliner to view that Maya reference nodes.

Editing a Maya reference prim when pulled (Edit as Maya data)

Once your reference prim is pulled for editing as Maya data, a Maya transform node will appear in the Outliner at your selected prim, containing your newly added Maya reference. This prim has a single attribute of only being transformable, all other attributes are locked.

Once you are done editing, you will have only the following two options to proceed:

Cancel Editing as Maya Data: This will revert your Maya reference from being in Edit as Maya mode back into a Maya reference prim, a USD object. This workflow is the equivalent of unloading a Maya reference prim.
Cache to USD: This workflow enables you to work with Maya data in USD scenes and then export them to a USD cache and author it back into your current USD hierarchy.

Tip: Adding a Maya reference supports undo and redo.

Cache a Maya reference into USD

After you finish animating a Maya reference in your USD hierarchy, you can cache this Maya reference to a file on disk (export) and even back into your existing USD hierarchy as USD data. This can happen through a 'Cache to USD' dialog where you have options for the file on disk, and how to author this file on disc back to your USD hierarchy. When you cache to USD, the cache file saved to disk also writes a default prim to the file. This results in a file on disk that you can reference/ payload in.

When a Maya reference node is pulled, on the root node of the hierarchy in USD, select the Cache to USD... option.
Select the location on disk for your output file for export.
Use the Cache to USD dialog to build your scope:
- Cache Options
  - Edit your preferences as per the regular export options in this section. Choose settings for Output, Geometry, Materials, Animation and Advanced settings.
- Author Cache File to USD Hierarchy
  - As USD Reference: Choose the type of USD Reference composition arc for your Maya Reference:
    
    Payloads are a type of reference. They are recorded, but not traversed in the scene hierarchy. Select this arc if your goal is to manually construct a “working set” that is a subset of an entire scene, in which only parts of the scene are required/loaded. Note: payloads are weaker than direct references in any given LayerStack.
    
    References are general and can be used to compose smaller units of scene description into larger aggregates, building up a namespace that includes the “encapsulated” result of composing the scene description targeted by a reference. Select this arc if your goal is not to unload your references.
  - Define in: Select what to define your Maya reference in. In either option, you can build out the name of your USD reference.
    - Variant: (if available) If selected, your Maya reference will be defined in a variant. This will enable your prim to have 2 variants you can switch between in the Outliner; the Maya reference and its USD cache.
      
      If defined in a variant, the variant will be the parent of the Maya reference, edits will be authored to your target layer and the reference composition arc (payload or general reference) will be inside your variant. Note: The maya reference node and the new usdEditAsMaya set remains in the Outliner.
      
      Important: When the cache is behind a variant, it is considered orphaned.
    - New Child Prim: If selected, your Maya reference will be defined in a new child prim. This will enable you to work with your Maya reference and its USD cache side-by-side.
      
      When defined in a new child prim, it will be a sibling to the root node of the Maya reference, all edits will be on the targeted layer and the reference composition arc (payload or general reference) will be on the child prim. Note: The maya reference node and the new usdEditAsMaya set remains in the Outliner.
      
      Important: If there are multiple roots in the Maya Reference that is cached, only the first root will be specified as the defaultPrim in the exported file. This means the exported file will have all the roots but only the default prim will be displayed in the the prim consuming the payload/general reference.
    Important: When you cache a pulled Maya reference to USD, the Export File dialog appears with options for caching. These options you select will persist in Maya memory from the last time you cached and even your last Maya session. Ensure you check these setttings each time as your selections will be saved in Maya.

Maya reference limitations

Important:

When a USD object is in a pulled state, a mixed-data model will be active, where the pulled object will be Maya data, yet still inside of the proxyShape node or prim. When in this state, current limitations bar selection, hierarchy and other general expected behavious. For example, if you select the USD parent node of a pulled object, the Maya data nested inside will not be a part of that selection, which will not allow operations such as hiding objects etc.

Related Concepts: For more information, see references in the Pixar USD Glossary.