概述
MysticalVillager 是一款面向 Paper 服务器的全面村民管理插件。它追踪服务器上每一次治愈、击杀和繁殖行为,并提供反滥用保护、可配置的奖励系统以及无需登录的实时网页仪表盘。
无论你是运营小型 SMP 还是大型网络,MysticalVillager 都能为你提供监控和奖励积极村民互动行为的工具,同时检测并防止滥用行为。
功能
追踪与统计
追踪每位玩家治愈、击杀和繁殖的村民数量。插件会维护连胜记录、个人最佳成绩以及整个服务器的全局统计数据。所有数据在重启后持久保存,可通过命令、PlaceholderAPI 或网页仪表盘访问。
奖励系统
奖励玩家治愈僵尸村民的行为,奖励形式包括金钱、经验值、物品或自定义命令。每种奖励类型都有独立的概率设置,冷却时间机制可防止刷取治愈奖励。系统通过 Vault 集成实现经济支持。
反滥用检测
评分系统分析玩家行为以检测可疑活动。它能捕捉快速治愈、反复针对同一村民的行为,并根据集中度和繁殖模式识别村民农场。当检测到滥用行为时,将阻止奖励发放并通知工作人员。
跨插件保护
自动拦截来自 Citizens NPC、MythicMobs 及其他类似插件生成的虚假村民。这可以防止玩家利用生成的生物来骗取奖励。
冷却保护
当玩家在冷却期间尝试治愈时,物品不会被浪费:
- 金苹果在被阻止时会保留在背包中
- 如果玩家在冷却期间将虚弱药水扔向僵尸村民附近,药水会被退回
- 通过标题消息显示剩余冷却时间的视觉反馈
击杀惩罚
可选的玩家击杀村民时损失经验值。可配置等级惩罚,并在屏幕上显示羞耻提示消息。
标题消息
治愈、击杀和繁殖事件对应的屏幕标题(title)和副标题(subtitle)。文本完全可配置,支持颜色代码。可按事件类型启用或禁用。
网页仪表盘
公共网页界面展示实时统计数据:
- 全局及按玩家划分的统计
- 可按类型(治愈/击杀/繁殖)和时间段筛选的排行榜
- 带有详细统计模态框的玩家搜索功能
- 显示治愈模式的每周活动图表
- 小时分布图
- 带有玩家头像的最新活动流
- 完全响应式设计,适配移动设备
仪表盘通过服务器发送事件(Server-Sent Events)自动更新,无需刷新页面。
Discord 集成
通过 Webhook 将事件发送到 Discord。支持治愈通知、滥用警报、农场检测警告和利用阻止提醒,并提供丰富的嵌入消息和玩家信息。
多语言
内置英语、荷兰语(Nederlands)、德语(Deutsch)、西班牙语(Español)和葡萄牙语(Português)。所有消息均可通过语言文件自定义。
PlaceholderAPI 支持
提供 15+ 个占位符,可用于记分板、全息图、标签页列表等。
要求
| 软件 |
版本 |
| Paper(或其分支如 Purpur) |
1.21.x |
| Java |
21+ |
可选集成:
- PlaceholderAPI
- Vault(用于金钱奖励)
安装
- 从 Modrinth 或 GitHub Releases 下载
- 将 JAR 文件放入
plugins/ 文件夹
- 重启服务器
- 编辑
plugins/MysticalVillager/config.yml
- 使用
/mysticalvillager reload 应用更改
命令
| 命令 |
描述 |
权限 |
/mysticalvillager help |
显示帮助 |
- |
/mysticalvillager stats [player] |
查看统计信息 |
mysticalvillager.stats |
/mysticalvillager leaderboard |
查看排行榜 |
mysticalvillager.leaderboard |
/mysticalvillager reload |
重载配置 |
mysticalvillager.reload |
/mysticalvillager debug [player] |
调试信息 |
mysticalvillager.debug |
别名: /villagers, /mvillager, /mystvillager
故意避免使用 /mv 以防止与 Multiverse 冲突。
权限
| 权限 |
描述 |
默认值 |
mysticalvillager.admin |
完整管理员访问权限 |
op |
mysticalvillager.stats |
查看自己的统计信息 |
true |
mysticalvillager.stats.others |
查看他人的统计信息 |
op |
mysticalvillager.leaderboard |
查看排行榜 |
true |
mysticalvillager.reload |
重载配置 |
op |
mysticalvillager.staffalerts |
接收滥用警报 |
op |
mysticalvillager.bypass.cooldown |
绕过治愈冷却 |
false |
mysticalvillager.bypass.antidupe |
绕过防重复检测 |
false |
网页仪表盘
访问地址为 http://your-server-ip:25574(端口可配置)
仪表盘采用深色主题和玻璃拟态设计。它显示:
- 实时统计计数器
- 带有过滤选项的排行榜
- 玩家搜索功能
- 活动图表(每周 + 每小时分布)
- 最近的治愈事件动态
- 配置好的奖励概率
速率限制可防止垃圾信息。如果超出限制,将显示友好的倒计时页面。
PlaceholderAPI
| 占位符 |
描述 |
%mysticalvillager_cured% |
玩家的治愈数 |
%mysticalvillager_killed% |
玩家的击杀数 |
%mysticalvillager_bred% |
玩家的繁殖数 |
%mysticalvillager_streak% |
当前连胜 |
%mysticalvillager_best_streak% |
最佳连胜 |
%mysticalvillager_global_cured% |
服务器总治愈数 |
%mysticalvillager_global_killed% |
服务器总击杀数 |
%mysticalvillager_global_bred% |
服务器总繁殖数 |
%mysticalvillager_top_curer% |
#1 治愈者名称 |
%mysticalvillager_leaderboard_<n>_name% |
第 N 名的名称 |
%mysticalvillager_leaderboard_<n>_count% |
第 N 名的数值 |
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 端点
| 端点 |
方法 |
描述 |
/api/stats/global |
GET |
全局统计 |
/api/stats/player/{uuid} |
GET |
玩家统计 |
/api/players/search?q=name |
GET |
按名称搜索玩家 |
/api/leaderboard?type=CURED&period=ALL |
GET |
排行榜 |
/api/activity/week |
GET |
每周活动数据 |
/api/activity/hour |
GET |
每小时分布 |
/api/events/recent?limit=10 |
GET |
最近的事件 |
/api/rewards |
GET |
已配置的奖励 |
/api/events/stream |
GET |
SSE 事件流 |
服务端推送事件 (SSE)
连接到 /api/events/stream 以获取实时更新:
connected - 初始连接已建立
stats_update - 统计数据发生变化
cure - 新的治愈事件
heartbeat - 心跳保持(每 30 秒一次)
数据库
支持 SQLite(默认)、MySQL 和 MariaDB。所有操作均为异步,并通过 HikariCP 进行连接池管理。
database:
type: sqlite # 或 mysql, mariadb
# MySQL/MariaDB 设置
host: localhost
port: 3306
database: mysticalvillager
username: root
password: ""
配置亮点
奖励
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&l村民被治愈!"
subtitle: "&7+500 金币"
kill:
enabled: true
title: "&c&l村民被击杀"
subtitle: "&7-2 XP 等级"
性能
- 异步数据库操作
- 激进缓存,具有可配置的 TTL
- 不阻塞主线程
- 高效的实体扫描
- HikariCP 连接池
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
- Download from Modrinth or GitHub Releases
- Drop the JAR into your
plugins/ folder
- Restart the server
- Edit
plugins/MysticalVillager/config.yml
- 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
评论 0
登录后参与评分
还没有评论,来抢沙发吧