> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rarity

> Colour-coded item tiers with borders, badges, filters, and sort modes.

The Awoken rework adds a rarity system on top of every item and weapon. A rarity-tagged item gets:

* A coloured **border + glow** on its inventory slot.
* A coloured **badge** in its tooltip.
* A **rarity glow** on the item-pickup notification.
* A **filter chip** in the toolbar so players can show only items of a chosen tier.
* A **sort mode** (Rarity ↑ / Rarity ↓) in the sort dropdown.

## Master toggle

The whole system can be turned off in one line.

```json config.json theme={"dark"}
{
  "showRarity": false
}
```

When `false`, slot glow/badges are hidden, the Rarity filter button disappears from the toolbar, and the rarity sort modes hide from the sort dropdown. The data is still respected - flipping the toggle back to `true` restores everything without restart.

## Tiers

Rarity tiers are defined as a map in `config.json`. The **order in the file** determines tier priority (top = lowest, bottom = highest), which is what the `Rarity ↑ / ↓` sort modes use.

```json config.json theme={"dark"}
{
  "rarity": {
    "common":    { "label": "Common",    "color": "#9d9d9d" },
    "uncommon":  { "label": "Uncommon",  "color": "#2ecc71" },
    "rare":      { "label": "Rare",      "color": "#3498db" },
    "epic":      { "label": "Epic",      "color": "#9b59b6" },
    "legendary": { "label": "Legendary", "color": "#f39c12" }
  }
}
```

| Field                    | Purpose                                                                    |
| ------------------------ | -------------------------------------------------------------------------- |
| Key *(e.g. `legendary`)* | Internal identifier referenced by items and weapons. Lowercase, no spaces. |
| `label`                  | Display name shown on badges, tooltips, and filter chips.                  |
| `color`                  | Hex colour used for the slot border, glow, badge and chip.                 |

## Applying rarity to an item

Add a `rarity` field to any item in `data/items.lua`. The key must match one of the keys in `config.json` → `rarity`.

```lua data/items.lua theme={"dark"}
return {
    ['lockpick'] = {
        label  = 'Lockpick',
        weight = 80,
        rarity = 'uncommon',
        tags   = { 'tool' },
    },

    ['gold_bar'] = {
        label  = 'Gold Bar',
        weight = 12000,
        rarity = 'legendary',
        tags   = { 'material', 'currency' },
    },
}
```

## Applying rarity to a weapon

Identical pattern in `data/weapons.lua`:

```lua data/weapons.lua theme={"dark"}
return {
    Weapons = {
        ['WEAPON_PISTOL'] = {
            label      = 'Pistol',
            tags       = { 'weapon', 'pistol' },
            rarity     = 'common',
            weight     = 1130,
            durability = 0.1,
            ammoname   = 'ammo-9',
        },

        ['WEAPON_HEAVYSNIPER_MK2'] = {
            label      = 'Heavy Sniper MK2',
            tags       = { 'weapon', 'sniper' },
            rarity     = 'legendary',
            weight     = 12000,
            durability = 0.5,
            ammoname   = 'ammo-snp',
        },
    },
}
```

<Info>
  Items without a `rarity` field render with no border or glow and are excluded when any rarity filter chip is active.
</Info>

## Customising tiers

Add, rename, or remove tiers freely. The UI re-renders from `config.json` on resource restart.

### Adding a tier

```json config.json theme={"dark"}
{
  "rarity": {
    "common":    { "label": "Common",    "color": "#9d9d9d" },
    "uncommon":  { "label": "Uncommon",  "color": "#2ecc71" },
    "rare":      { "label": "Rare",      "color": "#3498db" },
    "epic":      { "label": "Epic",      "color": "#9b59b6" },
    "legendary": { "label": "Legendary", "color": "#f39c12" },
    "mythic":    { "label": "Mythic",    "color": "#e91e63" }
  }
}
```

Then use it on an item:

```lua data/items.lua theme={"dark"}
['ancient_relic'] = {
    label  = 'Ancient Relic',
    weight = 500,
    rarity = 'mythic',
},
```

### Renaming a tier

If you change a key, **update every item/weapon that referenced the old key** - otherwise those items revert to "no rarity" until the keys are aligned.

### Re-ordering tiers

Tier order in `config.json` controls sort direction. Move keys up or down to change which tier counts as "highest" in `Rarity ↓`.