# Marketplace and Trade Modes ## Overview The marketplace is the game's player-to-player listing system. Selling is intentionally gated behind **Seller Mode**, while buying remains available in both modes. Listings are stored in `marketplace_listings`, require an upfront listing fee, and apply a burn tax when sold. This system covers: - `.mode seller` / `.mode adventure` - `.market` browsing and filters - `.player sell ` listings - `.item buy ` purchases - `.market cancel ` cancellations ## Commands | Command | What it does | Notes | |---|---|---| | `.mode` | Shows current mode and the switch rules | Works in normal channels | | `.mode seller` | Enables marketplace selling | 5-minute cooldown between mode changes | | `.mode adventure` | Turns off selling mode | Buying still remains possible | | `.market` | Shows the latest 30 active listings | `#sellers` / marketplace channel only | | `.market animals` | Filters to animal listings | Same pattern for `weapons`, `enchantments`, `stones` | | `.market mine` | Shows your 20 most recent listings | Includes sold/cancelled history entries too | | `.market cancel ` | Cancels one of your active listings | Returns escrowed stackables | | `.player sell ` | Creates a listing | Requires Seller Mode unless invoked by the marketplace modal UI | | `.item buy ` | Buys an active listing | Buyer cannot buy their own listing | ## Channel / Mode Rules ### Channel restrictions The marketplace command set is only allowed in the marketplace channel category (`#sellers` / `marketplace`): Allowed there: - `.market` - `.player sell` - `.item buy` - `.money` / `.balance` - `.inventory` / `.inv` - `.zoo` - `.mode` - `.help` / `.commands` ### Seller Mode The player's mode is stored on `users.user_mode`. Rules: - default mode is `adventure` - switching has a **5-minute cooldown** - `seller` mode is required for `.player sell ...` - `adventure` mode disables selling, but players can still buy listings ## Listing Fees and Taxes ### Listing fee Every listing charges an upfront fee equal to: ```text max(1, floor(price * 0.02)) + 500 ``` This fee is paid immediately by the seller and is **not refunded** on cancellation. ### Sale tax When a listing sells: ```text tax = max(1, floor(price * 0.05)) sellerProceeds = price - tax ``` The tax is burned and the seller receives the remaining 95% (rounded down by the tax calculation). ## Supported Listing Types The marketplace supports these item types: - `animal` - `weapon` - `enchantment` - `evolution_stone` ## Price Range Rules All listings must stay within the allowed price range: ```text min = floor(basePrice * 0.80) max = floor(basePrice * 1.50) ``` ### Animal base pricing Animals use their rarity's `sellValue` from `data/animals.js`, then apply an evolution multiplier: - stage 0: base price - stage 1: `base * 1.60` - stage 2+: `base * 1.80` Commonly relevant base prices: | Rarity | Base Sell Value | |---|---:| | Mythic | 7,000 | | Legendary | 40,000 | | Fabled | 200,000 | | Gods | 1,500,000 | | Ascendants | 3,000,000 | | Boundless | 3,000,000 | | Infinity | 10,000,000 | ### Weapon base pricing Weapons use their shop `price` directly. ### Enchantment base pricing | Tier | Base Price | |---|---:| | Mythic | 10,000 | | Legendary | 30,000 | | Fabled | 50,000 | ### Evolution stone base pricing | Stone | Base Price | |---|---:| | Mythic | 15,000 | | Legendary | 30,000 | | Fabled | 60,000 | | Gods | 100,000 | ## Listing Rules by Item Type ### Animals Animal listings require: - owned animal match by exact name/key, - no active duplicate listing for that instance, - not currently in a team, - not already marketplace listed, - not trade locked. Additional animal rules: - animals below **Mythic** rarity cannot be listed, - listing an animal clears `equipped=0` and `team_slot=0`, - listed animals are marked `marketplace_listed=1`. ### Weapons Weapon listings require: - an owned **unequipped** instance of that weapon type, - no active listing already tied to that weapon instance. Weapons keep their existing instance data when sold, including reroll bonuses and enchantments, because ownership is transferred on the same row. ### Enchantments Enchantment listings require: - at least one owned copy in inventory, - the enchantment is not "used" below full stacked usage, - if it is equipped anywhere, the seller must have duplicates. Current sell restrictions from `canSellEnchantment()`: - used enchantments (`usage < quantity * 50`) cannot be sold, - equipped enchantments cannot be sold unless quantity > 1. ### Evolution stones A player must own at least one copy in inventory. The listed copy is escrowed out of inventory immediately. ## Buy Flow When a listing is purchased: 1. buyer coins are deducted, 2. listing status changes from `active` to `sold`, 3. seller is credited with `price - tax`, 4. the underlying item is transferred. ### Animal purchase behavior Animals are heavily normalized on purchase: - owner changes to the buyer, - `equipped=0`, `team_slot=0`, `marketplace_listed=0`, `trade_locked=0`, - level resets to **1**, - XP resets to **0**, - stats are recalculated to fresh stage-appropriate level 1 values. ### Weapon purchase behavior Weapons are transferred as-is: - owner changes, - `equipped=0`, `animal_slot=0` - rerolls and weapon enchantments remain on the weapon instance. ### Enchantment / stone purchase behavior Stackable listings use `item_instance_id='v2'` and transfer back into inventory. - enchantments are added through `addEnchantmentWithUsage()`, preserving the usage-stack model - stones are inserted into `inventory` as `item_type='evolution_stone'` ## Cancellation Flow `.market cancel `: - only works for the seller's own active listing, - changes status to `cancelled`, - clears `marketplace_listed=0` on animals, - returns escrowed stackables (`enchantment`, `evolution_stone`) to inventory if the listing used the `v2` stackable path. The upfront 2% listing fee is **not** returned. ## Database / Storage Details ### Main table Listings live in `marketplace_listings` with fields for: - listing ID - seller / buyer identity - item type - item key - display name - underlying instance ID - rarity - stage - price - status - timestamps ### Related persistence flags - `users.user_mode` - `users.mode_switch_last` - `animals.marketplace_listed` - `animals.trade_locked` ## Strategic Tips / Balance Notes - Seller Mode is only needed to create listings; you can stay in Adventure Mode if you mainly buy. - Because animals reset to level 1 on sale, the market rewards **rarity and stage**, not previous leveling effort. - Trade-locked dungeon/tower animals cannot be listed until they lose that restriction; plain market-bought animals explicitly have `trade_locked` cleared on purchase. - Weapons are the most "sticky" market item because rerolls and enchants carry forward to the buyer. - Used enchantments are intentionally hard to liquidate because the system tracks a shared usage pool per enchant ID.