# Character

## [Character API](https://docs.idosgames.com/api/api-v2/character) — Configuration & Logic

***

### 1. Overview

The Character system allows you to create and manage characters in a game. Every player has a main character (Main) available immediately, and can unlock additional characters, upgrade their stats, increase their level (star rank), and equip items.

The system supports the following features:

* **Characters** — creation and unlocking of heroes (default Main + additional ones)
* **Stats** — configurable attributes with currency-based upgrades
* **Levels (Stars)** — ranking up characters, which increases stat limits
* **Equipment** — equipping/unequipping items from inventory into character slots
* **Customization** — individual stat and level settings for specific characters

<figure><img src="/files/fgwH5xCx77bK2KqzcUoM" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Qlf2yrl8XZcynqzO0wCc" alt=""><figcaption></figcaption></figure>

<https://platform.idosgames.com/TitleID/liveops/character>

***

### 2. Configuration Structure (Character Definitions)

All character settings are stored in the `CharacterDefinitions` section of the title configuration.

| Field                     | Type                            | Description                                                                           |
| ------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
| `AllowedCharacterIDs`     | List\<string>                   | List of allowed character IDs (excluding Main). Defines which heroes can be unlocked. |
| `AllowedEquipmentSlotIDs` | List\<string>                   | List of allowed equipment slots (e.g., Helmet, Armor, Weapon).                        |
| `StatDefinitions`         | List\<StatDefinition>           | Global stat definitions. Applied to all characters by default.                        |
| `CustomStatDefinitions`   | Dict\<string, List>             | Custom stats for specific characters. Key = CharacterID.                              |
| `LevelDefinitions`        | List\<CharacterLevelDefinition> | Global level (star) settings: cost, multipliers.                                      |
| `CustomLevelDefinitions`  | Dict\<string, List>             | Custom levels for specific characters. Key = CharacterID.                             |

***

#### 2.1. Allowed Section — Permitted Characters and Slots

**Allowed CharacterID**

This is the list of identifiers for additional characters that players can unlock. The main character "Main" is always permitted and does not need to be added to this list.

> 💡 If your game only has one character (Main), leave this list empty.

**How to add:** in the admin panel, enter a unique CharacterID (e.g., `warrior`, `mage`, `archer`) into the input field and click **+ Add**.

**Allowed Equipment SlotID**

The list of allowed slots for equipping items. Each SlotID defines a location where an item can be equipped (Helmet, Armor, Weapon, Ring, etc.).

> ⚠️ The EquipItems operation verifies that the specified slot is in this list. If the slot has not been added, equipping into it will be rejected.

***

#### 2.2. Stats Section — Character Attributes

**Base Stats (Global Stats)**

Base stats apply to all characters. Each stat (`StatDefinition`) has the following fields:

| Field               | Type                   | Description                                                                                  |
| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
| `StatID`            | string                 | Unique stat identifier (e.g., Health, Damage, AttackSpeed)                                   |
| `DisplayName`       | string                 | Display name for the UI                                                                      |
| `MaxLevel`          | int                    | Base maximum upgrade level for the stat. Can be increased by the character level multiplier. |
| `Weight`            | int                    | Stat weight for calculating character Power                                                  |
| `BaseCostResource`  | ItemOrCurrency         | Resource used to pay for upgrades (VirtualCurrency or Item)                                  |
| `BaseCost`          | long                   | Base cost for the first level upgrade                                                        |
| `CostScalingFactor` | double                 | Cost growth coefficient                                                                      |
| `BaseStatValue`     | double                 | Base stat value at level 1                                                                   |
| `StatScalingFactor` | double                 | Stat value growth coefficient per level                                                      |
| `Requirements`      | List\<StatRequirement> | Prerequisites: other stats that must reach a certain level before upgrading                  |
| `Description`       | string                 | Description for the UI                                                                       |
| `IconPath`          | string                 | Path to the stat icon                                                                        |

**Upgrade Cost Formula**

```
Cost(N) = Round( BaseCost × (1 + CostScalingFactor × (N - 1)) )
```

**Example:** if `BaseCost = 100`, `CostScalingFactor = 0.5`, then:

* Upgrade to level 1 costs **100**
* Upgrade to level 2 costs **150**
* Upgrade to level 10 costs **550**

**Custom Stats for CharacterID**

Custom stats allow you to override stat parameters for a specific character. The lookup logic is:

1. First, search for the stat in `CustomStatDefinitions` for the given CharacterID
2. If not found — use the global `StatDefinitions`
3. If not found anywhere — error

> 💡 This is useful when one character should have a different upgrade cost or a different MaxLevel. For example, "warrior" might have MaxLevel for Health = 150, while Main = 99.

***

#### 2.3. Levels Section — Character Levels (Stars)

Each character has a Level that can be increased. Levels determine the maximum stat upgrade limit and strengthen the character through multipliers.

**Base Levels**

Global level settings applied to all characters. Each level (`CharacterLevelDefinition`) contains:

| Field                    | Type                  | Description                                                                        |
| ------------------------ | --------------------- | ---------------------------------------------------------------------------------- |
| `Level`                  | int                   | Level number (1, 2, 3... = "Star")                                                 |
| `UpgradeCost`            | List\<ItemOrCurrency> | List of resources required to reach this level (currency, items, shards)           |
| `GlobalStatMultiplier`   | double                | Global stat power multiplier (default 1.0)                                         |
| `StatMaxLevelMultiplier` | float                 | MaxLevel multiplier for stats. For example, 1.5 will increase MaxLevel=100 to 150. |

**Effective MaxLevel Formula**

```
EffectiveMaxLevel = (int)( StatDef.MaxLevel × LevelDef.StatMaxLevelMultiplier )
```

This means that as the character's level increases, new stat levels become available.

**Custom Levels for CharacterID**

Similar to Custom Stats, you can set unique level configurations for a specific character: different upgrade costs and different power multipliers.

The lookup logic is the same: Custom first, then Global.

**Level Configuration Example**

| Level | Cost                  | GlobalStatMultiplier | StatMaxLevelMult |
| ----- | --------------------- | -------------------- | ---------------- |
| 1     | 100 Gold              | 1.0                  | 1.0              |
| 2     | 500 Gold + 10 Shards  | 1.2                  | 1.5              |
| 3     | 2000 Gold + 50 Shards | 1.5                  | 2.0              |

***

### 3. API Logic

#### 3.1. Main Character

The "Main" character is available to every player automatically. It does not need to be unlocked and always has a level of at least 1. If no database record exists yet, the system will create one automatically on the first stat upgrade.

#### 3.2. Unlocking Characters

Additional characters start at level 0 (locked / "greyed out"). To activate a character, the player must call `UpgradeCharacterLevel` (transitioning from level 0 to 1), paying the cost defined in the configuration.

> ⚠️ While a character is at level 0, stat upgrades and equipment are unavailable.

#### 3.3. Stat Upgrade (UpgradeStatLevel)

The stat upgrade process for one level includes:

1. Verify that the character is allowed (`IsAllowedCharacter`)
2. Verify that the character is activated (Level ≥ 1) — except for Main
3. Verify prerequisites (`Requirements`)
4. Consume the resource and increase the level

#### 3.4. Character Level Upgrade (UpgradeCharacterLevel)

The character level (star) upgrade process:

1. Determine the current level (0 if the character has not been created yet)
2. Look up the next level config (Custom → Global)
3. Consume the resource and increase the level

> ⚠️ **Important:** when transitioning from level 0 to 1, the full character structure is created (StatLevels, Equipment, Experience).

#### 3.5. Equipment (EquipItems / UnequipItems)

The equipment system links items from the player's inventory to character slots.

**EquipItems:**

* Verifies the slot is allowed (`AllowedEquipmentSlotIDs`)
* Verifies the item exists in inventory and is not equipped elsewhere
* If the slot already has an item — automatically unequips the old one

**UnequipItems:**

* Accepts a list of slots to clear
* Removes the entry from the character's slot
* Resets `IsEquipped` on the item in inventory

**UnequipAllCharacters:**

* Removes all equipment from all characters in a single operation
* Useful for resets or reconfiguration

***

### 4. Step-by-Step Configuration Guide

#### Step 1: Add Characters

If your game supports multiple characters, add their IDs in the **Allowed CharacterID** section. For example: `warrior`, `mage`, `archer`. The Main character does not need to be added.

#### Step 2: Configure Equipment Slots

Add the required slots in the **Allowed Equipment SlotID** section. Example slots: `Helmet`, `Armor`, `Weapon`, `Shield`, `Boots`, `Ring`, `Amulet`.

#### Step 3: Create Base Stats

In the **Base Stats** section, click **+ Add** and fill in the parameters for each stat. Required fields: `StatID`, `MaxLevel`, `BaseCost`, `CostScalingFactor`, `BaseCostResource`.

> 💡 We recommend starting with 2–4 base stats (Health, Damage, Defense, Speed) and adding more as the game evolves.

#### Step 4: Configure Levels (Stars)

In the **Base Levels** section, add level configurations from 1 to the maximum. For each level, specify the cost (`UpgradeCost`) and multipliers.

#### Step 5: Customization (Optional)

If you need unique settings for a specific character:

* Select a CharacterID from the allowed list
* Add custom stats with different parameters (**Custom Stats for CharacterID**)
* Add custom levels if a different upgrade cost is needed (**Custom Levels for CharacterID**)

#### Step 6: Save

After completing all settings, click the **Save All (server)** button. Changes are stored locally until saved to the server. The **Refresh** button allows you to discard local changes and reload the current data from the server.

***

### 5. Player Data Structure

Character data is stored in the `Characters` field of the `UserData`. It is a dictionary where the key is the CharacterID and the value is a `CharacterModel`.

#### CharacterModel

| Field         | Type                        | Description                                            |
| ------------- | --------------------------- | ------------------------------------------------------ |
| `CharacterID` | string                      | Character identifier ("Main" or GUID)                  |
| `Level`       | int                         | Current level (star). 0 = locked, 1+ = active          |
| `Experience`  | long                        | Character experience (reserved for future expansion)   |
| `Power`       | int                         | Character power (calculated based on stats and Weight) |
| `StatLevels`  | Dict\<string, int>          | Current stat levels. Key = StatID, value = level       |
| `Equipment`   | Dict\<string, EquippedItem> | Equipped items. Key = SlotID, value = EquippedItem     |

#### EquippedItem

| Field            | Type     | Description                                                  |
| ---------------- | -------- | ------------------------------------------------------------ |
| `ItemID`         | string   | Item identifier from the catalog                             |
| `ItemInstanceID` | string   | Reference to the specific instance in the player's inventory |
| `CatalogVersion` | string   | Catalog version or name of the item                          |
| `EquippedAt`     | DateTime | Date/time when the item was equipped                         |

***

### 6. API Actions

| Action                    | Description                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------ |
| `GetCharacterDefinitions` | Returns the full character configuration (stats, levels, slots)                      |
| `GetUserCharacters`       | Returns the current player's character dictionary                                    |
| `UpgradeStatLevel`        | Upgrades the specified stat by 1 level. Requires `CharacterID` and `StatID`          |
| `UpgradeCharacterLevel`   | Increases the character's level (star) by 1. Requires `CharacterID`                  |
| `EquipItems`              | Equips items into character slots. Requires `CharacterID` and `ItemsToEquip`         |
| `UnequipItems`            | Unequips items from the specified slots. Requires `CharacterID` and `UnequipSlotIDs` |
| `UnequipAllCharacters`    | Removes all equipment from all of the player's characters                            |

***

### 7. Usage Examples

#### Example 1: Simple Game with One Character

* **Allowed CharacterID:** empty (Main only)
* **Allowed Equipment SlotID:** Weapon, Armor, Helmet
* **Base Stats:** Health (MaxLevel=50), Damage (MaxLevel=50), Defense (MaxLevel=50)
* **Base Levels:** not needed (single character, stat upgrades only)

#### Example 2: RPG with Multiple Characters

* **Allowed CharacterID:** warrior, mage, archer
* **Allowed Equipment SlotID:** Helmet, Armor, Weapon, Shield, Ring, Amulet
* **Base Stats:** Health, Damage, AttackSpeed, Defense (MaxLevel=99)
* **Custom Stats:** mage — MagicPower (MaxLevel=120), warrior — BlockChance
* **Base Levels:** 1–5 with increasing cost and StatMaxLevelMultiplier
* **Custom Levels:** mage has cheaper upgrades, warrior has more expensive upgrades but a stronger multiplier

***

### 8. FAQ

**Q: Can I delete a stat after players have already upgraded it?** A: Technically yes, but player data will remain in the database. It is recommended not to delete it, but to set `MaxLevel = 0` to freeze further upgrades.

**Q: How does the Custom over Global priority work?** A: The system first looks for the setting in Custom (for the specific CharacterID). If not found, it falls back to Global. This applies to both Stats and Levels.

**Q: Can one item be equipped on multiple characters?** A: No. An item can only be equipped on one character at a time (`IsEquipped` flag in inventory). To transfer it, you must unequip it first.


---

# 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.idosgames.com/liveops/character.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.