Enchantment Cap

Belongs to: Server Owner Guide　·　Related: Item Definition

QI can limit the total enchantment level of a single item (the sum of all enchantment levels), enforced at the anvil / enchanting table. Config file: plugins/QinhItems/enchant_limits.yml.

---

1. Concept

Total enchantment level = the sum of all enchantment levels on an item. Example: Sharpness V(5) + Unbreaking III(3) + Fire Aspect II(2) = 10.

Priority: an item's explicit enchant_max_total_level > automatic calculation by type / tier.

Automatic calculation formula:

effective cap = min(type_defaults[item type], tier_defaults[item tier])

---

2. enchant_limits.yml Structure

type_defaults:
  # Cap per type
  weapon: 50
  armor: 40
  helmet: 40
  chestplate: 40
  leggings: 40
  boots: 40
  shield: 30
  bow: 40
  crossbow: 40
  trident: 40
  fishing_rod: 25
  tool: 40
  shears: 15
  flint_and_steel: 10
  elytra: 30
  horse_armor: 30
  ring: 25
  necklace: 25
  bracelet: 25
  accessory: 25
  gem: 0              # Not enchantable
  material: 0
  consumable: 0
  food: 0
  scroll: 0
  misc: 20

tier_defaults:
  # Cap per tier (the smaller value is taken against the type cap)
  TRASH: 5
  COMMON: 10
  UNCOMMON: 18
  RARE: 25
  VERY_RARE: 30
  LEGENDARY: 40
  EPIC: 45
  MYTHICAL: 50
  MAGICAL: 35
  UNIQUE: 55

---

3. Calculation Examples

Item	Type Cap	Tier Cap	Effective Cap
LEGENDARY weapon	weapon=50	LEGENDARY=40	min=40
RARE ring	ring=25	RARE=25	25
MYTHICAL chestplate	chestplate=40	MYTHICAL=50	min=40

Unmapped types / tiers fall back to a default of 30.

---

4. Item-Level Override

Set enchant_max_total_level directly in the item definition to specify it explicitly, overriding the automatic calculation:

my_sword:
  enchantments:
    sharpness: 5
  enchant_max_total_level: 12      # This sword caps at a total enchantment level of 12

---

5. Enforcement Mechanism

EnchantLimitAnvilListener checks whether the effective cap is exceeded when a player adds enchantments to an item via an anvil / enchanting table, and blocks it if exceeded. EnchantmentLimitsConfig loads from enchant_limits.yml at startup and reloads on /qi reload.

---

Next Steps

• Fragments and Templates
• Tier and Display: Tier definitions