> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/monster/monsterskill.md).

# MonsterSkill

The monster skill system is split across three files that work together to define monster special abilities. Each file has its own loader and its own index range.

## File Locations

* `Data/Monster/MonsterSkill.xml` - binds skill units to monsters by `Index`
* `Data/Monster/MonsterSkillUnit.xml` - defines skill-unit behaviour (target / scope / delay / elements)
* `Data/Monster/MonsterSkillElement.xml` - defines the individual effects applied by a skill unit

## Dependencies

| Depends On                                   | Purpose                                               |
| -------------------------------------------- | ----------------------------------------------------- |
| [Monster.xml](/docs/data/monster/monster.md) | Monster `Index` values referenced by MonsterSkill.xml |

| Used By                    | Purpose                                   |
| -------------------------- | ----------------------------------------- |
| Monster AI and combat code | Looks up skill units when a monster casts |

## System Overview

The three files form a chain:

```
Monster (Index 304 - Witch Queen)
    |-- MonsterSkill.xml binds Index 304 to skill units
Skill Unit (Number 1)
    |-- MonsterSkillUnit.xml binds the unit to element numbers
Skill Element (Number 1)
    |-- MonsterSkillElement.xml defines the actual effect
```

A monster entry has up to 10 skill unit slots in the loader. The shipped data only authors six (`UnitType0..UnitType5`); missing attributes default to 0 and produce an unbound slot. Each skill unit can combine up to 5 skill elements in a single cast.

## MonsterSkill.xml

Binds up to 10 `(UnitType, UnitIndex)` pairs to a single monster `Index`.

### Monster Entry Attributes

| Attribute                | Type      | Description                                                                                                                            |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`                  | int       | Monster Index from [Monster.xml](/docs/data/monster/monster.md). Entries with an Index outside 0..999 are ignored.                     |
| `UnitType0..UnitType9`   | int       | Trigger ID for slot N. Matched against the ID passed by the combat or AI code when the monster casts.                                  |
| `UnitIndex0..UnitIndex9` | int / `*` | Skill unit `Number` from MonsterSkillUnit.xml. `*` stands for "no unit"; the loader converts it to 0 which also fails the unit lookup. |

{% hint style="info" %}
`UnitType` is parsed as an integer. Any non-numeric label (for example `UnitType0="Witch Queen"`) is read as 0 and works as a default / fallback trigger. The label only helps humans reading the XML.
{% endhint %}

### Skill Slots

Each monster has 10 slots numbered 0..9 in the loader. Each slot holds:

* **UnitType** - the trigger ID the AI or combat code asks for. Slot 0 is used by the generic monster combat path as the default attack.
* **UnitIndex** - the `Number` of a unit in MonsterSkillUnit.xml. An unbound or missing unit silently disables the slot.

### Example Entry

```xml
<Monster Index="304"
         UnitType0="Witch Queen" UnitIndex0="0"
         UnitType1="4" UnitIndex1="0"
         UnitType2="1" UnitIndex2="*"
         UnitType3="*" UnitIndex3="*"
         UnitType4="*" UnitIndex4="*"
         UnitType5="*" UnitIndex5="*"/>
```

Witch Queen (Index 304):

* Slot 0: trigger 0 (the label "Witch Queen" parses as 0) -> UnitIndex 0 (unit 0 is not defined in the shipped data, so this slot is effectively empty)
* Slot 1: trigger 4 -> UnitIndex 0 (same as above)
* Slot 2: trigger 1 -> `*` disabled
* Slots 3..5 disabled, slots 6..9 unauthored and therefore unbound

## MonsterSkillUnit.xml

Defines skill behaviour: who it targets, how the scope is resolved, how long the cast animation takes, and which elements are applied.

{% hint style="info" %}
**Storage limit**: the server keeps up to 200 unique Units (`Number` in 0..199). Numbers outside that range are rejected by the loader.
{% endhint %}

### Unit Attributes

| Attribute            | Type      | Description                                                                                     |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------- |
| `Number`             | int       | Unique skill-unit ID. Referenced by `UnitIndex*` in MonsterSkill.xml.                           |
| `Name`               | string    | Descriptive name, up to 49 characters. Server-side only.                                        |
| `TargetType`         | int       | 1 = target enemies, 2 = target self or the casting monster.                                     |
| `ScopeType`          | int / `*` | 0 = circular area, 1 = directional hitbox, `*` = single target. `*` is stored internally as -1. |
| `ScopeValue`         | int       | Tile radius (for area) or hitbox length. Unused for single-target.                              |
| `Delay`              | int       | Cast delay in milliseconds. 300 is the typical value used in shipped data.                      |
| `Element0..Element4` | int / `*` | Element `Number` from MonsterSkillElement.xml, or `*` for "no element".                         |

### TargetType Values

| Value | Target                                                 |
| ----- | ------------------------------------------------------ |
| 1     | Enemy players and monsters                             |
| 2     | Self / allied monster (the caster's own index is used) |

### ScopeType Values

| Value              | Scope                                                             |
| ------------------ | ----------------------------------------------------------------- |
| 0                  | Circular area, `ScopeValue` is the radius in tiles                |
| 1                  | Directional hitbox, `ScopeValue` and the caster's facing are used |
| `*` (stored as -1) | Single target (the direct target of the cast)                     |

### 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
* Circular area, 6-tile radius
* 300 ms cast delay
* Applies Element 1 only

## MonsterSkillElement.xml

Defines individual effects (damage, debuffs, buffs, status effects) that a skill unit can apply.

{% hint style="info" %}
**Storage limit**: the server keeps up to 100 unique Elements (`Number` in 0..99). Numbers outside that range are rejected by the loader.
{% endhint %}

### Element Attributes

| Attribute         | Type      | Description                                                                                                            |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Number`          | int       | Unique element ID. Referenced by `ElementN` in MonsterSkillUnit.xml.                                                   |
| `Name`            | string    | Descriptive name, up to 49 characters.                                                                                 |
| `Type`            | int       | Effect kind (see Effect Types below).                                                                                  |
| `SuccessRate`     | int       | Success chance in percent (0..100). The check is `rand(0..99) > SuccessRate -> fail`. Values above 100 always succeed. |
| `ContinuanceTime` | int       | Duration in seconds (0 or -1 = instant, >0 = lasts that many seconds).                                                 |
| `IncAndDecType`   | int / `*` | How `IncAndDecValue` is applied. `*` stores -1 = no modification.                                                      |
| `IncAndDecValue`  | int / `*` | Value applied when the element succeeds. `*` stores -1 = unused.                                                       |
| `NullifiedSkill`  | int / `*` | Skill ID that this element cancels or blocks. `*` stores -1 = none.                                                    |
| `CharacterClass`  | int       | Restrict the element to a specific character class (0 = all).                                                          |
| `CharacterLevel`  | int       | Minimum character level required for the element to apply (0 = none).                                                  |

### Effect Types

| Type | Effect                                                                 |
| ---- | ---------------------------------------------------------------------- |
| 0    | Stun (adds the Stern effect, optionally timed)                         |
| 1    | Move (movement-related effect; no built-in logic in the shipped build) |
| 2    | HP modification (damage, heal, or cyclical DoT / HoT)                  |
| 3    | MP modification                                                        |
| 4    | AG modification                                                        |
| 5    | Defense modification (timed buff / debuff)                             |
| 6    | Attack modification (timed buff / debuff)                              |
| 7    | Durability reduction on the target's equipment                         |
| 8    | Summon helper monsters                                                 |
| 9    | Push / displacement                                                    |
| 10   | Stat - Energy modification                                             |
| 11   | Stat - Strength modification                                           |
| 12   | Stat - Dexterity modification                                          |
| 13   | Stat - Vitality modification                                           |
| 14   | Remove buff / debuff                                                   |
| 15   | Resist skill (grants resistance to a named skill)                      |
| 16   | Immune skill (grants full immunity to a named skill)                   |
| 17   | Teleport the target                                                    |
| 18   | Double HP buff                                                         |
| 19   | Poison DoT                                                             |
| 20   | Normal attack effect (non-magical hit)                                 |
| 21   | Berserk (damage boost)                                                 |

### IncAndDecType Values

`IncAndDecType` selects how `IncAndDecValue` is combined with the target's stat.

| Value | Name                    | Meaning                          |
| ----- | ----------------------- | -------------------------------- |
| 0     | None                    | No stat change                   |
| 1     | Percent Increase        | Add `value` percent              |
| 2     | Percent Decrease        | Subtract `value` percent         |
| 11    | Constant Increase       | Add `value`                      |
| 12    | Constant Decrease       | Subtract `value`                 |
| 100   | Cycle Percent           | Periodic percent change          |
| 101   | Cycle Percent Increase  | Periodic percent heal / buff     |
| 102   | Cycle Percent Decrease  | Periodic percent damage / debuff |
| 110   | Cycle Constant          | Periodic flat change             |
| 111   | Cycle Constant Increase | Periodic flat heal               |
| 112   | Cycle Constant Decrease | Periodic flat damage             |

**Notes**:

* For HP / MP / AG (Types 2 / 3 / 4) the `IncAndDecType` decides whether the effect is damage/drain or heal/restore.
* Cycle variants (100..112) apply the change repeatedly for `ContinuanceTime` seconds (DoT / HoT). Non-cycle variants apply 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
* 50% success chance
* 3-second duration
* No stat modification
* Affects all classes and levels

## Skill System Examples

{% tabs %}
{% tab title="Area MP Drain" %}

```xml
<!-- MonsterSkill.xml -->
<Monster Index="305"
         UnitType0="Blue Golem" UnitIndex0="0"
         UnitType1="5" UnitIndex1="*"
         UnitType2="*" UnitIndex2="*"
         UnitType3="*" UnitIndex3="*"
         UnitType4="*" UnitIndex4="*"
         UnitType5="*" UnitIndex5="*"/>

<!-- MonsterSkillUnit.xml -->
<Unit Number="5" Name="Monster Skill Unit"
      TargetType="1" ScopeType="*" ScopeValue="0"
      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 casts Unit 5 on a single target. Element 3 has a 50% chance to drain 50% of the target's MP 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="*"/>

<!-- MonsterSkillUnit.xml -->
<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"/>
<Unit Number="30" TargetType="2" ScopeType="*" ScopeValue="0" Delay="300" Element0="29" Element1="30"/>
```

Nightmare boss binding:

* Slot 0: trigger 0 (default attack) - unit 0 is unbound
* Slot 1: trigger 18 -> Unit 1 (directional hitbox, 6 tiles)
* Slot 2: trigger 19 -> Unit 30 (self / ally buff)
* Slot 3: trigger 20 -> Unit 2 (self / ally buff)
* Slot 4: trigger 21 -> no unit assigned

The engine or boss-phase code decides when to ask for triggers 18 / 19 / 20.
{% endtab %}

{% tab title="Healing Unit" %}

```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"/>
```

Targets self / ally (`TargetType=2`). Element 60 is an instant Type 2 (HP) effect with a Percent Increase of 10 - restores 10% HP on success.
{% 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="5" SuccessRate="30" ContinuanceTime="10"
         IncAndDecType="2" IncAndDecValue="10"/>
<Element Number="1" Name="Stun"
         Type="0" SuccessRate="50" ContinuanceTime="3"/>
```

Rolls each element independently. 30% chance to apply a 10% defense reduction for 10 seconds, plus a 50% chance to stun for 3 seconds.
{% endtab %}
{% endtabs %}

## Common Tasks

### Assign Skills to a Monster

1. Look up the monster `Index` in [Monster.xml](/docs/data/monster/monster.md).
2. Add a `<Monster>` entry in MonsterSkill.xml with the triggers and unit numbers you want.
3. Reference existing Units from MonsterSkillUnit.xml or author new ones.

### Create a New Skill

1. Author the effects in MonsterSkillElement.xml (one `<Element>` per effect).
2. Author the unit in MonsterSkillUnit.xml that references those elements.
3. Bind the unit to one or more monsters in MonsterSkill.xml.

### Disable a Monster's Skill

Set `UnitIndex*` to `*` for the slot you want to disable:

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

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

### Make a Skill More Reliable

Increase `SuccessRate` on the relevant element:

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

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

### Increase Duration

Raise `ContinuanceTime` on timed or cycle elements:

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

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

## Important Behavior

### Success Roll

The server rolls `rand(0..99)` and fails the element if that roll is strictly greater than `SuccessRate`. So `SuccessRate="50"` gives a 50% chance. Values above 100 always succeed.

{% hint style="warning" %}
**Stun resistance**: for Type 0 (stun), the target's `ResistStunRate` is subtracted from `SuccessRate` before the roll. If `SuccessRate=50` and the target has `ResistStunRate=20`, the effective success threshold is 30.
{% endhint %}

### Skill Execution Order

When a monster casts a skill:

1. The combat / AI code asks for a specific `UnitType` trigger.
2. The server scans the monster's 10 slots for any slot whose `UnitType` matches.
3. If more than one slot matches, one is picked at random.
4. The selected Unit's `TargetType` chooses who can be affected (enemy or self / ally).
5. The `ScopeType` and `ScopeValue` decide whether the cast is single-target, area or hitbox.
6. Each target in scope is visited once, and every element in the unit is rolled independently against that target.

### How UnitType Triggers Work

`UnitType` is a trigger ID, not a human-readable label. The engine and boss scripts pass specific IDs when they want a particular skill. Authoring a new UnitType value in the XML without matching code that actually asks for that ID will never fire the skill.

{% hint style="info" %}
Slot 0 (`UnitType0`) is the default slot used by the generic combat path when the server wants to know whether a monster has any special attack. Other slot IDs are driven by event, boss or AI logic.
{% endhint %}

### Multiple Elements Per Unit

A unit with several elements applies each element independently, so all, some or none may succeed on a given target:

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

This can apply stun, slow and defense reduction together if each roll passes.

### Wildcard Values

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

* `UnitIndex="*"` - slot disabled (loader resolves to no unit)
* `Element0="*"` - no element in this slot (stored internally as -1)
* `IncAndDecType="*"` / `IncAndDecValue="*"` / `NullifiedSkill="*"` - not used

### Delay Timing

`Delay` is the cast delay in milliseconds.

* 0 = instant
* 300 = typical value in shipped data
* 1000+ = slow cast that gives players time to react

## Common Issues

{% hint style="warning" %}
An invalid `UnitIndex` (pointing at a non-existent unit) silently disables the slot rather than crashing. Always double-check the unit `Number` exists in MonsterSkillUnit.xml.
{% endhint %}

{% hint style="warning" %}
`SuccessRate` above 100 is effectively 100% - there is no bonus from very high values. Use 100 for guaranteed effects.
{% endhint %}

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

* Instant effects (plain HP / MP / AG change): 0 or -1; the value is ignored.
* Timed buffs / debuffs (defense, attack, movement, etc.): duration in seconds.
* Cycle effects (DoT / HoT): duration in seconds over which the periodic tick runs.
  {% endhint %}

{% hint style="info" %}
All three files are only read at server startup. Monsters that are already spawned keep their original skill bindings until they die and respawn.
{% endhint %}

{% hint style="danger" %}
A unit with all 5 element slots filled produces 5 independent rolls per target per cast. Keep most units to 1-2 elements to limit overhead on large scopes.
{% endhint %}

## Related Files

* [Monster.xml](/docs/data/monster/monster.md) - monster Index values bound by this file
* [MonsterSetBase/](/docs/data/monster/monstersetbase.md) - where the monsters themselves spawn
* [KanturuMonsterSetBase.xml](/docs/data/monster/kanturumonstersetbase.md) - Kanturu event spawns
* [MonsterAIGroup.xml](/docs/data/monster/monsteraigroup.md) - AI groupings that use these monsters
* [MonsterAIUnit.xml](/docs/data/monster/monsteraiunit.md) - per-monster AI unit settings
* [MonsterAIRule.xml](/docs/data/monster/monsterairule.md) - AI rules
* [MonsterAIElement.xml](/docs/data/monster/monsteraielement.md) - AI element actions
* [MonsterAIAutomata.xml](/docs/data/monster/monsteraiautomata.md) - AI state machines
* [Skill.txt](/docs/data/skill.md) - base skill catalogue referenced when `NullifiedSkill` is set