Resource Usage - anticto/Mutable-Documentation GitHub Wiki

This section is only relevant for projects using Mutable at runtime. If your project is using a workflow that uses mutable only in the Editor then the resource usage will just be the standard one of the Unreal Engine resources created while editing.

When used at runtime to create assets from CustomizableObjects, Mutable is an engine additional component and it requires resources to work. These are:

  • CPU time.
    • most of it is in worker threads. This uses the Unreal Task system to split the work in multiple tasks.
    • small parts of the work will happen in the game thread. These must be small enough to avoid hitches.
  • Memory
    • The final assets generated by Mutable will be standard Unreal Engine resources (textures, skeletal meshes, animation blueprints, etc.).
    • In addition to that, while building these resources Mutable needs "working memory" for its intermediate operations.
  • Disk streaming bandwidth
    • Mutable will be loading its own data when the construction of a character is on-going. This uses the Unreal disk streaming system.

There are Unreal Insights channels for Mutable both for CPU and memory usage. They are disabled by default but enabling them in captures will give a very good idea of the work done at runtime.

When does Mutable work

All Mutable operations (instance generation or update) work in sequence: there are never 2 operations happening at the same time. For this reason all operations must be treated as asynchronous. There are callbacks to notify when they are completed.

When the parameters of a CustomizableObjectInstance are changed an explicit call will force its update. When Mutable has completed the update operation, the engine resources are created or replaced.

Mutable can be used integrated with Unreal's texture streaming functionality. When doing this, Mutable will queue work whenever a new texture mipmap is requested by the texture streaming system. This also happens sequentially with normal instance updates.

Memory and caches

The amount of working memory used by Mutable depends directly on the CustomizableObject being built. A ballpark estimation of the higher limit is around 2 times the memory for the the biggest generated texture in uncompressed format, or the biggest mesh. This however depends on the operations done to the textures, the use of UV layout blocks, or the CustomizableObject compilation settings.

Mutable will try to keep its working memory under a certain limit. This limit can be specified in INI files per-platform, but some projects may also be interested in controlling it for different in-game scenarios. For instance you may want to give Mutable a lot more memory to cache more data and speed up instance updates when you are in a character creation screen. In that case it can be directly set with the UCustomizableObject::SetWorkingMemory method, or the mutable.WorkingMemory CVAR.