> ## 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.

# Gear

> Managing what equipment elites can wear and how it is assigned.

`gear.yml` defines the pool of weapons and armor that elites can equip, how item rarity is determined, and the rules for each tier's equipment quality.

## Durability

Gear spawned on elites is never at full condition. This makes dropped equipment feel like a used battlefield pickup rather than a brand-new item.

```yaml theme={null}
Gear:
  spawnGearDurabilityMin: 0.02
  spawnGearDurabilityMax: 0.30
```

| Setting                  | What it does                                                                        | Default |
| :----------------------- | :---------------------------------------------------------------------------------- | :------ |
| `spawnGearDurabilityMin` | Minimum durability fraction. `0.02` means gear can spawn at as low as 2% condition. | `0.02`  |
| `spawnGearDurabilityMax` | Maximum durability fraction. `0.30` means gear spawns at most at 30% condition.     | `0.30`  |

## Two-Handed Weapons

Weapons in this list are treated as two-handed. Mobs holding a two-handed weapon will never equip a shield in their off-hand.

```yaml theme={null}
Gear:
  twoHandedWeaponIds:
    - "shortbow"
    - "crossbow"
    - "spear"
    - "staff"
    - "battleaxe"
    - "longsword"
    - "bomb"
```

If a weapon ID contains any of these strings, it counts as two-handed. Add your own modded weapon keywords here if needed.

## Weapon Categories

Weapons are organized into named categories in `gear.yml`. Mob rules reference these categories instead of individual weapon IDs, making it easy to control what weapons a mob type can equip.

Categories use a hierarchical tree structure. The default config ships with categories like Axes, Battleaxes, Clubs, Daggers, Longswords, Maces, Spears, Swords, Shortbows, Crossbows, Staves, Guns, Spellbooks, Pickaxes, and Shields.

```yaml theme={null}
Gear:
  weaponCategoryTree:
    name: "All"
    subcategories:
      - name: "Swords"
        weaponIds: ["Weapon_Sword_Iron", "Weapon_Sword_Cobalt", "Weapon_Sword_Steel", ...]
      - name: "Axes"
        weaponIds: ["Weapon_Axe_Iron", "Weapon_Axe_Cobalt", ...]
      - name: "Staves"
        weaponIds: ["Weapon_Staff_Bone", "Weapon_Staff_Nature", ...]
```

Mob rules reference categories using the `category:CategoryName` syntax. For example, `category:Swords` targets all weapons in the Swords category.

Categories can be managed through the [Admin UI](/config/admin-ui) under Global Config → Weapon Categories.

## Armor Categories

Armor follows the same category pattern as weapons. Armor IDs use the `Armor_Material_Slot` format:

* `Armor_Iron_Head` -- Iron helmet
* `Armor_Iron_Chest` -- Iron chestplate
* `Armor_Iron_Hands` -- Iron gauntlets
* `Armor_Iron_Legs` -- Iron leggings

Categories are organized by material (e.g., "Iron" contains all 4 iron armor slots).

## Rarity Rules

RPGMobs determines an item's rarity by checking its ID against keyword rules. The first matching keyword wins.

```yaml theme={null}
Gear:
  weaponRarityRulesContains:
    "wood": "common"
    "copper": "common"
    "iron": "uncommon"
    "steel": "uncommon"
    "thorium": "rare"
    "cobalt": "rare"
    "adamantite": "epic"
    "void": "epic"
    "flame": "legendary"
```

Armor uses the same system with `armorRarityRulesContains`.

These settings are editable through the [Admin UI](/config/admin-ui) under Global Config → Rarity & Tiers.

## Tier Equipment Quality

Each tier has restrictions on what rarity of equipment it can use, and weighted chances for picking a rarity.

```yaml theme={null}
Gear:
  tierAllowedRarities:
    - ["common"]               # Tier 1
    - ["uncommon"]             # Tier 2
    - ["rare"]                 # Tier 3
    - ["epic"]                 # Tier 4
    - ["epic", "legendary"]    # Tier 5

  tierEquipmentRarityWeights:
    - { "common": 1.0 }                       # Tier 1
    - { "uncommon": 1.0 }                     # Tier 2
    - { "rare": 0.70, "uncommon": 0.30 }      # Tier 3
    - { "epic": 0.70, "rare": 0.30 }          # Tier 4
    - { "legendary": 0.40, "epic": 0.60 }     # Tier 5
```

These settings are editable through the [Admin UI](/config/admin-ui) under Global Config → Rarity & Tiers.

## Armor Slots

Controls how many armor pieces each tier equips and the chance of getting an off-hand utility item.

```yaml theme={null}
Gear:
  armorPiecesToEquipPerTier:
    - 0  # Tier 1  -  no armor
    - 1  # Tier 2  -  one piece
    - 2  # Tier 3
    - 3  # Tier 4
    - 4  # Tier 5  -  fully armored

  shieldUtilityChancePerTier:
    - 0.0   # Tier 1
    - 0.0   # Tier 2
    - 0.20  # Tier 3  -  20% chance of a shield
    - 0.40  # Tier 4  -  40% chance
    - 0.60  # Tier 5  -  60% chance
```

## Equipment Lists

The `weaponCatalog` and `armorMaterials` lists are the item pools that elites draw from. If you add new weapons or armor from another mod, add their IDs here so elites can equip them.

```yaml theme={null}
Gear:
  weaponCatalog:
    - "Weapon_Sword_Iron"
    - "Weapon_Axe_Cobalt"
    - "Weapon_Staff_Bone"
    # ... full list in the generated config file

  armorMaterials:
    - "Iron"
    - "Cobalt"
    - "Adamantite"
    # ... full list in the generated config file
```

The default lists include all standard Hytale weapons and armor materials. The full lists are written to the generated config file on first run.

While `weaponCatalog` and `armorMaterials` still exist as flat item pools, the category trees (Weapon Categories and Armor Categories above) are the primary organizational system used by mob rules. Categories are the recommended way to control equipment assignment -- they let you group weapons and armor logically and reference entire groups at once from mob rules.