> For the complete documentation index, see [llms.txt](https://bizachi-dev.gitbook.io/bullethell-elemental-template/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bizachi-dev.gitbook.io/bullethell-elemental-template/scriptables/create-new-character.md).

# Create new character

To create a CharacterData, right-click inside any project folder, go to Create > BulletHellTemplate > Characters > Character Data.

Remember that this item has to be added to the **Game Instance > Character Data** list in the Login scene.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-dc9ed57427631e189ce40c2ae4a5a9f52e6ef915%2Fgame-character-details.jpg?alt=media" alt="Character details screen"><figcaption><p>Character details in the game: class, rarity, element, stats, skills, skins and items all come from the CharacterData.</p></figcaption></figure>

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-39c905d6f39a41af6a38555751153334c88d4931%2Fv16-character-data-general.png?alt=media" alt="CharacterData general information"><figcaption></figcaption></figure>

### General Information

**Character Id**: unique number of the character. Every save of the character (level, skins, upgrades, equipped items) uses it, so never change it after release. At least one character must have **Is Unlock** checked, and the first unlocked character in the Game Instance list is selected for new players.

**Character Name** / **Name Translations**: name shown in the menus, with one entry per language.

**Character Description** / **Description Translations**: text of the character details screen.

**Character Type**: element of the character. It changes the damage the character deals and receives against other elements. See [Create new Character Type](/bullethell-elemental-template/scriptables/create-new-character-type.md).

**Icon**: portrait used in the menus, lobby and shop.

**Tier Icon**: small badge on the character card of the character list.

**Character Class Type** / **Character Class Translated** / **Character Class Icon**: class name and icon shown in the menus (the demo uses names like Skirmisher, Tank, Marksman, Summoner). It is free text.

**Character Rarity**: Common, Uncommon, Rare, Epic or Legendary. Changes the colors of the character in the menus and the order in the shop.

### Models

**Character Model**: the model prefab of the default skin (see "Setting up the model" below).

**Character Skins**: extra skins. Each skin has an icon, a name (with translations), its own model prefab, **Is Unlocked** for skins owned from the start, and **Unlock Currency Id** and **Unlock Price** to buy it in the character screen.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-8356003440b51ef2d38839d2528cd21eb2449e4b%2Fv16-character-data-skills.png?alt=media" alt="Skills and items"><figcaption></figcaption></figure>

### Skills & Items

**Auto Attack**: the basic attack of the character (a [Skill Data](/bullethell-elemental-template/scriptables/create-new-skill.md)). Its range and width also shape the aim line shown while the player drags the attack button.

**Attack Control**: how the basic attack is used.

* **Inherit**: uses **Default Attack Control** of the Game Instance (the demo uses Manual With Ammo).
* **Automatic**: the character attacks the nearest enemy by itself.
* **Manual**: the player attacks with the attack button (mobile) or the left mouse button (PC). A tap aims at the nearest enemy, a drag aims by hand.
* **Manual With Ammo**: like Manual, but the character has a few charges that reload one by one.

With **Manual With Ammo** three more fields appear:

* **Ammo Charges**: shots available before reloading (default 3).
* **Recharge Seconds**: time to reload one charge. `0` uses the character's Attack Speed, so attack speed bonuses also reload faster.
* **Shot Interval**: shortest time between two shots while charges are left (default 0.25).

See [Attacks, Ammo and Controls](/bullethell-elemental-template/gameplay-systems/attacks-ammo-and-controls.md).

**Skills**: the skills of the skill buttons. The order matters: skill 0 plays the first **Skill Animations** entry of the model, skill 1 the second, and so on. The HUD shows 3 skill buttons.

**Item Slots**: equipment slots of the character. The names must match the **Slot** of the items (the demo uses `Head`, `Armor`, `Pants`, `Shoes`).

**Rune Slots**: rune slots (the demo uses `Rune Universal`, `Rune Defense`, `Rune Attack`, `Rune Support`).

### Unlocked Status

**Is Unlock**: check it for characters the player owns from the start. The others are unlocked through the shop, quests, the battle pass, map rewards, loot boxes or the wheel.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-9e0a1d9af53a457ef9c44ed1d2e24c2458b63700%2Fv16-character-data-exp.png?alt=media" alt="Experience, cost and base stats"><figcaption></figcaption></figure>

### Experience Settings

**Max Level**: highest level of the character.

**Exp Calculation Method**, **Initial Exp**, **Final Exp**: curve used by the **Auto Fill EXP** button to fill **Exp Per Level**.

**Exp Per Level**: XP needed for each level up. You can edit any value by hand after the auto fill.

### Upgrade Cost Settings

**Currency Id**: currency spent to level up the character (the demo uses `UP`).

**Initial Upgrade Cost**, **Final Upgrade Cost**, **Upgrade Cost Calculation Method**: curve used by **Auto Fill Upgrade Cost**.

**Upgrade Cost Per Level**: price of each level up.

### Base Stats

Stats of the character at level 1. See the list of stats below.

**Stats Percentage Increase By Level**: how much the stats grow per character level. `0.05` means +5% per level on HP, regen, leech, MP, damage, defense, shield, move speed and collect range. Attack Speed gets faster by the same rate. Max Stats and Max Skills do not grow.

### Upgrades

Permanent stat upgrades bought in the character screen. Click **Add New Upgrade** to add one.

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2FZ97IU3SZYd2Pi01LhBY0%2FUpgrade.png?alt=media&amp;token=5cb7ea01-fe6b-4eab-b580-b49aacfe7853" alt="Stat upgrade"><figcaption></figcaption></figure>

**Upgrade Name**: name shown in the menus (with translations).

**Stat Type**: the stat that increases. Use one upgrade per stat type.

**Upgrade Max Level**: how many times it can be bought.

**Upgrade Amounts**: amount added at each level. The values add up, so level 3 gives the first three values.

**Upgrade Costs**: price of each level. Both arrays need at least **Upgrade Max Level** values.

**Upgrade Icon**: icon in the menus.

**Currency Tag**: currency spent (default `GO`).

***

### Stats information

| Stat                           | Meaning                                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| **HP**                         | Maximum health.                                                                                |
| **HP Regen**                   | Health regenerated per second.                                                                 |
| **HP Leech**                   | Part of the damage dealt that heals the character: `0.05` = 5%.                                |
| **MP** / **MP Regen**          | Mana and mana per second. Skills can cost mana.                                                |
| **Damage**                     | Damage of the character. A skill deals its Base Damage plus Damage x its Attacker Damage Rate. |
| **Attack Speed**               | Time in seconds between two basic attacks. **Lower is faster.**                                |
| **Cooldown Reduction**         | Percentage removed from skill cooldowns: `10` = 10%.                                           |
| **Critical Rate**              | Chance of a critical hit: `0.3` = 30%.                                                         |
| **Critical Damage Multiplier** | Damage multiplier of a critical hit: `2` = double.                                             |
| **Defense**                    | Flat amount removed from every hit taken, never below the **Min Damage** of the map.           |
| **Shield**                     | Points that absorb damage before HP.                                                           |
| **Move Speed**                 | Movement speed.                                                                                |
| **Collect Range**              | Distance at which drops with auto-collect are picked up.                                       |
| **Max Stats**                  | Number of stat perks the character can hold in a match.                                        |
| **Max Skills**                 | Number of skill perks the character can hold in a match.                                       |

{% hint style="info" %}
The HUD shows up to 5 stat perks and 5 skill perks. If Max Stats or Max Skills plus the slot perks go above that, add more slots to the HUD prefab.
{% endhint %}

***

## Setting up the model (CharacterModel)

<figure><img src="https://215355839-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fc8AVbPtcUOjcVrQx9Eyu%2Fuploads%2Fgit-blob-962bef210356e1c536685b6f848b59ff39e413d2%2Fv16-character-model.png?alt=media" alt="CharacterModel in the Inspector"><figcaption><p>CharacterModel on VincentDefault.prefab.</p></figcaption></figure>

Every character uses the same Animator Controller, `BulletHellTemplate/Res/AnimController/HFSM_Generic.controller`. You do not edit or duplicate it: the **CharacterModel** component replaces its clips with the clips of your character when the game starts. The animation logic runs in a state machine (UnityHFSM) added automatically with the component.

{% stepper %}
{% step %}

#### Create the prefab

Import your model (the shipped characters use **Generic** rigs; Humanoid also works). Create a prefab with an empty root object and the model as a child, like `ThirdPartyResources/Characters/Adventurer/VincentDefault.prefab`.
{% endstep %}

{% step %}

#### Add the Animator

On the root, add an **Animator** with **Controller** = `HFSM_Generic`, the **Avatar** of your model and **Apply Root Motion** off.
{% endstep %}

{% step %}

#### Add CharacterModel and the clips

Add **CharacterModel** to the root and fill the clips (below). Only **Idle Set > Forward** and **Move Set > Forward** are required; missing directions use Forward.
{% endstep %}

{% step %}

#### Link it

Drag the prefab into **Character Model** of the CharacterData (or into a skin's model).
{% endstep %}
{% endstepper %}

### CharacterModel fields

**Animator**: the Animator to drive. Empty uses the one on the same object.

**Use HFSM**: keep it checked.

**Upper Body Mask**: default Avatar Mask for attacks and skills that should only move the upper body, so the legs keep running while the character shoots. With a **Generic** rig the mask must be created from your model's own skeleton (in the Avatar Mask, open **Transform**, import the skeleton of your model and uncheck the pelvis and the legs). A Humanoid mask does not work on a Generic rig.

**Use Runtime Mask Layer**: keep it checked. Masked actions are played on a separate layer, so any mask works with the shared controller.

**Use Showcase Anim / Showcase Anim**: animation played in the menus (character screen, profile, lobby).

**Use Victory Anim / Victory Anim**: animation played when the match is won.

**Idle Set / Move Set**: idle and run animations for 8 directions. With a single Forward clip the character simply turns.

**Attack**: basic attack animation.

**Receive Damage** / **Death**: hit and death animations.

**Skill Animations**: one entry per skill of the CharacterData, in the same order. Check **Use Avatar Mask** on entries that should only move the upper body (shots, casts) and leave it off for full-body moves (dashes, rolls, leaps). An entry can have its own **Mask**.

Each clip entry also has **Speed** (playback speed, 1 is normal) and **Transition** (blend time). A new entry starts with Speed 0, so set it when you add a clip.

**On Enter / On Exit / On Upgrade / On Attack End / On Skill End**: events for your own effects. On Upgrade is called in the character screen after a level up.

{% hint style="success" %}
A skill can force the choice made on the model with **Animation Mask Mode** on the [Skill Data](/bullethell-elemental-template/scriptables/create-new-skill.md): **Force Full Body** or **Force Upper Body**.
{% endhint %}