---

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

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.

database:
  type: sqlite  # or mysql, mariadb
  
  # MySQL/MariaDB settings
  host: localhost
  port: 3306
  database: mysticalvillager
  username: root
  password: ""

---

Configuration Highlights

Rewards

rewards:
  enabled: true
  chance: 100
  items:
    money:
      enabled: true
      chance: 80
      amount: 500
      command: "eco give %player% %amount%"
    experience:
      enabled: true
      chance: 50
      amount: 100
      command: "xp give %player% %amount%"

Anti-Abuse

antiAbuse:
  enabled: true
  threshold: 50
  scoring:
    fastCure: 5
    repeatedVillagerUuid: 10
    farmDetected: 15

Title Messages

titles:
  cure:
    enabled: true
    title: "&a&lVillager Cured!"
    subtitle: "&7+500 coins"
  kill:
    enabled: true  
    title: "&c&lVillager Killed"
    subtitle: "&7-2 XP levels"

---

Performance

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

---

License

MIT License - see LICENSE