Token Shop & XP Exchange

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 storefront engine belongs to the shared ZiggfreedCommon library that ships beside this mod: it owns the catalogue, the prices, the rotating shelves and the purchase limits, and this mod contributes the theme, the reward kinds and the menu route into it. 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.

Where shops live

In every one of those folders the file name is the id and the folder under it is plain organization, so two files of the same name in different folders are one id and the server says so. Precedence runs bottom to top: what the library ships, then a pack, then your own file under mods/ziggfreedcommon/.

{
  "general":    { "CategoryOrder": ["featured", "boosts", "items", "conversion"] },
  "xpexchange": { "Enabled": false }
}

An override is read leaf by leaf against whatever the pack already said about that id, so writing one line keeps everything else. A storefront id no pack defines is a storefront of your own rather than an error, and case is ignored wherever an id is written.

The Storefront

The Token Trader presents a shelf-grouped catalog. Each offer pays out through the shared reward vocabulary, 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 bundle of items dropped straight into your bag.
• Currency conversions - trade Bounty Tokens for another wallet.

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

The header carries a balance strip: the storefront lists which wallets it prices in, and each one shows as an icon and an amount, so a player can see what they can afford before they browse.

What a shelf is called

An offer names its shelf with a plain word (boosts, items, conversion, featured). What that shelf reads as is decided once, on the storefront, in its Categories text - never on each offer, or a dozen offers in one category would be a dozen chances to name it differently. The heading falls back through the convention key shop.category.<id> to the library's own word for the common shelves, and finally to the word itself, so an unnamed shelf still reads as something readable rather than a raw key. CategoryOrder fixes the sequence the shelves appear in; a category left off it follows the named ones alphabetically.

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 period so it stays a deliberate choice rather than a spin-to-win.

A shelf runs on the same rotation the Bounty Board's postings do, so a pack can define its own Featured shelf with its own cadence, draw weights and reroll cost, and the two can never disagree about what "daily" means. What a shelf shows is worked out from its id and the clock alone, so every player sees the same thing and a restart shows what was there before.

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 whole packet family is written as one generator file rather than one file per skill per size, so a skill added later gets its packets with no edit anywhere.

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

There is no player command for the shop. Players reach it 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 shelf-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 balances in the header.

Authoring an offer

One offer is one file under Server/ZiggfreedCommon/ShopEntries/: its text and icon, which storefront and shelf it lists on, its price, per-player purchase limits, its requirement gate, and what the purchase pays out. The field-by-field reference lives once, on Authoring Shops & Currencies: the offer. An offer's id is what a player's purchase count is filed under, so renaming one starts that count over.

Admin and validation

The shared economy's own admin family is the full surface, and this mod's /mmoshop is an alias over the same audit and the same catalogue.

The audit reports a missing or disabled cost wallet, a non-positive price, an unknown reward, an unfillable shelf slot, an unknown rotation or draw type, and a malformed icon id. It also runs once by itself when the first player joins, so a broken offer is caught before anyone sees it. Findings go to the server log.

Because the shop and its offers are localized, every offer name, description, wallet name, and reward line resolves through your server's language files - see Localization for how content packs ship their text, and Authoring Shops & Currencies for the full field reference.