📖 THE COMPLETE ECONOMY GUIDE

🌍 THE BIG PICTURE

This economy is a closed-loop virtual marketplace built from the ground up on two bodies of research: merchandise economics (how digital goods create value) and in-game economy implementation (how virtual worlds prevent collapse).

It has eight interconnected systems, 50 manufactured items, and one unbreakable rule:

The eight systems:

• 🏪 Vendors — NPC shops at fixed prices
• 🔨 Auction House — player-to-player marketplace with bidding
• 🤝 Trading — direct player swaps, no middleman
• ⚒️ Crafting — combine materials into finished goods
• ⭐ Battle Pass — 100-tier seasonal progression
• ✉️ Mail — item and coin delivery
• 💰 Currency Sinks — repair, reroll, teleport
• 🌍 World Pickup — three.js items in the 3D world

💸 THE MONEY FLOW

Coins enter through faucets, circulate through exchanges, and leave through sinks. Healthy economy = balanced flow.

The Item Lifecycle

Every item follows this path:

1. Created — manufactured by Playa 2.0, seeded into economy_items
2. Distributed — via vendor, auction, pickup, battle pass, mail, or crafting
3. Used — consumed, equipped, traded, or displayed
4. Drained — repaired (sink), consumed (gone), crafted away, or rerolled
5. Legendary exception — fixed-supply collectibles never drain. That's their power and their danger.

🚀 SETUP: From Zero to Running Economy

1 Go to /admin/economy. Read the ⓘ HELP at the top. It explains every system in plain language.

2 Enable systems in order: Vendors → Auction House → Trading → Battle Pass. Each toggle is independent. Start with one, test it, then add the next.

3 Create a vendor. Give it a name, coordinates, and a catalog (JSON of items and prices). Players will see it in their Vendors tab.

4 Grant test coins. Use POST /api/economy/grant (admin) to give players starting coins.

5 Create a battle pass season. Name, duration, premium price. 100 tiers auto-generate from existing items.

6 Place world pickups. Use the "Place Item in World" form — pick an item, set coordinates, set respawn timer.

7 Monitor. Check /api/economy/sinks/stats weekly. Watch the net balance.

🎮 FOR PLAYERS: How to Play the Economy

Earning Coins

• Pick up items in the world and sell them at auction
• Craft refined goods from raw materials (value-add)
• Complete battle pass tiers for coin rewards
• Trade smart — buy low, sell high

Spending Coins

• Vendors — fixed prices, instant purchase
• Auctions — bid for deals, or buyout for speed
• Crafting — invest materials to create higher-value items
• Sinks — repair your tools, reroll for cosmetics, teleport for convenience

Pro Tips (from the research)

• Don't hoard materials — craft them into finished goods. Crafting adds value.
• Watch auction end times — bid late on items ending soon for better prices.
• Repair before breaking — repair costs scale with damage. Fix early, pay less.
• Legendary items appreciate — fixed supply means they only get rarer. Buy and hold.

Full panel walkthrough: Creator's Handbook → Navigate

⚒️ FOR CREATORS: Manufacturing Guide

Playa 2.0's complete handbook lives at /economy/creator. The essentials:

The Five Questions (answer before designing anything)

1. Kind? Consumable, material, cosmetic, collectible, or tool?
2. Role? Sink, faucet, trade good, desire, or legend?
3. Rarity? Common → Mythic (price signals this)
4. Source? Crafted, vendor, auction, pickup, pass, or mail?
5. Exit? How does it leave the economy?

The Visual Style: Sovereign Intaglio

Ultra-dense gold linework on cosmic purple-black. Density = value. Every object looks engraved. Reference: the collection gallery.

👑 FOR ADMINS: Managing the Economy

Daily

• Check /api/economy/health — all 7 tables should report "ok"
• Glance at active auctions and trades for anomalies

Weekly

• Check /api/economy/sinks/stats — review the net coin balance
• If net is growing fast: increase sink costs or add new sinks
• If net is shrinking: reduce sink costs, add more faucets
• Review vendor catalogs — update prices based on auction data

Seasonal

• Create a new battle pass season (deactivates the old one automatically)
• Manufacture new items with Playa 2.0 (the shop cron does this weekly)
• Place seasonal world pickups for events

🧠 GAME THEORY: Why It's Designed This Way

Every design choice comes from the research. Here's the reasoning:

Sinks Before Faucets

From monetary theory: any currency without drains hyperinflates. We built four sinks (repair, reroll, teleport, auction fees) before adding significant faucets. Most games do this backwards and pay for it later.

Escrow, Not Trust

From auction theory: trades and auction bids use escrow (items/coins held by the system, not the players). This eliminates the "take the money and run" problem that kills player-to-player markets.

Anti Bait-and-Switch

From mechanism design: if either trader changes their offer, both confirmations reset. This makes the "swap a valuable for a worthless at the last second" scam mathematically impossible.

Server-Authoritative Everything

From security research: the client is never trusted. Proximity checks, balance checks, ownership verification — all server-side. A hacked client cannot create coins or duplicate items.

Rarity as Information

From signaling theory: the intaglio visual density signals rarity instantly. Players don't need to read stats — the eye knows. This reduces cognitive load and increases desire.

The 5% Fee

From market microstructure: a small transaction tax (5%) discourages wash trading and high-frequency flipping while being low enough not to deter legitimate trade. It's also a consistent sink.

Battle Pass > Loot Boxes

From behavioral economics: deterministic progression (100 visible tiers) retains better than random rewards. Players can see exactly what they're working toward. No gambling mechanics.

🔧 TROUBLESHOOTING: When Things Break

Nothing was deleted. That is always the first truth. Every system preserves data through crashes, toggles, and restarts.

The Recovery Ladder (in order)

1 Check health: Visit /api/economy/health. It shows which of the 7 tables are healthy.

2 Reactivate: Go to /admin/economy, click ⚡ Reactivate Economy API. Clears rate limits, verifies tables, recreates missing ones.

3 Toggle: Turn the broken system OFF, then ON. This resets its state without touching data.

4 Restart: systemctl restart epistles. Last resort. All data preserved.

Common Errors