Currencies

The shop system supports multiple currency types. Each shop specifies which currency it uses via the currencyId field. Currencies are provided by different mods and can also be based on physical items in the player's inventory.

Currency Types

Quest Tokens

Property	Value
Currency ID	quest_tokens
Provided by	Quest mod
Earned through	Completing quests (awarded as quest rewards)

Quest tokens are the primary progression currency. Players earn them by completing quests, and they can be spent in shops that accept quest_tokens.

Example quest reward

{
  "type": "quest_tokens",
  "amount": 5
}

Achievement Points

Property	Value
Currency ID	achievement_points
Provided by	Achievement mod
Earned through	Unlocking achievements

Achievement points are earned passively as players complete achievements. They serve as a secondary currency for shops that reward long-term play.

Shop using achievement points

{
  "id": "rare_collector",
  "currencyId": "achievement_points",
  "items": [ ... ]
}

Item-Based Currencies

Property	Value
Currency ID	item:<ItemId>
Provided by	Core mod (auto-detected)
Earned through	Gathering, crafting, looting

Any Hytale item can be used as a currency. The system counts items in the player's inventory and removes them on purchase. No additional setup is required -- the server automatically creates an item currency provider when it encounters an item: prefix.

Shop using gold bars as currency

{
  "id": "example_shop",
  "currencyId": "item:Ingredient_Bar_Gold",
  "items": [ ... ]
}

Common item currencies:

Currency ID	Item
item:Ingredient_Bar_Gold	Gold Bars
item:Ingredient_Bar_Iron	Iron Bars
item:Ore_Gold	Gold Ore
item:Rock_Gem_Ruby	Rubies

tip

You can use any valid Hytale item ID after the item: prefix. The display name is automatically derived from the item ID.

How Currencies Work in Shops

When a player opens a shop, the system looks up the currency provider matching the shop's currencyId. The provider handles three operations:

1. Balance check -- How many tokens/points/items does the player have?
2. Spend -- Deduct the cost when a purchase is made.
3. Refund -- Return the cost if the item could not be delivered (e.g. inventory full).

Purchase Flow

When a player buys an item, the following checks happen in order:

1. Permission -- Does the player have the required permission (if set)?
2. Purchase limit -- Has the player exceeded maxPurchases for this item today?
3. Balance -- Does the player have enough currency?
4. Transaction -- Currency is deducted and the item is given.
5. Refund on failure -- If the item cannot be placed in the inventory, the currency is returned.

info

Purchase counts reset daily. A player who has bought 3 out of 3 allowed pickaxes today will be able to buy again tomorrow.

Setting Up a Shop with Currencies

To create a shop that uses quest tokens:

shops/quest_rewards.json

{
  "id": "quest_rewards",
  "title": "Quest Reward Shop",
  "currencyId": "quest_tokens",
  "settings": {
    "itemsPerPage": 9,
    "dailyShopSize": 0,
    "showSoldOut": true,
    "allowBuyMultiple": false
  },
  "items": [
    {
      "itemId": "Potion_Health_Greater",
      "name": "Greater Health Potion",
      "quantity": 3,
      "cost": 5,
      "description": "3x Greater Health Potions",
      "category": "consumables"
    },
    {
      "itemId": "Weapon_Sword_Adamantite",
      "name": "Adamantite Sword",
      "quantity": 1,
      "cost": 50,
      "description": "The finest blade",
      "category": "weapons",
      "maxPurchases": 1
    }
  ]
}

caution

If the currency provider for a shop's currencyId is not registered (e.g. the Quest mod is not installed but the shop uses quest_tokens), the shop will fail to open and log a warning.