Token Shop & XP Exchange | MMO Skill Tree Docs

Overview

The Token Shop is where Bounty Tokens get spent. Earn tokens from Bounty Board contracts, then trade them at a placed Token Trader for XP boosts, item caches, and currency conversions. A second storefront, the XP Exchange, turns those same bounty earnings into per-skill XP packets. Both are sinks designed to give tokens somewhere to go without becoming a shortcut around leveling.

The engine ships inside the plugin jar, but the catalog ships in a content pack - the free MMO Skill Bounty Pack. Without a pack the shop has no offers and stays dormant, exactly like the Bounty Board it is paired with.

The Storefront

The Token Trader presents a category-grouped catalog. Each offer pays out through the unified reward model, so a shop reward is exactly a quest reward. Three kinds of offer ship in the pack:

XP boosts - timed XP-multiplier boost tokens (personal or global).
Item caches - a /give reward that drops items into your inventory.
Currency conversions - trade Bounty Tokens for another currency.

Every price renders as coin chips beside the Buy button, and unaffordable costs are colored so you can read your standing at a glance. Offers can be combat-level gated or capped per day; a locked offer shows its lock reason inline instead of just greying out. Purchases are a guarded transaction - if a reward fails to deliver mid-purchase it is queued and arrives on your next login, and if nothing could be delivered at all your payment is refunded automatically, so a purchase can never quietly eat your tokens.

Featured Shelf

Above the always-available catalog sits a rotating Featured shelf. Everyone sees the same Featured offers each rotation, and you can pay a small token cost to reroll the shelf for a fresh selection. The reroll is capped per day so it stays a deliberate choice rather than a spin-to-win.

The rotation runs on the same engine that drives the Bounty Board pools, so a pack can define its own Featured pool with its own rotation cadence, selection weights, and reroll cost.

XP Exchange

The XP Exchange is the second storefront, focused on skill XP. Every skill on your server gets its own XP packets, and a few are featured each day under Today's XP Deals (rerollable, like the Featured shelf). An all-skills bundle is always available for when you want broad progress.

Each exchange costs Bounty Tokens and Life Essence together, and every packet is capped per day. The dual cost plus the daily cap make it a steady sink rather than a way to buy your way to a max level. Life Essence comes from the same place it always has - see Currencies.

The Exchange grants real skill XP through the normal leveling path, so XP boosts you have active still apply and milestone rewards still trigger on the levels it pushes you through.

Opening the Shop

Launch is gated, the same way the Bounty Board is. Players reach the shop two ways:

The Token Trader block. The pack ships an MMO_Token_Trader placeable poster; pressing use on it opens the Token Shop inline.
The Adventurer's Guide. The hub NPC at world spawn has a shop tile that routes straight into the storefront when a catalog is loaded.

Admins (or the console) can open the shop for any player with /mmoshopui <player>, mirroring /mmobountyui. The shop is a two-panel master-detail page: a category-grouped catalog on the left and a detail panel with cost, requirement and limit lines, reward icons, and a Buy button (or a localized lock reason) on the right, with your live Bounty Token balance in the header.

The two-panel Token Shop page: the category-grouped catalog on the left, and the detail panel with cost/reward/Buy on the right.

Configuration

The shop is controlled by mods/mmoskilltree/token-shop.json. The file is override-based - it holds the catalog reference and a global on/off switch, and only the fields you change are written. The offers themselves are content-pack assets under Server/MMOSkillTree/ShopEntries/*.json, each carrying its cost, reward, category, optional combat-level or per-day gate, and localization keys.

A shop is not limited to a single storefront. A pack can define additional named Shop boards under Server/MMOSkillTree/Shops/*.json (the shipped pack ships a default general shop plus the XpExchange shop) - an entry or pool opts into one via its shop field, the same way a Bounty Board can be placed as several distinct boards. Each named shop gets its own catalog and its own requirements gate.

You can toggle the whole shop from the admin dashboard's Token Shop switch (it is also exposed as a shop feature flag), so a server can run bounties without the storefront, or vice versa. Per-player purchase counts are tracked on each player's save, and per-day caps reset on a UTC day change.

Shop entry fields

Field	Purpose
`cost`	A cost object in the shared schema (`{ "currencies": {...}, "items": [...] }`). The XP Exchange packets pair `bounty_token` with `life_essence`.
`rewards`	One or more unified rewards (XP, boost token, a `/give` item cache, or a currency conversion).
`category`	Groups the offer in the catalog (the left-panel tabs).
`requirements`	The shared gate block - `minCombatLevel`, a per-skill map, and required features. Locked offers explain why inline.
`limitPerDay` / `limitTotal`	Per-day and lifetime purchase caps for that offer, per player.
`titleKey` / `descriptionKey`	Localization keys so the offer text translates through the same language files as the menus.

Validation

Admins can audit the catalog with /mmoshop validate. The shop validator cross-checks every entry against your currency config and reports issues such as a missing or disabled cost currency, a non-positive cost, a missing reward currency, or an unknown category. The same audit runs once on the first player ready and its issue count surfaces in the admin dashboard, so a broken offer is caught before a player ever sees it. The console also offers /mmoshop list to dump the loaded catalog and /mmoshop reset for diagnostics.

Because the shop and its offers are localized, every offer name, description, currency name, and reward line resolves through your server's language files - see Localization for how content packs ship their text.