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.

Item Definitions

Field	Required	Default	Description
itemId	yes	--	The Hytale item ID (e.g. Tool_Pickaxe_Crude).
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.
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.
permission	no	--	Optional permission node required to see and buy this item.

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.