> ## 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.

# Tags

> Multi-select item tag system with a dynamic filter dropdown.

Tags are the Awoken rework's category system. Any item or weapon can declare one or more tags, and players use a multi-select filter dropdown to show only items matching the chosen tags.

The default config ships **26+ tags** out of the box, covering food, drink, medical, clothing, tools, electronics, documents, materials, currency, equipment, storage, and every weapon class (pistol, smg, shotgun, rifle, sniper, heavy, launcher, throwable, melee, attachment, ammo).

## How the filter works

The **Type** button in the toolbar opens a multi-select dropdown. Each tag is a coloured chip - clicking selects it, clicking again deselects.

Key behaviours:

* **Dynamic** - only tags actually present in the currently open inventory appear. If no item in this inventory has the `clothing` tag, the `clothing` chip is hidden.
* **OR logic** - items match if they have **any** of the active tags (not all of them).
* **Combines with rarity** - tag filter and rarity filter intersect (AND). Tags within a side are OR; the two filter groups are AND.
* **Combines with search** - text search runs on top of the tag-filtered set.
* **Persistent** - filter selections survive closing and reopening the inventory within the same session. Left and right grids keep independent state.

## Defining tags

Tags live in `config.json` under `itemTags`. Each entry needs a label and a colour:

```json config.json theme={"dark"}
{
  "itemTags": {
    "food":       { "label": "Food",       "color": "#27ae60" },
    "drink":      { "label": "Drink",      "color": "#3498db" },
    "medical":    { "label": "Medical",    "color": "#e74c3c" },
    "clothing":   { "label": "Clothing",   "color": "#9b59b6" },
    "tool":       { "label": "Tool",       "color": "#f39c12" },
    "electronic": { "label": "Electronic", "color": "#1abc9c" },
    "document":   { "label": "Document",   "color": "#bdc3c7" },
    "material":   { "label": "Material",   "color": "#95a5a6" },
    "currency":   { "label": "Currency",   "color": "#f1c40f" },
    "equipment":  { "label": "Equipment",  "color": "#e67e22" },
    "storage":    { "label": "Storage",    "color": "#8e44ad" },
    "weapon":     { "label": "Weapon",     "color": "#e74c3c" },
    "melee":      { "label": "Melee",      "color": "#c0392b" },
    "pistol":     { "label": "Pistol",     "color": "#e67e22" },
    "smg":        { "label": "SMG",        "color": "#d35400" },
    "shotgun":    { "label": "Shotgun",    "color": "#922b21" },
    "rifle":      { "label": "Rifle",      "color": "#1a5276" },
    "sniper":     { "label": "Sniper",     "color": "#154360" },
    "heavy":      { "label": "Heavy",      "color": "#7b241c" },
    "launcher":   { "label": "Launcher",   "color": "#6c3483" },
    "throwable":  { "label": "Throwable",  "color": "#d4ac0d" },
    "attachment": { "label": "Attachment", "color": "#717d7e" },
    "ammo":       { "label": "Ammo",       "color": "#e2b96f" }
  }
}
```

| Field               | Purpose                                                                    |
| ------------------- | -------------------------------------------------------------------------- |
| Key *(e.g. `food`)* | Internal identifier referenced by items and weapons. Lowercase, no spaces. |
| `label`             | Display name shown in the filter chip.                                     |
| `color`             | Hex colour of the chip dot and active highlight.                           |

## Applying tags to an item

Add a `tags` array to any item in `data/items.lua`. Multiple tags allowed.

```lua data/items.lua theme={"dark"}
return {
    ['burger'] = {
        label  = 'Burger',
        weight = 220,
        tags   = { 'food' },
    },

    ['bulletproof_vest'] = {
        label  = 'Bulletproof Vest',
        weight = 3000,
        rarity = 'epic',
        tags   = { 'clothing', 'medical' },
    },

    ['fleeca_card'] = {
        label  = 'Fleeca Card',
        weight = 10,
        rarity = 'legendary',
        tags   = { 'currency', 'document' },
    },
}
```

## Applying tags to a weapon

Identical pattern in `data/weapons.lua`. Weapons should always include the `weapon` tag plus a class tag:

```lua data/weapons.lua theme={"dark"}
return {
    Weapons = {
        ['WEAPON_COMBATPISTOL'] = {
            label  = 'Combat Pistol',
            tags   = { 'weapon', 'pistol' },
            rarity = 'uncommon',
        },

        ['WEAPON_GRENADE'] = {
            label = 'Grenade',
            tags  = { 'weapon', 'throwable' },
        },
    },
}
```

<Tip>
  Tagging weapons with both `weapon` and their class lets players filter "all weapons" or narrow further to "all shotguns" with a single click.
</Tip>

## Adding a custom tag

1. Add the entry to `config.json` → `itemTags`:

   ```json config.json theme={"dark"}
   "vehicle_part": { "label": "Vehicle Part", "color": "#34495e" }
   ```

2. Tag the relevant items:

   ```lua data/items.lua theme={"dark"}
   ['turbocharger'] = {
       label  = 'Turbocharger',
       weight = 4500,
       tags   = { 'vehicle_part' },
   },
   ```

3. Restart the resource. The new chip appears in the filter automatically whenever a tagged item is in view.

## Removing or renaming a tag

* **Renaming** a tag key requires updating every item/weapon that referenced the old key. Items with an orphan tag key simply ignore it.
* **Removing** a tag from `config.json` hides the chip from the filter, but items still carry the orphan key in their `tags` array harmlessly.

<Info>
  Tags declared on items but not present in `config.json` are silently ignored by the UI. You can use this to keep "private" categorisation that doesn't surface as a chip.
</Info>