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; it writes the same files.
File Structure
Section titled “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
Section titled “Shop JSON Format”{ "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
Section titled “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. |
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
Section titled “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
Section titled “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
Section titled “Sell Price Priority”When a player sells an item, the price per piece is determined by:
- Per-entry
sellPriceon a catalog entry (if > 0). - Explicit
sellItemslist entry for the item. - Percentage fallback —
sellPricePercentof the entry’scost, divided by itsquantity. 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
Section titled “Explicit Sell Items”Use sellItems to set sell prices for items that are not in the shop catalog:
{ "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. |
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
Section titled “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
Section titled “Command Purchases”Instead of granting a physical item, an entry can run a command:
{ "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.
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.
Purchase Safety
Section titled “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
Section titled “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.
Custom Shop Overrides
Section titled “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.
{ "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
itemIdas a base entry replace that base entry entirely. - Entries with a new
itemIdare appended to the shop.
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.