About roblox-economy
roblox-economy is a design reference for Roblox developers building or tuning in-game economies, including currencies, rewards, trading, and monetization. It provides heuristics for balancing currency flows and metrics for monitoring economic health.
Key features
- 01Currency types and design heuristics
- 02Faucet and sink balancing
- 03Progression time targets
- 04Inflation and deflation controls
- 05Atomic trade and confirmation rules
- 06Economy health metrics
Use cases
- 01Design a currency and reward system
- 02Balance earnings against purchases and upgrades
- 03Set safeguards for player trading
- 04Investigate inflation or deflation
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/roblox-economyin Claude Code to confirm it loaded.
Bundled filesreferences/full.md
Details
From the project READMEWhen to Load
Load when designing currency systems, balancing rewards, creating trading/marketplace systems, or diagnosing inflation/deflation in an existing game. Also relevant for monetization integration (GamePasses, battle passes, premium currency).
Quick Reference
Currencies (max 3) — design heuristic, not an engine limit
- Soft (Gold): gameplay-earned, primary transactions
- Premium (Gems): rare/purchased with Robux, exclusive items
- Tokens (Event Points): limited-time, expires per event
Faucets ↔ Sinks Balance
Faucets: quests, daily login, drops, PvP wins, selling items, achievements, rebirth Sinks: purchases, upgrades, repairs (10-20% tax), cosmetics, consumables, gacha
- Faucets > Sinks → inflation (currency worthless)
- Sinks > Faucets → deflation (new players stuck)
Time-to-Earn Targets
| Goal | Time |
|---|---|
| Early (first hour) | 5-15 min |
| Session | 30-60 min |
| Multi-session | 2-5 hrs |
| Long-term | 10-50 hrs |
| Prestige | 100+ hrs |
Rule: meaningful progress every 30-60 seconds (design heuristic).
Inflation Control
Hard sinks, variable pricing, seasonal resets, luxury goods, 10-20% trade tax (design heuristic), durability costs, prestige/rebirth resets.
Trading Rules
- Atomic: both sides complete or neither does (server-side)
- Double confirm: propose → review → confirm
- Value warnings on rarity mismatches
- Trade cooldowns + server-side logging for rollback
- Tax: 10-20% removed per transaction
Monetization
- Never sell soft currency for Robux (instant inflation)
- Premium currency → exclusive items or time-skips (not power)
- 2x Gold passes = inflation accelerators; cap or scale prices
- Cosmetic-only passes = safest (zero economy impact)
- Battle pass: unconverted premium currency expires end-of-season (sink)
Monetization Implementation
For purchase APIs (ProcessReceipt, GamePass, prompts, DevEx rates), see roblox-monetization.
Health Metrics
Track: earn rate by level, sink participation %, currency stockpile distribution, time-to-first-purchase, trade volume.
Common Mistakes
Infinite faucets/finite sinks · rewarding AFK · linear scaling without price scaling · no early wins · tradeable premium currency · no trade tax
📖 Full reference: references/full.md