# API

**Assembly:** `Spark.CharacterCustomization` **Interface:** `ICharacterCustomizationPlugin` **Implementation:** `CharacterCustomizationPlugin`

## Interface

```csharp
public interface ICharacterCustomizationPlugin
{
    // Database queries
    List<CustomizationCategoryEntry> GetAllCategories();
    CustomizationCategoryEntry GetCategory(string categoryId);
    List<CustomizationElementEntry> GetElementsInCategory(string categoryId);
    CustomizationElementEntry GetElement(string elementId);
    List<CustomizationColorEntry> GetColorsInCategory(string categoryId);
    CustomizationColorEntry GetColor(string colorId);
    List<CustomizationPresetEntry> GetAllPresets();
    CustomizationPresetEntry GetPreset(string presetId);

    // Customization operations
    bool ApplyElement(string entityId, string elementId);
    bool DeactivateElement(string entityId, string elementId);
    bool ApplyColor(string entityId, string colorId, Color? color = null);

    // State
    CustomizationState GetCustomizationState(string entityId);
}
```

## Database Entries

### CustomizationCategoryEntry

Extends `SparkDatabaseEntry`. Groups customization options (Hair, Face, Skin, etc.).

| Field       | Type | Description         |
| ----------- | ---- | ------------------- |
| `sortOrder` | int  | Display order in UI |

### CustomizationElementEntry

Extends `SparkDatabaseEntry`. A single customization option within a category.

| Field        | Type                       | Description      |
| ------------ | -------------------------- | ---------------- |
| `category`   | CustomizationCategoryEntry | Parent category  |
| `isRequired` | bool                       | Must be selected |
| `sortOrder`  | int                        | Display order    |

### CustomizationColorEntry

Extends `SparkDatabaseEntry`. A material-based color option.

| Field                  | Type                            | Description                           |
| ---------------------- | ------------------------------- | ------------------------------------- |
| `materialPropertyName` | string                          | Shader property (e.g., "\_BaseColor") |
| `colorOptions`         | List\<CustomizationColorOption> | Available colors                      |
| `sortOrder`            | int                             | Display order                         |

### CustomizationPresetEntry

Extends `SparkDatabaseEntry`. A complete preset configuration.

| Field            | Type                           | Description        |
| ---------------- | ------------------------------ | ------------------ |
| `presetElements` | List\<PresetCategoryData>      | Element selections |
| `presetColors`   | List\<PresetCategoryColorData> | Color selections   |

## State Classes

### CustomizationState

| Field      | Type                | Description               |
| ---------- | ------------------- | ------------------------- |
| `elements` | List\<ElementState> | Active element selections |
| `colors`   | List\<ColorState>   | Active color selections   |

### ElementState

| Field               | Type   | Description                  |
| ------------------- | ------ | ---------------------------- |
| `elementId`         | string | Selected element             |
| `activeOptionIndex` | int    | Active option within element |

### ColorState

| Field          | Type   | Description          |
| -------------- | ------ | -------------------- |
| `colorId`      | string | Color entry ID       |
| `currentColor` | Color  | Selected color value |

## Events

| Event                              | Fields                          | Description         |
| ---------------------------------- | ------------------------------- | ------------------- |
| `CustomizationElementAppliedEvent` | EntityId, ElementId, CategoryId | Element activated   |
| `CustomizationElementRemovedEvent` | EntityId, ElementId, CategoryId | Element deactivated |
| `CustomizationColorChangedEvent`   | EntityId, CategoryId, NewColor  | Color changed       |

## Commands

| Command                            | Fields                      | Description            |
| ---------------------------------- | --------------------------- | ---------------------- |
| `ApplyCustomizationElementCommand` | EntityId, ElementId, Color? | Apply element or color |

## Components

### CharacterCustomizationEntity

MonoBehaviour managing customization on a character.

**Initialization Methods:**

```csharp
void InitializeForPreview()      // Preview mode (character creation)
void InitializeFromSave()        // Load from save data
void InitializeFromPreset(CustomizationPresetEntry preset)
```

**Customization Methods:**

```csharp
void ApplyDefaultCustomization()
void RandomizeCustomization()
void ActivateElement(string elementId)
void DeactivateElement(string elementId)
void ActivateElementOption(string elementId, int optionIndex)
void ActivateColor(string colorId, Color? color = null)
void ActivateElementOptionRespectingEquipment()  // Equipment integration
```

**State Methods:**

```csharp
CustomizationState GetCurrentState()
void SaveCustomization()
void LoadCustomization()
void ReapplyCustomization()
```

**Events:** `OnElementActivated`, `OnElementDeactivated`, `OnColorActivated`, `OnColorChanged`

## Save Data

### CharacterCustomizationSaveData

Extends `SaveDataEntry`.

| Field            | Type                | Description              |
| ---------------- | ------------------- | ------------------------ |
| `playerElements` | List\<ElementState> | Saved element selections |
| `playerColors`   | List\<ColorState>   | Saved color selections   |

**Methods:**

```csharp
void SavePlayerCustomization(CustomizationState state)
CustomizationState GetPlayerCustomization()
```

## Usage

```csharp
var customization = Spark.GetPlugin<ICharacterCustomizationPlugin>();
if (customization != null)
{
    // Get categories
    var categories = customization.GetAllCategories();

    // Get elements in a category
    var hairOptions = customization.GetElementsInCategory("hair");

    // Apply an element
    customization.ApplyElement(entityId, "hair_long");

    // Apply a color
    customization.ApplyColor(entityId, "hair_color", Color.red);

    // Apply a preset
    var preset = customization.GetPreset("default_warrior");
    // Use CharacterCustomizationEntity.InitializeFromPreset(preset)

    // Get current state
    var state = customization.GetCustomizationState(entityId);
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkframework.dev/documentation/developer-guide/plugins/customization/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.