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:
  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%"

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

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