# 💎 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