States - anticto/Mutable-Documentation GitHub Wiki

When an application uses complex Customizable Objects with many parameters, updating the instances may be a costly process that takes many milliseconds. In game, however there are some usage scenarios that require these updates to be interactive (big delays are not acceptable). To solve these problem, Mutable has the concept of States.

A State represents a specific use case of a Customizable Object in your game. For example, at some point during the 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 color, nose size, hair style, etc. During this stage, you will not be modifying other parameters, like t-shirt color, torso tattoos, etc. In order for Mutable to provide maximum performance, you can create a State in your Customizable Object, with the subset of parameters that you will modify in this stage. Using this State, the system will generate an optimized version of the data that updates faster.

In the Editor Preview Instance, you can choose which state to use by using the State combobox located at the top:

In order to take advantage of states in-game, you must set the state if the CustomizableObject Instance before the update is issued with the following call:

void SetCurrentState(const FString& StateName);

Runtime Parameters

The Runtime Parameters array defines the set of parameters that Mutable will use to optimize a given State. Each of these parameters can be of the following types:

• Object Group
• Float Parameter
• Enum Parameter
• Color Parameter
• Texture Parameter
• Projector Parameter
• Group Projector Parameter

The Runtime Parameters array can be found on the bottom of the Base Object and Child Object properties details:

Optimization Options

States also give you more options in order to optimize the Customizable Object Instance construction time. In the example, the 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 three optimization options, in addition of the Runtime Parameters:

• Do not Compress Runtime Textures: Avoid texture compression for textures that may change in this State.
• Build Only First LOD: Only generate the LOD 0 of the object.
• Forced Parameter Values: List of Enumeration Parameters that will be modified when the state is selected. For example, allows to hide the jackets when editing the underneath shirts. The first filed represents the Enumeration Parameter name, while the second field is the forced value.

States are created at any Base Object Node. If no state is created, a default State with no optimized parameters and optimization options will be automatically created. Also a Child Object can can contain its own States. A State defined at a Child Object functions identically to a states defined at the Base Object.

Ideally, a game should have an "in-game" state with no optimized parameters, and several "customization" states to create and update objects in the different in-game customization scenarios.