Variant Manager Template 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.
• 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.

1. To enable the Variant Manager, use Edit > Plugins to open the Plugins browser. Search for the Variant Manager plugin and check its box to enable it.

Click image for full size.

1. Right-click in the Content Browser and select Level Variant Set from the Miscellaneous list.

Click image for full size.

1. When this is complete, you will have something that looks like this:

Click image for full size.

1. Click the + Variant Set button and name the new set:

Click image for full size.

1. Once the Variant Set is created, click the Add (+) button next to its name to create a Variant.

Click image for full size.

1. Right-click an Variant to rename it. Click the "Set from Viewport" button to show it from the Viewport

Click image for full size.

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.

Click image for full size.

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

1. Variants panel: 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 three Variant Sets: Paint, Logo Paint, and Rims. Those Variant Sets contain several Variants: visible in the image are Variants for Blue, Wild Cherry, and Naranja paint colors.

2. Actors panel: Whenever you have a Variant selected in the leftmost panel, the second panel (Actors) lists all of the Actors that are bound to that Variant. In the image above, the Paint > Blue 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. Activating the Variant causes the bound Actor to respond in a certain way: either by changing the value of a data property, or by calling a function.

3. Properties panel: When you select one or more bound Actors in the second column, the third panel (Properties) shows you what properties of those Actors are captured in this Variant. In the image above, the Variant captures the Material[1] property; this material determines the visible paint color of the surface.

   To capture a property of an Actor means to store a desired value for that property in the Variant.

4. Values panel: The rightmost panel (Values) shows the value saved in the Variant for each property visible in the Properties panel. In this case, when the Blue Variant switches on, the Variant Manager sets the Material[1] property of its bound Actors to a blue car paint Material.

5. Dependencies panel: Finally, the bottom panel (Dependencies) shows any constraints that are part of the selected Variant. A Dependency is a constraint that switches on other Variants when the current Variant is enabled. The current Variant does not have any dependencies but does show that it is a part of the Default Variant in the Packages Variant Set.

Setting Up Variants

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

1. 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. By right-clicking and selecting options from the context menu, you can:
   • Edit existing Variants.
   • Add new Variants and Variant Sets.
   • Move Variants from one set to another.
   • Assign thumbnail images to Variants and Variant Sets. These thumbnail images can later be used as part of a user interface like the one seen in the Product Configurator template.
   • Add any necessary Dependencies.

2. For each of the Variants you created above, you can bind one or more Actors. Bind a new Actor to a Variant by clicking the Add (+) button in the header of the Actors column. You can also drag Actors from the World Outliner panel on to the list of bound Actors, or on to the Variant in the left-hand column. It is also possible to bind and unbind Actors by right-clicking the list in the Actors panel and using the context menu.

3. For each bound Actor, 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:

   Click image for full size.

   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 are marked as Instance Editable.

   Capture additional properties at any time by clicking the Add (+) button in the header of the Properties panel, or right-clicking a bound Actor at any time to capture additional properties. Right-click a captured property to remove it from the list.

   Click image for full size.

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

4. For each captured property, you set the value that you want the Variant Manager to apply when the Variant activates. 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.

     Click image for full size.

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

     Click image for full size.

   When you update a captured value directly in the Values panel 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.

   Click image for full size.

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 active, 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 can 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. 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 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.

  Click image for full size.

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.

Setting Up Dependencies

Once the Variants and Variant sets are established, you can create optional Dependencies for any Variant. A Dependency is a constraint that is added to a Variant that switches on other dependent Variants when it is enabled, such as creating a Default variant that will set other Variants back to their initial setting:

Click image for full size.

Here is how to setup new dependencies for your Variants:

Click image for full size.

1. Select one of your Variants and click the Add (+) button in the Dependencies panel to create a new dependency.
2. A dependency needs to know the Variant Set and the Variant that you want to enable when your current selection switches on. Click the drop-down box under Variant Set and select the Variant Set that contains the Variant you want to add to the dependency.
3. Then select the Variant to enable from the Variant drop-down.

The Variant chosen for a dependency does not need to contain any bound Actors

Click image for full size.

Here we can see Dependencies used to create a variety of package setting options. Notice that the Variant shown contains only Dependencies and does not have any Actor bindings.

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 links 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. For more information on using the Variant Manager to create a configurator, please see the Product Configurator template documentation.

Each Level Variants Sets Asset works only 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.

Click image for full size.

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.

   Click image for full size.

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.

   Click image for full size.

   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:

   Click image for full size.

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.

   Click image for full size.

   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.

   Click image for full size.

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.

   Click image for full size.

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 vehicle model used on this page is courtesy of Allegorithmic.