{"id":108309,"date":"2026-06-06T09:19:09","date_gmt":"2026-06-06T06:19:09","guid":{"rendered":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/"},"modified":"2026-06-06T09:19:09","modified_gmt":"2026-06-06T06:19:09","slug":"mysticalvillager","status":"publish","type":"mod","link":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/","title":{"rendered":"MysticalVillager"},"content":{"rendered":"
\n

# MysticalVillager<\/p>\n

### Track, reward, and protect your server’s villager ecosystem<\/p>\n

![Paper](https:\/\/papermc.io\/)
\n![Java](https:\/\/adoptium.net\/)
\n![License](LICENSE)
\n![Modrinth](https:\/\/modrinth.com\/plugin\/mysticalvillager)<\/p>\n

[Features](#features) \u2022 [Installation](#installation) \u2022 [Commands](#commands) \u2022 [Dashboard](#web-dashboard) \u2022 [API](#api)<\/p>\n<\/div>\n

—<\/p>\n

## Overview<\/p>\n

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.<\/p>\n

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.<\/p>\n

—<\/p>\n

## Features<\/p>\n

### Tracking & Statistics
\nTrack 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.<\/p>\n

### Reward System
\nReward 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.<\/p>\n

### Anti-Abuse Detection
\nA 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.<\/p>\n

### Cross-Plugin Protection
\nAutomatically blocks fake villagers from Citizens NPCs, MythicMobs, and similar plugins. This prevents players from exploiting spawned mobs for rewards.<\/p>\n

### Cooldown Protection
\nWhen a player attempts to cure while on cooldown, items aren’t wasted:
\n– Golden apples stay in inventory when blocked
\n– Weakness potions are returned if thrown near zombie villagers while on cooldown
\n– Visual feedback via title messages shows remaining cooldown time<\/p>\n

### Kill Penalties
\nOptional XP loss when players kill villagers. Configurable level penalty with visual shame messages displayed on screen.<\/p>\n

### Title Messages
\nOn-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.<\/p>\n

### Web Dashboard
\nA public web interface displays real-time statistics:
\n– Global and per-player stats
\n– Leaderboards filterable by type (cured\/killed\/bred) and time period
\n– Player search with detailed stats modal
\n– Weekly activity charts showing cure patterns
\n– Hourly distribution graphs
\n– Recent activity feed with player avatars
\n– Fully responsive for mobile devices<\/p>\n

The dashboard updates automatically via Server-Sent Events – no page refresh needed.<\/p>\n

### Discord Integration
\nSend events to Discord via webhooks. Supports cure notifications, abuse alerts, farm detection warnings, and exploit blocks with rich embeds and player information.<\/p>\n

### Multi-Language
\nShips with English, Dutch (Nederlands), German (Deutsch), Spanish (Espa\u00f1ol), and Portuguese (Portugu\u00eas). All messages are customizable through language files.<\/p>\n

### PlaceholderAPI Support
\n15+ placeholders for use in scoreboards, holograms, tab lists, and more.<\/p>\n

—<\/p>\n

## Requirements<\/p>\n

| Software | Version |
\n|———-|———|
\n| Paper (or forks like Purpur) | 1.21.x |
\n| Java | 21+ |<\/p>\n

**Optional integrations:**
\n– PlaceholderAPI
\n– Vault (for money rewards)<\/p>\n

—<\/p>\n

## Installation<\/p>\n

1. Download from Modrinth or GitHub Releases
\n2. Drop the JAR into your `plugins\/` folder
\n3. Restart the server
\n4. Edit `plugins\/MysticalVillager\/config.yml`
\n5. Use `\/mysticalvillager reload` to apply changes<\/p>\n

—<\/p>\n

## Commands<\/p>\n

| Command | Description | Permission |
\n|———|————-|————|
\n| `\/mysticalvillager help` | Show help | – |
\n| `\/mysticalvillager stats [player]` | View statistics | `mysticalvillager.stats` |
\n| `\/mysticalvillager leaderboard` | View leaderboard | `mysticalvillager.leaderboard` |
\n| `\/mysticalvillager reload` | Reload config | `mysticalvillager.reload` |
\n| `\/mysticalvillager debug [player]` | Debug information | `mysticalvillager.debug` |<\/p>\n

**Aliases:** `\/villagers`, `\/mvillager`, `\/mystvillager`<\/p>\n

> `\/mv` is intentionally avoided to prevent conflicts with Multiverse.<\/p>\n

—<\/p>\n

## Permissions<\/p>\n

| Permission | Description | Default |
\n|————|————-|———|
\n| `mysticalvillager.admin` | Full admin access | op |
\n| `mysticalvillager.stats` | View own stats | true |
\n| `mysticalvillager.stats.others` | View others’ stats | op |
\n| `mysticalvillager.leaderboard` | View leaderboard | true |
\n| `mysticalvillager.reload` | Reload configuration | op |
\n| `mysticalvillager.staffalerts` | Receive abuse alerts | op |
\n| `mysticalvillager.bypass.cooldown` | Bypass cure cooldowns | false |
\n| `mysticalvillager.bypass.antidupe` | Bypass anti-dupe | false |<\/p>\n

—<\/p>\n

## Web Dashboard<\/p>\n

Access at `http:\/\/your-server-ip:25574` (port configurable)<\/p>\n

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

Rate limiting protects against spam. If exceeded, a friendly countdown page is shown.<\/p>\n

—<\/p>\n

## PlaceholderAPI<\/p>\n

| Placeholder | Description |
\n|————-|————-|
\n| `%mysticalvillager_cured%` | Player’s cures |
\n| `%mysticalvillager_killed%` | Player’s kills |
\n| `%mysticalvillager_bred%` | Player’s breeds |
\n| `%mysticalvillager_streak%` | Current streak |
\n| `%mysticalvillager_best_streak%` | Best streak |
\n| `%mysticalvillager_global_cured%` | Server total cures |
\n| `%mysticalvillager_global_killed%` | Server total kills |
\n| `%mysticalvillager_global_bred%` | Server total breeds |
\n| `%mysticalvillager_top_curer%` | #1 curer name |
\n| `%mysticalvillager_leaderboard__name%` | Position N name |
\n| `%mysticalvillager_leaderboard__count%` | Position N count |<\/p>\n

—<\/p>\n

## Discord Webhooks<\/p>\n

“`yaml
\ndiscord:
\n enabled: true
\n webhookUrl: “https:\/\/discord.com\/api\/webhooks\/…”
\n serverName: “My Server”
\n events:
\n cure: true
\n abuseDetected: true
\n farmDetected: true
\n exploitBlocked: true
\n“`<\/p>\n

—<\/p>\n

## API<\/p>\n

### REST Endpoints<\/p>\n

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

### Server-Sent Events<\/p>\n

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

—<\/p>\n

## Database<\/p>\n

Supports SQLite (default), MySQL, and MariaDB. All operations are async with connection pooling via HikariCP.<\/p>\n

“`yaml
\ndatabase:
\n type: sqlite # or mysql, mariadb<\/p>\n

# MySQL\/MariaDB settings
\n host: localhost
\n port: 3306
\n database: mysticalvillager
\n username: root
\n password: “”
\n“`<\/p>\n

—<\/p>\n

## Configuration Highlights<\/p>\n

\nRewards<\/summary>\n

“`yaml
\nrewards:
\n enabled: true
\n chance: 100
\n items:
\n money:
\n enabled: true
\n chance: 80
\n amount: 500
\n command: “eco give %player% %amount%”
\n experience:
\n enabled: true
\n chance: 50
\n amount: 100
\n command: “xp give %player% %amount%”
\n“`<\/p>\n<\/details>\n

\nAnti-Abuse<\/summary>\n

“`yaml
\nantiAbuse:
\n enabled: true
\n threshold: 50
\n scoring:
\n fastCure: 5
\n repeatedVillagerUuid: 10
\n farmDetected: 15
\n“`<\/p>\n<\/details>\n

\nTitle Messages<\/summary>\n

“`yaml
\ntitles:
\n cure:
\n enabled: true
\n title: “&a&lVillager Cured!”
\n subtitle: “&7+500 coins”
\n kill:
\n enabled: true
\n title: “&c&lVillager Killed”
\n subtitle: “&7-2 XP levels”
\n“`<\/p>\n<\/details>\n

—<\/p>\n

## Performance<\/p>\n

– Async database operations
\n– Aggressive caching with configurable TTLs
\n– No main thread blocking
\n– Efficient entity scanning
\n– HikariCP connection pooling<\/p>\n

—<\/p>\n

## License<\/p>\n

MIT License – see [LICENSE](LICENSE)<\/p>\n","protected":false},"excerpt":{"rendered":"

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.<\/p>\n","protected":false},"featured_media":108310,"template":"","meta":{"_minecraft_slug":"mysticalvillager","_minecraft_project_id":"gZv3HtvF","_minecraft_author":"mysticalcraft-ancientvipers","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":15,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"mysticalvillager.zip","_minecraft_size_bytes":55825819,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-15T22:49:57.379565Z","_minecraft_date_created":"2026-03-12T08:35:06.610943Z","_minecraft_date_modified":"2026-03-11T18:41:22.505836Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/mysticalvillager","_minecraft_icon_attachment_id":108310,"_minecraft_imported_at":"2026-06-06T06:19:11+00:00","_minecraft_import_hash":"5299040a2db971640375459e93cb675f","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,126,137,90,127,92],"mod_loader":[132],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-108309","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-management","mod_category-mobs","mod_category-optimization","mod_category-paper","mod_category-utility","mod_loader-paper","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\nMysticalVillager - Minecraft<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"MysticalVillager - Minecraft\" \/>\n<meta property=\"og:description\" content=\"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.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/\" \/>\n<meta property=\"og:site_name\" content=\"Minecraft\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/\",\"name\":\"MysticalVillager - Minecraft\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp\",\"datePublished\":\"2026-06-06T06:19:09+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/#primaryimage\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp\",\"contentUrl\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/wp-content\\\/uploads\\\/2026\\\/06\\\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp\",\"width\":96,\"height\":96},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/mysticalvillager\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Mods\",\"item\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/mods\\\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"MysticalVillager\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/#website\",\"url\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/\",\"name\":\"Minecraft\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/vpesports.com\\\/minecraft\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"MysticalVillager - Minecraft","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/","og_locale":"en_US","og_type":"article","og_title":"MysticalVillager - Minecraft","og_description":"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.","og_url":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/","og_site_name":"Minecraft","twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/","url":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/","name":"MysticalVillager - Minecraft","isPartOf":{"@id":"https:\/\/vpesports.com\/minecraft\/#website"},"primaryImageOfPage":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/#primaryimage"},"image":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/#primaryimage"},"thumbnailUrl":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp","datePublished":"2026-06-06T06:19:09+00:00","breadcrumb":{"@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/#primaryimage","url":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp","contentUrl":"https:\/\/vpesports.com\/minecraft\/wp-content\/uploads\/2026\/06\/mysticalvillager-icon-ed7894db0fed16f4a042331a529c9c890dc00225_96.webp","width":96,"height":96},{"@type":"BreadcrumbList","@id":"https:\/\/vpesports.com\/minecraft\/mods\/mysticalvillager\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/vpesports.com\/minecraft\/"},{"@type":"ListItem","position":2,"name":"Mods","item":"https:\/\/vpesports.com\/minecraft\/mods\/"},{"@type":"ListItem","position":3,"name":"MysticalVillager"}]},{"@type":"WebSite","@id":"https:\/\/vpesports.com\/minecraft\/#website","url":"https:\/\/vpesports.com\/minecraft\/","name":"Minecraft","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/vpesports.com\/minecraft\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod\/108309","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod"}],"about":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/types\/mod"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/media\/108310"}],"wp:attachment":[{"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/media?parent=108309"}],"wp:term":[{"taxonomy":"mod_category","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod_category?post=108309"},{"taxonomy":"mod_loader","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/mod_loader?post=108309"},{"taxonomy":"minecraft_version","embeddable":true,"href":"https:\/\/vpesports.com\/minecraft\/wp-json\/wp\/v2\/minecraft_version?post=108309"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}