# Configuration

**Version:** 2.0.6

The main file is:

```
mods/kyuubisoft_shops/config.json
```

It is created from the defaults on the first start. With KyuubiSoft Core installed, new default fields are merged into an existing file on every start; without Core, missing fields simply use their defaults.

**Changing settings:**

- In game: the **Settings** sections of the admin window (`/kssa admin`, see [Admin Panel](./admin-panel)). A save writes `config.json` and is active at once (except where noted).
- By hand: edit the file, then `/kssa reload` or restart.
- A few values are only read at server start; they are marked **restart** below.

Fields marked **no effect** are still read from the file but nothing in 2.0.6 uses them.

---

## `features`

```json
"features": {
  "playerShops": true,
  "adminShops": true,
  "directory": true,
  "ratings": true,
  "notifications": true,
  "shopOfTheWeek": false,
  "rentSystem": false,
  "claimsIntegration": true
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `playerShops` | `true` | `false`: nobody can open new player shops (license and `/ksshop create`); existing shops keep working | General: "Allow player shops" |
| `adminShops` | `true` | `false`: `/kssa createadmin` is refused. Template files in `admin-shops/` still load | - |
| `directory` | `true` | `false`: `/ksshop browse` is refused. The other ways into the market (`/ksshop myshops`, `rentalstations`, the shop window's back button) still open it | General: "Market active" |
| `ratings` | `true` | Together with `ratings.enabled`: `false` hides the Reviews tab and refuses new ratings in the shop window | General: "Ratings" (sets both) |
| `notifications` | `true` | **no effect** (see `notifications.enabled`) | - |
| `shopOfTheWeek` | `false` | Runs a daily task (first run 10 minutes after the start): ends expired features and, with `featured.autoFeatureTopRated`, features the best shops. **restart** | - |
| `rentSystem` | `false` | **no effect** (the legacy rent is `rent.enabled`; rental stands are `rentalStations`) | - |
| `claimsIntegration` | `true` | Only used together with `playerShops.requireClaim` | - |

---

## `playerShops`

```json
"playerShops": {
  "maxShopsPerPlayer": 3,
  "maxItemsPerShop": 45,
  "creationCost": 500,
  "requireClaim": false,
  "allowNpcCustomization": true,
  "nameMinLength": 3,
  "nameMaxLength": 24,
  "descriptionMaxLength": 100,
  "maxTagsPerShop": 5,
  "listingEnabled": true,
  "listingPricePerDay": 100,
  "listingMinDays": 1,
  "listingMaxDays": 30,
  "listingFreeDaysOnCreate": 7,
  "allowBuybackWithdraw": false
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `maxShopsPerPlayer` | `3` | Shops per player (at least 1). Packed shops count; shops on rented stands count unless `rentalStations.rentalShopsCountTowardShopLimit` is `false`. Raised per rank with `ks.shop.limit.shops.N` | General: "Shops per player" (1-100) |
| `maxItemsPerShop` | `45` | Different offers per shop (1-45). Raised with `ks.shop.limit.items.N`, never above 45 | - |
| `creationCost` | `500` | Gold paid when a shop opens (license or `/ksshop create`). `/ksshop delete` pays half of the current value back | General: "Opening cost" |
| `requireClaim` | `false` | With `features.claimsIntegration` and KyuubiSoft Claims installed: opening a shop inside a claim is only allowed for its owner, trusted players, co-owners and guild members who may build there (never banned players). In a Claims server zone only when the zone allows building, or for Claims admins. Free land is always allowed. Setting a packed shop up again is not checked | - |
| `allowNpcCustomization` | `true` | When a shop has no merchant look set, its merchant wears the owner's skin. `false`: the `npc.defaultSkinUsername` look instead. A look set in the editor is used either way | - |
| `nameMinLength` / `nameMaxLength` | `3` / `24` | Length of shop names (license, `/ksshop create`, rename, editor, `/kssa createadmin`). Names are unique across all shops, not case-sensitive | General: "Name at least" / "Name at most" (1-64) |
| `descriptionMaxLength` | `100` | Length of the shop description | General: "Description at most" (0-500) |
| `maxTagsPerShop` | `5` | **no effect** | - |
| `listingEnabled` | `true` | `true`: player shops show in the market only while their listing runs. `false`: new player shops are listed forever, buying a listing is refused and the editor hides the listing section. Shops that were already unlisted stay unlisted | General: "Market listing costs gold" |
| `listingPricePerDay` | `100` | Gold per listing day | General: "Listing per day" |
| `listingMinDays` / `listingMaxDays` | `1` / `30` | Days per purchase; more days are added to a running listing | General: "Listing at least" / "Listing at most" (1-365) |
| `listingFreeDaysOnCreate` | `7` | Free listing days for the first shop a player ever opens (remembered per player in the database, also after deleting the shop). `0` = none | General: "Free days for the first shop" |
| `allowBuybackWithdraw` | `false` | `true`: owners can take gold back out of the till (editor, Till tab). `false`: only packing up returns the till (as before 2.0.0) | General: "Owners may withdraw the buyback till" |

---

## `adminShops`

```json
"adminShops": {
  "unlimitedStock": true,
  "allowBuyAndSell": true,
  "defaultNpcSkin": ""
}
```

| Field | Default | Effect |
|-------|---------|--------|
| `unlimitedStock` | `true` | Offers of [server shop templates](#server-shop-templates) get unlimited stock (`stock` and `maxStock` from the file are ignored). Items dragged into a server shop in the editor always have the dragged amount as stock |
| `allowBuyAndSell` | `true` | **no effect** |
| `defaultNpcSkin` | `""` | **no effect**; use `npc.defaultSkinUsername`, `npcSkinUsername` in a template or the merchant look in the editor |

---

## `economy`

```json
"economy": {
  "provider": "auto",
  "currencyName": "Gold",
  "currencySymbol": "",
  "maxPrice": 1000000,
  "minPrice": 1
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `provider` | `"auto"` | **no effect**; the economy is always detected (Core first, then VaultUnlocked) | Economy: "Currency" shows what was found |
| `currencyName` / `currencySymbol` | `"Gold"` / `""` | **no effect**; the windows use the economy's currency name (fallback "Gold"). From 2.0.7 (not released yet) `currencyName` is used when the economy reports no name of its own; `currencySymbol` stays without effect | - |
| `minPrice` / `maxPrice` | `1` / `1000000` | Allowed price per piece in the editor (sale and buyback). The minimum is at least 1. A new offer starts at 10, moved into this range | Economy: "Minimum price" / "Maximum price" |

---

## `tax`

```json
"tax": {
  "enabled": false,
  "buyTaxPercent": 5.0,
  "sellTaxPercent": 5.0,
  "showTaxInPrice": true,
  "taxRecipient": "server"
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `enabled` | `false` | Switches both taxes on | Economy: "Collect taxes" |
| `buyTaxPercent` | `5.0` | Paid by the buyer on top of the price. The seller gets the full price | Economy: "Tax on purchases" (0-100) |
| `sellTaxPercent` | `5.0` | Taken from what a player receives when selling to a shop. The shop's till still pays the full price | Economy: "Tax on sales to shops" (0-100) |
| `showTaxInPrice` | `true` | **no effect**; the windows always show the tax line when a tax is on |
| `taxRecipient` | `"server"` | **no effect**; taxes always leave the economy |

Taxes are rounded to whole gold and added to the shop's "tax paid" total. `/kssa settax <0.0-1.0>` sets both percentages at once.

---

## `rent` (legacy daily rent)

```json
"rent": {
  "enabled": false,
  "costPerDay": 50.0,
  "gracePeriodDays": 3,
  "autoCloseOnExpire": true,
  "autoDeleteOnUnpaidDays": 7,
  "rentExemptForNewShopsDays": 7,
  "rentNotificationBeforeDays": 1,
  "maxCycleDays": 30
}
```

An old system that charges owners a daily rent for every player shop. It is not the [rental stands](./rentals) system and not in the admin window.

With `enabled: true` (**restart**) an hourly task (first run 5 minutes after the start) handles every player shop older than `rentExemptForNewShopsDays`: once the rent is more than `gracePeriodDays` overdue it tries to take `costPerDay` from the owner; if that fails and `autoCloseOnExpire` is on, the shop is closed. More than `autoDeleteOnUnpaidDays` overdue, the shop is deleted (stock and till go to the owner's mailbox, the merchant is removed). Owners see "A shop was closed / removed ..." notices on the mailbox's Sales tab. `rentNotificationBeforeDays` and `maxCycleDays` have **no effect**.

---

## `ratings`

```json
"ratings": {
  "enabled": true,
  "minStars": 1,
  "maxStars": 5,
  "allowComments": true,
  "commentMaxLength": 100,
  "cooldownMinutes": 60
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `enabled` | `true` | See `features.ratings` | General: "Ratings" |
| `minStars` / `maxStars` | `1` / `5` | Accepted rating range (kept within 1-5) | - |
| `allowComments` | `true` | `false`: ratings are diamonds only, the comment field is hidden | General: "Comments with ratings" |
| `commentMaxLength` | `100` | Longer comments are cut | General: "Comment at most" (0-500) |
| `cooldownMinutes` | `60` | How long a player waits before changing their rating of the same shop. `0` = any time | General: "Wait between ratings" |

Each player has one rating per shop; rating again replaces it.

---

## `notifications`

```json
"notifications": {
  "enabled": true,
  "batchOnLogin": true,
  "maxStoredPerPlayer": 50,
  "soundEnabled": true
}
```

A **sale notification** is stored when someone buys from your shop while you are offline.

| Field | Default | Effect |
|-------|---------|--------|
| `enabled` | `true` | `false`: hides the mailbox's Sales tab and refuses `/ksshop notifications` |
| `batchOnLogin` | `true` | On join: "While you were offline: N sale(s), N item(s) sold for X." plus a hint to `/ksshop notifications` |
| `maxStoredPerPlayer` | `50` | Only the newest N notifications per player are kept; the Sales tab shows up to 50 |
| `soundEnabled` | `true` | **no effect** |

---

## `npc`

```json
"npc": {
  "defaultEntityId": "NPC_Shopkeeper",
  "defaultSkinUsername": "",
  "lookAtPlayer": true,
  "interactionRange": 5.0,
  "showNameplate": true,
  "spawnDelaySecondsOnJoin": 3,
  "skinRetryDelaySeconds": 5
}
```

| Field | Default | Effect |
|-------|---------|--------|
| `defaultEntityId` | `"NPC_Shopkeeper"` | **no effect** (merchants use the plugin's own role `Shop_Keeper_Role`) |
| `defaultSkinUsername` | `""` | Player name whose skin merchants wear when no other look applies (server shops, free rental stands, `allowNpcCustomization: false`). Empty = default model |
| `lookAtPlayer` | `true` | Merchants turn their head to nearby players. **restart** |
| `interactionRange` / `showNameplate` | `5.0` / `true` | **no effect** (name tags are switched per shop in the editor) |
| `spawnDelaySecondsOnJoin` | `3` | Seconds (0-60) between the first player entering a world and the merchants of that world spawning, so skins apply reliably |
| `skinRetryDelaySeconds` | `5` | When a skin lookup fails, it is tried once more after this many seconds (0-60, 0 = no retry) |

Skins are looked up by player name at `playerdb.co` and cached in `skin-cache.json`.

---

## `directory`

```json
"directory": {
  "shopsPerPage": 9,
  "defaultSortBy": "rating",
  "showEmptyShops": false,
  "showClosedShops": false
}
```

**No effect** in 2.0.6. The market shows up to 60 shop cards and 120 offers, sorts by rating first, lists open shops only and also shows shops that sell nothing yet.

---

## `featured`

```json
"featured": {
  "enabled": false,
  "cost": 1000,
  "durationDays": 7,
  "maxFeaturedSlots": 3,
  "autoFeatureTopRated": false,
  "autoFeatureMinRating": 4.5,
  "autoFeatureMinSales": 50
}
```

A featured shop is listed first in the market when sorting by rating and carries a "Featured" chip.

| Field | Default | Effect |
|-------|---------|--------|
| `enabled` / `cost` | `false` / `1000` | **no effect** (players cannot buy a feature; admins set it) |
| `durationDays` | `7` | Length of a feature set by the admin window, `/kssa feature` or the automatic feature |
| `autoFeatureTopRated` | `false` | With `features.shopOfTheWeek`: features the best open player shops once a day |
| `autoFeatureMinRating` | `4.5` | Minimum average rating (and at least one rating) |
| `autoFeatureMinSales` | `50` | Minimum total revenue in gold (not the number of sales) |
| `maxFeaturedSlots` | `3` | The automatic feature only fills up to this many featured shops (admins can feature more by hand) |

---

## `rentalStations`

```json
"rentalStations": {
  "enabled": true,
  "defaultPricePerDay": 100,
  "defaultMaxDays": 7,
  "defaultMinBid": 500,
  "defaultBidIncrement": 10,
  "defaultAuctionDurationMinutes": 60,
  "maxConcurrentRentalsDefault": 1,
  "onEmptyAuction": "RESTART",
  "auctionAntiSnipingSeconds": 30,
  "auctionEndingSoonSeconds": 60,
  "extendMaxDays": 7,
  "releaseEarlyGoldRefundFraction": 0.0,
  "rentalShopsListFree": true,
  "rentalShopsCountTowardShopLimit": true
}
```

| Field | Default | Effect | Admin window (Rental stands settings) |
|-------|---------|--------|---------------------------------------|
| `enabled` | `true` | `false`: the market hides the Rental stands tab. The expiry and countdown tasks only start when it is `true` at server start. **restart** | "Rental stands active" |
| `rentalShopsListFree` | `true` | A shop on a rented stand is listed in the market for free until the rental ends | "Rented shops are listed for free" |
| `rentalShopsCountTowardShopLimit` | `true` | Shops on rented stands count toward `playerShops.maxShopsPerPlayer`, as before 2.0.0. `false`: only a player's own shops (packed ones included) use the shop limit, so a rented stand never blocks opening or receiving a shop. Missing = `true` | - |
| `defaultPricePerDay` | `100` | Price per day of new fixed-price stands | "Price per day" |
| `defaultMaxDays` | `7` | Longest rental at once of new fixed-price stands; rental days of the winner of new auction stands | "Maximum duration" |
| `defaultMinBid` | `500` | First bid of new auction stands | "Minimum bid" |
| `defaultBidIncrement` | `10` | Minimum raise over the high bid | "Bid step" |
| `defaultAuctionDurationMinutes` | `60` | Length of an auction round | "Auction duration" (1-10080 min) |
| `maxConcurrentRentalsDefault` | `1` | Stands one player may rent at the same time; more with `ks.rental.limit.N` | "Stands per player" |
| `auctionAntiSnipingSeconds` | `30` | A bid in the last N seconds extends the auction by N seconds. `0` = off | "A late bid extends by" |
| `auctionEndingSoonSeconds` | `60` | One chat message to all online players when an auction has N seconds left. `0` = off | "Ending soon" notice |
| `extendMaxDays` | `7` | Most days per extension of a fixed-price rental | "Extend at most" |
| `releaseEarlyGoldRefundFraction` | `0.0` | Share (0.0-1.0) of the paid days left that is refunded when a fixed-price rental is ended early | "Refund on early release" (in percent) |
| `onEmptyAuction` | `"RESTART"` | What happens when an auction ends without bids: `RESTART` new round, `VACANT` the auction rests until an admin restarts it, `DELETE` the stand is deleted together with its placeholder shop and merchant | "Auction without bids": Restart / Let rest / Delete |

The `default*` values only apply to stands created afterwards. Details: [Rental Stands](./rentals).

---

## `mailbox`

```json
"mailbox": {
  "deliverPurchasesToInventory": false,
  "combineSaleEarnings": false
}
```

| Field | Default | Effect | Admin window |
|-------|---------|--------|--------------|
| `deliverPurchasesToInventory` | `false` | `true`: purchases go straight into the buyer's inventory; only what does not fit is mailed. `false`: every purchase is mailed (as before 2.0.0) | Economy: "Purchases straight into the inventory" |
| `combineSaleEarnings` | `false` | `true`: the earnings of a shop are added to one open money mail per shop ("Earnings from X · N sales"). `false`: one money mail per sale | Economy: "Collect sale earnings in one mail" |

---

## `database`

```json
"database": {
  "type": "sqlite",
  "sqlitePath": "shops.db",
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "database": "hytale",
    "username": "root",
    "password": ""
  }
}
```

`type` is `sqlite` (file `sqlitePath` inside the data folder) or `mysql` (uses the `mysql` block). **restart**. The tables are created on the first start; see [API Reference](./api-reference#database-tables).

---

## `itemBlacklist`

```json
"itemBlacklist": []
```

Item IDs (for example `Weapon_Sword_Mithril`, compared without case) that cannot be put into a shop in the editor. Offers that already exist stay until their owner takes them out. Change it with `/kssa blacklist`, the admin window (**Blacklist**) or by hand; both in-game ways save the file.

---

## `categories`

```json
"categories": [
  { "id": "weapons",   "displayName": "Weapons",   "icon": "Iron_Sword",          "sortOrder": 1 },
  ...
]
```

**No effect** in 2.0.6. The eight categories are fixed: weapons, armor, tools, resources, potions, food, building, misc. Their names come from the language files (`shop.category.*`, `shop.ui.editor.cat.*`, `shop.ui.create.cat.*`), the market icons are built in.

---

## Server shop templates

Every `*.json` file in `mods/kyuubisoft_shops/admin-shops/` is one server shop. The folder is created on the first start with the disabled example `example_blacksmith.json`:

```json
{
  "enabled": false,
  "id": "blacksmith",
  "name": "Village Blacksmith",
  "description": "Fine weapons and sturdy armor.",
  "category": "weapons",
  "npcSkinUsername": "Blacksmith",
  "currencyId": "",
  "worldName": "",
  "posX": 0, "posY": 0, "posZ": 0,
  "npcRotY": 0,
  "items": [
    {
      "itemId": "Weapon_Sword_Iron",
      "buyPrice": 150,
      "sellPrice": 75,
      "stock": -1,
      "maxStock": -1,
      "buyEnabled": true,
      "sellEnabled": true,
      "dailyBuyLimit": 0,
      "dailySellLimit": 0,
      "category": "weapons"
    }
  ]
}
```

| Field | Meaning |
|-------|---------|
| `enabled` | `false` skips the file. Missing = enabled (files from before 2.0.0). Disabling a file does not remove a shop that was already created; delete it in game |
| `id` | A UUID, or any text (turned into a fixed UUID). `/kssa deleteadmin <id>` accepts the text |
| `name`, `description`, `category` | Shop name, description and one of the eight category IDs |
| `npcSkinUsername` | Player name whose skin the merchant wears |
| `worldName` | World of the shop; empty = the server's default world |
| `posX`, `posY`, `posZ`, `npcRotY` | Position and facing of the merchant |
| `items[].buyPrice` | What customers pay per piece (with `buyEnabled`) |
| `items[].sellPrice` | What the shop pays per piece when customers sell (with `sellEnabled`); the server pays, there is no till |
| `items[].stock`, `maxStock` | Only used with `adminShops.unlimitedStock: false`; `-1` = unlimited / no cap |
| `items[].dailyBuyLimit` | Buyback quota: the shop buys at most this many in total, then stops buying the item. `0` = no limit |
| `items[].category` | Shown next to the rarity in the shop window's item detail (the market filters by the shop's `category`) |
| `currencyId`, `items[].dailySellLimit` | **no effect** |

Offers fill the grid in file order. Templates carry no item metadata (enchantments).

**When a template is applied:** the plugin remembers the content of each file it applied (`admin-shops/.applied.json`).

- No shop with that id yet: the shop is created.
- The file is new or changed since it was last applied: the existing shop is rewritten from it (offers, name, description, category, look, position).
- The file is unchanged: the shop is left as admins edited it in game.
- The file is unchanged and the shop was deleted in game: it stays deleted until the file changes.

Changed files are applied on the next start. On the first start of 2.0.0 nothing is recorded yet, so every enabled template rewrites its shop once.

---

## Localization

- Language files: `mods/kyuubisoft_shops/localization/<lang>.json` for `en-US`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`, `pl-PL`, `tr-TR`, `it-IT`.
- Each player sees their language from `/kslang` (if the server lets players choose), otherwise the server's default player language (set in KyuubiSoft Core's `/ksadmin` hub, Language tab), otherwise their client language. Missing keys fall back to `en-US`.
- The files carry `"_localization_version"` (32 in 2.0.6). When a file on disk is older, it is saved as `<lang>.json.backup-v<old>` and replaced by the new default. Your own edits are not merged; copy them over from the backup.
- Edits are loaded by `/kssa reload` or the admin window's **Reload**.
- The names and descriptions of the license and the mailbox block are part of the asset pack in the jar (`Server/Languages/<lang>/shops.lang`) and cannot be changed in the data folder.
- A few texts are not translated: the bound license tooltip ("Shop Token: ..."), the free stand name plates (`[100g/day]`, `[AUCTION 500g]`), `[CLOSED]` on name plates and some chat lines of `/ksshop history`, `/ksshop search` and `/kslang` (bare `/kslang` answers in chat with your current language, the available codes and how to change it).