Unreal Engine modules

The system is structured as an Unreal plugin with two additional Unreal modules: one for the editor and one for the runtime. These modules use external libraries for the Mutable runtime, which is a standalone library with no dependencies.

Folder Structure

This is the basic folder structure of an Unreal Engine game that uses Mutable. The hierarchy only shows the relevant folders for Mutable source code.


The folder “source” is optional (and by default not included with all licenses) and it contains the source code of the standalone runtime and tools libraries. These are already included in the “lib” folder as precompiled binaries for each supported platform, with the required headers in the “include” folder.


The “source” folder may also contain the source code for the standalone tools for Mutable. These tools are not required for normal Mutable usage but they can be very helpful to debug and profile your project.


Engine changes

Most of Mutable happens in the plugin described above. However, there are some changes that are required in the engine and tools, that cannot be done from a plugin. All changes in the code are labelled with comments including "anticto", so they are easy to locate. These are the changes required for each currently supported Unreal Engine versions:

Unreal Engine 4.19

  • Added an additional cook step to build the CustomizableObject assets before anything else:
    • Engine/Source/Editor/UnrealEd/Private/Commandlets/CookCommandlet.cpp
  • Added some texture streaming tweaks for mutable textures:
    • /Engine/Source/Runtime/CoreUObject/Public/Serialization/BulkData.h
    • /Engine/Source/Runtime/CoreUObject/Private/Serialization/BulkData.cpp
    • /Engine/Source/Runtime/Engine/Private/Texture2D.cpp
    • /Engine/Source/Runtime/Engine/Private/TextureDerivedData.cpp
    • /Engine/Source/Runtime/Engine/Private/Streaming/Texture2DStreamIn_IO_AsyncMutable.h  [new file]
    • /Engine/Source/Runtime/Engine/Private/Streaming/Texture2DStreamIn_IO_AsyncMutable.cpp  [new file]
  • Added some methods for direct creation of mesh rendering resources:
    • /Engine/Source/Runtime/Engine/Public/StaticMeshResources.h
    • /Engine/Source/Runtime/Engine/Private/StaticMesh.cpp
    • /Engine/Source/Runtime/Engine/Public/Rednering/SkinWeightVertexBuffer.h
    • /Engine/Source/Runtime/Engine/Private/Rendering/SkinWeightVertexBuffer.cpp

We aim at reducing the number of this engine changes as our development progresses.

Packaging a project

When a project is packaged for distribution, Mutable will compile all the relevant CustomizableObject assets. This compilation step will be done with maximum optimisation so it will take longer than compiling an object in the editor. Additionally, the data used by the CustomizableObjects will be prepared for disk streaming. Thanks to this, the memory usage of your project will be kept low regardless how may options you have in your objects.

In order to package a project using Mutable you need to include an additional folder in the packaging process: <YourProject>/Content/MutableStreamedData . You can do this in the DefaultGame.ini file of your project:

+DirectoriesToAlwaysStageAsUFS=(Path="MutableStreamedData") )

or from the project settings in the Unreal editor: