Skip to content

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.

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

{
"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
}
]
}
FieldTypeDescription
idstringUnique shop identifier (matches the file name without .json). Letters, digits, _ and - only.
titlestringName in the window. Can be a language key or plain text.
currencyIdstringCurrency used for purchases. See Currencies.
permissionstringOptional. Players without this permission cannot open the shop.
iconstringOptional item ID shown left of the title in the shop window (2.8.0). Empty = no icon.
openViastringWhere 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).
settingsobjectShop behavior settings (see below).
itemsarrayThe entries offered in this shop.
FieldDefaultDescription
itemsPerPage9Entries per page (3x3 grid).
dailyShopSize00 = fixed catalog. Any value above zero enables a daily rotation with that many entries.
showSoldOuttrueWhether entries that reached their purchase limit are still shown.
allowBuyMultiplefalsetrue 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.

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

FieldDefaultDescription
buyEnabledtrueWhether buying is enabled. Set to false for a sell-only shop (no “Buy” tab).
sellEnabledfalseWhether players can sell items at this shop.
sellCurrencyIdnullCurrency for sell payouts. null = same as the shop’s currencyId.
sellPricePercent50Fallback sell price as a percentage of the buy price, per piece (see below).
sellWhitelistnullIf set, only these item IDs can be sold. null = all items.
sellBlacklistnullThese item IDs can never be sold. Always wins over the whitelist.
sellItemsnullFixed sell prices for items (see below).

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.

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 }
]
}
FieldDescription
itemIdThe Hytale item ID.
sellPriceFixed sell price per piece.
maxSellsPerDayMaximum 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.

FieldRequiredDefaultDescription
itemIdyes—The Hytale item ID (e.g. Tool_Pickaxe_Crude). Also used as a unique key for command entries.
nameno—Older name field (language key or plain text). The editor keeps it untouched; displayName wins.
displayNameno—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.
quantityno1How many pieces the player receives per purchase.
costyes—Price in the shop’s currency.
sellPriceno0Sell price per piece. 0 = use the sellPricePercent fallback.
descriptionno—Short description shown in the shop window.
weightno100Selection weight for daily rotation shops. Higher values mean the entry appears more often.
categoryno—Optional category, shown as a filter pill in the shop window (e.g. food, tools, armor).
maxPurchasesno0Maximum purchases per player per day (counts purchases, not pieces). 0 means unlimited.
maxSellsno0Maximum sells per player per day. 0 means unlimited.
permissionno—Optional permission. Without it the entry is shown as locked and cannot be bought.
commandno—Command to execute instead of granting an item. Supports {player}, {PlayerName} and {uuid}.
commandRunAsServernotruetrue = run the command as the console, false = run it as the buyer.
enabledno—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. :::

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.

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

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.

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

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.

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.