This is the old deprecated documentation for Mutable. Please visit for the latest release.

Basic Concepts


The following diagram shows the elements involved in a project with customizable objects using Mutable:

Mutable Assets

Mutable for Unreal Engine 4 brings two new type of assets to the engine.

Customizable Object

This asset represents an object that can be customized. It includes all the possible variations that can be applied, and defines the parameters that can be controlled at run-time (by the player, or by game code), and how they affect the final objects.

There is a special tool calle Customizable Object Editor inside the Unreal Editor to show and edit this kind of asset. It looks like this:

To create a Customizable Object in the Content Browser, you can click in the 'Add New' button and select 'Customizable Object'.

In the Content Browser, a Customizable Object looks like this:


A Customizable Object will define several parameters. The parameters are what the game or application (so probably the player) will be able to modify at runtime. There are several types of parameters, and they can be created by several nodes:

  • Slider parameters: numeric parameters with decimals, ranging between 0.0 and 1.0. These are usually created explicitely by a Float Parameter Node, and used for continuous effects like texture effects, or mesh morphs.
  • Enumeration parameters: they represent an option in a predefined set of options. These are created by Object Group Node, to select a child object.
  • Checkbox parameters: they only have two possibilities (enabled or disabled). These are created by Object Group Node when the group type is "Toggle Each".
  • Projecto parameters: they represent a projector with a position that will be modified at runtime. They are created with the Projector Parameter Node.

Customizable Object Instance

This asset represents an instance of a CustomizableObject, so it is a “customized object”. It simply contains a set of values for the parameters of an object. It can be used by game actors to create their in-game meshes and materials.

Again, there is a special tool to handle these assets in the Unreal Editor:

To create an instance from a Customizable Object, you can right-click the Customizable Object in the Content Browser and select 'Create New Instance'.

A Customizable Object Instance looks like this in the Content Browser:

Feature Status

Mutable has many features, but not all are at the same level of maturity. Please check the following table. If you require improvements in one specific feature, don't hesitate to contact us.

Feature Planned Testing Implemented Mature
Mesh merging      
Mesh removal of hidden parts      
Mesh texture layout packing      
Texture layer blending      
Texture projectors      
Hierarchical object system      
Object interaction variations      
Data driven user-interface      
Object States optimization      
LOD Support      
Data streaming      

Platform Support

Feature Planned Testing Implemented Mature
Windows 64 bit      
Windows 32 bit      
Linux 64 bit      
Linux 32 bit      
XBox One      
Playstation 4      

Hierarchycal Object System


Mutable organizes the data for each Customizable Object in a hierarchy of parts. Each object has a root object node that can define a base mesh and materials with some parameters. This object can have any number of child objects that can:

  • add new materials to the final object
  • extend the mesh used by a material in the parent object
  • remove part of the mesh in the parent object
  • patch the textures of a material in the parent object
  • activate user-defined Tags that can be use in sibling objects to apply different effects.

At the same time, child objects can chave thier own child objects in an unlimited hierarchy.


The children of an object can be organized in Groups. The Groups define the logic between the object and its parent in regard of how are the children activated. For instance, all t-shirt children can be grouped with an object parameter that only lets the users select one of them at a time, or none.

Two Child Objects directly connected to the parent (they are not a selectable option in the Preview Instance Viewport):

Two Child Objects grouped. The Group type is 'toggle', so the child objects appear as toggleable options in the Viewport:

Two Child Objects grouped. The Group type is set as 'One'. Only one child object can be selected in the viewport:

Twi Child Objects grouped. The Group type is 'One or none'. In the viewport, the child objects can be selected or not:

Multiple Assets

A big CustomizableObject can be split into several assets. This is very important when multiple users work in the same data and also for version control. There are 2 features to assist with this:

  • Child Objects can select as parent an Object Group in a different asset, instad of directly connecting them in a graph.
  • There 2 special diagram nodes to export and import connections from the graph in other assets.

This is useful for editor data, but it has nothing to do with data streaming in packaged games. Data streaming for packaged games will happen regardless the CustomizableObject is split in multiple assets or not.

Object Interactions

Mutable has several features to handle object interactions. The most basic one is the Object Groups, which create instance parameters that select only one child object from a set, so it is not possible to add more than one of them. An example of this is a group for character hats, that will let you select one har or none, but never two hats. 

Additionally, Mutable has a system to create different variations of an object based on what other objects are added to an instance. For example, you may have a character with several hair styles, and optionally hats. You may want to create variations for some of the hairstyles to be used when a type of hat is also present in the character.  You can use the Material Variations for this.

Another example of object interaction is the selective removal of mesh fragments. This can be seen in the section Remove unseen mesh parts.

These two types of object interactions use the Tag system. You can define your own Tags and they are enabled when an object is active in an instance. The Material Node is the place where you can add the tags which are just text labels. Then, there are several nodes that will act differently based on what tags are enabled in a particular instance, like the Material Variation Node, or the Clip Mesh With Mesh Node.

Texture Layouts


Object States

When an application uses complex Customizable Objects with many parameters, updating the instances may be a costly process that takes many milliseconds. However there are some usage scenarios for games that these updates need to be interactive, and big delays are not acceptable. In order to optimize your data to solve these problem, Mutable has the concept of States.

A State represents a specific use case of the Customizable Object in your game. For example, at some point during character creation you may want to let the player customize the face and hair of a character. During this stage, you show a close up camera of the character head and display a user interface for the related parameters: hair colour, nose size, hair style, etc. During this stage, you will not be modifying other parameters, like t-shirt colour, torso tattoos, etc. In order for Mutable to provide maximum performance, you can create a State in your Customizable Object, indicating that the subset of parameters that you will modify in these stage, and the system will generate an optimised version of the data that updates faster.

States also give you more options in order to optimise the instance construction time. For instance, in the previous example of the head customization stage, your game may have more graphic resources available because instead of being inside a level, you are in a smaller lobby scene. This means that you can afford to temporarily use more memory for your character. For each individual State Mutable gives you these optimisation options:

  • List of parameters that may be modified.
  • Option to avoid texture compression for textures that may change in this state.
  • Option to generate only LOD 0 of the object.

States are created in any Base Object Node. If no state is created, a default state with no optimized parameters and sensible optimisation options will be automatically created.

A normal game will want to create a "default" state to create customizable objects to be used in-game (no optimized parameters), and then several states to create and update objects in the different in-game customization scenarios.

The editor user interface for preview instances has the object state selection combobox at the top.