💎 MysticalCurrency

Enterprise-grade Physical Currency, Lottery & Economy System for Paper 1.21.1

Turn your Minecraft economy into a real, tangible experience.

MysticalCurrency allows players to withdraw physical currency items, trade them in the world, and deposit them back into their Vault balance. Combined with a powerful lottery system, anomaly detection, advanced anti-dupe protection, and a live web dashboard — this is not just another economy plugin.

It’s a complete financial ecosystem for serious survival servers.

---

🚀 Features Overview

---

💰 Physical Currency System

Bring money to life.

• 4 fully configurable currency tiers

  • 🪙 Shard (IRON_NUGGET, $0.01)
  • 🟡 Coin (GOLD_NUGGET, $1)
  • 🗺 Banknote (MAP, $10)
  • 🏦 Capital (GOLD_INGOT, $100)

• Polished Bank GUI

  • Step multipliers
  • Custom withdraw amounts
  • Deposit all / per-tier
  • Inventory space validation (prevents failed withdrawals)

• Player-to-player money transfers

• Full Vault integration (EssentialsX & any Vault-compatible economy)

• Optional inflation control system

---

🎰 Advanced Lottery System

A fully featured, secure, configurable lottery framework.

• Configurable ticket costs, jackpots & schedules
• Progressive jackpot support
• Suspense animations with countdown & sounds
• Secondary prize tiers (percentage-based)
• Soft & hard pity system
• Ticket expiry support
• Cron-based scheduled draws
• Physical, signed lottery tickets with right-click book preview
• Admin ticket distribution commands
• Lottery seasons with automatic stat archiving
• Weekly seasonal resets (configurable)

---

🔒 Enterprise Security

Built for high-population survival servers.

• HMAC-SHA256 signed currency & lottery tickets
• Auto-generated secret key on first run
• Automatic invalid item removal
• Full interaction protection
• Anti multi-account detection (IP-hash based, optional)
• Anomaly detection with rate limiting:
  • Withdraw spikes
  • Transfer spikes
  • Ticket purchase spikes
  • Claim spikes
• Temporary auto-blocking on suspicious behavior
• Inventory space validation before withdrawals

---

📊 Statistics & Leaderboards

• Per-player tracking:

  • Tickets bought
  • Wins
  • Money won
  • Biggest win
  • Deposits
  • Withdrawals
  • Transfers

• Statistics GUI

• Leaderboards:

  • Most wins
  • Most money won
  • Recent winners

• SQLite database (async queries, zero main-thread blocking)

---

🌐 Multi-Language Support

Full i18n system — no translatable text in config.yml

Included languages:

• 🇬🇧 English
• 🇳🇱 Dutch (Nederlands)
• 🇩🇪 German (Deutsch)
• 🇵🇹 Portuguese (Português)

Add new languages easily by placing a YAML file inside:

plugins/MysticalCurrency/lang/

---

🔗 Integrations

PlaceholderAPI

Live updating placeholders:

• Active lottery
• Jackpot amount
• Top wins
• Top money
• Player stats
• Season info

Discord Webhooks

Receive structured embed notifications for:

• Draw results
• Winners
• Big transactions
• Exploit attempts
• Anomalies
• Season resets

Web Dashboard (Optional)

• REST API
• Token authentication
• Rate limiting
• Optional HTTPS/SSL
• Async & performance-safe

---

⚙️ Economy Controls

• Inflation control (dynamic tax brackets)
• Config migration system (safe updates)
• Automatic config backups
• Schema versioning
• Probability balancing system (optional)
• Anomaly detection thresholds fully configurable

---

📦 Requirements

| Dependency | Required | Version |
|------------|----------|---------|
| Paper | ✅ | 1.21.1+ |
| Java | ✅ | 21+ |
| Vault | ✅ | 1.7+ |
| Economy Plugin | ✅ | Any Vault-compatible (e.g. EssentialsX) |
| PlaceholderAPI | ❌ | 2.11+ |

---

⚙️ Installation

1. Download the latest .jar
2. Place it in your plugins/ folder
3. Start the server
4. Default config & language files generate automatically
5. HMAC secret key is auto-generated on first run
6. Set preferred language in config.yml → general.locale

---

💻 Commands

Player Commands

| Command | Description |
|---------|------------|
| /bank | Open Bank GUI |
| /bank withdraw <amount> [tier] | Withdraw currency |
| /bank deposit [all|tier] | Deposit currency |
| /bank transfer <player> <amount> | Transfer money |
| /bank balance | Check balance |
| /bank stats | View statistics |
| /lottery | View active lottery |
| /lottery buy [amount] | Buy ticket(s) |
| /lottery claim | Claim prizes |
| /lottery stats [player] | View lottery stats |

Admin Commands

| Command | Description |
|---------|------------|
| /mc reload | Reload config & language |
| /mc migrate <status|run> | Run config migration |
| /mc backup now | Backup config |
| /mc webhooktest | Send test Discord webhook |
| /mc dashboard <status|start|stop|regen-cert> | Manage dashboard |
| /lottery create <name> <minutes> | Create lottery |
| /lottery start | Start lottery |
| /lottery stop | Cancel lottery |
| /lottery draw | Force draw |
| /lottery give <player> | Give ticket |
| /lottery giveall | Give tickets to all |
| /lottery season <start|end> | Manage seasons |

---

🔐 Permissions

| Permission | Description |
|------------|------------|
| mysticalcurrency.bank | Access bank |
| mysticalcurrency.lottery | Access lottery |
| mysticalcurrency.lottery.admin | Lottery admin |
| mysticalcurrency.admin | Full admin |
| mysticalcurrency.bypass.anomaly | Bypass anomaly detection |
| mysticalcurrency.antidupe.alert | Receive anti-dupe alerts |

---

🧱 Built for Performance

• Async SQLite queries
• Async webhooks
• Async dashboard
• Zero main-thread blocking
• No memory leaks
• Optimized for 100+ player survival servers