This page gives a high level overview of the scripting support for interacting with MetaHuman Character assets.
There are example scripts in Engine\Plugins\MetaHuman\MetaHumanCharacter\Content\Python\examples which can be used as a reference on how to use the API for different tasks.
The scripting API was designed to be most useful when writing Python code to interact with MetaHuman Character assets, but the same functionality can be used from Editor Utility Blueprints.
MetaHuman Character Asset
The MetaHuman Character asset is where all information about a MetaHuman Character is stored. There are several properties that can be edited directly in this asset including makeup, eyes, and skin. See test_set_character_properties.py for a list of all the properties that can be set in the character (without needing to open it to edit), and examples/example_create_asset.py for an example on creating new character assets.
MetaHuman Character Editor Subsystem
The MetaHuman Character Editor Subsystem provides the interface needed to perform edits on the face, body, as well as downloading texture sources, and auto-rigging. The subsystem is also needed when writing code that performs edits for a character that has its editor opened. It allows interactive edits to the character and every change will be automatically reflected in the viewport.
The following table describes the main functions needed to perform most edits in a character asset from MetaHumanCharacterEditorSubsystem.
| Function | Description |
|---|---|
try_add_object_to_edit(character) | Tries to load a MetaHuman Character asset to be edited. The subsystem will create and track all data needed to perform edits to the character. Note that opening a MetaHuman Character asset editor will also call this function as the character has to be registered in the subsystem. |
remove_object_from_edit(character) | Removes an object from the subsystem. This is important to character specific data that the subsystem is holding. Note that closing a MetaHuman Character asset editor will also remove it from the subsystem. |
is_object_added_for_editing(character) | Checks if a character is registered for editing in the subsystem. |
Committing Changes
All properties that can be set directly in the MetaHuman Character object don’t require the character to be registered for editing in subsystem, however, when interacting with a character that has its editor opened, unless a commit function is used, changes are not going to be reflected in the viewport.
See examples/example_live_edit.py for an example of this in action. To use this script, select a MetaHuman Character Asset in the Content Browser and then execute it. The script will open the editor and will perform edits to the face using the translate_face_landmarks function and then it will call commit_face_state. This is important as translate_face_landmarks doesn’t actually save the changes to the character asset itself, it will only update the preview data. commit_face_state is responsible for serializing the changes.
This pattern must be followed to update the viewport with changes to the skin, including makeup and the head and body models
Downloading Textures and Auto-Rigging
The subsystem provides the functions request_texture_sources and request_auto_rigging which can be used to call the MetaHuman Cloud services to download textures and auto-rigging, respectively. Both functions take a struct parameter which can be used to make it a blocking request and report or progress or not.
Known Issues: Unable to remove the rig once generated.
Configuring Outfits and Grooms
Grooms and clothing use a generic slot system through the MetaHumanPipelineSlotSelection object. See examples/example_add_grooms.py or examples/example_add_clothing.py for examples of how to select grooms and outfits programmatically.
The API also allows configuring the parameters of each wardrobe item that is applied to the character. See test_set_character_instance_params.py for an example of editing the different groom and outfit parameters. It is important to call asset_for_preview before editing the parameters as this is required to make all the instance parameters available in the character’s collection.
Conforming Head
The head can be generated using the conform tools. Heads support conform from DNA, conform from template and fit from vertices. See examples/example_conform_head.py for more detail.
Sculpting
Both head and body can be sculpted directly through the API. The face sculpting can be achieved by manipulating the vector position for each landmark, see examples/example_sculpt_face.py. The parametric body system can be manipulated in a very similar way, each slider in the UI is represented by a body constraint and can be activated and have the target measurement set for each, see examples/example_sculpt_body.py.
Assembly
The final stage of the process is to assemble a character. The API supports each of the pipelines currently available, UE Cine, UE Optimized, UEFN and DCC. Each pipeline has additional parameters that can be configured to customize the assembly process. Examples of which can be seen in examples/example_assembly.py.