Configure USD Prim

A mesh's geometry is only half its identity in USD. The other half is a pile of metadata - is the prim active, visible, what is it "for," what kind of thing is it - and that metadata decides whether renderers, viewports, and DCCs actually show it. Configure USD Prim is the node that edits all of that without touching a triangle.

You'll reach for it when a prim exists but won't cooperate. The classic case: you've brought in an asset and a subtree isn't showing up, and it turns out someone set the prim inactive, or its purpose doesn't match what your viewer draws. Or you're assembling a scene and want to mark a group of prims as "proxy only" so they don't load in final renders. It's a finishing-and-debugging node, not a headline act - but it's the one that fixes the weird "why is half my scene missing" moments.

The inputs that matter

• USD and prim_path (default /Root/Mesh) - the target. Missing prims get created as Xforms.
• active - boolean. An inactive prim is removed from the stage entirely at render time: no geometry, no contribution. That's the sledgehammer toggle.
• visibility - inherited, visible, or invisible. Subtler than active: invisible hides just this prim (children can still inherit differently), and inherited means "take whatever the parent says."
• purpose - default, render, proxy, guide. This one catches people out. Renderers and viewports selectively draw purposes: proxy is what viewports typically show as a stand-in, and if you set a mesh's purpose to proxy or guide, the final render may skip it entirely. Leave it default unless you know why you're changing it.
• kind - a free-text string like component, group, or assembly. Purely organizational metadata (model hierarchies); nothing renders differently because of it.
• comment - a multiline note stored as prim metadata. Free documentation that lives inside the file.

Output is the USD stage, modified in place.

How it works

Under the hood it's a tour of USD's metadata APIs: SetActive for the active flag, CreateVisibilityAttr().Set(...) for visibility (only on imageable prims), the purpose attribute on gprims, SetKind for kind, and a comment field written onto the prim's spec in the root layer. Nothing about vertices or transforms changes - this node is 100% about how the stage interprets the prim.

Install & troubleshooting

Pack install, one time: ComfyUI Manager → search "ComfyUI-OpenUSD", or

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

then restart. Deps: usd-core==26.5, numpy==2.5.0, trimesh.

The troubleshooting trap: if you set a prim to invisible or non-default purpose and then can't see it in the viewer, that's the node working as designed, not a bug. Re-check your purpose and visibility values before hunting for geometry bugs. And if a whole subtree vanishes, check active first - inactive is the only one of these knobs that completely removes a prim from the scene.