# MonsterSkill

The monster skill system uses a modular approach with three configuration files that work together to define monster abilities.

## File Locations

* `GameServer/Data/Monster/MonsterSkill.xml` - Assigns skills to monsters
* `GameServer/Data/Monster/MonsterSkillUnit.xml` - Defines skill behavior
* `GameServer/Data/Monster/MonsterSkillElement.xml` - Defines skill effects

## Dependencies

| Depends On                                                                 | Purpose                            |
| -------------------------------------------------------------------------- | ---------------------------------- |
| [Monster.xml](https://axiomemu.gitbook.io/docs/gameserver/monster/monster) | Skills reference monsters by Index |

| Used By       | Purpose                              |
| ------------- | ------------------------------------ |
| Combat system | Monster AI uses skills during battle |

## System Overview

The skill system is hierarchical:

```
Monster (Index 304 - Witch Queen)
    ↓ references (from MonsterSkill.xml)
Skill Unit 0 (Type: "Witch Queen", Index: 0)
    ↓ references (from MonsterSkillUnit.xml)
Skill Element 1 (Stun effect)
    ↓ defines (from MonsterSkillElement.xml)
Type: Stun, SuccessRate: 50%, Duration: 3 seconds
```

A monster can have up to 10 skill unit slots. Each skill unit can combine up to 5 skill elements to create complex abilities.

## MonsterSkill.xml

Assigns skill units to specific monsters.

### Monster Entry Attributes

| Attribute      | Type   | Description                                                 |
| -------------- | ------ | ----------------------------------------------------------- |
| `Index`        | int    | Monster Index from Monster.xml                              |
| `UnitType0-9`  | int    | Skill trigger ID for slot 0-9 (see UnitType Values below)   |
| `UnitIndex0-9` | int/\* | Skill Unit Index from MonsterSkillUnit.xml (or \* for none) |

### Skill Slots

Each monster has 10 skill slots (0-9). Each slot has:

* **UnitType**: Numeric trigger ID that the monster AI uses to decide when to cast this skill
* **UnitIndex**: References a Unit from MonsterSkillUnit.xml (or "\*" = disabled)

### UnitType Values

UnitType is always an integer that identifies when the skill should be triggered:

* **0**: Default/always available skill (most common attacks)
* **1-100**: Custom trigger IDs used by monster AI logic
* **Descriptive strings in XML** (like "Witch Queen", "Blue Golem"): These are parsed as 0 by the server - they're just human-readable labels

{% hint style="info" %}
The XML parser converts non-numeric UnitType values to 0. So `UnitType0="Witch Queen"` and `UnitType0="0"` are functionally identical - both become trigger ID 0.
{% endhint %}

### Example Entry

```xml
<Monster Index="304"
         UnitType0="Witch Queen" UnitIndex0="0"
         UnitType1="4" UnitIndex1="0"
         UnitType2="1" UnitIndex2="*"
         UnitType3="*" UnitIndex3="*"
         UnitType4="*" UnitIndex4="*"
         UnitType5="*" UnitIndex5="*"
         UnitType6="*" UnitIndex6="*"
         UnitType7="*" UnitIndex7="*"
         UnitType8="*" UnitIndex8="*"
         UnitType9="*" UnitIndex9="*"/>
```

Witch Queen (Index 304) has:

* Slot 0: Trigger ID 0 (parsed from "Witch Queen" string = 0) → Uses Unit 0
* Slot 1: Trigger ID 4 → Uses Unit 0
* Slot 2: Trigger ID 1 → Disabled (UnitIndex="\*")
* Slots 3-9: Disabled

## MonsterSkillUnit.xml

Defines skill behaviors including targeting, range, delay, and which elements to apply.

{% hint style="info" %}
**Maximum limits**: The server can store up to 200 unique Units (Numbers 0-199). Unit numbers outside this range will be ignored.
{% endhint %}

### Unit Attributes

| Attribute    | Type   | Description                                                                  |
| ------------ | ------ | ---------------------------------------------------------------------------- |
| `Number`     | int    | Unique skill unit ID (referenced by MonsterSkill.xml)                        |
| `Name`       | string | Descriptive name (for admin reference)                                       |
| `TargetType` | int    | Who is targeted (1 = enemies, 2 = self/allies)                               |
| `ScopeType`  | int/\* | Area of effect (0 = circular area, 1 = line/hitbox, \* = single target only) |
| `ScopeValue` | int    | Range/radius in tiles (0 if single target)                                   |
| `Delay`      | int    | Cast time in milliseconds (usually 300)                                      |
| `Element0-4` | int/\* | Element Index from MonsterSkillElement.xml (or \* for none)                  |

### TargetType Values

| Value | Target                  |
| ----- | ----------------------- |
| 1     | Enemy players/monsters  |
| 2     | Self or allied monsters |

### ScopeType Values

| Value    | Scope                                                      |
| -------- | ---------------------------------------------------------- |
| 0        | Circular area (ScopeValue = radius in tiles)               |
| 1        | Line/hitbox (ScopeValue = length, uses directional hitbox) |
| \* (XML) | Single target only (internally stored as -1)               |

### Example Unit

```xml
<Unit Number="1" Name="Monster Skill Unit"
      TargetType="1" ScopeType="0" ScopeValue="6"
      Delay="300"
      Element0="1" Element1="*" Element2="*" Element3="*" Element4="*"/>
```

Skill Unit 1:

* Targets enemies (TargetType=1)
* Circular area (ScopeType=0)
* 6-tile radius (ScopeValue=6)
* 300ms cast time
* Applies Element 1 only

## MonsterSkillElement.xml

Defines individual skill effects like damage, debuffs, buffs, and status effects.

{% hint style="info" %}
**Maximum limits**: The server can store up to 100 unique Elements (Numbers 0-99). Element numbers outside this range will be ignored.
{% endhint %}

### Element Attributes

| Attribute         | Type   | Description                                            |
| ----------------- | ------ | ------------------------------------------------------ |
| `Number`          | int    | Unique element ID (referenced by MonsterSkillUnit.xml) |
| `Name`            | string | Descriptive name                                       |
| `Type`            | int    | Effect type (see Effect Types below)                   |
| `SuccessRate`     | int    | Chance to apply (0-100, where 50 = 50%)                |
| `ContinuanceTime` | int    | Duration in seconds (0 = instant, 10 = 10 seconds)     |
| `IncAndDecType`   | int    | Stat affected (or \* for none)                         |
| `IncAndDecValue`  | int    | Amount to increase/decrease stat (or \* for none)      |
| `NullifiedSkill`  | int    | Skill ID to cancel/block (or \* for none)              |
| `CharacterClass`  | int    | Restrict to character class (0 = all)                  |
| `CharacterLevel`  | int    | Minimum character level (0 = any)                      |

### Effect Types

| Type | Effect                                 |
| ---- | -------------------------------------- |
| 0    | Stun (freeze target)                   |
| 1    | Move (movement speed modification)     |
| 2    | HP modification (damage or heal)       |
| 3    | MP modification                        |
| 4    | AG modification                        |
| 5    | Defense modification                   |
| 6    | Attack modification                    |
| 7    | Durability (item durability reduction) |
| 8    | Summon (spawn helper monsters)         |
| 9    | Push (knockback/teleport)              |
| 10   | Stat Energy modification               |
| 11   | Stat Strength modification             |
| 12   | Stat Dexterity modification            |
| 13   | Stat Vitality modification             |
| 14   | Remove Skill (cancel buffs)            |
| 15   | Resist Skill (buff resistance)         |
| 16   | Immune Skill (immunity buff)           |
| 17   | Teleport Skill (forced teleport)       |
| 18   | Double HP (HP boost)                   |
| 19   | Poison (damage over time)              |
| 20   | Normal Attack (direct damage)          |
| 21   | Berserk (damage boost)                 |

### IncAndDecType Values

These values control how IncAndDecValue is applied:

| Value | Type                    | Description                                                |
| ----- | ----------------------- | ---------------------------------------------------------- |
| 0     | None                    | No stat modification (use with effects that don't need it) |
| 1     | Percent Increase        | Increase stat by percentage                                |
| 2     | Percent Decrease        | Decrease stat by percentage                                |
| 11    | Constant Increase       | Increase stat by fixed amount                              |
| 12    | Constant Decrease       | Decrease stat by fixed amount                              |
| 100   | Cycle Percent           | Periodic percentage change                                 |
| 101   | Cycle Percent Increase  | Periodic percentage increase (DoT heal)                    |
| 102   | Cycle Percent Decrease  | Periodic percentage decrease (DoT damage)                  |
| 110   | Cycle Constant          | Periodic constant change                                   |
| 111   | Cycle Constant Increase | Periodic constant increase                                 |
| 112   | Cycle Constant Decrease | Periodic constant decrease                                 |

**Note**: For Type 2 (HP), Type 3 (MP), Type 4 (AG), the IncAndDecType determines whether it's damage/drain (decrease) or heal/restore (increase).

**Cycle Types**: The CYCLE variants (100-112) create damage/healing over time effects. The effect is applied periodically during the ContinuanceTime duration, not just once.

### Example Element

```xml
<Element Number="1" Name="Monster Skill Element"
         Type="0" SuccessRate="50" ContinuanceTime="3"
         IncAndDecType="*" IncAndDecValue="*"
         NullifiedSkill="*"
         CharacterClass="0" CharacterLevel="0"/>
```

Element 1:

* Type 0 = Stun effect
* 50% success chance
* Lasts 3 seconds
* No stat modifications
* No skill blocking
* Affects all classes and levels

## Skill System Examples

{% tabs %}
{% tab title="Basic Attack Skill" %}

```xml
<!-- MonsterSkill.xml -->
<Monster Index="305"
         UnitType0="Blue Golem" UnitIndex0="0"
         UnitType1="5" UnitIndex1="*"
         UnitType2="*" UnitIndex2="*"
         UnitType3="*" UnitIndex3="*"
         UnitType4="*" UnitIndex4="*"
         UnitType5="*" UnitIndex5="*"
         UnitType6="*" UnitIndex6="*"
         UnitType7="*" UnitIndex7="*"
         UnitType8="*" UnitIndex8="*"
         UnitType9="*" UnitIndex9="*"/>

<!-- MonsterSkillUnit.xml -->
<Unit Number="0" Name="Blue Golem Slam"
      TargetType="1" ScopeType="0" ScopeValue="3"
      Delay="300"
      Element0="3" Element1="*" Element2="*" Element3="*" Element4="*"/>

<!-- MonsterSkillElement.xml -->
<Element Number="3" Name="MP Drain"
         Type="3" SuccessRate="50" ContinuanceTime="10"
         IncAndDecType="2" IncAndDecValue="50"
         NullifiedSkill="*"
         CharacterClass="0" CharacterLevel="0"/>
```

Blue Golem uses a 3-tile radius attack (Trigger ID 0) that has 50% chance to reduce target MP by 50% for 10 seconds.
{% endtab %}

{% tab title="Boss Multi-Skill" %}

```xml
<!-- MonsterSkill.xml -->
<Monster Index="361"
         UnitType0="Nightmare" UnitIndex0="0"
         UnitType1="18" UnitIndex1="1"
         UnitType2="19" UnitIndex2="30"
         UnitType3="20" UnitIndex3="2"
         UnitType4="21" UnitIndex4="*"
         UnitType5="*" UnitIndex5="*"
         UnitType6="*" UnitIndex6="*"
         UnitType7="*" UnitIndex7="*"
         UnitType8="*" UnitIndex8="*"
         UnitType9="*" UnitIndex9="*"/>

<!-- MonsterSkillUnit.xml -->
<Unit Number="0" TargetType="1" ScopeType="*" ScopeValue="0" Delay="300" Element0="29" Element1="30"/>
<Unit Number="1" TargetType="1" ScopeType="1" ScopeValue="6" Delay="300" Element0="31"/>
<Unit Number="2" TargetType="2" ScopeType="*" ScopeValue="0" Delay="300" Element0="32" Element1="33"/>
```

Nightmare boss has:

* Slot 0: Trigger ID 0 → Single-target attack (Unit 0, targets enemies)
* Slot 1: Trigger ID 18 → Line attack (Unit 1, 6-tile hitbox)
* Slot 2: Trigger ID 19 → Self-buff (Unit 30, targets self)
* Slot 3: Trigger ID 20 → Self-buff (Unit 2, targets self)
* Slot 4: Trigger ID 21 → Disabled (no Unit assigned)

The boss AI script would call UseMonsterSkill with trigger IDs 18, 19, 20 at specific HP thresholds.
{% endtab %}

{% tab title="Healing Skill" %}

```xml
<!-- MonsterSkillUnit.xml -->
<Unit Number="46" Name="Healing"
      TargetType="2" ScopeType="*" ScopeValue="0"
      Delay="300"
      Element0="60" Element1="*" Element2="*" Element3="*" Element4="*"/>

<!-- MonsterSkillElement.xml -->
<Element Number="60" Name="Heal"
         Type="2" SuccessRate="100" ContinuanceTime="0"
         IncAndDecType="1" IncAndDecValue="10"
         NullifiedSkill="*"
         CharacterClass="0" CharacterLevel="0"/>
```

Heals self or allies. TargetType=2 means self/allies. Type=2 (HP), IncAndDecType=1 (percent increase) with IncAndDecValue=10 restores 10% HP instantly.
{% endtab %}

{% tab title="Debuff Combo" %}

```xml
<!-- MonsterSkillUnit.xml -->
<Unit Number="28" Name="Multi-Debuff"
      TargetType="1" ScopeType="*" ScopeValue="0"
      Delay="300"
      Element0="8" Element1="1" Element2="*"/>

<!-- MonsterSkillElement.xml -->
<Element Number="8" Name="Defense Down"
         Type="2" SuccessRate="30" ContinuanceTime="10"
         IncAndDecType="112" IncAndDecValue="10"/>
<Element Number="1" Name="Stun"
         Type="0" SuccessRate="50" ContinuanceTime="3"/>
```

Applies two effects: 30% chance to reduce defense by 10% for 10 seconds, and 50% chance to stun for 3 seconds.
{% endtab %}
{% endtabs %}

## Common Tasks

### Assign Skills to Monster

1. Find monster Index in Monster.xml
2. Add entry to MonsterSkill.xml with appropriate UnitIndex values
3. Reference existing Units or create new ones

### Create New Skill

1. **Design the skill**: Decide on targeting, range, effects
2. **Create Elements** in MonsterSkillElement.xml (damage, debuffs, etc.)
3. **Create Unit** in MonsterSkillUnit.xml referencing Elements
4. **Assign to monster** in MonsterSkill.xml

### Disable Monster Skills

In MonsterSkill.xml, set UnitIndex to "\*":

```xml
<!-- Before -->
<Monster Index="340" UnitType0="Dark Elf" UnitIndex0="30"/>

<!-- After (disabled) -->
<Monster Index="340" UnitType0="Dark Elf" UnitIndex0="*"/>
```

### Make Skill More Reliable

Increase `SuccessRate` in MonsterSkillElement.xml:

```xml
<!-- Before: 50% chance -->
<Element Number="1" SuccessRate="50" .../>

<!-- After: 90% chance -->
<Element Number="1" SuccessRate="90" .../>
```

### Increase Skill Duration

Increase `ContinuanceTime` in MonsterSkillElement.xml:

```xml
<!-- Before: 3 seconds -->
<Element Number="1" ContinuanceTime="3" .../>

<!-- After: 10 seconds -->
<Element Number="1" ContinuanceTime="10" .../>
```

### Add HP-Based Skill Trigger

Use numeric UnitType in MonsterSkill.xml:

```xml
<Monster Index="500"
         UnitType0="Normal Attack" UnitIndex0="0"
         UnitType1="30" UnitIndex1="5"
         UnitType2="*" UnitIndex2="*"/>
```

Monster uses Unit 5 when HP drops below 30%.

## Important Behavior

### Success Rate

{% hint style="info" %}
SuccessRate is a percentage (0-100), not out of 10000 like drop rates. A value of 50 = 50% chance. The calculation is: if (random(0-99) > SuccessRate) then fail, else succeed.
{% endhint %}

{% hint style="warning" %}
**Stun resistance**: For Stun effects (Type 0), the target's ResistStunRate is subtracted from SuccessRate before the check. So if SuccessRate=50 and target has ResistStunRate=20, the actual success chance is 30%.
{% endhint %}

### Skill Execution Order

When a monster casts a skill:

1. Monster AI calls UseMonsterSkill with a specific UnitType trigger ID
2. System searches monster's skill slots for matching UnitType
3. If multiple slots match, one is randomly selected
4. The skill's TargetType determines who can be affected (enemy or self/ally)
5. ScopeType and ScopeValue determine area of effect targeting
6. Each Element in the Unit is applied to all targets in range
7. SuccessRate for each Element is rolled independently per target

### How UnitType Triggers Work

The UnitType value is a trigger ID used by monster AI code to decide when to use skills:

* **UnitType 0**: Default attack skill - used during normal combat
* **UnitType 1-30**: Custom triggers called by specific monster AI logic or boss scripts
* **UnitType 31+**: Special event or boss phase triggers

{% hint style="info" %}
The monster AI code (in Monster.cpp and MonsterAIElementInfo.cpp) hardcodes when to call each UnitType. For example, a boss script might call `UseMonsterSkill(monsterIndex, targetIndex, 18, -1, 0)` when HP drops below 20%, which triggers any skill slot with UnitType=18.
{% endhint %}

### Multiple Elements

A Unit with multiple Elements applies ALL elements that succeed their SuccessRate check:

```xml
<Unit Element0="1" Element1="3" Element2="5"/>
```

Could apply stun (Element 1), slow (Element 3), AND defense reduction (Element 5) all at once if all success checks pass.

### Wildcard Values

`*` means "none" or "disabled":

* `UnitIndex="*"` = skill slot disabled
* `Element0="*"` = no element in this slot
* `IncAndDecType="*"` = no stat modification

### Delay Timing

Delay is cast time in milliseconds:

* 0 = instant cast
* 300 = normal (most skills)
* 1000+ = slow cast (gives players time to react)

## Common Issues

{% hint style="warning" %}
**Invalid UnitIndex crashes monster AI.** Ensure UnitIndex references an existing Unit Number in MonsterSkillUnit.xml or use "\*" to disable.
{% endhint %}

{% hint style="warning" %}
**SuccessRate > 100 doesn't guarantee success.** Values above 100 are treated as 100%. Use 100 for guaranteed effects.
{% endhint %}

{% hint style="warning" %}
**ContinuanceTime meaning depends on effect type:**

* For instant effects (normal HP/MP/AG changes): Use 0 - the value is ignored
* For stat debuffs/buffs (Defense, Attack, Movement, etc.): Duration in seconds the debuff lasts
* For CYCLE effects (DoT/HoT): Duration in seconds that the periodic effect continues
  {% endhint %}

{% hint style="info" %}
**Changes require server restart.** Skill data is loaded on startup. Monsters already spawned keep their old skill configuration until server restart.
{% endhint %}

{% hint style="danger" %}
**Too many skill elements cause lag.** Each Unit can have up to 5 Elements, but using all 5 with complex effects on every cast impacts performance. Keep most skills to 1-2 elements.
{% endhint %}
