Using Mutable from Blueprint - anticto/Mutable-Documentation GitHub Wiki

Creating a Customizable Character

Create a new blueprint with "actor" as parent class and open it. Alternatively, you can use a class/BP that has a skeletal mesh component.

In the blueprint editor, select the Skeletal Mesh component and add a Customizable Skeletal component as a child. Name the Skeletal Mesh and the Customizable Skeletal components "Body" and "Body_CO" respectively.

Having selected the newly created component, go to the details panel and chose the instance to be used.

Set the component name of the Body. By doing this you will already see the body of the character in the BP's viewport.

To add another component for the head, add a new Skeletal Mesh component. It should be a child of the Body Skeletal Mesh component. Name it "Head".

Create a new Customizable Skeletal component as child of the "Head" Skeletal Mesh component. Name it "Head_CO"

Select the "Head_CO" component and add the same instance that we added to the body component. Select the component name "Head".

Now, you should be able to see your character completed:

Changing Parameters

Parameters are stored by instances and can be accessed or modified using the API nodes. Here are examples on how to set parameter values based on their type:

• Boolean Parameter:

• Int Parameter: It's important to make sure that the desired option actually exists within the instance. Search existing parameters using the FindParameter node and then get the available option with GetIntParameterAvailableOption. Both nodes have the CustomizableObject as target, which can be accessed through the CustomizableObjectInstance.

• Float Parameter

• Color Parameter

• Projector Parameter

Update Instances

To apply recent changes in parameters, the instance needs to be updated. This can be achieved by adding an UpdateSkeletalMeshAsync node after one or more changes.

Updated Delegate

Events can be registered to this delegate. The broadcasting will take place after the completion of the skeletal mesh update.

Parameter Information

Sometimes, additional information like the amount of parameters within an instance, their type or the name of an int parameter's option might come in handy. This information is kept in the source CustomizableObject, accessible through the instance, and can be retrieved using the following nodes:

• Get Parameter Count

• Get Parameter Name

• Get Parameter Type by Name

• Find Parameter

• Get Int Parameter Num Options

• Get Int Parameter Available Option

Changing States

States can also be queried and changed using the node API:

As when changing parameters, the instance needs to be updated with a UpdateSkeletalMeshAsync node after a State change.

State Information

Information about the number and name of States a CustomizableObject has and the number and names of parameters in a State can be useful. This information is stored per CustomizableObject, accessible through a CustomizableObjectInstance and can be retrieved using the following nodes:

Compiling a Customizable Object from a Blueprint or Code

A Customizable Object can be compiled from a Blueprint or Code using the function Compile. The parameters of this function are:

• Customizable Object: The customizable Object that is going to be compiled.
• Compilation Parameters: This is a structure that allows users define some parameters of the compilation.

  • Skip if Compiled: If this bool is set to true, the compilation will not occur if the Customizable Object is already compiled.

  • Skip if Out of Date: If this bool is set to true, the compilation will not occur if the Customizable Object or its contents are out of date (child Customizable Objects, Data Tables, referenced Materials...).

  • Gather References: If this bool is set to true, all asset references used in this Customizable Object will be stored in the object. Marks the Customizable Object as modified.

  • Async: If this bool is set to true, the Customizable Object will be compiled asynchronously. If is compiled synchronously and the Customizable Object is not ready the compilation will fail.

  • Compile Only Selected Instance: This is a pointer to a Customizable Object Instance asset. If this pointer is not null, only the options selected in the Customizable Object Instance will be compiled. This is useful because it will reduce the compilation time.

  • Optimization Level: This option determines if the Customizable Object will be compiled with optimizations or not. If the Optimization Level is set to "None" the compilation will be faster. However, the update of the skeletal mesh will be slower since the compilation will skip all the optimizations. If the Optimization Level is set to "Maximum" the compilation will take longer. However, the update of the skeletal mesh will be much more faster.

  • Texture Compression: There are three options:

    • None: The compilation will not use texture compression.
    • Fast: Use Mutable's fast low-quality compression.
    • High Quality: Use Unreal's highest quality compression which is 100x slower to compress.

  • Callbacks: Functions that will be called once the compilation has finished.