Log inGet started
World

Market Square: Currencies, Wallets and Shops Kit

README.md

economyKit

economyKit 1.2.12 gives any multiplayer Zero game money, cheat-proof wallets and shops: currencies, prices, income and fees are data, and one authoritative machine decides every buy, sell, grant, spend and trade.

What you get: seven shop screens (grid store, vendor list, vending machine, between-wave quick buy, upgrade tree, two-player trade window, one-item showcase), three shopkeepers to put in your world (a merchant behind his counter, a vending kiosk, a hooded spirit of light), twelve currency styles, five wallet displays (including a resource bar for strategy games), a ready-made General Store any shopkeeper opens when you name no shop, income, fees and upkeep, player-to-player trading, menusKit's eight looks, keyboard, gamepad and touch controls, phone layouts, English and Brazilian Portuguese, two guides, and 41 automated tests.

Install: search ZeroMind for economyKit and install it into your world (from code or the shell, zeromind.installAsset with the package id d113a24e-3a87-40d2-a725-af49b56f629b). One install brings inventoryKit, saveKit, menusKit and navUiKit with it. Then try the shopkeeper below.

Guides: two guides ship inside this package and install with it. Open them from the Docs panel, or ask your agent for them by name:

A shopkeeper selling three items

Install economyKit into a new world (one install brings inventoryKit, saveKit, menusKit and navUiKit with it), replace the contents of scenes/main.scene/entrypoint.luau with this, and press Play:

local Economy = require("economyKit.economy")

function onLoad()
    Economy.setup({ wallet = "corner" })
    Economy.defineShop({
        id = "smithy", title = "The Smithy", screen = "vendor",
        items = {
            { item = "sword", price = 40 },
            { item = "shield", price = 60 },
            { item = "healthPotion", price = 12 },
        },
    })
    Economy.spawnShopkeeper({ kind = "counter", shop = "smithy", position = { 0, 0, 6 } })
end

A merchant stands behind his counter 6 m in front of you, and your coins sit in the top-left corner (every new wallet starts with 100). Walk up to him and press E (gamepad X, or tap the Shop button on a touch screen). Buy the sword and the shield: the bank takes 100 coins, both land in your inventoryKit bag (Tab), and the health potion now shows dimmed with "Need 12 more"; pressing Buy on it is refused with "Not enough Coins: you need 12 more". Escape (gamepad B, or the ✕ button) closes the shop and you walk again. Stop and press Play again: your coins and items are still there.

Styles, and how to switch them

Every style of a family draws the same data and raises the same events, so a world switches with one setting and nothing else. Every style also carries tags (style, genre, setting, plus input for screens and size for wallets) so a game can pick by them; see the end of this section.

FamilyStylesSwitch with
Shop screensgrid (store of cards with a detail pane), vendor (shopkeeper portrait, greeting and priced list), vending (vending machine with slot codes, LCD and DISPENSE), quickBuy (strip of big buttons between waves, with the wave timer), upgradeTree (tiers that unlock the next), trade (two players' offers side by side), showcase (one item at a time on a lit stage, browsed left and right, every item as a thumbnail below)a shop's screen field; Economy.setScreen("vending") forces every shop into one style; Economy.open(shop, { screen = "grid" }) for one opening
Currency iconscoins, gems, tokens, scrap, souls, energy (energy cells), tickets, banknotes, stars, wood, stone, food: each its own painted icon, frame shape and glow. On the ground the first eight are 3D models; stars, wood, stone and food stand as a spinning token, a rim in the currency's colour around its painted icon. Sample currencies with the same ids come with the kit (Economy.setup({ currencies = { "wood", "stone", "food" } }))a currency's icon field
Wallet displayscorner (rolling counters, top left), panel (full wallet with names, top right, or bottom right with panelBottom), popup ("+10" / "−25" rising where the eye is), minimal (one line of text, bottom left; on a phone held upright that cannot fit the names it shows each currency's icon and number, shortening amounts of 10,000 and more to "12k" or "1.2M" only if they still would not fit, so a full wallet stays on one line), bar (a resource bar across the top centre, one segment per currency, the way strategy and city-building games show wood, stone and food)Economy.setup({ wallet = "panel" }) or Economy.setWallet({ "corner", "popup" }) (several at once is fine)
Shopkeeperscounter (a merchant behind a wooden counter, warm lamp), machine (a vending kiosk with a lit screen), holo (a hooded spirit of light floating over a rune plinth)Economy.spawnShopkeeper({ kind = "holo", shop = ... }), or the Shopkeeper component's kind field in a scene. A placed keeper's screen field picks the screen it opens; changing it (or kind, shop, radius) while playing takes effect at once
LooksmenusKit's eight: scifi, fantasy, cartoon, pixel, minimal, military, horror, cozya shop's look field, or Economy.setLook("pixel") for every shop without one. Every screen keeps its text readable in every look: secondary text, prices and warnings are held to at least 3.6:1 contrast with the panel they sit on, and the screens that paint their own dark body (vending machine, quick buy, upgrade tree) switch a parchment or paper look to light ink there

Economy.catalogue() returns all of these as data, plus every currency, shop, price list, income, sink and event the game knows. Its screens, icons, wallets and keepers are lists of { id, name, label, tags } (name in the player's language), for example:

{ id = "energy", name = "Energy cells", label = "economy.icon_energy",
  tags = { style = { "neon", "tech", "battery cell" }, genre = { "shooter", "strategy", "tower defense" }, setting = { "sci-fi", "cyberpunk" } } }

Economy.styles(family, query) picks from one family ("screen", "icon", "wallet" or "keeper") by tag: Economy.styles("icon", { setting = "sci-fi" }) gives energy cells and scrap, Economy.styles("keeper", { genre = "rpg" }) the counter merchant, and a bare word matches any tag (Economy.styles("screen", "gamepad")).

Things a player cannot afford always look it: dimmed, with the price in red and how much is missing ("Need 12 more"), or "Sold out" / "Needs Boots" for stock limits and upgrade prerequisites. Something the player already bought and cannot buy again shows a gold "Owned" instead of a price, and a small bag badge on a card says how many of an item the player already carries. The bank refuses anything it should anyway if a request arrives.

Every wallet display shows money moving: when coins come in the counter flashes green with "+25" beside it for about a second, and red with "−20" when they are spent; quick changes the same way add up into one number. A purchase also shows a short line in the shop with a check (bought) or a cross (refused, with the reason).

Add a currency

Add one data asset anywhere in your world, bound to economyKit.currency; the kit finds it by itself. myGame/currencies/stars.data/values.yaml:

contract: economyKit.currency
values:
  id: stars
  name: "Stars"
  nameKey: "economy.currency_stars"   # optional: a key in your own locales/<lang>/economy.json
  icon: tokens                        # one of the eight icon styles
  color: "#ffd84a"
  start: 0                            # what a new wallet holds
  max: 99999                          # the most one wallet can hold
  persist: true                       # false: starts over every session (match cash)
  order: 10                           # position in wallet displays

Or from code: Economy.defineCurrency({ id = "stars", icon = "tokens", start = 0 }). Your own currencies are always on; of the kit's eight samples only coins is on unless you pass Economy.setup({ currencies = { "coins", "gems" } }).

Add a price list and a shop

A shop points at a price list, so shops can share prices and a game changes a price in one place. myGame/prices/armory.data/values.yaml:

contract: economyKit.priceList
values:
  id: armory
  currency: coins            # prices are in this unless an entry says otherwise
  sellRate: 0.5              # what the shop pays back, as a share of the price
  entries:
    - { item: sword, price: 40 }
    - { item: arrows, price: 8, qty: 10 }            # one purchase gives 10
    - { item: amulet, price: 6, currency: gems }      # priced in another currency
    - { item: ironKey, price: 80, stock: 1 }          # one per player
    - { item: helmet, price: 90, requires: sword }    # upgrade trees: buy the sword first
    - { item: bread, price: 4, sell: 0 }              # the shop will not buy it back

myGame/shops/armory.data/values.yaml:

contract: economyKit.shop
values:
  id: armory
  title: "The Armory"
  titleKey: ""             # or a translation key
  priceList: armory
  screen: grid             # grid, vendor, vending, quickBuy, upgradeTree, trade
  keeper: counter          # counter, machine, holo
  look: fantasy            # any menusKit look, or "" for the game's
  buy: true
  sell: true
  fees: [marketFee]        # economyKit.sink ids charged on purchases and sales here

Items are inventoryKit items (Inventory.catalogue().items lists them; a game adds its own with inventoryKit's inventoryKit.inventoryItem contract). Put the shop in the world with Economy.spawnShopkeeper({ kind = "counter", shop = "armory", position = { x, y, z }, yaw = 0 }) in onLoad, or add the Shopkeeper component to an entity in your scene. A keeper faces its own −Z (yaw 0 faces a player standing towards −Z). Economy.open("armory") opens a shop from anywhere (a menu, a key, a trigger).

Income and sinks

contract: economyKit.income
values: { id: salary, currency: coins, amount: 5, every: 10, onWave: false, waveGrowth: 0, cap: 1000 }

every pays every connected player each N seconds; onWave: true pays when the host's game code calls Economy.wave(n) (amount + waveGrowth × (wave − 1)); cap stops paying a player who already holds that much.

contract: economyKit.sink
values: { id: marketFee, kind: fee, currency: coins, amount: 0, percent: 10, appliesTo: [buy] }

kind: fee is added to purchases, sales or trades of the shops that list it (appliesTo: buy, sell, trade; trades use Economy.setup{ tradeFees = { ... } }). kind: upkeep takes amount from every player every every seconds, never below floor. kind: charge is a one-off a game takes with Economy.charge("revive"). The kit ships allowance, waveBounty, soulTrickle (incomes) and marketFee, tradeFee, rent, revive (sinks); switch samples on with Economy.setup({ income = { "allowance" }, sinks = { "rent" } }).

Events

Economy.on("balanceChanged", function(e) print(e.currency, e.value, e.delta, e.why.kind) end)
Economy.on("purchaseMade", function(e) print("bought", e.item, e.count) end)
Economy.on("purchaseRefused", function(e) print(e.text) end)   -- "Not enough Coins: you need 40 more"
Economy.on("saleMade", function(e) end)
Economy.on("tradeCompleted", function(trade) end)

All events: balanceChanged, purchaseMade, purchaseRefused, saleMade, saleRefused, tradeCompleted, tradeUpdated, tradeRefused, tradeCancelled, spendRefused, refused (any refusal), shopOpened, shopClosed, bankChanged, ready, and wave on the host. Each refusal carries code, values and text (in the player's language). On the machine running the bank, "bank.<event>" hears every player's events (bank.purchaseMade, bank.tamper, ...), for server-side game logic.

Trading between two players

A shop with screen = "trade" (the sample tradingPost) opens the trade window: pick a player in the room, they get the invitation as a window of their own (and a navUiKit toast when the game runs a navUiKit HUD), both put items from their bags and money in, and both press Accept. Any change resets both accepts. The bank then checks both sides can still cover their offers, takes the items out of both bags, sees them gone, moves the money and hands the items over. If anything fails along the way (an item moved, a player left, a balance changed) everything is given back and nothing moves. From code: Economy.tradeWith(peerId), tradeOffer({ items = {...}, money = {...} }), tradeReady(), tradeCancel(). Economy.tradeWith("npc:tobi") practises with a trader who answers on his own (define your own in setup{ npcTraders = ... }).

How it stays cheat-proof

  • One bank. Exactly one machine in a room runs the bank: the lowest peer id (the host when the room was made; the next machine takes over if it leaves). A game can name a different machine with setBankChooser (rtsKit names its match host). If the bank's host component ever fails to start, it is replaced within two seconds, so the bank always comes up once its code can run. Every other machine only sends requests on the economyKit channel. The relay names the sender, and the bank maps that machine to its account through the scene's players registry (the avatar the relay says it owns), so nobody can act for someone else.
  • Requests, not balances. A machine asks to buy, sell, spend or trade; the bank checks the price list, stock, prerequisites, room in the bag and its own copy of the wallet, then applies the change whole or refuses with a reason. Retried requests are answered again, never charged twice.
  • Selling and trading take items first. The bank asks the player's machine to hand items over and pays only once it sees them gone from that player's synced inventory.
  • Grants. Economy.grant(player, currency, n) called on the bank's machine (host game code: kill rewards, quests) applies at once. From a player's machine it is refused unless the game allowed that reason: setup{ clientGrants = { quest = { max = 50, perMinute = 100 } } }.
  • Kept between sessions. Wallets live in the world's runtime data under economyKit/<ns>.<world>/w/<account> (the namespace plus this world's id, so a wallet never follows a player into another world), written only by the bank. A change to those paths the bank did not make (a player writing the shared store by hand) is put back at once and raised as bank.tamper. Each player's machine also copies its confirmed wallet into its saveKit profile (Save.get("economyKit")), so it travels with the player's save; the bank never trusts that copy. Coins on the ground (Economy.spawnCoin) pay only a player whose avatar the bank sees standing there.

Checked here: a balance written straight into the shared store (99,999 coins) was put back within a frame and the following purchase was still refused for lack of gems; a balance written into the player's own saveKit profile changed nothing; balances, purchases and stock came back after leaving and re-entering play.

Shared accounts: team wallets

A wallet can belong to a team instead of a player: name it "acct:<name>" ("acct:team1", "acct:ai") wherever a target goes. The bank keeps it like any wallet (in the same store, with each currency's start, max and persist), but no player plays as it: it is never sent to a machine as "your wallet", never copied into a saveKit profile, and income and upkeep pass it by. Only game code on the bank's machine changes it, so a strategy game's barracks, a computer opponent or a shared guild bank all run through the same cheat-proof rules.

Economy.defineCurrency({ id = "gold", name = "Gold", icon = "coins", start = 200, persist = false })
Economy.defineCurrency({ id = "wood", name = "Wood", icon = "scrap", start = 100, persist = false })

-- on the bank's machine (host game code)
if Economy.isBank() then
	Economy.grant("acct:team2", "gold", 25, "mine")                     -- a worker drops off ore
	local res = Economy.debit("acct:team2", { gold = 60, wood = 20 }, "trainSoldier")
	if not res.ok then print(res.text, res.missing.wood) end              -- "Not enough Wood: you need 20 more", 20
	Economy.credit("acct:team2", { gold = 60, wood = 20 }, "cancelled")  -- a refund, all at once
end

-- on any machine: show a team's balance
local stop = Economy.watchAccount("acct:team1", function(info) print(info.balances.gold, info.deltas.gold) end)
local gold = Economy.balanceOf("acct:team1", "gold")
  • balanceOf(target, cur?) answers a number for one currency, or { [currency] = n }. On the bank's machine it reads any account (a peer id, a user id, an avatar, "u:<id>", "acct:<name>", nil for the local player). On a player's machine it reads shared accounts from the store the bank writes (every machine has it) and the player's own wallet; anything else is nil, "notBank".
  • debit(target, costs, reason?) takes every currency in costs or nothing. It answers { ok = true, costs, balances, rec } or { ok = false, code, values, text, missing }: code = "short" when something is short (the text names the biggest shortfall, in the player's language) and missing = { [currency] = n } lists every currency that fell short; badAmount, unknownCurrency, noAccount, or notBank when called off the bank's machine.
  • credit(target, costs, reason?) gives every currency at once, refused whole (cap) when any would pass its max. Same answer.
  • watchAccount(target, fn?) calls fn({ key, balances, deltas, rev }) on every change of that account, and fires the accountChanged event; it returns a function that stops watching. Reading is all a player's machine can do: a balance written into the store by hand is put back by the bank as for any wallet.
  • Shared balances are as readable as every wallet in the shared store: any machine can read any team's account. A game that hides an opponent's gold hides it on screen.
  • persist = false currencies of shared accounts start over when a new session's bank starts, and are kept when the bank moves to another machine mid-session (the host left).

Controls, phones and the web

Keyboard: E opens the shop in front of you, arrows/WASD move, Enter/Space buys, F or Q/R switch Buy/Sell (and accept a trade), 1-6 pick in the quick-buy strip, Escape closes. In the upgrade tree the arrows move between the nodes as drawn: Up and Down within a tier, Left and Right between tiers side by side, and through every node in order when the tiers stack on a phone. Gamepad: X opens, d-pad moves, A buys, Y/bumpers switch tabs, B closes. Touch and mouse: tap the Shop button, tap cards and buttons, ✕ closes. A finger's tap on any of the kit's buttons is also read by the kit itself and pressed once, so it works even when the touch controls are up (#21441); a tap the UI presses as well still counts once. While a shop is open the player's walking and camera are stood down (economyKit.economyBlock); closing hands them back, whichever way it closes (the quick-buy strip leaves you free to move).

Every label in every screen reads whole in every look, in both languages, on a desktop window and on a phone held either way: a wrapping label is never narrower than its longest word, with 5% to spare for text a browser draws a little wider, a name in a fixed-width tile gets a smaller font before it would break, and a one-line label is never squeezed narrower than its text. The wallet displays read whole too: the minimal line is never wider than the screen, whatever minimalWidth a game asks for, and keeps each entry in one piece (on a phone held upright, all eight sample currencies fit on one line as icon and number, whatever the amounts: amounts of 10,000 and more are shortened there, "12k" or "1.2M", only when the full numbers would not fit), the wallet panel is wide enough for its longest currency name beside its longest amount, and on a short screen it takes shorter rows so a full wallet fits its height. On a phone each shop's title has a row of its own beside the close button, with the Buy and Sell tabs and the wallet chips below it, so a long title never shares its room. On a screen held upright every screen and wallet display is laid out for a 430-point phone and scaled to fit (the same way inventoryKit does), clear of the safe area; on a short screen (a phone held sideways) the shop panels, the quick-buy tiles, the vendor's portrait and the grid's detail pane shrink so every button stays on screen, and a quick-buy shop with more items than one row of tiles holds there shows them a page at a time, with arrows either side to turn the page (the page follows the keyboard or gamepad selection). Economy.setInsets({ left = 180 }) keeps the kit clear of your own HUD. All timers use the engine's wall clock, so the kit runs the same in the browser.

Translations

Every word comes from locales/en/economy.json and locales/pt-BR/economy.json in the package (shop titles, greetings, currency and item names, refusals, buttons). A game overrides any word, or adds a language, with its own /locales/<lang>/economy.json. Names you add use nameKey / titleKey / greetingKey, or fall back to the plain name / title.

Starting over (a new game)

Economy.resetWallet starts a wallet over: every currency back to its start, and what the player bought (one-per-player items, upgrades, stock limits) forgotten. The items already in the player's bag stay there; the bag is inventoryKit's.

  • While you build, in the editor: Economy.resetWallet() deletes your own saved wallet, and Economy.resetWallet("all") every saved wallet of this world. The next Play starts them fresh.
  • In the game, from your code on the bank's machine (a "New game" button, a new season): Economy.resetWallet(player). Pass { keepPurchases = true } to keep what they bought.
  • Letting players do it themselves: set Economy.setup({ playerResets = true }); then Economy.resetWallet() on a player's machine asks the bank to start that player's own wallet over. Without it the bank refuses ("notAllowed"), and no player can ever reset someone else's wallet.

Common questions

  • I set start on my currency but my wallet does not start there. start is what a brand-new wallet holds. A wallet that already exists in this world keeps its balance. Wallets are kept per world, so a fresh world starts every player at start.
  • The editor shows no shopkeeper or wallet. Economy.setup and Economy.spawnShopkeeper run in onLoad, which runs when the game starts. Press Play to see them.
  • Coins or events count twice after a few Plays. Listeners added with Economy.on (and with other kits' on, such as pickupsKit's or inventoryKit's) outlive a Play. Each on returns a function that removes its listener: keep them and call them in your scene's onUnload.
  • Economy.grant from my game code is refused. Only the bank's machine pays out freely. Put rewards behind if Economy.isBank() then ... end, or allow a reason from players' machines with setup{ clientGrants = { quest = { max = 50, perMinute = 100 } } }.
  • Coins picked up with pickupsKit do not reach the wallet. pickupsKit counts its own coins. On the bank's machine, listen to Pickups.on("collect", ...) and grant the player it names; the example guide shows the five lines.
  • What a bought item does is up to my game. Bought items land in the player's inventoryKit bag. Read it with Economy.inventory().count("boots") when the bag changes (Economy.inventory().on("change", ...)) and apply the effect; the example guide does this for speed, jump and a coin magnet.
  • E does nothing near a shopkeeper. Stand within the keeper's radius (3.2 m unless set) until the prompt shows. While a shop is open, walking and the camera pause; Escape, B or the close cross hand them back.

Reference

local Economy = require("economyKit.economy")

  • Setup: setup(opts) (currencies, income, sinks, wallet, screen, look, ns, clientGrants, clientWaves, playerResets, tradeFees, npcTraders, save, labels, toasts, insets, and where the wallet displays sit: panelTop or panelBottom (points from the top or bottom of the screen), popupPos ({ left | right, top }), minimalBottom, minimalWidth), configure(opts), config(), setWallet, setScreen, setLook, setInsets, catalogue(), styles(family, query).
  • Data: define(kind, t), defineCurrency, definePriceList, defineShop (with inline items), defineIncome, defineSink, reload(), currencies(), currency(id), shops(), shop(id), priceList(id).
  • Wallet: balance(cur), balances(), wallet(), isReady(), key(), canAfford(costs), quote(shop, item, n).
  • Actions (each returns a request id and takes an optional cb(info)): buy(shop, item, n), sell(shop, item, n), spend(cur, n, reason) or spend({ cur = n }, nil, reason), charge(sinkId), grant(player, cur, n, reason), resetWallet(player?, opts?) (see Starting over), wave(n).
  • Trading: tradeWith(peer | "npc:<id>"), trade(), tradeAnswer(accept), tradeOffer(offer), tradeReady(ready), tradeCancel(), tradePartners().
  • Screens: open(shop, opts) (an empty shop opens the kit's General Store), close(), isOpen(), current().
  • World: spawnShopkeeper(opts) (kind, shop, position, yaw, label, labelWidth, marker, name), spawnCoin(pos, opts).
  • Events: on(event, fn) returns a function that stops listening. Text: text(reason), currencyName, itemName, shopTitle.
  • Bank: isBank(), bankPeer(), setBankChooser(fn) (fn() returns the peer id that should run the bank, or nil for the lowest peer; set the same chooser on every machine. An RTS names the machine that simulates its match, so deposits and training costs are paid on that machine at once).
  • Shared accounts (a team's, a guild's, a computer opponent's wallet; see below): balanceOf(target, cur?), debit(target, costs, reason?), credit(target, costs, reason?), watchAccount(target, fn?); grant takes "acct:<name>" too.
  • Kits it brings: inventory() returns the inventoryKit module economyKit runs on (inventoryKit.inventory), so your code and other kits change the same bag economyKit fills without installing inventoryKit themselves.

Components: Shopkeeper (kind, shop, screen, label, labelWidth, marker, radius), CoinPickup (placed by spawnCoin), EconomyHost (started by the kit itself; never place it).

Tests

economyKitTests (41 tests) runs the sample data through the contracts, the ledger and the bank against fake players and a fake shared store: buying with fees, refusals with shortfalls, stock and prerequisites, retries, selling, tamper repair, grants, income, waves, upkeep and charges; trades that complete, that fail for money, that are refused for a full bag, and that are cancelled before both accept or fail halfway through the hand-over (nothing moves, and only goods that really left a bag go back); and saving the economy and loading it into a new bank, with wallets, purchases and stock coming back the same; shared team accounts (taking several currencies all or nothing, giving them back, reading them off the bank's machine); and the bank itself, which runs on the lowest peer unless the game names another machine, and comes up again when its host never ticked, and stops when its host goes away; starting a wallet over, and refusing it to a player unless the game allows it. On the screen side: every shop screen and wallet display at desktop and phone sizes, every screen readable in all eight looks (at least 3:1 contrast for every text), no label able to break inside a word or be squeezed narrower than its text on any screen, look, size or language, the minimal wallet line fitting an upright phone with all eight currencies at any amounts, shop titles staying whole on an upright phone, the upgrade tree's arrows moving between its nodes as drawn, a long quick-buy strip paging on a short screen, the close button drawn as a cross in every look, "Owned" in place of a red "Sold out" on every buy screen, the green and red "+25" / "−20" on every wallet display, the General Store a shopkeeper with no shop runs, every style carrying tags, both languages, and this README's first example's calls. tools.use("tests", "run", { suite = "economyKitTests" }).

Known limits

  • The bank runs on a player's machine (the lowest peer), not on a dedicated server: Zero rooms have none. Machines that are not the bank cannot change any balance; a player alone in a world is their own bank, so a modified client playing alone can change its own money.
  • Items are as trustworthy as inventoryKit's inventories, which each player's own machine owns: the bank checks that a seller holds what they sell, as their synced inventory shows it.
  • #14448: two engines signed in to one account collide as one player, so a real two-player trade on one account cannot be run. The kit gives a second session of the same account its own wallet (u:<id>#2); the trade rules are covered by the tests with two fake players.
  • #20750: the web build's frame rate drops in busy multiplayer scenes. Market Square (all six stalls and every wallet display at once) in the browser ran at about 14 to 22 fps, and the gallery's own counter read 17 FPS (about 60 ms a frame); this was measured on a machine busy with other work at the time, so treat it as a rough figure.
  • #21420: installing a package with several dependencies takes about a minute; economyKit brings four kits with it.
  • #11895: a screen-sized panel cannot be positioned smaller than the screen, so every kit screen places its elements inside a full-screen root of its own.
  • #7781: a 3D text keeps its previous string until it is respawned, so a shopkeeper's name sign is respawned, not edited, when the player switches language.
  • #21441: with touch active, a tap on a content button above the touch controls can be missed. The kit reads taps on its own buttons itself and presses them once, so the Shop button, Buy and close work under a finger; a game's own buttons next to the kit's are not covered.
  • #19258: after a publish, the store description on ZeroMind can lag one release behind. The README and this package's description are current for the release they ship in.

Changes

  • 1.2.12: carries inventoryKit 1.0.27, saveKit 1.3.13, menusKit 1.3.19 (controlsKit 1.3.2), navUiKit 1.3.9 and pickupsKit 2.3.12, the releases questKit, arpgKit and townsfolkKit ship with, so a world that installs economyKit beside them holds one bag (one inventoryKit) and one release of each shared kit; every file naming them re-derived; current engine library. No economy behaviour changed.

  • 1.2.11: carries inventoryKit 1.0.24 and saveKit 1.3.10, built on pickupsKit 2.3.11 with the current SecondWind, juiceKit, MatchFlow, Lifeline, menusKit and controlsKit, so a world that installs economyKit beside cropsKit holds one release of each (cropsKit 1.0.12 carries the same inventoryKit). inventoryKit 1.0.24 skips an inventory left over from an earlier play session, which had shadowed the live one so that purchases were refunded. The world also moved to the current engine library. Suite: 41 of 41.

  • 1.2.10: carries navUiKit 1.3.7 and menusKit 1.3.13, both built against controlsKit 1.3.1, so a world that installs economyKit (or towerDefenseKit, which brings it) holds one controlsKit instead of several releases side by side. No code change.

  • 1.2.9: Economy.setup({ inventory = false }) does not start inventoryKit. For a game that only keeps balances (a team bank, scores) and never puts items in a bag: inventoryKit's screen host otherwise runs every frame (about 6 ms a frame in a debug engine build with nothing open). Leaving it out keeps every other part of the economy as it was.

  • 1.2.8: brings navUiKit 1.3.5 (a HUD drawn in a box lets taps through its messages too, and its README no longer says only canvases can let taps pass) and MatchFlow 1.4.0 (build breaks between waves, endRound, endless waves, late joiners in co-op). No economyKit code changed.

  • 1.2.7: brings navUiKit 1.3.4, whose messages (toasts such as "Not enough gold" or "Bought") no longer take every tap on the screen while they show, so a phone game's own buttons and taps on the world keep working under them. No change to economyKit's own behaviour.

  • 1.2.6: brings menusKit 1.3.12 (its camera settings no longer cost about 19 ms a frame in a scene with a big crowd) and controlsKit 1.3.1, on the engine's current built-in library (@builtin 0c1a80c). Worlds that install economyKit get one current menusKit instead of the 1.3.4 copy. No change to economyKit's own behaviour. (1.2.5 is the number open pull request #5 asks for.)

  • 1.2.4: 1.2.3 published again on the engine's current built-in library (@builtin 5f65687; a world on an older one is hidden from players), with a clearer package description that says what each part gives a game and how to drop it in. No behaviour changes from 1.2.3. 41 tests.

  • 1.2.3: a fresh install of economyKit loads again. 1.2.0 to 1.2.2 installed saveKit with its main save module empty ("module 'saveKit.save' not found"), so saveKit, inventoryKit and economyKit did not start in a new world; installs of 1.1.9 and earlier were not affected. The cause was Market Square's own copy of saveKit, which after being put back to its shipped 1.3.2 files counted as a new local version of saveKit's save module, so economyKit asked for that version beside the saveKit it installs. saveKit is now installed in Market Square straight from ZeroMind, and economyKit asks for exactly the saveKit 1.3.2 it brings. Everything else is 1.2.0. 41 tests.

  • 1.2.2: did not fix installing (see 1.2.3).

  • 1.2.1: did not fix installing (see 1.2.3). Meant to fix installing 1.2.0. In a fresh world, 1.2.0 installed saveKit with its main save module empty, so saveKit, inventoryKit and economyKit stopped with "module 'saveKit.save' not found". It came from how Market Square's copy of saveKit was put back to its shipped 1.3.2 files for 1.2.0: the files were replaced rather than edited, so they were published as this world's own copy beside the installed saveKit. saveKit is now the installed 1.3.2 again, file for file, and economyKit 1.2.1 is otherwise exactly 1.2.0. 41 tests.

  • 1.2.0: a polish and variety release; every call, screen and style from 1.1.9 works as before, and the default look is still scifi, so an existing game looks the same until it picks something new. Look and feel: something a player already bought shows a gold "Owned" with a check instead of a red "Sold out" on the grid, vendor, vending, quick-buy and upgrade screens, and is no longer dimmed as if unaffordable; a grid card carries a small bag badge with how many the player already holds; a purchase line in the shop has a check or a cross and pops in; every wallet display (corner, panel, the new bar) flashes green with "+25" when money comes in and red with "−20" when it goes, for about a second, adding up quick changes. Defaults: a shopkeeper with no shop (Economy.spawnShopkeeper({ position = ... }), or a Shopkeeper component left empty) now runs the kit's General Store, eight everyday items for 3 to 55 coins in the game's own look, where before it opened nothing. Variety: a seventh shop screen, showcase (one item at a time on a lit stage, browsed left and right, every item as a thumbnail; it lays the item beside its details on a short screen), with a sample shop, the Curio Cabinet; four new currency styles with painted icons and sample currencies, wood, stone and food for strategy and survival games and stars for casual ones, standing on the ground as spinning tokens in the currency's colour (3D models for them could not be generated this release); a fifth wallet display, bar, a resource bar across the top centre. Starting over: Economy.resetWallet(target?, opts?) puts a wallet back to each currency's start and forgets what was bought (keepPurchases keeps it); in the editor it deletes saved wallets ("all" for every one), in a game the bank's machine resets anyone, and players may reset their own only with setup{ playerResets = true }. README section "Starting over (a new game)"; the coin game guide's steps now each say what to do and what you should see, and both guides cover starting over. saveKit in Market Square is back to its shipped 1.3.2 files. 41 tests.

  • 1.1.9: completes 1.1.8, which was published from the contributor's branch before review. 1.1.8's new test never ran a bank (it detached a host that had none and searched the source text), so it could not catch the bug it was for; it now runs a bank, detaches its host and checks the bank stops exactly once and lets go of the saved wallets, while a host that is not the bank's leaving changes nothing. 1.1.8 also made the "host that never ticked" test read the kit's source by module name, which vfs.read does not accept, so that test failed in a world with the kit at its root (36 of 37); that test and "versions agree" now find the kit's files wherever it is installed, in a world's root or under deps/. The bank fix itself is unchanged and was checked live: after Stop the bank is gone, a wallet deleted in edit mode stays deleted, and the next Play starts the bank and buys normally. Built on @builtin d7aa03b. 37 tests.

  • 1.1.8: one fix. When play stops, the bank on that machine now stops with its host; before, it kept running in edit mode with nothing ticking it, still subscribed to the saved wallets, and put back every change it had not made itself: a wallet reset from edit mode came straight back, and in a room where one player stops while others play on, the stopped machine's bank could undo the writes of the bank that takes over. A host replaced because it never ticked no longer stops the bank on its way out. One new test (37 tests).

  • 1.1.7: built on menusKit 1.3.4 and navUiKit 1.2.1 (both the same calls economyKit uses, now with their own guides), so the guide links to menusKit's two guides open in a freshly installed world; before, a fresh install brought menusKit 1.3.1, which has no guides. Built on @builtin 81db178. The README now lists the guides of the kits that come with economyKit and has a "Common questions" section (a currency's start, listeners that outlive a Play, grants from players' machines, pickupsKit coins into the wallet, what a bought item does, opening a shop). The guides' links to menusKit use its guides' own titles, and the how-to links navUiKit's guide. Every shop screen, wallet display and call works as in 1.1.6; 36 tests.

  • 1.1.6: two fixes, nothing else changed. The upgrade tree's arrow keys and d-pad now move between the nodes as they are drawn: Up and Down within a tier, Left and Right between tiers side by side, and through every node in order when the tiers stack on a phone (before, Down always jumped two nodes, so in a one-column tree it skipped every other upgrade and in the Soul Forge it jumped to the next tier). On a short screen (a phone held sideways), a quick-buy shop with more items than one row of tiles holds now shows a page at a time, with arrows either side to turn the page and the page following the selection; before, its tiles wrapped into a second row and pushed the shop's title, timer and wallet off the top of the screen. Shops that already fit are drawn exactly as before. The example guide moves between tiers with the arrow keys and the gamepad d-pad, and the how-to guide's opening names the in-game currency and wallet it covers. Two new tests (36 tests).

  • 1.1.5: two guides ship inside the package: "How to add money, wallets and a shop to my game" (the how-to) and "Make a coin collecting game with a shop and upgrades" (an example game from an empty world, followed step by step in a fresh world before release). Built on @builtin 72f1168. The README's opening now names this release and its 34 tests, and Known limits cites #19258. No code changes from 1.1.4 beyond the version string; 34 tests.

  • 1.1.4: setBankChooser(fn) lets a game say which machine runs the bank (rtsKit runs it on its match host, so a worker's delivery and a barracks' training cost are paid where the match is simulated). A host component that never ticked (a load that failed or was still waiting for content) is replaced within two seconds; before, the bank could stay down for the whole session and every deposit was refused with "Only the bank's machine can do that". Two new tests.

  • 1.1.3: republished so the release and the world it lives in hold the same bytes (1.1.2's world head carried a later @builtin repin no release named, and installs that pinned that head failed with VERSION_NOT_FOUND). No code change.

  • 1.1.2: built on inventoryKit 1.0.10, saveKit 1.3.2 and @builtin a9870f6, so a world that installs economyKit (or a kit built on it, such as productionKit) loads it from deps/: the inventoryKit it brought before named pickupsKit through @root:: and failed outside a world's source root.

  • 1.1.1: economy.module requires inventoryKit and saveKit by name (inventoryKit.inventory, saveKit.save) instead of by a /source/... path, so a world that installed economyKit with those kits under deps/ loads it (1.1.0 failed with "could not resolve require").

  • 1.1.0: shared accounts for team wallets. A target "acct:<name>" is a wallet the bank keeps for a team (or a computer opponent) with no player behind it, respecting each currency's max and persist, never mapped to a player or mirrored into saveKit. New on the bank's machine: Economy.balanceOf(target, cur?) for any account, Economy.debit(target, costs, reason?) taking a multi-currency cost all or nothing (refusal short with its text and missing per currency) and Economy.credit giving one back at once. On every machine: Economy.balanceOf("acct:<name>") reads a shared account from the store and Economy.watchAccount / the accountChanged event follow it. Existing calls behave as before. Three new tests (32 tests).

  • 1.0.13: economyKit and inventoryKit's own components run on one inventoryKit again. economyKit's modules were pinned to an older inventoryKit release than the inventoryKit package it ships, so an install loaded two copies of the bag code: Inventory.setup{ hud = false } (and Economy.inventory()) reached economyKit's copy while the bag strip was drawn by the other, and the strip could not be turned off. inventoryKit is updated to its latest release and every reference repinned to it; 29 tests.

  • 1.0.12: Economy.inventory() returns the inventoryKit module economyKit runs on, so a kit built on economyKit (buildPlaceKit, for one) can turn the bag's strip and keys off without requiring inventoryKit itself. A direct require of a kit that came in as economyKit's dependency was published with no version, and ZeroMind then refused to install the kit that made it.

  • 1.0.11: documentation only, no code changes from 1.0.10: the package description and the README's opening now read as a store listing (what you get, how to install, then the shopkeeper example).

  • 1.0.10: shop titles stay whole on a phone held upright in every look: "Adventurer's Outfitters" broke as "Adventurer'" / "s Outfitters" in the pixel look because the title shared a wrapping row with the wallet chips and had only about 1.5% more room than its longest word, so text drawn a little wider in a browser broke at the apostrophe. A phone header now gives the title a row of its own beside the close button (tabs and wallet chips below), and every wrapping label keeps 5% more than its longest word (plus its letter spacing and two points). The minimal wallet line really fits all eight sample currencies on one line on an upright phone: inside the floating wallet box the wrapping row had been laid out narrower than its own entries and dropped the last one (banknotes) onto a second line, so on a phone the row now gets its room as a width; icons count at their true widths (banknotes and tickets are wider than tall), the line is fitted with 6% to spare, its font and gaps tighten slightly when needed, and amounts of 10,000 and more shorten there ("12k", "1.2M") only if the full numbers still would not fit. The wallet panel is now as wide as its longest currency name beside its longest amount ("Células de energia" was squeezed beside a large amount in Portuguese). New test: shop titles stay whole on an upright phone, and the wallet-line test now covers large amounts and true icon widths (29 tests).

  • 1.0.9: the minimal wallet line reads whole on a phone held upright: it is never wider than the screen, whatever minimalWidth a game asks for (Market Square asked for 1240 points and "Banknotes" ran off the right edge), every entry stays in one piece, and when the names cannot fit on one line it shows each currency's icon and number, so all eight sample currencies fit one line. On a short screen (a phone held sideways) the wallet panel takes shorter rows and starts at the top, so a full wallet of eight fits its height. Known limits now carry the measured browser frame rate for Market Square. New test: the minimal line fits an upright phone (28 tests).

  • 1.0.8: every label reads whole in every look, language and size: a wrapping label is never narrower than its longest word (names like "Cloth" and "Sword" broke between letters because the UI lays labels out in whole points), names in fixed-width tiles shrink their font instead of breaking, one-line labels are never squeezed by their row, and long titles and hints wrap. Phones held sideways keep every button on screen (shorter panels, smaller quick-buy tiles, a compact vendor portrait and grid detail pane, stacked upgrade tiers when columns get narrow). The kit presses its own buttons when a finger taps them, so touch works with the touch controls up (#21441). Shopkeeper signs are respawned when the language changes (#7781). Wallets are kept per world (economyKit/<ns>.<world>/...), so a store an engine carried over from another world never sets a player's balance; existing wallets in a world that ran 1.0.7 start over once. New test: no label can break inside a word (27 tests).

  • 1.0.7: documentation only, no code changes from 1.0.6: the Known limits entry on simulated touches cites its issue (#21441), and the test suite's description counts and lists all 26 tests.

  • 1.0.6: a placed shopkeeper picks up a change to its screen (or kind, shop, radius) while playing; every screen reads in every look (the quick-buy strip and upgrade tree used dark fantasy ink on their dark tiles; secondary text, prices and warnings are now held to at least 3.6:1 contrast); the close button is a drawn cross, not a character some looks' fonts lacked; the catalogue lists screens, icons, wallets and keepers with names and style / genre / setting tags, and Economy.styles picks by tag; panelBottom and minimalWidth place the wallet panel and widen the minimal line; review records for the Portuguese catalog. Fixed: a trade that failed halfway through the hand-over could send items back to a player whose own hand-over had failed, copying them; it now returns only goods it saw leave a bag. Six new tests: full-bag and cancelled-halfway trades, a save and load round trip, contrast in every look, the close cross, and style tags.

  • 1.0.5: Economy.setup starts inventoryKit for the player, so bought items come back after Stop and Play (or a rejoin) in a game that never calls Inventory.setup itself, such as the three-item example above. Before, the bag was saved but not loaded again until something was given.

  • 1.0.4: a shopkeeper's name sign stays on one line and shrinks to fit labelWidth (long names used to wrap and draw over themselves); the floating coin over a keeper can be turned off (marker = false); popupPos places the "+10 / −25" popups and stacks many at once in columns of four; signs are rasterised at scale 1 (above 1 cropped the tops of the letters).

  • 1.0.3: refreshed model previews; no code changes from 1.0.2.

  • 1.0.2: installs cleanly into an empty world: its Model and Light components now resolve to the engine's own, not to older copies another kit had carried into the authoring world, and saveKit is pinned as a full dependency.

  • 1.0.1: first release on the world's main branch. The text module is now economyKit.lang (a package-relative ~.text failed to resolve after a world reload).

  • 1.0.0: a candidate published from a side branch for the fresh-install check; superseded by 1.0.1.