Server Shop

The server shop is a category-based item browser where players can buy and sell items defined by the server.

How It Works

Players open the shop with /shop. They see a list of categories on the left, and items in the selected category on the right. Clicking an item shows its details, price, and a quantity selector.

Categories

Each category has its own config file in config/TaleShop/categories/.

Field	Required	Description
id	Yes	Unique identifier (auto-generated from filename)
displayName	Yes	Name shown in the UI
iconMaterial	Yes	Item ID used as the category icon
permission	No	Permission node required to access this category

Category Permissions

Add a permission field to restrict a category to specific ranks:

{
  "id": "vip_shop",
  "displayName": "VIP Shop",
  "iconMaterial": "Gem_Diamond",
  "permission": "taleshop.category.vip"
}

Players without taleshop.category.vip won't see this category.

Items

Normal Items

Items that give the player a physical item on purchase.

{
  "material": "Tool_Pickaxe_Iron",
  "displayName": "Iron Pickaxe",
  "description": "A sturdy mining tool",
  "buyPrice": 100,
  "sellPrice": 50,
  "permission": "taleshop.buy.pickaxe"
}

Field	Required	Description
material	Yes	The item ID
displayName	No	Custom display name (uses default item name if empty)
description	No	Short description shown in the shop
buyPrice	No	Price to buy (set to 0 or omit to disable buying)
sellPrice	No	Price when selling (set to 0 or omit to disable selling)
permission	No	Permission required to buy this item

Command Items

Items that execute a command instead of giving a physical item.

{
  "type": "COMMAND",
  "material": "Gem_Diamond",
  "displayName": "VIP Rank",
  "buyPrice": 1000,
  "commands": ["say {player} is now VIP!"]
}

Available placeholders in commands:

• {player} - Player's name

• {uuid} - Player's UUID

Pricing

Pricing Modes

Set PricingMode in config to control what types of pricing are active:

Mode	Money Prices	Item Costs
BOTH (default)	Active	Active
MONEY	Active	Ignored
ITEM	Ignored	Active

Item-Based Costs

Require specific items to buy, acting as an alternative currency:

{
  "material": "Weapon_Sword_Iron",
  "displayName": "Iron Sword",
  "buyPrice": 0,
  "buyCosts": [
    { "material": "Ore_Iron_Ingot", "amount": 5 },
    { "material": "Wood_Oak_Trunk", "amount": 2 }
  ]
}

The player needs both the money price (if set) AND the required items.

Sell Bonuses

Give bonus items alongside money when a player sells:

{
  "material": "Ore_Gold_Raw",
  "sellPrice": 30,
  "sellCosts": [
    { "material": "Coin_Gold", "amount": 1 }
  ]
}

When the player sells Gold Ore, they receive $30 AND 1 Gold Coin.

Stock Limits

Control how many times an item can be bought or sold.

{
  "material": "Potion_Regen_Health",
  "buyPrice": 200,
  "stockLimit": {
    "buyMode": "PER_PLAYER",
    "buyLimit": 5,
    "buyRenewalHours": 24,
    "sellMode": "SERVER",
    "sellLimit": 100
  }
}

Stock Modes

Mode	Description
NONE (default)	No limit
PER_PLAYER	Each player has their own independent limit
SERVER	Shared limit across all players

Stock Renewal

Set buyRenewalHours or sellRenewalHours to automatically reset the stock after a period. Leave unset for no automatic renewal.

Admins can manually reset stock with /shop resetstock.

Enchantments

Items can have enchantments if the SimpleEnchantments plugin is installed:

{
  "material": "Weapon_Sword_Iron",
  "buyPrice": 500,
  "enchantments": {
    "sharpness": 3,
    "unbreaking": 1
  }
}

Set Hooks.SimpleEnchantments.UseRomanNumerals in config to display enchantment levels as Roman numerals (III instead of 3).

Partial ID Matching

Some mods append runtime suffixes to item IDs (e.g. HyFishing_Salmon_Common_Item__dtt_abc123). With PartialIdMatching enabled (default: true), TaleShop matches these items to their shop entry using prefix matching.

This means you only need to add HyFishing_Salmon_Common_Item to the shop, and all variants are automatically recognized.

Search and Sorting

The shop UI has a search bar and sort dropdown:

• Search: Type to filter items. Supports multi-word search (e.g. "iron sword" matches items containing both words).

• Sort options: Name (A-Z), Name (Z-A), Buy Price (Low), Buy Price (High), Sell Price (Low), Sell Price (High).

Notifications

Every buy/sell transaction shows a toast notification with:

• Item icon

• Transaction details (item name, quantity, price)

• Colored border by type (green for buy, amber for sell)

• Sound effect