> For the complete documentation index, see [llms.txt](https://xerickerspigot.gitbook.io/arenalegends/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xerickerspigot.gitbook.io/arenalegends/gameplay/shopkeeper.md).

# Shopkeeper

The shopkeeper lets players spend round gold on equipment, consumables, anvil rolls, and mythic item rolls during preparation.

## Configuration File

Shopkeeper settings live in:

```
/gameplay/shopkeeper.yml
```

Menu layout and item display live in `/menus/menu-shopkeeper.yml`.

## NPC Display

The NPC appears in the lobby at the `SHOPKEEPER` marker.

| Setting area        | What it controls                               |
| ------------------- | ---------------------------------------------- |
| `entity.type`       | NPC entity type.                               |
| `entity.profession` | Villager profession when the type supports it. |
| `entity.hologram`   | Text shown above the NPC.                      |

## Shop Settings

| Key                        | What it controls                              |
| -------------------------- | --------------------------------------------- |
| `setting.gold-cost.anvil`  | Cost of an extra anvil stat roll.             |
| `setting.gold-cost.mythic` | Cost of a mythic item roll.                   |
| `setting.discard-items`    | Whether shop logic can discard handled items. |
| `setting.hide-categories`  | Categories hidden from the shop menu.         |

## Categories

`category-builder` defines category icons and display data.

| Category      | Contains                     |
| ------------- | ---------------------------- |
| `ALL`         | All visible shop items.      |
| `WEAPONS`     | Weapons.                     |
| `ARMOR`       | Armor pieces.                |
| `POTIONS`     | Potions.                     |
| `SUMMONS`     | Spawn eggs and summon items. |
| `CONSUMABLES` | Consumable utility items.    |
| `ANVIL`       | Anvil stat roll actions.     |
| `MYTHICS`     | Mythic item roll actions.    |

The shipped `setting.hide-categories` hides `ANVIL` and `MYTHICS`.

## Shop Items

Shop items are generated from YAML files under the item configuration folders.

| Group         | What it contains                                                     |
| ------------- | -------------------------------------------------------------------- |
| `weapons`     | Swords, axes, bows, crossbows, spears, mace, and trident.            |
| `armors`      | Armor pieces by material tier.                                       |
| `potions`     | Normal and splash potions.                                           |
| `consumables` | Arrows, shields, TNT, golden apples, and other utility items.        |
| `eggs`        | Summon items.                                                        |
| `mythics`     | Mythic weapons, enchantments, potions, gold bundles, and roll items. |

Item display uses the format documented in [Item Builders](/arenalegends/menus/item-builders.md).

## Item Keys

| Key                                         | What it controls                                                                                          |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `purchase.gold-cost`                        | Gold price.                                                                                               |
| `purchase.round-unlock`                     | Round from which the item appears in the shop.                                                            |
| `purchase.max-concurrent`                   | How many copies one player can own.                                                                       |
| `purchase.consumable`                       | Whether the item is consumed on use.                                                                      |
| `purchase.virtual`                          | No item is placed in the inventory; pair with `command`.                                                  |
| `purchase.category`                         | Shop category used for filtering.                                                                         |
| `upgrade.shared-id`, `upgrade.upgrade-tier` | Shared upgrade tracking across item tiers.                                                                |
| `enchant.*`                                 | Enchantment entries: `is-enchant`, `max-purchases`, `cost-increase-per-purchase`, `enchants`, `apply-to`. |
| `mythic.is-mythic`                          | Marks the item as a mythic roll candidate.                                                                |
| `command`                                   | Commands run on purchase with the `player->` and `console->` prefixes.                                    |
| `equipment-builder.<slot>.*`                | Item data per equipment slot.                                                                             |