VillageAI 插件
版本: 3.3.2
API: Paper 1.21 / Java 21
作者: Duong2012G
VillageAI 将原版 Minecraft 村庄转变为鲜活、具有反应能力的社区。 村庄能够自我防御、管理自身的供需经济、发布任务, 并根据玩家声望动态做出反应——无需任何外部依赖。
功能
| 系统 | 描述 |
|---|---|
| 状态机 | 村庄在 SAFE(安全)→ ALERT(警戒)→ DEFENDING(防御中)→ NIGHT / RAID(夜间/袭击)之间自动循环 |
| 空间铃索引 | 通过 ChunkCoord 索引实现 O(1) 复杂度的村庄查找——区块事件触发时无需全量扫描 |
| 经济系统 | 基于供需的定价机制,并带有按玩家声望计算的乘数(−50% 至 +50%) |
| 袭击 | 可配置的多波次袭击,包含多种怪物和绿宝石奖励 |
| 升级 | WALL(城墙)· WATCHTOWER(瞭望塔)· GRANARY(粮仓)· FORGE(铁匠铺)——每项升级都带来实质性的游戏性影响 |
| 任务 | 24 小时 DeliveryQuest(配送任务)周期,设有截止时间;通过与村民交互获得奖励 |
| 交易 GUI | 54 格箱子界面,实时显示价格以及折扣/加价指示器 |
| 村民命名 | 每个村民拥有自定义名称标签,显示其职业和生命值 |
| 异步存储 | 原子文件保存(写入临时文件 → 重命名),并自动备份 |
安装
- 确保你正在运行 Paper 1.21(或兼容分支)并使用 Java 21。
- 将
VillageAI-3.3.2.jar放入服务器的plugins/文件夹中。 - 启动(或重启)服务器——请勿使用
/reload命令。 - 首次运行时,配置文件将在
plugins/VillageAI/目录下生成。
注意: 官方不支持 PlugMan 热重载。更新插件时请务必完全重启服务器。
从源码构建
# 克隆/解压源码,然后执行:
mvn clean package -DskipTests
# 阴影 Jar 包将位于:
target/VillageAI-3.3.2.jar
要求:Java 21,Maven 3.8+。
命令
| 命令 | 权限 | 描述 |
|---|---|---|
/villageai info |
villageai.info |
显示最近村庄的状态 |
/villageai list |
villageai.admin |
列出所有已加载的村庄 |
/villageai reload |
villageai.admin |
重新加载配置(热重载) |
/villageai debug |
villageai.admin |
切换调试输出 |
/villageai raid start |
villageai.admin |
强制开始一次袭击 |
/villageai raid stop |
villageai.admin |
强制停止一次袭击 |
/vtrade |
villageai.trade |
打开最近村庄的交易 GUI |
/vtrade buy <item> [qty] |
villageai.trade |
通过命令直接购买 |
/vtrade sell <item> [qty] |
villageai.trade |
通过命令直接出售 |
/vquest list |
villageai.quest |
查看当前活跃的任务 |
/vquest accept <id> |
villageai.quest |
接受一个任务 |
权限
villageai.info: true # 所有玩家
villageai.trade: true # 所有玩家
villageai.quest: true # 所有玩家
villageai.admin: op # 仅限管理员
配置概览
config.yml 中的关键设置:
village:
check_radius: 64 # 敌对玩家检测半径(方块)
door_radius: 8 # 夜间/警戒状态的房门扫描半径
tick_interval: 40 # 村庄刻率(刻,默认 2 秒)
defense:
max_golems: 2 # 每村最大铁傀儡数量
alert_to_defense_delay: 10000 # 生成铁傀儡前的延迟(毫秒)
bell_sound_cooldown: 15000 # 摇铃间隔(毫秒)
reputation:
hostile_threshold: -30 # 低于此值将触发铁傀儡攻击
interact_reward: 2 # 右键点击村民获得的声望点数
damage_penalty: -25 # 攻击村民损失的声望点数
raid:
max_waves: 5
wave_interval_seconds: 60
reward_per_wave: 64 # 完成每波袭击获得的绿宝石数量
night:
enabled: true
close_doors_at_night: true
3.3.2 版本修复
本次发布解决了六个 Bug——完整详情请参阅 CHANGELOG.md:
- [严重]
TradeService.executeTrade()验证了交易但未转移物品 - [严重] 在交易 GUI 中快速双击可能导致重复消费(Double-spend)
- [中等] 在多世界服务器上
getNearestVillage()会因IllegalArgumentException崩溃 - [中等]
tradeHistory列表无限增长——在长期运行的服务器上导致内存泄漏 - [中等] 当 24 小时计时器触发且存在相同任务时,会生成重复任务
- [性能] 用 O(1) 反向查找映射替换了
onEntityDeath中的 O(n) 村庄扫描 - [性能] 用缓存的门列表替换了
closeAllDoors()中的区块扫描
数据存储
村庄数据以 YAML 格式保存至 plugins/VillageAI/villages/ 目录,每个村庄对应一个文件。
保存操作使用异步原子写入模式(写入 .tmp → 重命名为最终文件)进行,以防止崩溃导致的数据损坏。
每个文件旁都会保留前一次保存的 .bak 备份。
许可证
本插件按“原样”提供,仅供教育和服务器运营商使用。 未经作者许可,禁止重新分发或转售。
VillageAI Plugin
Version: 3.3.2
API: Paper 1.21 / Java 21
Author: Duong2012G
VillageAI transforms vanilla Minecraft villages into living, reactive communities. Villages defend themselves, manage their own supply-and-demand economy, issue quests, and dynamically react to player reputation — all without any external dependencies.
Features
| System | Description |
|---|---|
| State machine | Villages cycle through SAFE → ALERT → DEFENDING → NIGHT / RAID automatically |
| Spatial bell index | O(1) village lookups via ChunkCoord index — no full-scan on chunk events |
| Economy | Supply/demand pricing with per-player reputation multipliers (−50 % to +50 %) |
| Raids | Configurable multi-wave raids with mob variety and emerald rewards |
| Upgrades | WALL · WATCHTOWER · GRANARY · FORGE — each adds tangible gameplay effects |
| Quests | 24-hour DeliveryQuest cycle with deadlines; reward on villager interaction |
| Trade GUI | 54-slot chest GUI with live price display and discount/markup indicators |
| Villager names | Custom name tags per villager showing profession and health |
| Async storage | Atomic file save (write-temp → rename) with automatic backup |
Installation
- Ensure you are running Paper 1.21 (or a compatible fork) with Java 21.
- Drop
VillageAI-3.3.2.jarinto your server'splugins/folder. - Start (or restart) the server — do not use
/reload. - Configuration files are generated in
plugins/VillageAI/on first run.
Note: PlugMan hot-reload is not officially supported. Always use a full server restart when updating the plugin.
Building from Source
# Clone / unzip the source, then:
mvn clean package -DskipTests
# The shaded jar will be at:
target/VillageAI-3.3.2.jar
Requirements: Java 21, Maven 3.8+.
Commands
| Command | Permission | Description |
|---|---|---|
/villageai info |
villageai.info |
Show status of the nearest village |
/villageai list |
villageai.admin |
List all loaded villages |
/villageai reload |
villageai.admin |
Reload config (hot) |
/villageai debug |
villageai.admin |
Toggle debug output |
/villageai raid start |
villageai.admin |
Force-start a raid |
/villageai raid stop |
villageai.admin |
Force-stop a raid |
/vtrade |
villageai.trade |
Open trade GUI for the nearest village |
/vtrade buy <item> [qty] |
villageai.trade |
Buy directly via command |
/vtrade sell <item> [qty] |
villageai.trade |
Sell directly via command |
/vquest list |
villageai.quest |
View active quests |
/vquest accept <id> |
villageai.quest |
Accept a quest |
Permissions
villageai.info: true # All players
villageai.trade: true # All players
villageai.quest: true # All players
villageai.admin: op # Operators only
Configuration Overview
Key settings in config.yml:
village:
check_radius: 64 # Hostile-player detection radius (blocks)
door_radius: 8 # Door-scan radius for night/alert
tick_interval: 40 # Village tick rate (ticks, default 2 s)
defense:
max_golems: 2 # Max iron golems per village
alert_to_defense_delay: 10000 # ms before spawning golems
bell_sound_cooldown: 15000 # ms between bell rings
reputation:
hostile_threshold: -30 # Rep below this triggers golem targeting
interact_reward: 2 # Rep gained per villager right-click
damage_penalty: -25 # Rep lost per villager attack
raid:
max_waves: 5
wave_interval_seconds: 60
reward_per_wave: 64 # Emeralds per completed wave
night:
enabled: true
close_doors_at_night: true
Bug Fixes in 3.3.2
Six bugs were resolved in this release — see CHANGELOG.md for full details:
- [Critical]
TradeService.executeTrade()validated trades but never transferred items - [Critical] Double-spend possible via rapid double-click in Trade GUI
- [Medium]
getNearestVillage()crashed withIllegalArgumentExceptionon multi-world servers - [Medium]
tradeHistorylist grew without bound — memory leak on long-running servers - [Medium] Quest duplicates generated when 24-hour timer fired with identical quest active
- [Performance]
onEntityDeathO(n) village scan replaced with O(1) reverse-lookup map - [Performance]
closeAllDoors()block scan replaced with cached door list
Data Storage
Village data is saved to plugins/VillageAI/villages/ as YAML, one file per village.
Saves are performed asynchronously using an atomic write pattern (write to .tmp →
rename to final file) to prevent data corruption on crash. A .bak backup of the
previous save is kept alongside each file.
License
This plugin is provided as-is for educational and server-operator use.
Redistribution or resale without permission from the author is not permitted.
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VillageAI
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
[3.3.2] — 2025-06-01
Bug Fixes
? 严重 — TradeService 未转移物品 (TradeService.java)
executeTrade() 正确验证了玩家的库存,但从未实际移除物品或给予绿宝石。任何仅依赖 TradeService.executeTrade() 的代码路径都会通过验证并在后端更新供需,而玩家的库存完全不受影响——这实际上等同于免费交易。修复方案将所有物品交换逻辑(removeItems、giveEmeralds、giveItems)移入 executeTrade() 内部,使得无论调用位置如何,操作都是原子且一致的。
? 严重 — 在交易 GUI 中快速双击导致双重消费 (TradeGui.java)
玩家可以在 buildGui() 完成重建库存之前两次点击同一个报价槽位,导致 executeTrade() 对同一报价执行两次。这使得每次点击对都会扣除两倍的物品并奖励两倍的绿宝石。修复方法是添加一个基于静态 ConcurrentHashMap 的 processingTrade 集合,作为每个玩家的互斥锁:在第一个事务完成并在 finally 块中释放锁之前,第二次点击将无效。
? 中等 — 跨世界距离检查时出现 IllegalArgumentException (VillageManager.java)
getNearestVillage() 在查询位置和每个村庄中心之间调用 Location.distanceSquared(),但未检查两个位置是否共享同一个世界。在多世界服务器(下界、末地、自定义维度)上,这会抛出 IllegalArgumentException: Cannot measure distance between worlds X and Y,导致非主世界维度的玩家触发最近村庄查找时每次都产生堆栈跟踪。修复方法是在距离调用前添加显式的 World.equals() 守卫。此外,还添加了 512 块的软上限,以防止该方法返回数千格之外的村庄。
? 中等 — 无限制的 tradeHistory 内存泄漏 (VillageEconomy.java)
tradeHistory(CopyOnWriteArrayList)在每次交易时都会被追加,但从未被修剪或在重启间持久化。在运行数周而未重启的高负载服务器上,此列表会无限增长并浪费堆空间。修复方法是将列表限制为 MAX_HISTORY_SIZE = 500 个条目;随着新条目的添加,旧条目会被移除(先进先出)。
? 中等 — 24 小时生成刻钟任务重复 (Village.java)
generateNewQuests() 使用新生成的列表调用 activeQuests.addAll(),但未检查是否存在具有相同标题的现有任务。如果 24 小时计时器触发时相同的任务仍处于活动状态,则该任务会在村庄的活动列表中重复出现。修复方法是将现有的活动标题收集到 Set<String> 中,并在插入前过滤新列表。
? 性能 — 突袭期间每次实体死亡时进行 O(n) 村庄扫描 (VillageListener.java, RaidManager.java)
onEntityDeath() 遍历所有村庄,调用 isRaiding(),获取会话,然后在 spawnedMobs 上执行 Set.contains() —— 这在热事件处理器中是 O(村庄数 × 生物数)。修复方法是在 RaidManager 中添加一个 mobToSession 反向查找映射(ConcurrentHashMap<UUID, RaidSession>)。该映射在生物生成时填充,并在生物死亡或突袭取消时清理。onEntityDeath() 现在通过单次映射查找以 O(1) 解析所属会话。
? 性能 — closeAllDoors() 每晚重新扫描多达 4913 个方块 (Village.java)
夜间关门路径在世界时钟跨过 12300 刻时,始终围绕村庄中心扫描一个 (2r+1)³ 的方块立方体。现在它重用 cachedDoorLocations,即与 stage1() 保持温暖的相同缓存(10 秒 TTL)。如果缓存在前几个夜晚非常冷(在任何警报触发之前),该方法会内联填充它,使后续的夜晚循环从 O(r³) 变为 O(门数量)。
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
插件
使床在所有维度中爆炸的模组
插件
为 Armor Poser 模组添加兼容性
插件
SkyBlock、OneBlock、Boxed、SkyGrid、AcidIsland、CaveBlock、Poseidon、StrangerRealms——以及更多!这些只是由 BentoBox 支持的基于岛屿的游戏模式之一。来自原版 ASkyBlock 的作者。
评论 0
登录后参与评分
还没有评论,来抢沙发吧