Skip to content

Currencies

Each shop names one currency in its currencyId field (and optionally a different payout currency in sellCurrencyId). Currencies come from other KS mods, from an economy plugin, or from items in the player’s inventory.

PropertyValue
Currency IDquest_tokens
Provided byQuest mod
Earned throughCompleting quests (awarded as quest rewards)

Quest tokens are the main progression currency. Players earn them by completing quests and spend them in shops that accept quest_tokens.

Example quest reward
{
"type": "quest_tokens",
"amount": 5
}
PropertyValue
Currency IDachievement_points
Provided byAchievement mod
Earned throughUnlocking achievements

Achievement points are earned as players complete achievements. They work well for shops that reward long-term play.

Shop using achievement points
{
"id": "rare_collector",
"currencyId": "achievement_points",
"items": [ ... ]
}
PropertyValue
Currency IDseason_tokens
Provided bySeason Pass mod

When the Season Pass mod is installed, its season tokens can also be used as an NPC shop currency.

PropertyValue
Currency IDeconomy
Provided byAn economy plugin through Core’s economy bridge

Core connects to an economy plugin through VaultUnlocked (any economy that registers there, for example Ecotale) or EliteEssentials. The bridge also finds an economy plugin that starts after Core. Use "currencyId": "economy" to sell for the server’s money.

A failed balance read is never treated as a balance of 0, and the payment itself always decides whether a purchase goes through.

PropertyValue
Currency IDitem:<ItemId>
Provided byCore (automatic)
Earned throughGathering, crafting, looting

Any Hytale item can be used as a currency. The shop counts the items in the player’s inventory and removes them on purchase. No setup is needed — Core creates the currency the first time it sees an item: ID.

Shop using gold bars as currency
{
"id": "example_shop",
"currencyId": "item:Ingredient_Bar_Gold",
"items": [ ... ]
}

Common item currencies:

Currency IDItem
item:Ingredient_Bar_GoldGold Bars
item:Ingredient_Bar_IronIron Bars
item:Ore_GoldGold Ore

When a player opens a shop, Core looks up the currency for the shop’s currencyId. The currency handles three things:

  1. Balance — How many tokens, points, coins or items does the player have?
  2. Spend — Take the price when a purchase is made.
  3. Refund — Give it back if the purchase could not be delivered.

When a player buys an entry, the checks run in this order:

  1. Permission — Does the player have the entry’s permission (if set)?
  2. Purchase limit — Would this purchase exceed maxPurchases for today?
  3. Balance — Can the player pay?
  4. Space — Does the item fit into the inventory? If not, nothing is charged.
  5. Payment — The price is taken.
  6. Delivery — The item is added all at once. If that fails, the full price is refunded and the purchase is not counted.

For command entries, step 4 is replaced by a check that the command exists and may run; a command that fails while running is refunded.

Purchase counts reset daily. A player who bought 3 of 3 allowed pickaxes today can buy again tomorrow.

Rewards that pay a named currency (for example “gems”) are paid in exactly that currency or reported as failed — they are no longer paid silently in the main currency. Common names such as “gold”, “money” or “coins” still pay the server economy.

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",
"quantity": 3,
"cost": 5,
"description": "3x Greater Health Potions",
"category": "potions"
},
{
"itemId": "Weapon_Sword_Adamantite",
"quantity": 1,
"cost": 50,
"description": "The finest blade",
"category": "weapons",
"maxPurchases": 1
}
]
}