Character Customization System

Introduction

The BlinkBox Character Customization system is a robust, modular framework for Unity designed to allow players to customize their in-game avatars. It supports cloud saving, multiplayer synchronization (Photon), and bot customization.

Key Features

• Modular Clothing System: Separate slots for Head, Face, Chest, Legs, Foot, and Accessories.
• Cloud Persistence: Saves player customization to a MySQL database via PHP.
• Multiplayer Sync: Automatically synchronizes character appearance across the network using Photon PUN.
• Bot Support: Easily apply random or specific customizations to AI bots.
• Gender Support: Built-in support for Male, Female, and Unisex items.
• ScriptableObject Architecture: Easy to manage items and data through the Unity Inspector.

Setup & Installation

Follow these steps to integrate the Character Customization system into your project.

1. Scene Setup

1. Ensure you have the CharacterCustomizer prefab in your scene. This is the central manager.
2. Assign the `CharacterCustomizerData` asset to the `CharacterCustomizer` component in the Inspector.

2. Player Setup

To make a character customizable:

1. Attach the CharacterCustomizationPlayer script to your player prefab.
2. Assign the CharacterData asset that corresponds to this character (e.g., Male or Female data).
3. Important: Assign the references for each body part array (Head, Face, Chest, etc.) in the inspector. These should correspond to the `ClothItem` components on the child objects of your character mesh.

3. Handling Multiple Characters (Male/Female)

If your player prefab contains multiple character models (e.g., a Male and a Female mesh) that need to be swapped based on selection:

1. Attach the CharacterActivationManager component to the parent object containing the character meshes.
2. This script automatically detects all child CharacterCustomizationPlayer components.
3. It listens for character change events and activates the correct GameObject based on the currently selected Character ID.

Core Components

CharacterCustomizer.cs

This is the singleton manager (CharacterCustomizer.Instance). It handles the global state, data loading/saving, and bot generation.

• Data Handling: Manages `CharacterCustomizerData` containing all items.
• Networking: Handles connection events to initialize character data after Photon connection.
• Bot Factory: Provides methods like GetBot(Team team) to spawn customized bots.

CharacterCustomizationPlayer.cs

The component attached to the actual character model. It is responsible for the visual representation.

• Equipping Items: The EquipItem(ClothsItemInfo item) method is the primary way to change appearance.
• Data Application: Parses the JSON data string from `CharacterData` and applies it to the model.
• Validation: Checks gender compatibility before equipping items.

Data Structures

The system relies heavily on ScriptableObjects for data management.

ClothsItemInfo

Defines a single customization item. Create these in Assets/Addons/BlinkBox/CharacterCustomization/Data/ClothsItem/.

CharacterData

Defines a specific character (e.g., "Standard Male", "Standard Female"). Contains base stats and the persistent JSON string for their current look.

CharacterCustomizerData

The master database. Must contain references to ALL `ClothsItemInfo` assets and `CharacterData` assets used in the game.

Adding Content

Method 1: Using Editor Tools (Recommended)

1. Open the Cloth Item Editor window.
2. Switch to the "Create New" tab.
3. Fill in the item details (Name, Type, Gender, Icon).
4. Click Create Item. The tool will automatically create the asset and assign a unique ID.

Method 2: Manual Creation

1. Import Mesh: Import your clothing mesh and add it as a child of your character prefab (skinned to the armature).
2. Add Component: Add the ClothItem script to this new GameObject.
3. Create Data: Right-click in Project view -> BlinkBox/Character Customizer/ClothsItem.
   • Set a unique ID.
   • Set the Name, Type, Gender, and Icon.
4. Link Data: Drag the created `ClothsItemInfo` into the ClothItem component on the mesh.
5. Register: Add the `ClothsItemInfo` to the `CharacterCustomizerData` list.
6. Player Setup: Add the `ClothItem` reference to the appropriate array (e.g., Chest array) in the `CharacterCustomizationPlayer` component.

Editor Tools

The addon includes custom editor windows to manage content efficiently.

Cloth Item Editor

Menu: BlinkBox > Character Customizer > Cloth Item Editor

This is your primary hub for managing item data.

• Browse Items: View, filter, and search all existing items.
• Create New: Easily create new item assets with auto-ID generation.
• Statistics: View distribution of items by type and rarity.

Cloth Item Assigner

Menu: BlinkBox > Character Customizer > Cloth Item Assigner

Helps assign item data to GameObjects in your scene or prefabs.

• Select a GameObject in the scene.
• Open the Assigner window.
• Find the item definition you want to link.
• Click assign to automatically add the ClothItem component and link the data.

UI System

The CharacterCustomizationUI script manages the customization interface.

• Dynamic Loading: Automatically populates lists based on the `CharacterCustomizerData`.
• Filtering: Filters items by the selected gender.
• Categorization: Tabs for Head, Face, Chest, etc., switch the displayed list.

To modify the UI, edit the Character Customization UI prefab. Ensure buttons are linked to the LoadItems methods in the script.

API Reference

Common methods for developers integrating the system.

CharacterCustomizer

// Get the singleton instance
CharacterCustomizer.Instance

// Get a random bot (useful for AI spawners)
GameObject bot = CharacterCustomizer.GetBot(Team.Team1);

// Get a specific bot by index
GameObject bot = CharacterCustomizer.GetBotByIndex(Team.Team1, 0);

CharacterCustomizationPlayer

// Equip an item (saves automatically)
public void EquipItem(ClothsItemInfo item);

// Equip temporarily (for previews/bots, does not save)
public void TempEquipItem(ClothsItemInfo item);

// Force reload from saved data
public void LoadSavedCharacterData();