> For the complete documentation index, see [llms.txt](https://devmosaic.gitbook.io/devmosaic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devmosaic.gitbook.io/devmosaic/resources/devmosaic-ox-inventory-rework-v2/rarity-system.md).

# Rarity System

The rarity system applies visual tiering to inventory slots — border glow, background gradient and animated pulse — based on a rarity field set on each item in data/items.lua.

### Default Tiers

| Key         | Label     | Text Colour        | Border / Glow      | Animation    |
| ----------- | --------- | ------------------ | ------------------ | ------------ |
| `common`    | Common    | `#ffffff` white    | `#636363` grey     | None         |
| `uncommon`  | Uncommon  | `#84cc16` lime     | `#84cc16` lime     | None         |
| `rare`      | Rare      | `#0ea5e9` sky blue | `#0ea5e9` sky blue | None         |
| `epic`      | Epic      | `#c026d3` purple   | `#c026d3` purple   | None         |
| `legendary` | Legendary | `#eab308` gold     | `#eab308` gold     | Pulsing glow |

***

### Assigning Rarity to an Item

Add a `rarity` key to any item in `data/items.lua`:

```lua
['weapon_pistol'] = {
    label  = 'Pistol',
    weight = 1000,
    stack  = false,
    rarity = 'rare',
}
```

Items without a `rarity` field use the `common` style by default.

***

### Tier Configuration

Every visual property of every tier is editable in `data/rarity.lua`:

```lua
Levels = {
    legendary = {
        label      = 'Legendary',
        text       = '#eab308',
        color      = '#eab308',
        background = 'radial-gradient(#00000000, #a1620725)',
        animation  = true,
    },
}
```

| Field        | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `label`      | Badge text shown in the slot                                  |
| `text`       | CSS colour of the item name label                             |
| `color`      | CSS colour of the slot border glow and rarity badge           |
| `background` | Any valid CSS `background` value — gradients or solid colours |
| `animation`  | `true` enables a pulsing glow (recommended for top tier only) |

***

### Adding Custom Tiers

Add any new key to the `Levels` table and assign it to items:

```lua
divine = {
    label      = 'Divine',
    text       = '#ff0080',
    color      = '#ff0080',
    background = 'radial-gradient(#00000000, #ff008030)',
    animation  = true,
},
```

Then in `data/items.lua`:

```lua
['angel_sword'] = {
    label  = 'Angel Sword',
    weight = 3000,
    rarity = 'divine',
}
```

No other changes are required.

***

### Disabling the Rarity System

Set `Enabled = false` in `data/rarity.lua`:

```lua
return {
    Enabled = false,
    Levels = {
        -- Existing rarity levels can remain here.
    },
}
```

This completely disables rarity presentation across the inventory UI. Rarity labels, colours, backgrounds, glows, and loadout slot framing are hidden in inventory, utility, clothing, shop, hotbar, notification, and drag-preview slots.

{% hint style="info" %}
You do not need to remove `rarity` fields from `data/items.lua` or item metadata. They are ignored while the system is disabled and become active again if you set `Enabled = true`.
{% endhint %}