Variant Manager Overview

The Variant Manager is a specialized UI panel in the Unreal Editor that you can use to set up multiple different configurations of the Actors in your Level. Each of these configurations is referred to as a Variant. The Variant Manager helps you to:

• Set up these Variants,
• Organize the Variants into categories called Variant Sets,
• Define what Actor properties each Variant should control, or what functions the Variants should invoke, and
• Activate or "switch on" different Variants in the Unreal Editor.

To use the Variant Manager, you must have the Editor > Variant Manager Plugin enabled for your Project.

If you start from a Template in either the Architecture, Engineering, and Construction or Automotive, Manufacturing, and Product Design category, this Plugin may be enabled for you by default.

The Variant Manager Panel

The Variant Manager UI is an editor for a specialized type of Asset called a Level Variant Sets Asset. Every time you double-click a Level Variant Sets Asset, the Variant Manager panel opens up for you to set up and work with the Variants managed by that Asset.

The UI of the Variant Manager is divided into four columns.

1. The Variants column: The panel on the left lists all the Variants and Variant Sets being managed by this Level Variant Sets Asset. For example, the image above shows two Variant Sets: Paint and Brake Caliper. Those Variant Sets contain several Variants: visible in the image are Variants for Blue, Red, Yellow, Black, and Dark Grey paint colors, and a Variant for Red brake calipers.

2. The Actors column: Whenever you have a Variant selected in the leftmost column, the second column (Actors) lists all of the Actors that are bound to that Variant. In the image above, the Paint > Red Variant is selected, so the Actors list includes the Static Mesh Actors for all the painted parts of the motorcycle body.

   When you create a binding between an Actor and a Variant, you create a link between them. When that Variant is activated, that bound Actor will respond in a certain way: either by changing the value of a data property, or by calling a function.

3. The Properties column: When you select one or more bound Actors in the second column, the third column (Properties) shows you what properties of those Actors have been captured in this Variant. In the image above, the Material[0] and Material[1] properties is captured; these materials determine the visible paint color of the surfaces.

   When you capture a property of an Actor, it means that you store a desired value for that property in the Variant.

4. The Values column: Finally, the rightmost column (Values) shows the value saved in the Variant for each property visible in the Properties column. In this case, when the Red Variant is switched on, the Variant Manager sets the Material[0] property of its bound Actors to a red car paint Material.

Setting Up Variants

The overall workflow for setting up scene variants typically follows the columns described above from left to right.

1. You decide on what Variants you'll need in your scene, and how to categorize your Variants into Variant Sets. Based on those decisions, you use the controls offered by the left-hand column to set up the Variant Manager with these same Variant Sets and Variants.

   With the controls in this panel—most of which you access by right-clicking and choosing options from the context menu—you can add new Variant Sets and Variants, move Variants from one Variant Set to another, rename Variants and Variant Sets, assign thumbnails to Variants, and delete Variants and Variant Sets that you don't need anymore.

2. For each of the Variants you created above, you bind one or more Actors.

   You can bind new Actors to a Variant by dragging them from the World Outliner panel on to the list of bound Actors, or on to the Variant in the left-hand column. You can also bind and unbind Actors by right-clicking the list in the Actors panel and using the context menu.

3. For each bound Actor, you choose which properties you want the Variant Manager to change.

   Every time you bind a new Actor, the Variant Manager automatically opens a window that invites you to choose which properties you want to capture. For example:

   

   You can capture any property that is exposed to Blueprints. If the Actor you've bound is a Blueprint Actor, this includes any Variables that you've created in the class and that you've marked as Instance Editable.

   You can also right-click a bound Actor at any time to capture additional properties, or right-click a captured property to remove it from the list.

   You can also set up the Variant Manager to call functions exposed by the bound Actor when the Variant is activated. For details on this, see Calling Functions on Variant Activation.

4. For each property, you set the value that you want the Variant Manager to apply when the Variant is activated.

   You can set captured values at any time by editing them directly in the Values column of the Variant Manager. Alternatively, you can modify the property values elsewhere in the Unreal Editor UI, then update the saved value to match the property's current value by doing any of the following:

   • Click the Record the current value icon next to the property value.

     

   • Right-click the property or its captured value and choose Record Current Value from the context menu.

     

   When you update a captured value directly in the Values column for a Variant that you have already switched on, you won't see your change reflected immediately in the Level Viewport. To see the effect of your change, switch on the Variant again. Or, right-click either the property or its captured value, then choose Apply Recorded Value from the context menu.

   

If you use Datasmith to import scenes from third-party applications that support setting up variants, including Autodesk VRED and 3DExcite Deltagen, and you have variants already set up in your source scenes, Datasmith will automatically set up a Level Variant Sets Asset and Actor for you. All you'll have to do is create the Blueprint logic or UMG widgets in your Project that can switch your variants on in response to user interaction.

Automatic Binding and Capturing

As an alternative to binding Actor properties one-by-one using the approach outlined in the previous section, you can bind Actors and capture their properties automatically as you modify them in the Level.

To toggle automatic binding and capturing, use the toggle button at the top of the Variants column on the left of the Variant Manager UI.

While automatic capturing is activated, the Variant Manager listens for every change that you make to the Actors in your Level. Whenever you change a property that the Variant Manager is able to capture, it automatically captures the new value you have set for the modified property and saves it in the Variant that you currently have selected—that is, the Variant that is highlighted in orange in the leftmost column. If the Actor you modified was not already bound to the selected Variant, it is bound automatically.

Automatic binding and capturing can make it faster and easier to set up your Variants. Typically, you use it as follows:

1. Click the Variant you want to modify in the left-hand Variants column to select it. Or, double-click the Variant if you want to switch on its current state before you make changes.

2. Toggle the auto-capture button to its activated state.

3. Modify the Actors that you want to bind to the Variant you have selected. As you work, you should see the Variant Manager automatically bind every Actor you modify and capture every new property value you set.

4. When your Variant is set up the way you want it, you can either:

   • Continue capturing properties for another Variant by clicking or double-clicking the new Variant in the left-hand Variants column.

   • Stop capturing changes by toggling the auto-capture button back to its disabled state.

Be aware when you activate auto-capture mode. If you forget that you have it activated while you work in your Level, you may accidentally record undesired changes to the currently selected Variant.

Activating Variants in the Editor

Whenever you activate a Variant, either at runtime or in the Unreal Editor, the Variant Manager iterates through the list of Actors that you've bound to that Variant. For each of these Actors, it sets all captured properties to the values that you've stored in the Variant. It also calls any functions that you've configured the bound Actor to call.

You can activate Variants in the Unreal Editor when you have the Variant Manager UI open. Use either of the following methods:

• Double-click the Variant you want to activate in the leftmost column.

• Right-click the Variant you want to activate in the leftmost column, and choose Switch On from the context menu.

  

The Variant Manager uses a small status indicator to show which Variants are switched on: that is, ones whose captured properties all match the values that are currently applied to the bound Actors in the Level. This happens when you switch on the Variant, and it also can happen if you set the same property values manually in the Level.

For details on activating Variants at runtime, see Runtime Blueprint API below.

About the Level Variant Sets Asset and Actor

Each Level Variant Sets Asset stores information about Actors that live in a specific Level. While you have that Level open in the Unreal Editor, you can use the Variant Manager UI to activate different Variants. As you do, the bound Actors in the Unreal Editor immediately update the values of their captured properties.

If you only need to activate Variants in the Unreal Editor, but not at runtime, then the Level Variant Sets Asset is the only thing you need to set up.

However, Variants are often most useful at runtime in a packaged Project. For example, suppose you have a 150% BOM model of a car in an Unreal Engine Level, with multiple variants that represent different trims. It may be useful to be able to switch between these different trim options in the editor. But if your goal is to create a car configurator that lets end users choose the trim they want, you'll also need to make your Variants controllable by a viewer at runtime.

To do this, you'll need to drag your Level Variant Sets Asset into your Level. This creates a new Level Variant Sets Actor in the Level that is linked to the Asset you used to create it. This special kind of Actor offers a Blueprint interface that you can use to interact with your Variants from Blueprint gameplay logic and UMG interfaces that you create in your Project.

Each Level Variants Sets Asset is limited to working with the Actors in a single Level. If you open a different Level, the Variant Manager UI will no longer affect the objects in that new Level.

If you need to control Actors in multiple different Levels, you'll need to create a separate Level Variant Sets Asset for each Level, and set each one up separately. Or, if you want them to control the same Actors in the same ways, you can put all the Actors that you need the Level Variants Sets Asset to control into a single sublevel, and add that sublevel to both of the Levels that need those Variants.

Runtime Blueprint API

The Level Variant Sets Actor offers a Blueprint API that you can use to interact with your Variants and Variant Sets at runtime. This API supports two main uses:

• Switching on Variants that you identify by name or by index. See Activating a Variant below.

• Querying data about the Variant Sets and Variants that you have configured, including their display names. See Accessing Variant Data below.

Activating a Variant

You can switch on any Variant in your Level Variant Set if you know either the name or the index value of both the Variant and its parent Variant Set.

The simplest way to switch on a Variant is to drag right from a reference to the Level Variant Set Actor, find the Level Variant Sets category, and choose either Switch On Variant By Index or Switch On Variant By Name.

Accessing Variant Data

You can access the structure of all Variant Sets and Variants that you've configured in the Variant Manager.

1. Drag right from a reference to the Level Variant Set Actor, find the Level Variant Sets category, and choose Get Level Variant Sets.

   

2. Once you have a reference to the Level Variant Sets Asset, drag right from the Return Value port and find the Level Variant Sets category to access the Variant Sets set up in the Asset.

   

   Use the Get Variant Set or Get Variant Set By Name node to retrieve a Variant Set from its index or its name. Get Num Variant Sets returns the total number of Variant Sets configured in the Level Variant Sets Asset. You can combine this with the Get Variant Set node to loop through all the Variant Sets:

3. Once you have retrieved a reference to a Variant Set, drag right from its Return Value port and find the Variant Set category to work with the data the Variant Set contains.

   

   You can use the Get Display Text node to retrieve the name you set for the Variant Set in the Variant Manager UI.

   You can also access the Variants within the Variant Set using a set of nodes similar to the ones you used to access the Variant Sets themselves. Use the Get Variant or Get Variant By Name node to retrieve a Variant from its index or its name. Get Num Variants returns the total number of Variants configured in this Variant Set. You can combine this with the Get Variant node to loop through all the Variants in the Variant Set, just as shown above for looping through Variant Sets.

4. Once you have retrieved a reference to a Variant, drag right from its Return Value port and find the Variant category to get its display name, switch it on, and access its bound Actors.

   

This sample Blueprint graph uses the approach outlined above to iterate through all configured Variant Sets and Variants. It prints the name of each Variant Set and each Variant in order to the screen and the output log.

You could use the same kind of approach to iterate through your Variant Sets and Variants to do something different. With a little imagination and general UMG knowledge, you can use this information to write a UI system that automatically creates UI widgets that reflect the Variant Sets and Variants you have configured in your Level Variant Sets Asset.

For background information about working in Blueprints, see Blueprint Visual Scripting. For more about creating user interfaces with UMG, see the UMG UI Designer documentation.

Credits

The car model used on this page is courtesy of Allegorithmic.