MysticalVillager

<div align="center"> # MysticalVillager ### Track, reward, and protect your server's villager ecosystem (https://img.shields.io/badge/Paper-1.21.x-blue?style=flat-square&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAACXBIWXMAAAsTAAALEwEAmpwYAAAA2klEQVQoz42SsQ3CMBCF3yFTZAYWYAKmiJTJYABKhoAVmIIxKBmAHdhBiC5Kclec7UQKLyp8vnfn986AMcbB1X0A7xjjEwB8/qmqCvR+AwBmvijjKC5J0L4k5xi/Oa01EEAogRDCxGd01AQwBQCstRPAuq4fRFQCwGK0u4hIa+1UVR0A7EYSu7u7N3e/A8CYNDjnHiJyAnBI+t31M/dca+0EYGFmW9eDiOwBfJzzNIQwcQAwxozLQJxz7yKSdZfcAGDd9z1F5AXgPPQNnwDgOY7jl5n9vYkv809/AVg6OFR6DzoAAAAASUVORK5CYII=)](https://papermc.io/) (https://img.shields.io/badge/Java-21+-ED8B00?style=flat-square&logo=openjdk&logoColor=white)](https://adoptium.net/) (https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE) (https://img.shields.io/badge/Download-Modrinth-00AF5C?style=flat-square&logo=modrinth)](https://modrinth.com/plugin/mysticalvillager) (#features) • (#installation) • (#commands) • (#web-dashboard) • (#api) </div> --- ## Overview MysticalVillager is a comprehensive villager management plugin for Paper servers. It tracks every cure, kill, and breed on your server while providing anti-abuse protection, configurable rewards, and a real-time web dashboard that requires no login. Whether you run a small SMP or a large network, MysticalVillager gives you the tools to monitor and reward positive villager interactions while detecting and preventing abuse. --- ## Features ### Tracking & Statistics Track villagers cured, killed, and bred per player. The plugin maintains streaks, personal bests, and global statistics across your entire server. All data persists across restarts and is accessible through commands, PlaceholderAPI, or the web dashboard. ### Reward System Reward players for curing zombie villagers with money, experience, items, or custom commands. Each reward type has its own probability, and cooldowns prevent spam curing. The system integrates with Vault for economy support. ### Anti-Abuse Detection A scoring system analyzes player behavior to detect suspicious activity. It catches rapid cures, repeated targeting of the same villager, and detects villager farms based on concentration and breeding patterns. When abuse is detected, rewards are blocked and staff are notified. ### Cross-Plugin Protection Automatically blocks fake villagers from Citizens NPCs, MythicMobs, and similar plugins. This prevents players from exploiting spawned mobs for rewards. ### Cooldown Protection When a player attempts to cure while on cooldown, items aren't wasted: - Golden apples stay in inventory when blocked - Weakness potions are returned if thrown near zombie villagers while on cooldown - Visual feedback via title messages shows remaining cooldown time ### Kill Penalties Optional XP loss when players kill villagers. Configurable level penalty with visual shame messages displayed on screen. ### Title Messages On-screen title and subtitle messages for cure, kill, and breed events. Fully configurable text with color code support. Can be enabled or disabled per event type. ### Web Dashboard A public web interface displays real-time statistics: - Global and per-player stats - Leaderboards filterable by type (cured/killed/bred) and time period - Player search with detailed stats modal - Weekly activity charts showing cure patterns - Hourly distribution graphs - Recent activity feed with player avatars - Fully responsive for mobile devices The dashboard updates automatically via Server-Sent Events - no page refresh needed. ### Discord Integration Send events to Discord via webhooks. Supports cure notifications, abuse alerts, farm detection warnings, and exploit blocks with rich embeds and player information. ### Multi-Language Ships with English, Dutch (Nederlands), German (Deutsch), Spanish (Español), and Portuguese (Português). All messages are customizable through language files. ### PlaceholderAPI Support 15+ placeholders for use in scoreboards, holograms, tab lists, and more. --- ## Requirements | Software | Version | |----------|---------| | Paper (or forks like Purpur) | 1.21.x | | Java | 21+ | **Optional integrations:** - PlaceholderAPI - Vault (for money rewards) --- ## Installation 1. Download from (https://modrinth.com/plugin/mysticalvillager) or (https://github.com/yourname/mysticalvillager/releases) 2. Drop the JAR into your `plugins/` folder 3. Restart the server 4. Edit `plugins/MysticalVillager/config.yml` 5. Use `/mysticalvillager reload` to apply changes --- ## Commands | Command | Description | Permission | |---------|-------------|------------| | `/mysticalvillager help` | Show help | - | | `/mysticalvillager stats ` | View statistics | `mysticalvillager.stats` | | `/mysticalvillager leaderboard` | View leaderboard | `mysticalvillager.leaderboard` | | `/myst