> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rpgmobs.frotty27.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobs

> Defining per-mob rules for equipment and elite eligibility.

`mobs.yml` lets you define specific rules for individual NPC types. This is where you control which mobs can become elites, what weapons they should use, and how they are matched by the system.

## How Mob Rules Work

When a hostile NPC spawns, RPGMobs checks it against the mob rules list. The first matching rule wins. If no rule matches, the mob is **not** transformed into an elite.

Rules are matched using a scoring system:

* **Exact match** (highest priority) -- the mob's role ID matches a value in `matchExact`.
* **Prefix match** -- the role ID starts with a value in `matchStartsWith`.
* **Contains match** -- the role ID contains a value in `matchContains`.
* **Exclusions** -- if the role ID contains any value in `matchExcludes`, the rule is skipped.

## Example Rules

```yaml theme={null}
Mobs:
  rules:
    Goblin_Miner:
      enabled: true
      matchExact: ["Goblin_Miner"]
      enableWeaponOverrideForTier: [true, true, true, true, true]
      weaponOverrideMode: ALWAYS
      allowedWeaponCategories: ["category:Pickaxes"]

    Trork_Shaman:
      enabled: true
      matchExact: ["Trork_Shaman"]
      weaponOverrideMode: ALWAYS
      allowedWeaponCategories: ["category:Staves"]

    Goblin_Lobber:
      enabled: true
      matchExact: ["Goblin_Lobber"]
      enableWeaponOverrideForTier: [false, false, false, false, false]
      weaponOverrideMode: ONLY_IF_EMPTY
```

## Weapon Override Modes

| Mode            | What it does                                                                                 |
| :-------------- | :------------------------------------------------------------------------------------------- |
| `ALWAYS`        | Replaces the mob's weapon with one matching the criteria, regardless of what it was holding. |
| `ONLY_IF_EMPTY` | Only equips a weapon if the mob's hands are empty.                                           |
| `NONE`          | Never changes the mob's equipment. Use this for custom bosses or unarmed mobs.               |

## Weapon Category Restrictions

Use `allowedWeaponCategories` to restrict what weapons a mob can be given. Categories are defined in `gear.yml` and referenced using the `category:CategoryName` syntax.

```yaml theme={null}
Mobs:
  rules:
    Goblin_Miner:
      enabled: true
      matchExact: ["Goblin_Miner"]
      weaponOverrideMode: ALWAYS
      allowedWeaponCategories: ["category:Pickaxes"]

    Trork_Shaman:
      enabled: true
      matchExact: ["Trork_Shaman"]
      weaponOverrideMode: ALWAYS
      allowedWeaponCategories: ["category:Staves"]
```

When `allowedWeaponCategories` is set, only weapons from those categories are eligible during equipment assignment. An empty list means all weapons from the tier's allowed rarities are available.

## Armor Category Restrictions

Use `allowedArmorCategories` to restrict what armor materials a mob can wear. Works the same as weapon categories.

```yaml theme={null}
Goblin_Scrapper:
  enabled: true
  matchExact: ["Goblin_Scrapper"]
  allowedArmorCategories: ["category:Iron", "category:Leather"]
```

An empty list means all armor materials are available (default behavior).

## Per-Tier Enable

The `enableWeaponOverrideForTier` array lets you toggle weapon overrides per tier. Set a tier to `false` to let the mob keep its default weapon at that tier level.

```yaml theme={null}
enableWeaponOverrideForTier: [true, true, true, true, true]
```

## Armor Slot Restrictions

Some mob models don't support all armor slots (e.g., floating heads, bodiless creatures). Use `allowedArmorSlots` to control which armor pieces the mob can equip.

```yaml theme={null}
Eye_Void:
  enabled: true
  matchExact: ["Eye_Void_Fire", "Eye_Void_Frost", "Eye_Void_Lightning"]
  weaponOverrideMode: NONE
  allowedArmorSlots: ["HEAD"]

Skeleton_Incandescent_Head:
  enabled: true
  matchExact: ["Skeleton_Incandescent_Head"]
  weaponOverrideMode: NONE
  allowedArmorSlots: ["HEAD", "CHEST"]
```

| Value               | What it does                                                  |
| :------------------ | :------------------------------------------------------------ |
| `[]` (empty)        | All armor slots are available (default behavior).             |
| `["HEAD"]`          | Only the head slot gets armor.                                |
| `["HEAD", "CHEST"]` | Only head and chest slots get armor.                          |
| `["NONE"]`          | No armor slots are available -- the mob gets no armor at all. |

Valid slot names: `HEAD`, `CHEST`, `HANDS`, `LEGS` (case-insensitive).

## Mob Rule Category Tree

Mob rules are organized into a hierarchical category tree in `mobrules.yml`. Categories group related mob rules together, making it easy to reference them in abilities and loot templates using the `category:CategoryName` syntax.

The default tree organizes 200+ mob rules into families:

* **Goblins** -- Lobber, Miner, Scavenger, Scrapper, Thief subcategories
* **Trorks** -- Sentry, Warrior subcategories
* **Skeletons** -- Standard, Burnt, Frost, Sand, Pirate, Incandescent subcategories
* **Zombies** -- Aberrant subcategory
* **Outlanders**, **Wraiths**, **Void**

When an ability or loot template links to `category:Skeletons`, it targets all skeleton mob rules across all subcategories.

The category tree can be managed through the [Admin UI](/config/admin-ui) in the Mob Rules tab.

**Tip:** The default configuration includes rules for **most** standard Hytale hostile NPCs. If you add custom NPCs from another mod, add a matching rule here so they can become elites.