Add a reference using a specific variant

I have an asmb similar to this

def Xform "test" (
    references = @VERY_HEAVY_FILE.usd@
    variantSets = "lod"
    variantSet "lod" = {
        "bbox" {
            def Cube "geo" {
                # Here I have defined some attrs for the cube
        "hi" {

I’m trying to add the asmb above as a reference to a prim in my stage using Unreal but it fails for reasons that we are investigating yet…
If I add it with no payloads it takes around 10 minutes to load.
What I’m trying to do now if to load it using the variant name “bbox” but it crashes also because it’s loading the variant “hi” (the “hi” is our default for the variantset “lod”) and later changing to “bbox”.
I wanted to use
But I read in the docs that you cannot use a variant when adding a reference.

So my question is, is there a way I can add a reference choosing the variant selection so no references are read?


Yes! You can add a reference (or any other arc, or opinion) to the currently selected variant of any VariantSet, using the UsdVariantSet::GetVariantEditContext() to construct a UsdEditContext that will target the Variant on your stage. @BigRoyNL has posted a number of nice examples involving variant editing here, recently!

I believe the question asked here is slightly different. The question being:

Can a reference target a specific prim path with a variant selection? Like target prim path: /test{lod=bbox} (overriding whatever is the default prim)

At least that’s how I’m interpreting this:

But I read in the docs that you cannot use a variant when adding a reference.

I think the intended example was:

reference = Sdf.Reference(
    # Can we target a prim path with variant selection

Basically he’s trying to avoid having Unreal load the heavy file even before he’s able of setting the Prim’s variant selection to bbox to avoid the hi variant even getting loaded. @magost is that correct?

Have you considered instead of referencing the file to add the file as a sublayer and adding a sublayer above it that just overrides the variant selection so that Unreal maybe picks up that variant selection when composing that Usd Stage? (Note that I have no knowledge on what or what not Unreal USD loading might defer or not).

Basically you want to make Unreal compose the stage with the variant selected before unreal loads it (or composes the stage), right?

Ah, sorry I misread that! THe way we’d typically deal with this is by not defining the content “inline” in a Variant, but instead inside another “over” prim somewhere (root level, or inside some organizational “folder” like </lodVariants>), and then the Variant simply makes a reference to that prim (which can be authored as per my earlier, misinformed message). Since it’s in a “simple” prim now, other scene description is free to reference it.

Yes, what I was planning to do is to add a reference with a variant selection in an existing prim.
We were able to manage this by (in the prim where we want to add the reference) creating the variant set and selecting the desired name that we want first. Once the variant selection is set, we add the reference. What is happening is that USD, or at least this is what happens in UE, is loading that variant selection by default (instead of the fallback value that we have defined). This allow us to reduce the loading times.

@spiff if we follow the suggestion in your last reply, shouldn’t we face the same issue that we have now?
Our fallback value for the variant set “lod” is “hi”. If we have the variant name “hi” referencing the prim “</lodVariants/hi>”, where we are referencing our huge asmb, once we load the asmb the whole geometry will be loaded making our loading time the same as if we were referencing it inline within the variant.
Maybe I did not understood right?

Many thanks!

Hi Manuel,
If you have tucked the “heavy reference” inside the “hi” variant (which it sounded from your last post that you were trying?), then you should be able to force the “bbox” variant selection before adding the reference to your asmb, in the stage’s Session layer, such that it is “ephemeral”. I’m not sure if UE gives you that access, but if you can use Sdf.PrimSpec.variantSelections on the layer directly, and I think. the UsdVariantSet API should work here, too…