UsdPayloadSet

The UsdPayloadSet node adds payloads to a scene. A payload is a special type of reference that can be optionally loaded or kept unloaded, providing a mechanism to defer the loading of certain, often resource intensive, parts of a scene until they are required. This allows for more efficient scene management and faster initial load times.

Unlike standard references that are loaded automatically when a scene is opened, payloads provide flexibility by letting users choose when to load them through the Payload working set. This is useful for large scenes where only a subset of the content might be needed immediately. Payloads which aren’t loaded are still visible in renders (same principle as deferred loading).

To improve efficiency, Katana uses a deferred loading mechanism, for all data including USD. In the Katana Scene Graph tab, locations are only loaded and evaluated as you expand the graph. The same behavior has been introduced to the Scene Explorer tab and is used for both the USD Scene Graph and the Katana Scene Graph. However, if you need more control over this loading behavior with USD, you can use the Payload Working Set and Visibility Working Set. These give you full control over loading behaviour, or when locations are loaded.

Payloads are typically used for elements like background sets, props, or secondary characters that might not be needed immediately during scene setup or initial playbacks.

By using payloads, artists and TDs can more effectively manage and navigate complex scenes, ensuring resources are used efficiently and only loading heavy or less-critical data when it's genuinely needed.

Inputs

Connection Type

Connection Name

Function
Input in The incoming scene graph data that the node will operate on or modify.

Controls

Control (UI)

Default Value

Function
primPaths N/A Specify locations where payloads are applied. They are generated at each specified path, in the order in which the paths are listed.
asset N/A Loads in the attached file as a payload. This gets converted to the "asset/path.usda" section of a full payload path: @asset/path.usda@</prim/path>
assetPrimPath N/A The path to the prim that is to be used as a payload, located inside the asset file. Or if no file is added, a prim path to a prim in the current stage can be used. This gets converted to the "prim/path" section of a full payload path: @asset/path.usda@</prim/path>
listPosition prepend

Specifies how the payloads are added to the scene. Options are:

  • append - adds new payloads by placing them at the end of the list. This ensures that they are evaluated after existing values, giving them the potential to override preceding definitions.

  • prepend - adds new payloads to the front of the list, causing them to be evaluated before, and potentially overridden by values added later or in subsequent layers.

  • delete - removes the payloads from the list, preventing their properties from influencing the composed prim in the scene.

  • reset to explicit - clears any existing payloads on the prim and sets the payload list to be only the ones you're adding. It essentially instructs the USD scene to ignore any payloads on the prim(s) and only use the new ones.

For more information, refer to the USD Glossary under List Editing.