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.
Currency Types
Section titled “Currency Types”Quest Tokens
Section titled “Quest Tokens”| Property | Value |
|---|---|
| Currency ID | quest_tokens |
| Provided by | Quest mod |
| Earned through | Completing 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.
{ "type": "quest_tokens", "amount": 5}Achievement Points
Section titled “Achievement Points”| Property | Value |
|---|---|
| Currency ID | achievement_points |
| Provided by | Achievement mod |
| Earned through | Unlocking achievements |
Achievement points are earned as players complete achievements. They work well for shops that reward long-term play.
{ "id": "rare_collector", "currencyId": "achievement_points", "items": [ ... ]}Season Tokens
Section titled “Season Tokens”| Property | Value |
|---|---|
| Currency ID | season_tokens |
| Provided by | Season Pass mod |
When the Season Pass mod is installed, its season tokens can also be used as an NPC shop currency.
Server Economy
Section titled “Server Economy”| Property | Value |
|---|---|
| Currency ID | economy |
| Provided by | An 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.
Item-Based Currencies
Section titled “Item-Based Currencies”| Property | Value |
|---|---|
| Currency ID | item:<ItemId> |
| Provided by | Core (automatic) |
| Earned through | Gathering, 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.
{ "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 |
How Currencies Work in Shops
Section titled “How Currencies Work in Shops”When a player opens a shop, Core looks up the currency for the shop’s currencyId. The currency handles three things:
- Balance — How many tokens, points, coins or items does the player have?
- Spend — Take the price when a purchase is made.
- Refund — Give it back if the purchase could not be delivered.
Purchase Flow
Section titled “Purchase Flow”When a player buys an entry, the checks run in this order:
- Permission — Does the player have the entry’s permission (if set)?
- Purchase limit — Would this purchase exceed
maxPurchasesfor today? - Balance — Can the player pay?
- Space — Does the item fit into the inventory? If not, nothing is charged.
- Payment — The price is taken.
- 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.
Named currencies in rewards
Section titled “Named currencies in rewards”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.
Setting Up a Shop with Currencies
Section titled “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", "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 } ]}