Add USD Variant

Variants are USD's answer to "one asset, many versions, no duplicated files." A single prim can carry a variant set - a named collection of choices, like "shadingVariant: red / blue / green" or "LOD: high / low" - and you flip between them by changing which variant is selected. Game studios lean on this for LODs and for shipping one asset that has several material passes. This node is how you stamp that structure onto a stage from the graph.

Honestly, for a lot of what ComfyUI users do, variants are optional. If you're generating one mesh and shading it one way, you don't need a variant set at all - Apply USD Material is the node you actually want. Reach for Add USD Variant when you're building a reusable asset pipeline: you want one stage that can produce several versions, or you're handing a stage to a renderer/DCC that will flip the selection itself.

How it works

The mechanism is three short calls on the prim: GetVariantSets().AddVariantSet(name) creates the set, AddVariant(name) drops a choice into it, and SetVariantSelection(name) - only if you leave set_selection on - marks it as the active one. A variant set with no selection just sits there doing nothing, which is a perfectly valid state if you're setting it up for someone else to choose from later.

Like the other composition nodes in this pack, prim_path supports * and ? wildcards, so one node can add the same variant set to a whole subtree of prims. Missing prims get created as Xforms first.

The inputs

• USD - your stage.
• prim_path - where the variant lives (default /Root/Mesh).
• variant_set_name - the set's name, default shadingVariant.
• variant_name - the choice you're adding, default default.
• set_selection - boolean, on by default. Leave it on unless you want to build the set without committing to a pick.

Output: a USD stage with the variant structure stamped on it. Note that this node only creates the structure - the actual content under each variant (the geometry, the material binding that differs per choice) is something you'd wire in with the pack's other nodes or via its Python scripting node, which is where a real variant workflow gets interesting.

Install & gotchas

Same as every node in the pack: ComfyUI Manager → "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 (usd-core is the heavy download).

The trap here is subtle: creating a variant set by hand on a prim that already has content is easy to do in a way that shadows the content - the prim's existing opinions live outside any variant, so once you select a variant that has no opinions, the base content still shows. If your variant "isn't doing anything," check that the variant actually contains opinions (via a Set USD / scripting node) rather than expecting the empty variant to hide the base. And remember: the USD socket only connects to this pack's nodes.