Configuration

Shop Configuration

Each shop is defined as a JSON file in the shops/ folder inside your KyuubiSoft Core data directory. The server extracts default shops on first startup, and you can freely edit them afterward — your changes are preserved across updates.

File Structure

kyuubisoft_core/
  shops/
    example_shop.json
    general_store.json
    blacksmith.json
    alchemist.json
    daily_deals.json
    rare_collector.json
  custom/
    custom_example_shop.json          <-- your overrides (never overwritten)
    custom_example_shop.json.example  <-- auto-generated template

Shop JSON Format

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

Top-Level Fields

Field	Type	Description
id	string	Unique shop identifier (matches the filename without .json).
title	string	Display title. Can be a localization key or plain text.
currencyId	string	Currency used for purchases. See Currencies.
settings	object	Shop behavior settings (see below).
items	array	List of items available in this shop.

Settings

Field	Default	Description
itemsPerPage	9	Items displayed per page (3x3 grid).
dailyShopSize	0	Set to 0 for a fixed catalog. Any value above zero enables daily rotation with that many items.
showSoldOut	true	Whether to show items that have reached their purchase limit.
allowBuyMultiple	false	Whether players can buy more than one of an item in a single transaction.

Buy/Sell Configuration

Shops can support both buying and selling. The following top-level fields control sell behavior:

Field	Default	Description
buyEnabled	true	Whether buying is enabled. Set to false for sell-only shops.
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	Default sell price as a percentage of the buy cost.
sellWhitelist	null	If set, only these item IDs can be sold. null = all items.
sellBlacklist	null	These item IDs can never be sold.
sellItems	null	Explicit sell prices per item (see below).

Sell Price Priority

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

1. Per-item sellPrice on a catalog item (if > 0).
2. Explicit sellItems list entry for the item.
3. Percentage fallback — sellPricePercent of the item’s buy cost.

Items not in the catalog and not in sellItems cannot be sold.

Explicit Sell Items

Use sellItems to define sell prices for items that are not in the shop catalog, or to override the percentage calculation:

{
  "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 for this item.
maxSellsPerDay	Maximum sells per player per day. 0 = unlimited.

Command items (items with a command field) are never sellable, regardless of whitelist/blacklist settings.

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 items.
name	no	—	Display name. Can be a localization key or plain text.
quantity	no	1	How many of the item the player receives per purchase.
cost	yes	—	Price in the shop’s currency.
sellPrice	no	0	Explicit sell price. 0 = use the sellPricePercent fallback.
description	no	—	Short description shown in the shop UI.
weight	no	100	Selection weight for daily rotation shops. Higher values mean the item appears more often.
category	no	—	Optional category string used for filtering (e.g. food, tools, armor).
maxPurchases	no	0	Maximum purchases per player per day. 0 means unlimited.
maxSells	no	0	Maximum sells per player per day. 0 means unlimited.
permission	no	—	Optional permission node required to see and buy this item.
command	no	—	Command to execute instead of granting an item. Supports {player}, {PlayerName}, {uuid} placeholders.
commandRunAsServer	no	true	true = execute command as console, false = execute as the player.

Command Purchases

Instead of granting a physical item, a shop entry can execute a command:

{
  "itemId": "xp_boost",
  "name": "100 XP Boost",
  "cost": 10,
  "command": "/ksadmin addxp {player} 100",
  "commandRunAsServer": true
}

When command is set, the shop executes the command instead of adding items to the player’s inventory. The itemId is used as a unique identifier for the entry (it does not need to be a real Hytale item ID for command purchases).

If the command fails, the currency is refunded to the player automatically.

Daily Rotation

When dailyShopSize is greater than zero, the shop selects a random subset of items each day using weighted random selection. The rotation is deterministic per player — the same player sees the same daily shop on the same day. Purchase counts and rotation state reset daily.

Tip

Set higher weight values on items you want to appear more frequently in the daily rotation. An item with weight: 200 is twice as likely to be selected as one with weight: 100.

Custom Shop Overrides

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

custom/custom_example_shop.json

{
  "items": [
    {
      "itemId": "Food_Bread",
      "quantity": 10,
      "cost": 3,
      "category": "food",
      "maxPurchases": 5
    },
    {
      "itemId": "Potion_Health_Greater",
      "name": "Greater Health Potion",
      "quantity": 1,
      "cost": 20,
      "description": "Full heal",
      "category": "potions",
      "maxPurchases": 1
    }
  ]
}

The merge logic works as follows:

• Items with the same itemId as a base item replace that base item entirely.
• Items with a new itemId are appended to the shop.

Caution

Custom files are never overwritten by updates. If you want to revert to defaults, simply delete the custom file and restart the server.