Character Customization and Skins System

Purpose and Scope

The character customization and skins system controls how player and AI characters change their visual appearance: base skins, MetaHuman/Mutable customization, face components, wardrobe stations and weapon/armor skins. It is built on top of item data assets, dedicated skin data assets, the BP_CharacterSkinComponent and UI wardrobe widgets. All core customization parameters are fully replicated in multiplayer.

---

Runtime Architecture

Core Components and Actors

• BP_CharacterSkinComponent
  Main runtime component responsible for applying and switching character skins (player and AI). It reads skin item data, corresponding skin clarification DataAssets and, if applicable, Mutable parameters and face components, then configures meshes, animation blueprints and retarget assets on the character.

• BP_FaceComponent
  Actor used for head/face when head is a separate skeletal mesh from the body. It provides a dedicated skeletal mesh and animation instance for facial animations (for example, during dialogues).

• BP_Face_Mutable
  Child of BP_FaceComponent for Mutable‑based heads. It adds HeadMutableComponent to initialize and drive a Mutable head object.

• BP_EquipmentPoint
  World actor used as a wardrobe station (like a wardrobe in a safehouse). Interacting with this actor opens the wardrobe UI where the player can change skin, clothing and weapons.

Data Assets and Containers

• DA_CharacterSkinsContainer : BP_DA_CharacterSkins
  DataAsset that stores all skin DataAssets available for the player.

  • Skins : TArray<DT_ItemData> – list of item data rows (or references) representing all player skins.

• DA_AI_SkinsContainer : BP_DA_CharacterSkins
  Same structure as above but for AI skins. AI characters pick their skins from this container.

• BP_ItemData (skin items)
  Each skin is represented as a normal BP_ItemData‑based item DataAsset. The inventory‑type DataAsset includes:

  • Standard item fields (name, description, categories).
    
  • Inventory Texture – icon/preview used in wardrobe UI for this skin.

Skins are never stored as inventory items. The wardrobe always shows the full list of skins from DA_CharacterSkinsContainer, regardless of current inventory contents.

---

Skin Data Assets Hierarchy

Skins use a dedicated clarification DataAsset hierarchy to describe their meshes, Mutable capability and usage context.

Base Skin Master: BP_Skins_Data_Master

BP_Skins_Data_Master is the master DataAsset class for all skin clarification assets. It does not define parameters itself; it exists as a common parent so that all specific skin types share a common base.

BP_CharacterSkinData

BP_CharacterSkinData inherits from BP_Skins_Data_Master and defines common high‑level skin properties:

• MeshSetup : ESkinMeshSetup

  • SingleMesh – body and head are one skeletal mesh.
    
  • SeparateMeshes – body and head are separate meshes (head uses a face component).

• LoadType : E_AssetLoadType

  • Bot – hard reference, loaded immediately. Used for AI skins.
    
  • Player – async load (soft reference), used to reduce loading times for player skins.

• bUseMutableSkin : bool
  If true, this skin uses the Mutable system and can be customized at runtime (body/head parameters, materials, colors). If false, it uses static meshes with fixed configuration.

• Retarget Asset Tag : FName
  Tag used to select an IK Retargeter in the character’s animation blueprint (ABP_GenericRetarget via IKRetargeter_Map). When the skin changes, BP_CharacterSkinComponent uses this tag to pick the correct retarget asset.

• HandsModifier
  Optional offsets/rotations for specific hand bones. Usually left unused; reserved for fine‑tuning hand pose per skin.

This base class is then specialized depending on whether the skin is Mutable, player‑only or AI‑only, and whether it uses single or separate meshes.

Mutable Skins: BP_MutableCharacter

BP_MutableCharacter inherits from BP_CharacterSkinData (via BP_Skins_Data_Master) and is used for skins that rely on the Mutable plugin.

Parameters:

• Mutable Body Object : UCustomizableObject*
  Mutable object for the body (and possibly head) mesh. Used to generate and update the skeletal mesh from parameter values.

• ABP Face : TSubclassOf<UAnimInstance>
  Animation blueprint class for the face skeletal mesh component. Required so dialogues and other systems can play face animations.

When bUseMutableSkin is true and the skin uses BP_MutableCharacter, BP_CharacterSkinComponent and BP_Face_Mutable read Mutable parameters (via MutableBodyParameters/MutableHeadParameters) and update the generated meshes accordingly.

Player Single Mesh Skins: BP_PlayerSingleMeshSkin

Used for player skins where body and head are one skeletal mesh.

• Parent class: BP_PlayerSingleMeshSkin (inherits from BP_CharacterSkinData).
  
• Parameter:
  • Body : TSoftObjectPtr<USkeletalMesh> – soft reference to the combined body+head mesh.

This setup is simpler and does not use a separate face component.

Player Separated Mesh Skins: BP_PlayerSeparatedMeshSkin

Used for player skins where body and head are different meshes.

• Parent class: BP_PlayerSeparatedMeshSkin.
  
• Parameter:
  • Head : TSoftObjectPtr<BP_FaceComponent> – soft actor reference to a face component type used as the head.

The body is configured elsewhere, while the head is provided by a specialized BP_FaceComponent (or BP_Face_Mutable for Mutable heads).

AI Single Mesh Skins: BP_BotSingleMeshSkin

Used for AI characters with a single combined body+head mesh.

• Parent class: BP_BotSingleMeshSkin.
  
• Parameter:
  • Body : USkeletalMesh* – direct skeletal mesh reference (hard‑loaded).

These skins typically use LoadType = Bot and avoid async loading.

AI Separated Mesh Skins: BP_BotSeparatedMeshSkin

Used for AI characters with separate head mesh.

• Parent class: BP_BotSeparatedMeshSkin.
  
• Parameter:
  • Head : BP_FaceComponent* – actor reference to a face component for the AI head.

---

Mutable Parameters and F_StringTwoParams

Runtime customization parameters for Mutable skins are stored in BP_CharacterSkinComponent:

• MutableBodyParameters : TArray<F_StringTwoParams>
  
• MutableHeadParameters : TArray<F_StringTwoParams>

Each F_StringTwoParams entry:

• Parameter : FString – unique parameter name.
  
• ParameterType : EMutableParameter – which type field is valid.
  
• BoolParameterValue / IntegerParameterValue / FloatParameterValue / ColorParameterValue / TextureParameterValue / TransformParameterValue.

These arrays hold the full runtime state of both body and head Mutable parameters. They are:

• Applied by BP_CharacterSkinComponent to the Mutable Body Object in BP_MutableCharacter.
  
• Used by BP_Face_Mutable via HeadMutableComponent to configure the head’s Mutable object.

The same arrays are saved and loaded via BP_SaveGame_Player.BodyParams and HeadParams, keeping appearance consistent across sessions.

---

Wardrobe and Customization UI

Wardrobe Station: BP_EquipmentPoint

BP_EquipmentPoint is the world actor that acts as a wardrobe/customization station, similar to a wardrobe in a safe house. When the player interacts with it:

• The game opens an in‑game wardrobe UI.
  
• The player can change:
  • character skin,
    
  • equipped clothing,
    
  • equipped weapons.

Wardrobe Widgets

There are two main wardrobe widgets:

• WBP_Wardrobe_Placeholder_Menu
  Used in the pre‑game menu (before starting a session). It lets the player configure initial appearance and equipment.

• WBP_Wardrobe_Placeholder_InGame
  Used at runtime when interacting with BP_EquipmentPoint. It is tied to the live inventory and equipment of the player.

Workflow:

1. The wardrobe UI lists all available skins using DA_CharacterSkinsContainer.Skins plus icons from each skin’s BP_ItemData.InventoryTexture.
   
2. The player selects a skin, clothing and weapons in the UI.
   
3. When the player presses Apply, WBP_Wardrobe_Placeholder_InGame sends the chosen configuration to the player controller.
   
4. The player controller forwards this data to BP_CharacterSkinComponent and equipment components to:
   • switch the character skin,
     
   • update equipped clothing,
     
   • update equipped weapons.

Skins are always available in the wardrobe based on DA_CharacterSkinsContainer; they are not unlocked via inventory items.

---

Weapon and Clothing Skins

Weapon and clothing skins are handled through their own item DataAssets and clarification assets; there is no separate global “skin system” for them.

• Weapon skins
  • Configured via weapon item DataAssets and their clarification info.
    
  • When the player changes a skin in inventory or via BP_EquipmentPoint, the weapon actor receives a call to update its materials.
    
  • The weapon’s skeletal mesh materials are switched at runtime to the chosen skin variant.
• Clothing/armor skins
  • Defined via armor/clothing item DataAssets and their clar‑data.
    
  • Wardrobe UI and equipment components select which clothing items are worn; visual representation (mesh/skin) is driven by the item’s clar data.

The character customization and skins system focuses on the base character skin and Mutable parameters; weapon and clothing skins reuse the inventory and equipment system’s own configuration.

---

Multiplayer Behavior

All appearance data is fully replicated in multiplayer:

• Active skin selection (via BP_ItemData + skin DataAsset).
  
• Mutable body and head parameters (via MutableBodyParameters and MutableHeadParameters).
  
• Face component state (including switching to BP_Face_Mutable when needed).
  
• Clothing and weapon skins (through the inventory/equipment system’s replication).

There are no special restrictions: all customization options available in singleplayer are also available and synchronized in multiplayer. Server authority over equipment and skins ensures that other clients see the correct appearance at all times.

---

Typical Flows

Changing Skin in Pre‑Game Menu

1. The game loads DA_CharacterSkinsContainer and lists all skins.
   
2. The player uses WBP_Wardrobe_Placeholder_Menu to pick a skin.
   
3. The chosen skin is stored in GameInstance or a similar pre‑game configuration.
   
4. When the session starts, BP_CharacterSkinComponent applies that skin and, if needed, initializes Mutable parameters.

Changing Skin at Wardrobe Station

1. The player interacts with BP_EquipmentPoint.
   
2. WBP_Wardrobe_Placeholder_InGame opens and shows all available skins and equipped gear.
   
3. The player selects a new skin and optionally changes clothes and weapons.
   
4. On Apply, the player controller sends the new configuration to the character.
   
5. BP_CharacterSkinComponent:
   • Resolves BP_ItemData → skin clarification DataAsset (BP_CharacterSkinData/its children).
     
   • Switches meshes, retarget asset and face component as required.
     
   • Applies Mutable parameters if bUseMutableSkin is enabled.

Saving and Loading Appearance

1. On save, the save system reads:
   • Current skin item (via BP_ItemData).
     
   • MutableBodyParameters and MutableHeadParameters from BP_CharacterSkinComponent into BodyParams and HeadParams.
     
2. On load, the character skin component:
   • Restores the active skin item.
     
   • Reapplies Mutable parameters to body and head Mutable objects.
     
   • Ensures face component (BP_FaceComponent or BP_Face_Mutable) matches the current skin type.

---

Limitations and Notes

• All skins are always available in the wardrobe; there is no unlock/progression system for skins by default.
  
• Player skin is always defined through BP_ItemData + skin clarification DataAssets; world items are not used to “equip” skins.
  
• Mutable customization relies solely on MutableBodyParameters and MutableHeadParameters; other systems must not attempt to directly modify Mutable meshes.
  
• Weapon and clothing skins are handled by the inventory/equipment system; this document focuses on character base skin and appearance.