Player Shop — Moderator Guide
Overview
The Player Shop is a full game economy you run without touching a spreadsheet: currencies, priced items, hidden black markets, lootboxes, betting events, auctions, and optional income systems — all controlled from Discord commands plus a private web dashboard.
Everything works standalone or alongside a running game. While a game is running with an active-player role configured, only players holding that role can use the shop; with no game running, the shop is open to everyone.
Two-server setups: all shop data is keyed to the chat server. During a game, players must use shop commands from the chat server — the active-player role lives there and can never match on the role server.
Getting started
/shopadmin open— opens your shop (creates it the first time; you can name it)./shopadmin currency create— make a currency, e.g. Gold with the 🪙 emoji./shopadmin item add— stock an item with a price. Leave stock empty for unlimited./shopadmin grant— give players some pocket money.
Players then use /shop to browse and buy, and /bag to see what they hold.
/shopadmin subcommand reference
Every subcommand requires the server's moderator role. Names that take a currency, item, shop, auction or event autocomplete as you type.
┌──────────────────────────┬──────────────────────────────────────┬──────────────────────────────────────────────────┐
│ Subcommand │ Options │ What it does │
├──────────────────────────┼──────────────────────────────────────┼──────────────────────────────────────────────────┤
│ open │ [name] │ Open a shop (creates it if new; a new name │
│ │ │ creates a second shop, e.g. Black Market) │
│ close │ [name] │ Close a shop; balances and inventories are kept │
│ currency create │ name [emoji] [transferable] │ Create a currency (transferable defaults to True)│
│ grant │ currency amount [player] [role] │ Give currency, or remove it with a negative │
│ │ │ amount; pick one player or a whole role │
│ loan │ asset debt player amount │ Grant equal asset and debt in one action; │
│ │ │ negative amount = repayment │
│ scale │ currency factor [player] [role] │ Multiply balances by a factor (e.g. 1.15 │
│ │ [everyone] │ interest); target a player, a role, or everyone │
│ item add │ name price currency [stock] [emoji] │ Add a simple item to the open shop (omit stock │
│ │ [description] [shop] │ for unlimited) │
│ item stock │ item quantity │ Set an item's stock to an exact quantity │
│ give │ player item [quantity] │ Put an item into a player's bag (default 1) │
│ take │ player item [quantity] │ Take an item out of a player's bag (default 1) │
│ tag │ player tag │ Give a player a visibility tag │
│ untag │ player tag │ Remove a visibility tag │
│ dashboard │ │ Private link to the shop dashboard (5 minutes) │
│ storefront │ shop │ Post the live public storefront in this channel │
│ leaderboard │ [currency] [item] [number] │ Post the top holders (default 10, max 25); pick │
│ │ │ exactly one of currency or item │
│ logchannel │ [channel] │ Set the shop log channel; omit to turn off │
│ betchannel │ [channel] │ Set the bet log channel; omit to turn off │
│ module │ module enabled │ Turn Activity income, Time income or Theft on or │
│ │ │ off (numbers are set on the dashboard first) │
│ trading │ enabled │ Turn /trade on or off (off by default) │
│ auction post │ auction │ Post an auction's bidding embed in this channel │
│ event post │ event │ Post an event's betting embed in this channel │
└──────────────────────────┴──────────────────────────────────────┴──────────────────────────────────────────────────┘
Shop data is keyed to the chat server, so every subcommand works the same whether you run it in the chat server or the role server.
Emoji on currencies and items
- A typed standard emoji (🪙) always works.
- Custom emoji work as full markup —
<:name:id>or<a:name:id>for animated — and the image also serves as item art on the dashboard and in embeds. - A bare
:shortcode:is resolved against emojis the bot can see. If the bot isn't in the emoji's home server, it genuinely cannot render it and the emoji is dropped with a warning.
The dashboard
/shopadmin dashboard links you to a private, phone-friendly web page (moderator role required — checked server-side on every request). Four tabs, and the page remembers which one you're on across refreshes:
- Stock — every shop with its items: prices (buy and optional sell-back), stock counts, per-player purchase limits, availability windows, images, visibility rules, lootbox contents, item stat effects. Sections highlight amber when you have unsaved edits.
- Players — every player with shop data: balances you can edit directly, inventory give/take, tags, and per-player stat overrides. Includes bulk grant to everyone listed.
- Events — create and run betting events and auctions (see below).
- Ledger — the append-only history of every purchase, sale, grant, bet, payout, trade, and moderator action. Filterable by player and action. This is your dispute-settling source of truth — lootbox rolls even record the weights at roll time.
The Stock tab also shows each shop's running profit per currency (money taken in from buys minus paid out in sell-backs), derived from the ledger.
Money rules
- Balances never go negative. Deductions clamp at zero.
- Debt is a currency. Create a non-transferable currency called Debt and grant it; players can't trade it away.
/shopadmin loanhands a player money the proper way: equal amounts of an asset currency (to spend) and a debt currency (what they owe), granted in one atomic action so the books always balance. A negative amount is a repayment — it takes both back, each clamping at zero./shopadmin scalemultiplies one player's balance, every member of a role, or every holder (everyone:True) by a factor —×1.15daily on Debt makes loan-shark play real. Rounds up when growing, down when shrinking./shopadmin grantaccepts a single player or a whole role at once (every non-bot member holding it); negative grants take money away.- Resets: zero one currency or all of them from the dashboard when a season ends.
- Every mutation lands in the ledger. There is no unlogged way to move money.
Visibility: hidden shops and items
Gate any item — or an entire shop — behind rules, ANDed together:
- has role / lacks role (role checks always run against the role's home guild)
- alive / dead (needs a running game that can answer)
- team (managed games)
- tag — free-form labels you place on players from the Players tab (works standalone; use tags instead of team roles when roles would out the wolves)
Rules fail closed: a rule that can't be answered (no game running) hides the item. A hidden shop or item is indistinguishable from one that doesn't exist — browsing, buying, /trade name lookups, and autocomplete all answer as if it were never there.
Multiple shops can be open at once: a public general store, a mafia-only black market, a secret shop revealed by a breadcrumb hunt. Players who can see several shops get a picker; players who can see one go straight in.
Perishable items
Give any item an expiry from its dashboard card: a number of minutes, hours, or days from the moment you save (700 minutes is fine). Past that instant the item dies everywhere at once — it can't be bought, sold, traded, or opened, its held effects stop counting immediately, and within a minute a sweep archives it and removes every copy from every bag (each disappearance is ledgered). The clock is stored on the item itself, so bot restarts change nothing. The item card shows the current death date and a Clear expiry button to lift it.
Lootboxes
Mark an item as a lootbox and fill it with weighted entries on the dashboard. Buying one rolls per unit and delivers the prize instead of the box (with a big reveal); a lootbox can also contain other lootboxes, opened one level per action from /bag. Rolls and their weight snapshots are ledgered. Archiving a lootbox is the kill switch — even already-owned copies can no longer be opened.
Player trading
/trade lets players swap items and currency with each other — off by default. Turn it on per server with /shopadmin trading enabled:True (and off again with enabled:False) or the dashboard toggle. Non-transferable currencies (Debt) can never change hands in either direction. Offers are public messages with Accept/Decline buttons; the swap happens atomically when the target accepts, and both sides are re-verified at that moment. Offers expire after 20 minutes (survives bot restarts — the clock is the offer's own timestamp): the posted message updates and stale accepts are refused.
Storefront, leaderboards, logs
/shopadmin storefrontposts one live-updating public shop embed for the server: it refreshes as stock changes and players buy from it through ephemeral replies. Only rule-free items in rule-free shops can appear on it — if the shop is gated, the command refuses./shopadmin leaderboardposts the top N holders of any currency or item, using server display names.- Purchases are private by default. Set
/shopadmin logchannelfor an activity feed of buys, sells, grants, and trades;/shopadmin betchannelfor bets, event closures, payouts, and auction activity. Point both at the same channel if you like, and control who reads them with normal channel permissions.
Economy modules
Optional income systems, all off by default. Set the numbers (currency, amounts, cooldowns, odds) on the dashboard's Modules card first; then switch each module on or off there or with /shopadmin module. The command refuses to enable a module that has never been configured.
Activity income
Pay players for chatting. Two flavors:
- Hotword monitoring — pick the channels (or whole categories) to watch and a hotword; when an eligible message matches, the bot pays and reacts with the currency's emoji (a red ❌ means the player is on cooldown). After a restart the bot backfills recent messages it missed, paying retroactively. An empty channel list means the hotword is inactive.
- /work — a simple command on a cooldown, no channel watching involved.
Time income
A steady wage: X currency every Y hours, paid by a background job to eligible players.
Theft
Enable /steal and players can rob each other. You configure the success chance, how much a successful heist takes (flat or percentage), the penalty for getting caught, and whether victims are told who robbed them.
Item stat effects
Items can bend those rules for their owner: income bonuses, better steal odds, lighter penalties. Effects apply once per item type no matter how many copies are owned — sell a Lucky Coin or a Ski Mask. Per-player overrides are also available on the Players tab.
Betting events
Create an event on the dashboard's Events tab: a name, a currency, and outcomes with fractional odds (3:1 pays three-to-one profit plus the stake back). Post it to a channel; players bet through buttons with preset amounts. One bet per player — a new bet refunds the old stake first, so misclicks are always recoverable while betting is open.
Lock to pause betting (the embed's totals stay live), resolve to pay winners automatically, or cancel to refund every stake in full. Closures, payouts, and refunds all post to the bet-log channel.
Auctions
Also on the Events tab: auction an item — or any prize you can type — with a starting bid and increment. The posted embed has one Bid button that always takes the current price. Money is escrowed: debited while a player is winning, refunded the moment they're outbid. Close manually or set a deadline, optionally with anti-snipe extension (late bids push the deadline out). A per-auction option shows bidders by name or keeps them anonymous. The prize is minted for the winner — shop stock is untouched.
Two optional twists:
- Buyout price — adds a Buy now button: paying it wins instantly and ends the auction (the standing bid is refunded). Once regular bidding would reach the buyout price, only Buy now remains.
- Sell on behalf of a player — pick a seller when creating the auction (requires an item prize the seller owns). The item is escrowed out of their inventory for the duration, so they can't trade or sell it while it's on the block, and the winning bid is paid to them automatically when the hammer falls. If the auction is cancelled or closes with no bids, the item goes back to them. Sellers can't bid on their own auctions.
Data lifecycle
- The Manage Servers page shows counts of all shop data per server and can clear shop data alone.
/cleanupgamewipes all shop data along with the game: shops, items, currencies, balances, inventories, tags, events, auctions, trades and the ledger, and resets shop settings (modules, log channels, trading) to defaults. The confirmation embed says so before you confirm.- Changing a config's server IDs warns and then wipes the old servers' game and shop data — rotating role servers is common, and stale economies must not leak into the next game.