> For the complete documentation index, see [llms.txt](https://kubkitdev.gitbook.io/mmoforge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kubkitdev.gitbook.io/mmoforge/how-it-works/how-mmoforge-works.md).

# How MMOForge Works

#### `Qualities`

> A **quality** is the result of a reforge. They're defined in `qualities.yml`. Each one has:
>
> * **suffix**: text added to the item's name (e.g. `&b(Razor Sharp)`). Empty = adds nothing.
> * **modifier**: % applied to the item's stats (`0.18` = +18%, `-0.08` = −8%).
> * **weight**: weight for the roll (higher = more likely).
> * **sound**: sound played when obtained.
> * **extra-stats**: extra stats it adds (see "Smart extra stats").
>
> Default qualities (worst to best): Broken, Bad, Normal, Sharp, Razor Sharp, Masterful, Divine. You can pretty mucho customize anything.

####  `Rarities & Quality cap`

> Each **rarity** (MMOItems tier) defines in `tiers.yml`:
>
> * The **cost** to reforge (money + items).
> * **allowed-qualities**: which qualities that rarity can REACH (empty = all).
>
> This way, variety grows with rarity. By default:
>
> In the menu's book, unreachable qualities show as "✖ not available". (These are the ones that come by default you don't necessarily have to use these, you can create your own and as many as you want.)

| Rarity    | Can roll          | Never below                  |
| --------- | ----------------- | ---------------------------- |
| Common    | up to Sharp       | —                            |
| Uncommon  | up to Razor Sharp | —                            |
| Rare      | up to Masterful   | Bad                          |
| Epic      | up to Masterful   | Bad                          |
| Legendary | up to Divine      | Normal                       |
| Mythical  | up to Divine      | **Sharp** (never downgrades) |

#### `Reforge cost`

> The cost is defined per rarity in `tiers.yml`:
>
> * **money**: money (Vault) per reforge.
> * **items**: required items. Formats:
>   * `VANILLA:<MATERIAL>:<amount>` → `VANILLA:DIAMOND:2`
>   * `MMOITEMS:<TYPE>:<ID>:<amount>` → `MMOITEMS:MATERIAL:SHARPENING_STONE:5`
> * **reroll-money-multiplier**: money grows with each reforge of the same item.
> * **reroll-money-cap**: maximum money per reforge (0 = no cap).
>
> Formula: `cost = MIN( money × multiplier^reforges , reroll-money-cap )`.

#### `Smart extra stats`

> High qualities can **add new stats** with `extra-stats`. The "smart" part: an extra stat is **only applied if it's compatible with the item type** (listed in its category in `categories.yml`).
>
> With a single quality definition:
>
> * A **sword** with Divine gets offensive extras (lifesteal, crit…).
> * **Armor** with Divine gets defensive ones (health, damage reduction…).
> * A **staff** with Divine gets magic damage, mana…
>
> On re-roll, the previous quality's extras are removed automatically (they don't stack).

#### `Pity System`

> The **pity** system prevents extreme bad luck. It works like this:
>
> * The target is **the best quality the item's rarity can reach** (automatic: an Epic aims for Masterful, a Mythical for Divine).
> * **Each reforge raises the chance** of that target quality.
> * When you hit the threshold (`threshold`, default 30), the next reforge **guarantees** the target.
> * **Only reaching the target resets** progress; intermediate qualities do NOT, so you never lose your investment.
>
> Progress is **per player** and shown in the menu's "Your Progress" panel.

#### `Protection Shield`

> The **shield** prevents your next reforge from rolling a "bad" quality.
>
> * **3 uses per item** by default (configurable).
> * **More uses via permission** (VIP): `mmoforge.shield.vip` (6), `mmoforge.shield.elite` (10).
> * **The cost rises with each use** on the same item (`use-multiplier`) → rewards strategic use, punishes abuse.
> * The button shows remaining uses and the current cost. When they run out, it can't be activated.
>
> Combine it with pity to "secure" good rolls while progressing toward the target.