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 this 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.

Creating States

To create a new state, you must first select the top-most Base Object. The Details panel contains the State array in which you can add, remove and edit existing or new States. If no State is created, a default State with no optimized parameters and optimization options will be automatically created.

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.

Runtime Parameters

The Runtime Parameters array defines the set of parameters that Mutable will use to optimize a given State. These parameters are the ones you expect the user to be constantly editing in the given State.

Optimization Options

States also give you more options in order to further optimize them. For each individual State, Mutable gives you the following optimization options, in addition to the Runtime Parameters:

• Texture Compression Strategy: Avoid Texture Compression for textures that may change in this State. Reduces the update latency by avoiding unnecessary compression and decompression operations. Useful for customization screens, which are usually less memory constrained than in-game.
• Disable Mesh Streaming: Although Mesh Streaming is always enabled, it can be disabled per State. This removes the mesh popping and reduces the latency when generating them.
• Disable Texture Streaming: Similar to Disable Mesh Streaming, disables texture streaming. This removes the texture popping and reduces the latency when generating them.
• Live Update Mode: Considerably speeds up updates by reusing data from previous updates. Very memory intensive. Useful for continuous updates like texture projections.
• Build Only First LOD: Only generates the first LOD (highest quality). Reduces the update latency by skipping other LODs.
• Forced Parameter Values: List of Enumeration Parameters that will be automatically changed when the State is selected. For example, allows you to hide the jackets when editing the shirts underneath. The first field represents the Enumeration Parameter name, while the second field is the forced value.

Using States

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 in the Customizable Object Instance before the update is issued with the following call:

void SetCurrentState(const FString& StateName);