CharacterAssistant System

Purpose and Scope

CharacterAssistant is an Editor Utility Widget used to quickly add new character skins into an RPG Engine v6 project for both player and AI characters. It supports MetaHuman, UE4 and UE5 skeletal meshes and automates the creation and registration of all required skin assets, including item data, clarification DataAssets, optional face actors and Mutable objects.

This document explains what CharacterAssistant generates, how it selects the correct asset classes for different skin types, and how it integrates with the runtime character customization and skins system. It does not provide step‑by‑step recipes; those are covered in How‑To guides for adding MetaHuman and non‑MetaHuman player skins.

---

High-Level Overview

CharacterAssistant is an Editor Utility Widget that runs entirely in the Unreal Editor and never in game runtime. Its purpose is to transform user-selected skeletal meshes and configuration parameters into ready-to-use skin assets that plug into the existing BP_CharacterSkinComponent runtime system.

The tool supports three main input families: MetaHuman characters, UE5 mannequin-style characters and UE4 skeleton-based characters. For each family it can generate skins for either player or AI, automatically decide whether to use single-mesh or separate head/body layout and, when requested, prepare a Mutable-compatible setup.

---

Generated Assets and Data Flow

CharacterAssistant creates all required assets to make a new skin visible in the wardrobe and usable at runtime. In a typical generation pass it produces:

• A BP_ItemData asset for the skin item, which the wardrobe and save system use to represent the selected skin.
• An inventory entry in the global item data (DT/Inventory context) corresponding to that BP_ItemData row or asset.
• A skin clarification DataAsset of the appropriate subclass of BP_CharacterSkinData (e.g. BP_PlayerSingleMeshSkin, BP_PlayerSeparatedMeshSkin, BP_BotSingleMeshSkin or BP_BotSeparatedMeshSkin), depending on whether the skin is for player or AI and whether it uses single-mesh or separate head/body.
• For separate head skins, a head actor asset (BP_FaceComponent or BP_Face_Mutable) so the runtime can drive facial animations independently from the body.
• When UseMutablePlugin is enabled, a UCustomizableObject asset created by copying and renaming an existing CO_Example asset, serving as the Mutable source for the skin.

The tool also registers the new skin in the correct container DataAsset. If Generated for AI is disabled, it adds a reference to the new BP_ItemData row into DA_CharacterSkinsContainer.Skins; if Generated for AI is enabled, it adds it into DA_AI_SkinsContainer.Skins instead. This ensures the wardrobe UI and AI character setup can discover the skin without any manual DataTable editing.

CharacterAssistant does not perform duplicate checking when writing assets or updating the containers. If an asset with the same name already exists or a skin entry with the same item reference is present, the tool will simply overwrite the existing assets and container entries according to the editor’s normal save behavior.

---

Common Parameters (Shared Fields)

Several configuration fields are always available regardless of the current mode (MetaHuman or non‑MetaHuman). These fields define the basic presentation of the skin and how it will appear in the wardrobe UI.

• Name
  Human‑readable name of the skin and the base for the generated DataAsset names. Typically this becomes the display name in UI and part of the asset naming convention in the Content Browser.

• ShortName
  A shorter identifier for the skin used where UI space is limited. This field can also help with naming conventions for internal assets or debugging.

• Abbreviation
  A very short code or acronym for the skin. This is useful for compact labels, debug overlays, or building consistent asset name prefixes.

• Description
  A longer text description of the skin shown in more detailed UI views or tooltips. It is stored inside BP_ItemData and reused across menus and wardrobe screens.

• Icon (Texture2D)
  Texture used as the wardrobe icon for this skin. The typical workflow is to select the desired texture in the Content Browser and then click the small square button near the Icon field to assign the selected asset.

• UseSimpleTexture
  Boolean flag that controls how the icon is rendered. When true (default), the icon is used as a simple texture; when false, the system uses a special material that isolates the texture’s alpha channel so that icons with transparent backgrounds render correctly.

The widget integrates tightly with the Content Browser selection. For all asset reference fields such as Icon, Head and Body, the user can select an asset in the Content Browser and then press the “Use Selected Asset” style button (square picker) to assign it to the corresponding field in CharacterAssistant.

---

MetaHuman Mode

MetaHuman mode is enabled via the Metahumans switch on the widget. In this mode CharacterAssistant assumes that the skin is based on a MetaHuman and therefore always uses a separate head and body setup; the choice between single-mesh and separate-head is not exposed to the user and remains fixed as separate.

MetaHuman Mode Fields

When MetaHuman mode is active, the following mode-specific parameters become available in addition to the common fields.

• Generated for AI
  Determines whether the skin should be created for the player or for AI. This flag controls which skin container DataAsset is updated: player skins are added to DA_CharacterSkinsContainer, while AI skins go to DA_AI_SkinsContainer.

• UseMutablePlugin
  When enabled, CharacterAssistant creates a UCustomizableObject asset for the skin by copying and renaming an existing CO_Example asset in the project. This Mutable object must later be configured manually in the editor, as the tool does not currently fill any Mutable parameters automatically.

• OprimizaMaterials
  A MetaHuman-specific optimization toggle, enabled by default. MetaHuman assets ship with complex and heavy materials, especially for head and eyes, which can be costly at runtime. When this flag is true, CharacterAssistant replaces the parent materials for the head, eyes and body with optimized project materials, such as MI_Head_Baked_LOD0 and its related instances, which are configured to support features like opacity/stealth while being significantly cheaper.

• Reference Actor
  An actor reference used as the source for pre-filling the head and body mesh references. When a reference actor is set, the tool attempts to read its body and head skeletal meshes and populate the Head and Body fields automatically where possible.

• Head (Skeletal Mesh)
  The skeletal mesh for the head of the MetaHuman skin. The recommended workflow is to select the desired head skeletal mesh in the Content Browser and then press the picker button to assign it into this field.

• Body (Skeletal Mesh)
  The skeletal mesh for the body of the MetaHuman skin. As with the head, this is usually chosen by selecting the skeletal mesh in the Content Browser and using the picker to assign it.

Skeleton and Material Handling in MetaHuman Mode

In MetaHuman mode CharacterAssistant performs automatic skeleton replacement and material optimization. It replaces the skeletal mesh’s skeleton with the project’s primary character skeleton, which already contains all required sockets for weapons, equipment and effects, avoiding manual socket copying from the source mesh.

With OprimizaMaterials enabled, the tool also updates the parent materials of all relevant material instances on the MetaHuman head, eyes and body meshes. These parents are swapped to project-provided optimized materials such as MI_Head_Baked_LOD0, which both reduce material complexity and preserve support for gameplay effects that rely on opacity and masking, such as stealth modes where the character becomes partially transparent.

When UseMutablePlugin is active, the generated MetaHuman skin is prepared for a Mutable integration path. CharacterAssistant creates a UCustomizableObject from CO_Example, but the designer is responsible for configuring its parameters and linking it to the appropriate BP_MutableCharacter setup in the runtime skin hierarchy.

---

Non-MetaHuman Mode

Non‑MetaHuman mode is used for skins based on UE4 and UE5 skeletal meshes that are not MetaHumans. This includes standard mannequins and any custom character meshes bound to UE4 or UE5 skeletons. The mode is active when the Metahumans switch is disabled.

Non-MetaHuman Mode Fields

When non‑MetaHuman mode is selected, the widget exposes the following additional parameters.

• Generated for AI
  Same meaning as in MetaHuman mode: controls whether the skin is registered in the player or AI skin container.

• UseMutablePlugin
  Works identically to MetaHuman mode: when true, CharacterAssistant creates a new UCustomizableObject asset by copying CO_Example, but does not populate any Mutable parameters. The resulting skin can be wired into a Mutable-based runtime setup later.

• HeadActor (bool)
  Controls whether the skin uses a separate head actor or a single combined body+head mesh. When HeadActor = false, CharacterAssistant generates a single-mesh skin using a combined body+head skeletal mesh; when HeadActor = true, it generates a separate-head setup and creates a corresponding head actor asset.

• Skeleton (enum: UE4 / UE5 / MetaHuman)
  Defines which skeleton the tool should retarget the input meshes to. In non‑MetaHuman mode this parameter affects only skeleton replacement and retargeting behavior; it does not influence materials or other data-driven aspects of the skin.

• Head (Skeletal Mesh, conditional)
  Head skeletal mesh used only when HeadActor = true. The user selects a head mesh in the Content Browser and assigns it through the picker button, similar to MetaHuman mode.

• Body (Skeletal Mesh)
  Body (or combined body+head) skeletal mesh for the skin. It is required in both single-mesh and separate-head configurations and is assigned via Content Browser selection.

Skeleton and Materials in Non-MetaHuman Mode

For non‑MetaHuman skins CharacterAssistant also performs skeleton replacement. It reassigns the selected skeletal meshes to the chosen project skeleton (UE4, UE5 or the MetaHuman skeleton option) so that they inherit all of the sockets and animation setup expected by the runtime system.

Unlike MetaHuman mode, non‑MetaHuman mode does not perform any automatic parent material replacement. To support features such as opacity-based stealth modes, designers must manually adjust the master materials of the new skin to use the project’s function MF_Mannequin_OpacityMask in the OpacityMask pin. If the master material does not expose an OpacityMask input, the BlendMode must be changed to Masked so that the opacity mask is honored.

The overall behavior of UseMutablePlugin mirrors MetaHuman mode. A UCustomizableObject is created, but no fields or parameters are automatically configured, and the integration with BP_MutableCharacter and runtime Mutable parameters is left to manual setup.

---

Skeleton and Materials Handling

CharacterAssistant centralizes skeleton and material preparation for new skins so that they integrate smoothly with existing runtime systems.

Skeleton Replacement

In both MetaHuman and non‑MetaHuman modes, the tool replaces the source meshes’ skeleton with a project-standard skeleton. This skeleton already contains the full set of sockets required by the framework, including weapon attach points, equipment sockets and effect anchors. By reassigning the skeleton, CharacterAssistant avoids the need to manually duplicate sockets from each imported character mesh.

The exact skeleton chosen depends on the mode and the Skeleton parameter in non‑MetaHuman mode. For MetaHuman mode, the appropriate MetaHuman-compatible skeleton is used; for non‑MetaHuman UE4/UE5 characters, the tool retargets to the UE4 or UE5 mannequin skeleton according to the user’s selection.

Material Optimization and Stealth Support

In MetaHuman mode, with OprimizaMaterials enabled, CharacterAssistant replaces the parent materials of the head, eyes and body material instances with project-optimized materials such as MI_Head_Baked_LOD0 and its variants. This reduces shader complexity and ensures that gameplay-driven effects that rely on opacity and masking, such as stealth modes where the player becomes partially transparent, behave consistently across all generated MetaHuman skins.

In non‑MetaHuman mode there is no automatic material replacement. Designers must:

• Use MF_Mannequin_OpacityMask in their master materials and connect it to the OpacityMask input.
• Ensure the material’s BlendMode is set to Masked if the OpacityMask pin is not currently available.

These manual steps are required to ensure that non‑MetaHuman skins participate in the same opacity-based visual effects as MetaHuman skins.

---

Mutable Integration

CharacterAssistant can optionally prepare skins for use with the Mutable plugin via the UseMutablePlugin toggle. When this option is enabled in either MetaHuman or non‑MetaHuman mode, the tool performs an extra step:

• It creates a new UCustomizableObject asset by duplicating the existing CO_Example asset in the project and renaming it according to the skin’s naming pattern.

The tool does not currently populate any parameters inside the new Mutable object. There is no engine-side API support used here to auto-generate Mutable parameters or connect them to specific meshes or materials, so all parameter setup and mapping must be completed manually after the asset is created.

At runtime, Mutable-based skins integrate with the existing customization system via BP_MutableCharacter and the mutable parameter arrays stored on BP_CharacterSkinComponent. The body and head customization state is held in MutableBodyParameters and MutableHeadParameters arrays of F_StringTwoParams, which are applied by BP_CharacterSkinComponent to the Mutable Body Object and by BP_Face_Mutable to the head’s Mutable object. These same arrays are saved and loaded using BodyParams and HeadParams fields in BP_SaveGame_Player, ensuring persistence of appearance across sessions.

CharacterAssistant’s role in this pipeline is limited to asset creation. It sets up the UCustomizableObject and the associated skin DataAsset so that they can be wired into the Mutable runtime flow, but does not attempt to edit runtime parameters or save structures.

---

Editor Workflow and Limitations

CharacterAssistant is designed as a one-click generator once the inputs are configured. The typical workflow for designers is:

1. Select the relevant assets in the Content Browser:
   • For MetaHuman mode: an appropriate Reference Actor and, if needed, head/body meshes and an icon texture.
   • For non‑MetaHuman mode: body (and optionally head) skeletal meshes and an icon texture.
2. Open CharacterAssistant and fill in the shared fields: Name, ShortName, Abbreviation, Description, Icon, UseSimpleTexture.
3. Choose the mode and mode-specific options:
   • Enable or disable Metahumans to switch between MetaHuman and non‑MetaHuman workflows.
   • Set Generated for AI to indicate whether this is a player or AI skin.
   • In non‑MetaHuman mode, set HeadActor (single vs separate head) and Skeleton (UE4/UE5/MetaHuman) appropriately.
   • Optionally enable UseMutablePlugin to create a Mutable object and, in MetaHuman mode, enable OprimizaMaterials to optimize materials.
4. Press the main Generate button.

On a successful run, the tool:

• Creates or updates the BP_ItemData, inventory entry and skin clarification DataAsset for the new skin.
• Creates BP_FaceComponent or BP_Face_Mutable as needed when a separate head is required.
• Performs skeleton replacement based on the configured skeleton type.
• Optimizes MetaHuman materials if OprimizaMaterials is enabled.
• Optionally creates a UCustomizableObject for Mutable setups.
• Registers the new skin in DA_CharacterSkinsContainer or DA_AI_SkinsContainer by adding a reference to the created BP_ItemData.

Limitations and Caveats

There are several important limitations and caveats to be aware of when using CharacterAssistant.

• No validation or error messages
  The utility does not currently provide explicit error messages or validation feedback. If required fields such as Body mesh or Icon are not configured correctly, the tool may still generate assets, but they can be incomplete or misconfigured without an obvious warning.

• Asset overwrite behavior
  There is no built-in duplicate protection. If assets with the generated names already exist, they may be overwritten when the Generate button is pressed, which can lead to data loss if not tracked in version control.

• Manual material work for non‑MetaHuman
  Non‑MetaHuman skins do not receive automatic material optimization. Designers must manually wire MF_Mannequin_OpacityMask and ensure appropriate blend modes if they want these skins to participate in opacity-based visual effects.

• Mutable configuration remains manual
  While CharacterAssistant creates the UCustomizableObject for Mutable-enabled skins, it does not set up any parameters or connections inside that object. All Mutable configuration must be done by hand after asset creation.

Despite these limitations, CharacterAssistant significantly reduces the amount of manual editor work required to add new skins. It centralizes naming, skeleton binding, basic material setup and container registration, which helps keep the skin pipeline consistent and less error-prone.

---

Related Docs

• docs/systems/character-customization-and-skins.md – runtime character customization and skins system (containers, BP_CharacterSkinComponent, wardrobe UI, Mutable parameters).
  
• docs/how-to/characters/how-to-add-player-skin-metahuman.md – step-by-step guide for adding a MetaHuman-based player skin using CharacterAssistant.
  
• docs/how-to/characters/how-to-add-player-skin-non-metahuman.md – step-by-step guide for adding a non‑MetaHuman player skin using CharacterAssistant.
  
• docs/reference/data-assets-reference.md – reference for skin-related DataAssets such as BP_Skins_Data_Master, BP_CharacterSkinData, BP_PlayerSingleMeshSkin, BP_PlayerSeparatedMeshSkin, BP_BotSingleMeshSkin, BP_BotSeparatedMeshSkin (when available).