> 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

Monster skill assignments, skill units, and skill elements

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