MysticalCurrency

💎 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 Vault integration - 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