Character
Character API — 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
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.
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:
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
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:
First, search for the stat in
CustomStatDefinitionsfor the given CharacterIDIf not found — use the global
StatDefinitionsIf 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:
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
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
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:
Verify that the character is allowed (
IsAllowedCharacter)Verify that the character is activated (Level ≥ 1) — except for Main
Verify prerequisites (
Requirements)Consume the resource and increase the level
3.4. Character Level Upgrade (UpgradeCharacterLevel)
The character level (star) upgrade process:
Determine the current level (0 if the character has not been created yet)
Look up the next level config (Custom → Global)
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
IsEquippedon 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
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
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
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.
Last updated