Quality Reforge Tutorial

A beginner-friendly, step-by-step guide. Follow along and you will be able to set up your server's quality (tier) system: when players reforge equipment, it randomly lands on Common / Rare / Epic / Legendary quality, and each quality adds its own stats.

If you have not read Reforge System yet, skim it first to learn what quality reforge does.

What does quality reforge do?

In short: the player puts equipment into the reforge GUI, pays money, and the item's quality is rerolled.

Which quality you get is decided by the weights you configure in tier.yml
After landing on a quality, that quality's stat modifiers are applied to the item (for example, Legendary adds +10 attack damage)
The item name gets the quality's color prefix (for example, Legendary names turn gold)

Before you start: three prerequisites

Quality reforge only works when all of the following are set in plugins/MMOitemsReforge/config.yml:

reforge:
  modes:
    quality:
      enabled: true        # ① Quality reforge master switch
  cost: 50.0               # ② Money charged per quality reforge (Vault)
  max-quality-reforge-count: 10   # ③ Max quality reforges per item (0 = unlimited)

note

max-quality-reforge-count follows the item: one item can be quality-reforged 10 times, then it is done; a fresh item gets 10 more.

Meet tier.yml

The quality config file is:

plugins/MMOitemsReforge/tier.yml

On first start the plugin ships a complete example there (common / uncommon / rare / epic / legendary). Edit it directly or add your own tiers following the same pattern.

The most important rule: tier IDs must match MMOItems

Tier IDs in tier.yml (common, rare, ...) must correspond to tiers that actually exist in MMOItems. MMOItems defaults are:

COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, MYTHIC

Case does not matter

IDs are case-insensitive here: rare, Rare, and RARE all work — the plugin normalizes them to MMOItems uppercase IDs. But spelling must be correct: if you removed a tier in MMOItems, remove it here too.

Hands-on: writing a tier

A complete "rare" tier, line by line:

tiers:
  rare:                      # ← Tier ID, must match MMOItems RARE
    display-name: "&bRare"   # Display name (debug logs only, players never see it)
    weight: 15               # Weight: controls the chance (explained below)
    name-prefix: "&b"        # Name prefix: item name turns cyan after reforge
    name-suffix: ""          # Name suffix: usually empty
    tooltip-style: "minecraft:rare"   # 1.20.5+ client tooltip border color
    stat-modifiers:          # Stats applied when this tier is rolled
      ATTACK_DAMAGE: 4       # +4 attack damage
      ATTACK_SPEED: 2        # +2 attack speed
      CRITICAL_STRIKE_CHANCE: 5   # +5 crit chance (added even if the item lacks it)

What players see: the item name is colored cyan (&b) and the stats are boosted.

weight: how do chances work?

Chance = own weight ÷ sum of all weights. Higher means more likely.

The default five tiers:

Tier	weight	Chance
common	50	50/100 = 50%
uncommon	30	30/100 = 30%
rare	15	15/100 = 15%
epic	4	4/100 = 4%
legendary	1	1/100 = 1%

To tune difficulty just change the numbers. Weights should be integers: to make Legendary truly rare, do not write 0.5 — instead raise the others (e.g. 100/60/30/8/1).

stat-modifiers: how to write stat values?

Three forms, mixable:

stat-modifiers:
  ATTACK_DAMAGE: 5        # ① Flat value: +5 (also accepts "+5")
  ATTACK_SPEED: "10%"     # ② Percentage: +10% of the item's current stat
  MAX_MANA: "-15%"        # ③ Negative percentage: debuffs are allowed

info

Flat values are added straight onto the item's stat.
Percentages are calculated from the item's current base stat value. A percentage on a stat the item does not have does nothing; a flat value on a missing stat adds the stat.
Stat IDs use MMOItems stat names in uppercase: ATTACK_DAMAGE, CRITICAL_STRIKE_CHANCE, MAX_HEALTH, ...

Advanced: different stats per item type (per-type overrides)

Stat modifiers can also be configured per MMOItems item type by nesting a type name under stat-modifiers:

stat-modifiers:
  # Shared part: applies to every type
  ATTACK_DAMAGE: 2
  # Type override: swords only (overrides shared ATTACK_DAMAGE)
  SWORD:
    ATTACK_DAMAGE: 8
  # Type override: armor only
  ARMOR:
    MAX_HEALTH: 5

Merge rule: start from the shared part, then overlay the matching type's section. In the example a sword ends up with ATTACK_DAMAGE: 8, while armor gets ATTACK_DAMAGE: 2 + MAX_HEALTH: 5.

A special DEFAULT group merges into the shared part, handy for keeping shared entries together:

stat-modifiers:
  ATTACK_DAMAGE: 2        # shared
  DEFAULT:                # merged into shared, same effect as above
    CRITICAL_STRIKE_CHANCE: 3
  SWORD:
    ATTACK_DAMAGE: 8

drop-effect: drop effects (optional)

Add effects to reforged items when they drop on the ground (requires the relevant listener):

drop-effect:
  glow: true              # item glows
  glow-color: "AQUA"      # glow color (optional)
  show-name: true         # show item name above the drop
  vfx:                    # visual effect particles
    enabled: true
    material: "POTION"    # item used to render the VFX
    model-data: 1         # CustomModelData (for resource packs)
    color: "#55FFFF"      # VFX color (hex)

Valid glow-color values: BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, LIGHT_PURPLE, YELLOW, WHITE.

Two common pitfalls

Pitfall 1: never preserve MMOITEMS_TIER

Quality reforge works by rerolling the MMOITEMS_TIER NBT. If you add MMOITEMS_TIER to reforge.preserve-nbt-tags in config.yml, the quality never changes and the reforge money is wasted.

Pitfall 2: tier.yml has its own switch

At the bottom of tier.yml:

preserve-tier-on-reforge: false

true means the current tier is kept on reforge (only stats reroll); false rerolls the tier. Keep false for the gambling experience.

Lucky points and quality reforge

When the lucky system is enabled (reforge.lucky-system.enabled: true), reforges accumulate lucky points. Enabling the lucky bonus consumes all accumulated points and adjusts each quality's chance by the matching range in quality-bonus-by-lucky (for example, +25 for Legendary at 100 points).

See Reforge System for details.

Applying your changes

/mmoreforge reload

After a reload, tier.yml, config.yml, and modifiers/ all take effect. If the reload errors, check YAML indentation (spaces only, never tabs).

Homework: a complete custom tier

Paste this block under tiers: in tier.yml and reload (assumes a MYTHIC tier exists in your MMOItems):

  mythic_plus:
    display-name: "&dMythic+"
    weight: 1                    # extremely rare relative to the other tiers
    name-prefix: "&d&l"
    name-suffix: "&d&l ✦"
    tooltip-style: "minecraft:epic"
    drop-effect:
      glow: true
      glow-color: "LIGHT_PURPLE"
      show-name: true
      vfx:
        enabled: true
        material: "POTION"
        model-data: 3
        color: "#FF00FF"
    stat-modifiers:
      ATTACK_DAMAGE: "25%"       # big percentage boost
      ATTACK_SPEED: "15%"
      CRITICAL_STRIKE_CHANCE: 20
      CRITICAL_STRIKE_POWER: 30
      MAX_HEALTH: 20

note

Remember mythic_plus maps to a MYTHIC_PLUS tier in MMOItems (the rare → RARE uppercase rule). If MMOItems has no such tier, add one in MMOItems' tier config or change the ID here to an existing tier.

What does quality reforge do?​

Before you start: three prerequisites​

Meet tier.yml​

The most important rule: tier IDs must match MMOItems​

Hands-on: writing a tier​

weight: how do chances work?​

stat-modifiers: how to write stat values?​

Advanced: different stats per item type (per-type overrides)​

drop-effect: drop effects (optional)​

Two common pitfalls​

Lucky points and quality reforge​

Applying your changes​

Homework: a complete custom tier​

See Also​