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.

{
  "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.

{
  "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.

{
  "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

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:

Balance check — How many tokens/points/items does the player have?
Spend — Deduct the cost when a purchase is made.
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:

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

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:

{
  "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
    }
  ]
}