MysticalVillager

---

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 Modrinth or GitHub 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 [player]` | View statistics | `mysticalvillager.stats` | | `/mysticalvillager leaderboard` | View leaderboard | `mysticalvillager.leaderboard` | | `/mysticalvillager reload` | Reload config | `mysticalvillager.reload` | | `/mysticalvillager debug [player]` | Debug information | `mysticalvillager.debug` |

Aliases: `/villagers`, `/mvillager`, `/mystvillager`

> `/mv` is intentionally avoided to prevent conflicts with Multiverse.

---

Permissions

| Permission | Description | Default | |------------|-------------|---------| | `mysticalvillager.admin` | Full admin access | op | | `mysticalvillager.stats` | View own stats | true | | `mysticalvillager.stats.others` | View others' stats | op | | `mysticalvillager.leaderboard` | View leaderboard | true | | `mysticalvillager.reload` | Reload configuration | op | | `mysticalvillager.staffalerts` | Receive abuse alerts | op | | `mysticalvillager.bypass.cooldown` | Bypass cure cooldowns | false | | `mysticalvillager.bypass.antidupe` | Bypass anti-dupe | false |

---

Web Dashboard

Access at `http://your-server-ip:25574` (port configurable)

The dashboard features a dark theme with glass-morphism design. It shows: - Live statistics counters - Leaderboards with filtering options - Player search functionality - Activity charts (weekly + hourly distribution) - Recent cure events feed - Configured reward chances

Rate limiting protects against spam. If exceeded, a friendly countdown page is shown.

---

PlaceholderAPI

| Placeholder | Description | |-------------|-------------| | `%mysticalvillager_cured%` | Player's cures | | `%mysticalvillager_killed%` | Player's kills | | `%mysticalvillager_bred%` | Player's breeds | | `%mysticalvillager_streak%` | Current streak | | `%mysticalvillager_best_streak%` | Best streak | | `%mysticalvillager_global_cured%` | Server total cures | | `%mysticalvillager_global_killed%` | Server total kills | | `%mysticalvillager_global_bred%` | Server total breeds | | `%mysticalvillager_top_curer%` | #1 curer name | | `%mysticalvillager_leaderboard_<n>_name%` | Position N name | | `%mysticalvillager_leaderboard_<n>_count%` | Position N count |

---

Discord Webhooks

```yaml discord: enabled: true webhookUrl: "https://discord.com/api/webhooks/..." serverName: "My Server" events: cure: true abuseDetected: true farmDetected: true exploitBlocked: true ```

---

API

REST Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | `/api/stats/global` | GET | Global statistics | | `/api/stats/player/{uuid}` | GET | Player statistics | | `/api/players/search?q=name` | GET | Search players by name | | `/api/leaderboard?type=CURED&period=ALL` | GET | Leaderboard | | `/api/activity/week` | GET | Weekly activity data | | `/api/activity/hour` | GET | Hourly distribution | | `/api/events/recent?limit=10` | GET | Recent events | | `/api/rewards` | GET | Configured rewards | | `/api/events/stream` | GET | SSE event stream |

Server-Sent Events

Connect to `/api/events/stream` for real-time updates: - `connected` - Initial connection established - `stats_update` - Statistics changed - `cure` - New cure event - `heartbeat` - Keep-alive (every 30s)

---

Database

Supports SQLite (default), MySQL, and MariaDB. All operations are async with connection pooling via HikariCP.

```yaml database: type: sqlite # or mysql, mariadb

MySQL/MariaDB settings

host: localhost port: 3306 database: mysticalvillager username: root password: "" ```

---

Configuration Highlights

---

Performance

- Async database operations - Aggressive caching with configurable TTLs - No main thread blocking - Efficient entity scanning - HikariCP connection pooling

---

License

MIT License - see LICENSE