Sublayer USD

If references are USD's "import this other file into a prim," sublayers are its "merge these files into one big stack." Every USD stage already has a root layer, and a sublayer is just another layer listed underneath it. All of them compose together into the scene you see - and here's the part that confuses everyone at first: the layers aren't equal. Earlier in the stack wins. A layer higher up overrides anything lower down that disagrees with it.

So why would you want that in a ComfyUI workflow? Two cases. First, the boring-but-common one: you have a base asset in one file and a set of overrides - a different color, a replaced texture path - in another. Sublayer the override on top and the base file never has to change. Second, it's how this pack keeps your graph honest: whenever things get composition-tangled (reference arcs colliding with your local edits), you can break the stack down with Layer Break USD and re-layer cleanly.

How it works

The node does the minimal thing: it appends a path to your root layer's subLayerPaths list. That's genuinely all a sublayer is - an entry in a list on the root layer. The position dropdown is the only real choice:

• prepend - the new layer goes to the front of the list, i.e. strongest: it can override everything already stacked.
• append - it goes on the bottom, weakest: it only fills in what nothing else defines.

It also de-dupes: add the same sublayer twice and it silently removes the old entry first, so you can't accidentally stack the same file on itself.

The inputs

• USD - the stage you're stacking onto.
• sublayer_path - a file path to a .usda/.usd/.usdz. Default is the placeholder path/to/sublayer.usda; this is what you'll set.
• position - prepend or append, default prepend.

Output is the same USD stage with the new layer list, ready to feed the viewer or a Save USD node. Note the paths are stored absolute, and the same "move the file and it breaks" caveat as references applies - keep your sublayered assets in one place.

Install & troubleshooting

Install once for the whole pack: ComfyUI Manager → search "ComfyUI-OpenUSD", or

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

then restart. It pulls in usd-core==26.5, numpy==2.5.0, and trimesh - the usd-core wheel is big, so give the first install a minute.

If a sublayered stage looks "wrong," your first suspect is layer order - prepend vs append changes who wins. And if you genuinely can't untangle which layer is fighting you, that's exactly what Layer Break USD exists for: it freezes everything currently composed into a single base layer so the fight stops.