💎 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]`
/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>`
/mc backup now	Backup config
/mc webhooktest	Send test Discord webhook
`/mc dashboard <status	start
/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>`

---

🔐 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