Authoring Shops & Currencies

The economy is shared library content, so a wallet, a storefront or an offer authored for this mod works for any mod reading the same library, and one screen serves them all. Five asset types cooperate here, all with the file name as the id and all supporting "Parent": "<id>" reuse - and two more, boards and the contracts on them, are documented with quests instead, because a contract IS a quest: see Boards and contracts.

MyEconomyPack/
├── manifest.json
└── Server/ZiggfreedCommon/
    ├── Currencies/MyStudio/Bounty_Token.json
    ├── Shops/MyStudio/General.json          # a storefront
    ├── ShopPools/MyStudio/Featured.json     # a rotating shelf
    ├── ShopEntries/MyStudio/Boost_Mining.json
    └── ShopEntryGenerators/MyStudio/Xp_Packets.json

The shipped MMO Skill Bounty Pack is the real-world reference for this shape, laid out the same way under its own namespace. Zip your pack folder with the manifest at the root and drop the .zip in your mods directory - see Building the zip.

The owner's last word lives in mods/ziggfreedcommon/currencies.json, shops.json and shop-pools.json. Each one overrides by id, one leaf at a time ({ "general": { "Enabled": false } } closes a storefront), and an unknown id is simply a new entry. See ZiggfreedCommon.

The storefront

Server/ZiggfreedCommon/Shops/<ns>/<Id>.json. The storefront is the page: what it is called, which wallets show in its header, which shelves it has and in what order.

{
  "Text": { "TitleKey": "shop.general.title", "FlavorKey": "shop.general.desc" },
  "Icon": "Ore_Iron",
  "Order": 0,
  "Currencies": ["Bounty_Token", "Life_Essence"],
  "CategoryOrder": ["items", "boosts", "conversion", "featured"]
}

The rotating shelf

Server/ZiggfreedCommon/ShopPools/<ns>/<Id>.json. A shelf that re-draws its offers on a cadence, instead of listing everything it holds. Its rotation vocabulary is the same one a board uses, so a shelf and a board can never drift apart about what a cadence means.

{
  "Text": { "TitleKey": "shop.xpexchange.featured" },
  "Shop": "XpExchange",
  "Order": 0,
  "Rotation": { "Period": "Daily" },
  "Selection": { "Type": "Weighted_Random" },
  "Slots": [ { "Tier": "lesser" }, { "Tier": "greater" }, { "Tier": "master" } ],
  "Reroll": { "Cost": { "Currencies": { "Bounty_Token": 30 } }, "MaxPerPeriod": 2 }
}

The offer

Server/ZiggfreedCommon/ShopEntries/<ns>/<Id>.json. One purchasable thing: what it costs, what it pays out, where it sits, and who may buy it.

{
  "Text": { "TitleKey": "shop.boost_mining.title", "FlavorKey": "shop.boost_mining.desc" },
  "Icon": "Tool_Pickaxe_Crude",
  "Shop": "General",
  "Listing": { "Category": "boosts", "SortOrder": 20 },
  "Cost": { "Currencies": { "Bounty_Token": 150 } },
  "Limits": { "Daily": 3 },
  "Requires": {
    "Factors": [ { "Factor": "hytale:stat", "Param": "MMO_Level_MINING", "Min": 1 } ]
  },
  "Rewards": [
    { "Kind": "Mmo_Boost_Token",
      "Params": { "Skill": "MINING", "Multiplier": "3.0", "DurationMinutes": "20" } }
  ]
}

Offer generators: one file writes a family

Server/ZiggfreedCommon/ShopEntryGenerators/<ns>/<Id>.json writes a whole family of offers from one table. It loads after the offers themselves, and it merges nothing: it writes ordinary child bodies carrying Parent and lets the same decode do the rest.

{
  "Base": "Xp_Packet",
  "IdPattern": "shop_xp_{tier}_{skill}",
  "ForEach": [
    { "Token": "skill", "Source": "mmoskilltree:skills" },
    { "Token": "tier", "Values": [
        { "tier": "lesser",  "tokens": 75,  "essence": 30, "xp": "1500",  "minLevel": 1,  "order": 40, "daily": 3 },
        { "tier": "greater", "tokens": 165, "essence": 65, "xp": "7500",  "minLevel": 30, "order": 42, "daily": 3 }
    ] }
  ],
  "Child": {
    "Text": { "TitleKey": "shop.xp_packet.{tier}.title", "TextArgs": { "Title": ["{skill}"] } },
    "Listing": { "Category": "conversion", "SortOrder": "{order}",
                 "Chains": [ { "Id": "{skill}", "Tier": 1 } ] },
    "Cost": { "Currencies": { "bounty_token": "{tokens}", "life_essence": "{essence}" } },
    "Limits": { "Daily": "{daily}" },
    "Pool": { "Id": "XpExchange", "Tier": "{tier}" },
    "Requires": { "Factors": [
        { "Factor": "hytale:stat", "Param": "MMO_Level_{skill}", "Min": "{minLevel}" } ] },
    "Rewards": [ { "Kind": "Mmo_Xp", "Params": { "Skill": "{skill}", "Amount": "{xp}" } } ]
  }
}

• Substituting a KEY is load-bearing, not a nicety: it is how a per-skill requirement names its own stat channel (MMO_Level_{skill}) with no escape hatch on the schema.
• A row value keeps its own TYPE, so write it the way the field it fills wants it: an XP amount is quoted because a reward's parameters are text, while a price is not because a price is a number. Get it the wrong way round and the whole family fails to decode and is reported.
• A token nothing binds is an error and that one offer is skipped, rather than shipping something wrong.

Shelf words and band words

A shelf says something too, and the STOREFRONT names it: Categories is keyed by the category's own word and merges per category under Parent. It is deliberately separate from CategoryOrder - one decides what a shelf says, the other where it sits - and it lives on the storefront rather than on each offer, because a dozen offers in one category would otherwise be a dozen chances to name that shelf differently.

The word a screen shows is resolved in this order: the storefront's own Categories entry, then the key shop.category.<id> from a mod that ships it, then the library's own default, then the raw category word. The library ships a word for the common shelves (items, boosts, conversion, featured) in 9 languages, so a storefront using those needs nothing. Boards work the same way with Grades and board.grade.<id>.

The wallet

Server/ZiggfreedCommon/Currencies/<ns>/<Id>.json. The one real choice is what backs it, and nothing else changes with that choice.

{
  "Icon": "Ingredient_Bar_Gold",
  "Color": "#ffcc44",
  "Cap": 0,
  "Meta": { "mmoskilltree": { "ShowOnSidebar": true,
                              "ShowOnMasteryPage": false,
                              "XpConversionPercent": 0 } }
}

{ "Backing": { "Item": "Ingredient_Life_Essence" }, "Color": "#a7e0a7" }

A pack shipping a wallet ships two lang keys, not one: currency.<id>.name for the name itself, and the counted key a reward chip reads ("+{0} Bounty Tokens"), composed from that same translated name. A wallet with only the name key still renders on a reward chip, just as the raw key until the counted one is shipped too.

Checking your work

/zigcommerce validate runs the whole economy audit - wallets, storefronts, shelves, offers, boards, contracts - and /mmoshop validate and /mmobounty validate are the aliases over it. It reports a price in a wallet nobody defines, an offer on a storefront nobody ships, a shelf that can never be drawn, a slot word no offer fills, a gate naming a factor nothing answers, and a reward naming a kind nothing pays out. Unknown means warning (some mod may supply it later); impossible means an error.

The catalogue itself ships in the standalone MMO Skill Bounty Pack, so both the shop and the boards are dormant on a server with no economy content installed. For the player-facing side, see Token Shop, Currencies and Bounty Board.