# Configuration

# Shop Configuration

Each shop is a JSON file in the `shops/` folder of the Core data folder (`mods/kyuubisoft_core/shops/`). The server extracts the shipped shops on first start, and you can freely edit them afterwards — your changes are kept across updates. You can also edit every shop in game with the [Shop Editor](https://wiki.kyuubisoft.com/hytale/shop-system/admin-panel/); it writes the same files.

## File Structure

```
mods/kyuubisoft_core/
  shops/
    example_shop.json
    general_store.json
    blacksmith.json
    alchemist.json
    daily_deals.json
    rare_collector.json
    .removed_defaults                 <-- shipped shops you deleted or renamed
  custom/
    custom_example_shop.json          <-- your overrides (never overwritten)
  shop_data/                          <-- per-player purchase and sell counters
```

:::info Deleted shipped shops stay deleted
When you delete or rename one of the shipped shops in the shop editor, its ID is written to `shops/.removed_defaults` and the shop is not extracted again on the next start. Remove the line from that file to get the shipped shop back.
:::

## Shop JSON Format

```json
{
  "id": "example_shop",
  "title": "shop.example.title",
  "currencyId": "item:Ingredient_Bar_Gold",
  "icon": "Ingredient_Bar_Gold",
  "openVia": "any",
  "settings": {
    "itemsPerPage": 9,
    "dailyShopSize": 0,
    "showSoldOut": true,
    "allowBuyMultiple": false
  },
  "items": [
    {
      "itemId": "Food_Bread",
      "quantity": 5,
      "cost": 2,
      "weight": 100,
      "category": "food",
      "maxPurchases": 0
    }
  ]
}
```

## Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique shop identifier (matches the file name without `.json`). Letters, digits, `_` and `-` only. |
| `title` | string | Name in the window. Can be a language key or plain text. |
| `currencyId` | string | Currency used for purchases. See [Currencies](https://wiki.kyuubisoft.com/hytale/shop-system/currencies/). |
| `permission` | string | Optional. Players without this permission cannot open the shop. |
| `icon` | string | Optional item ID shown left of the title in the shop window (2.8.0). Empty = no icon. |
| `openVia` | string | Where the shop opens (2.8.0): `any` (default — at its NPC and by command), `npc` (only at its NPC; `/ksnpcshop open` and `sell` refuse) or `command` (only by command; the NPC does not open it). |
| `settings` | object | Shop behavior settings (see below). |
| `items` | array | The entries offered in this shop. |

## Settings

| Field | Default | Description |
|-------|---------|-------------|
| `itemsPerPage` | `9` | Entries per page (3x3 grid). |
| `dailyShopSize` | `0` | `0` = fixed catalog. Any value above zero enables a daily rotation with that many entries. |
| `showSoldOut` | `true` | Whether entries that reached their purchase limit are still shown. |
| `allowBuyMultiple` | `false` | `true` shows a quantity stepper: players choose how many bundles they buy, and everything is checked and paid in one step. `false` buys one bundle per click. Command entries are always bought one at a time. |

## Buy/Sell Configuration

Shops can support both buying and selling. These top-level fields control the "Sell" tab:

| Field | Default | Description |
|-------|---------|-------------|
| `buyEnabled` | `true` | Whether buying is enabled. Set to `false` for a sell-only shop (no "Buy" tab). |
| `sellEnabled` | `false` | Whether players can sell items at this shop. |
| `sellCurrencyId` | `null` | Currency for sell payouts. `null` = same as the shop's `currencyId`. |
| `sellPricePercent` | `50` | Fallback sell price as a percentage of the buy price, per piece (see below). |
| `sellWhitelist` | `null` | If set, only these item IDs can be sold. `null` = all items. |
| `sellBlacklist` | `null` | These item IDs can never be sold. Always wins over the whitelist. |
| `sellItems` | `null` | Fixed sell prices for items (see below). |

### Sell Price Priority

When a player sells an item, the price per piece is determined by:

1. **Per-entry `sellPrice`** on a catalog entry (if > 0).
2. **Explicit `sellItems` list** entry for the item.
3. **Percentage fallback** — `sellPricePercent` of the entry's `cost`, divided by its `quantity`. The fallback is a price **per piece**, so a bundle can never be sold back for more than it cost. Pieces worth less than 1 are not sellable through the fallback.

Items that are neither in the catalog nor in `sellItems` cannot be sold. Entries that are switched off (`enabled: false`) do not count. Damaged or modified items are listed as "not sellable" when the shop cannot take them.

### Explicit Sell Items

Use `sellItems` to set sell prices for items that are not in the shop catalog:

```json
{
  "sellItems": [
    { "itemId": "Ore_Gold", "sellPrice": 3, "maxSellsPerDay": 50 },
    { "itemId": "Ore_Iron", "sellPrice": 1, "maxSellsPerDay": 100 }
  ]
}
```

| Field | Description |
|---|---|
| `itemId` | The Hytale item ID. |
| `sellPrice` | Fixed sell price per piece. |
| `maxSellsPerDay` | Maximum sells per player per day. `0` = unlimited. |

:::info
Command entries (entries with a `command` field) are **never** sellable, regardless of whitelist/blacklist settings.
:::

Players only lose the items they sell once the payout went through. If the payout fails, they keep their items.

## Item Definitions

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `itemId` | yes | -- | The Hytale item ID (e.g. `Tool_Pickaxe_Crude`). Also used as a unique key for command entries. |
| `name` | no | -- | Older name field (language key or plain text). The editor keeps it untouched; `displayName` wins. |
| `displayName` | no | -- | Name shown in the shop (text or language key, 2.9.0). Without it, real items show the game's translated item name in each player's language. |
| `quantity` | no | `1` | How many pieces the player receives per purchase. |
| `cost` | yes | -- | Price in the shop's currency. |
| `sellPrice` | no | `0` | Sell price per piece. `0` = use the `sellPricePercent` fallback. |
| `description` | no | -- | Short description shown in the shop window. |
| `weight` | no | `100` | Selection weight for daily rotation shops. Higher values mean the entry appears more often. |
| `category` | no | -- | Optional category, shown as a filter pill in the shop window (e.g. `food`, `tools`, `armor`). |
| `maxPurchases` | no | `0` | Maximum purchases per player per day (counts purchases, not pieces). `0` means unlimited. |
| `maxSells` | no | `0` | Maximum sells per player per day. `0` means unlimited. |
| `permission` | no | -- | Optional permission. Without it the entry is shown as locked and cannot be bought. |
| `command` | no | -- | Command to execute instead of granting an item. Supports `{player}`, `{PlayerName}` and `{uuid}`. |
| `commandRunAsServer` | no | `true` | `true` = run the command as the console, `false` = run it as the buyer. |
| `enabled` | no | -- | `false` hides the entry from players and from the daily rotation, and it is not bought back (2.9.0). Without the field the entry is offered. |

:::tip Category labels
The shop window translates common categories (`armor`, `cure`, `food`, `health`, `mana`, `materials`, `potions`, `repair`, `stamina`, `tools`, `utility`). Other category names are shown as written. You can translate your own with the key `shop.ui.cat.<category>` in Core's `custom_<lang>.json`.
:::

### Command Purchases

Instead of granting a physical item, an entry can run a command:

```json
{
  "itemId": "xp_boost",
  "displayName": "100 XP Boost",
  "cost": 10,
  "command": "ksadmin addxp {player} 100",
  "commandRunAsServer": true
}
```

When `command` is set, the shop runs the command instead of adding items to the inventory. The `itemId` is only the entry's key here — it does not need to be a real item ID.

How command purchases are protected (since Core 2.8.0):

- A command that does not exist, or that the buyer may not use (when it runs as the buyer), is refused **before** paying.
- A command that fails while running is refunded, and the purchase does not count toward the limit.
- If the buyer changed world meanwhile, the refund still reaches them. For a buyer who went offline, an economy refund is paid by player ID.

:::warning
Console commands run with full server rights, no matter who buys. In the shop editor, entries that run as the console can only be added, changed or removed with `ks.core.admin.dialog.console` — see [Permissions](https://wiki.kyuubisoft.com/hytale/shop-system/permissions/).
:::

## Purchase Safety

- Items are only charged when they fit: with a full inventory the purchase is refused before paying.
- Granting is all or nothing — a bundle is never added only partly.
- Negative, NaN or infinite amounts are refused before they reach an economy plugin.
- Shop files are saved atomically, so a half-written file never replaces a good one.

## Daily Rotation

When `dailyShopSize` is greater than zero, the shop draws that many entries each day, weighted by `weight`. Every player gets their **own pick**, new at midnight (server time) — the same player sees the same daily shop all day. Purchase and sell counters start fresh every day. If the pool has fewer entries than `dailyShopSize`, players simply see all of them.

:::tip
Set higher `weight` values on entries you want to appear more often. An entry with `weight: 200` is twice as likely to be drawn as one with `weight: 100`.
:::

## Custom Shop Overrides

You can override or extend any shop without modifying the shipped files. Place a file named `custom_<shopId>.json` in the `custom/` folder.

```json title="custom/custom_example_shop.json"
{
  "items": [
    {
      "itemId": "Food_Bread",
      "quantity": 10,
      "cost": 3,
      "category": "food",
      "maxPurchases": 5
    },
    {
      "itemId": "Potion_Health_Greater",
      "quantity": 1,
      "cost": 20,
      "description": "Full heal",
      "category": "potions",
      "maxPurchases": 1
    }
  ]
}
```

The merge works like this:

- Entries with the **same `itemId`** as a base entry **replace** that base entry entirely.
- Entries with a **new `itemId`** are **appended** to the shop.

:::caution
Custom files are never overwritten by updates. To go back to the shipped shop, delete the custom file and run `/ksadmin reload`.
:::

Shops that other mods register (for example the Quests token shop) are not stored here. The shop editor shows them read-only; you change them in that mod's own files.