Add USD Reference / Payload

References are the heart of how USD composes a scene. Instead of copying geometry into your file, a reference says "at this prim, pull in everything from that other .usda/.usd/.usdz." That one idea is why USD files stay small and why a studio can have ten artists editing ten different files that all show up in one shot. This node is how you do that from the ComfyUI canvas without ever opening a USD tool or a DCC.

You'll reach for it the moment your workflow isn't a single generated mesh anymore - you have a character in one file, a room in another, props scattered across a few more, and you want them composed into one stage that renders together. It's the node that turns the pack from "I made a cube" into "I assembled an asset library."

How it works

Under the hood it does exactly one USD API call: GetReferences().AddReference(assetPath, primPath) on the prim you point at - or the payload variant, GetPayloads().AddPayload(...). The only real difference between the two is laziness: a payload is a reference that doesn't actually load its content until the stage is explicitly told to (stage.Load()), which keeps big scenes snappy. A reference loads eagerly. For most of what you do in ComfyUI, reference is fine.

The node also does a trick worth knowing: prim_path accepts wildcards (* and ?), so you can add the same reference to every matching prim in the stage in one pass instead of one node per prim.

The inputs that matter

• USD - your stage, usually straight out of Create USD Stage or Load USD.
• prim_path - where the reference lands (default /Root/Mesh). If the prim doesn't exist, the node creates it as an Xform.
• arc_type - reference or payload. Start with reference.
• file_path - the .usd/.usda/.usdz you're pulling in. This is the whole point, so it's the one you'll actually edit.
• target_prim_mode - Use default prim (grabs whatever the source file declares as its default prim) or specify prim, which unlocks referenced_prim_path so you can pull a specific prim out of a file that has several.

It returns a USD stage with the arc stamped on it - wire it onward to another composition node, a material, or straight into USD Viewer to see the result.

Install & gotchas

Every node in ComfyUI-OpenUSD installs the same way: ComfyUI Manager → search "ComfyUI-OpenUSD", or

cd ComfyUI/custom_nodes
git clone https://github.com/cjhosken/ComfyUI-OpenUSD

then restart. The pack pins usd-core==26.5 (Pixar's Python bindings - a chunky wheel) plus numpy==2.5.0 and trimesh, so the first install downloads a fair bit. The README also mentions usd2gltf, but the shipped code never imports it - don't go hunting for that wheel.

Where people get burned: this node stamps an absolute path to your reference file. Move the file and the reference silently breaks (the stage just won't show that geometry). Keep referenced assets in one folder, and use the pack's Save USD node with its make_paths_relative option if you're shipping a stage anywhere. And remember the "USD" socket is this pack's own type - it only plugs into other OpenUSD nodes, not into core ComfyUI's 3D MESH sockets.