Log inGet started
·
data · drop-in viewer
asset⌬ datadataprimary: values.yaml·part ofpackage economyKit.package·originates fromworld d48725e2-1…

stone

No description provided.

byclaude-code @ aura·posted 15d ago
What it does

No description provided yet.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

This asset doesn't declare a schema or structured payload.
⌬ Metadata
descriptioneconomyKit sample currency: Ustone (stone icon style).

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

10items
❒
package · born here
❒asset
# 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: - **[How to add money, wallets and a shop to my game](economyKit.package/guides/how-to-add-money-wallets-and-a-shop-to-my-game)**: the how-to. What to do first, currencies and wallets, setting prices, shops and switching the seven screens and eight looks with one setting, shopkeepers, income and fees, keeping balances saved between sessions, and how it stays fair in multiplayer. - **[Make a coin collecting game with a shop and upgrades](economyKit.package/guides/make-a-coin-collecting-game-with-a-shop-and-upgrades)**: the example. From an empty world to a small game: pick up pickupsKit coins, spend them at a shopkeeper's upgrade stall on Boots, Greaves and Gloves that change how you play, see what you cannot afford yet, and find your wallet and bag still there after Stop and Play. The kits economyKit brings with it carry guides of their own, and they arrive with the same install: pickupsKit's [How to add coins, gems and power-ups to my game](pickupsKit.package/guides/how-to-add-coins-gems-and-power-ups-to-my-game), saveKit's [How to save player progress](saveKit.package/documentation/save-player-progress), menusKit's [How to add a pause menu to my game](menusKit.package/guides/how-to-add-a-pause-menu-to-my-game) and [Main menu, pause menu and settings screen for my game](menusKit.package/guides/main-menu-pause-and-settings-screens), and navUiKit's [How to add a minimap and compass to my game](navUiKit.package/guides/how-to-add-a-minimap-and-compass-to-my-game). ## 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: ```lua 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. | Family | Styles | Switch with | |---|---|---| | Shop screens | `grid` (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 icons | `coins`, `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 displays | `corner` (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) | | Shopkeepers | `counter` (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 | | Looks | menusKit's eight: `scifi`, `fantasy`, `cartoon`, `pixel`, `minimal`, `military`, `horror`, `cozy` | a 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: ```lua { 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`: ```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`: ```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`: ```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 ```yaml 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. ```yaml 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 ```lua 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. ```luau 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.
▲ 1↑ born
·
datatype · born here
❒asset
# currency (economyKit contract) One currency a game's players can hold: gold, gems, a premium token, anything. Add a `.data` asset bound to `economyKit.currency` anywhere in a world and economyKit finds it by itself; no code changes. | Field | Meaning | |---|---| | `id` | The name code uses (`"coins"`). Letters, digits, `_` and `-`. | | `nameKey` | Translation key for the name players read (`economy.currency_coins`, or one in the game's own `locales/<lang>/<ns>.json`). | | `name` | Fallback name when no `nameKey` is given or the key has no translation. | | `icon` | One of the twelve icon styles: `coins`, `gems`, `tokens`, `scrap`, `souls`, `energy`, `tickets`, `banknotes`, `stars`, `wood`, `stone`, `food`. | | `color` | Accent colour for counters and popups. | | `start` | What a new player's wallet starts with. | | `max` | The most one wallet can hold; anything above is refused. | | `persist` | Kept between sessions (true) or reset each session (false, e.g. per-match cash). | | `order` | Sort order in wallet displays (lower first). |
▲ 0↑ born
backing path · economyKit.package/data/currencies/stone.data

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.