村庄守卫者

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

村庄守卫者是一个 Fabric 项目，它让普通村民能够作为一个协调一致的聚落对危险做出响应。它不会让每个村民都永久性地带有攻击性，而是评估每次事件，并在需要时激活临时的防御职责。

一小群可控的敌对生物可能只会惊动附近的守卫者。更大规模的群体、正在进行的袭击、压倒性的威胁，或玩家攻击村民，都可能导致整个聚落动员起来，将平民转移到安全地带，与铁傀儡协调行动，并最终开始有序的恢复。

其目标是保留玩家熟悉的《我的世界》村庄体验，同时让紧急情况更加可见、结构化和可信。

动态村庄防御

每个聚落都会经历一个分阶段的防御系统：

正常： 村民继续普通的村庄生活。监控以较低的频率运行，且每天早晨可能会有数量有限的盔甲匠巡逻队前往已登记的哨塔。
本地警戒： 已检测到可能的或有限的威胁。附近的村民会变得警觉，但不会立即扰乱整个聚落。
本地小规模冲突： 符合条件的防御者会处理村庄当前防御能力认为可控的威胁。
全面防御： 聚落动员所有防御者，激活平民和儿童保护，协调铁傀儡，并使用已登记的防御基础设施。
撤退： 如果威胁大幅超出可用防御能力，村民会停止不安全的追击，并在避难所或铁傀儡支援附近重新集结。
恢复： 在危险持续消失一段可配置的冷却时间后，村庄会尝试归还装备、进行批准的修复、清理，并恢复正常生活。

威胁升级是基于上下文的。威胁规模、距离、生命值、装备、符合条件的防御者、处于危险中的儿童、附近的铁傀儡、袭击和玩家攻击行为都会影响响应方式。附近的一只僵尸不会自动把整个村庄变成一支军队。

决策模型还包含一个用于兼容扩展的“遏制失败”升级信号。当前的內建运行时主要通过袭击状态、已确认的攻击以及威胁与能力的评分来进行升级。

威胁检测与升级

村庄守卫者会对以下几种已验证的威胁来源做出响应：

直接攻击村民的行为；
正在进行的袭击；
对村民造成伤害的袭击参与者；
附近的原版敌对生物和袭击者；
综合评分超过村庄能力的较大敌对群体；
添加到 defensivemod:aggressors 标签中的兼容实体；
通过单独的数据标签识别的高威胁实体；
通过村民身份兼容 API 提交的本地遇险事件；
可用防御者生命值、装备和铁傀儡支援的变化；
直接攻击村民的玩家。

内置的侵略者数据涵盖了常见威胁，例如僵尸、骷髅、女巫、掠夺者、卫道士、唤魔者、劫掠兽和恼鬼。数据包可以扩展侵略者、高威胁、忽略和同盟实体的标签。

玩家攻击行为

攻击村民的玩家被视为极端威胁，可以立即迫使受影响的聚落进入全面防御状态。

敌对状态与具体攻击玩家的 UUID 绑定。附近和平的玩家不会自动被计入敌对玩家名单。在遭遇不再邻近后，敌对状态会在一个可配置的冷却时间后过期。

基于职业的防御者

村庄守卫者使用现有的职业，并且不会添加永久的守卫职业。

默认的职能映射为：

盔甲匠 — 保护者： 优先使用盾牌、防御武器、哨塔、入口和受保护的位置。
武器匠 — 近战防御者： 使用可用的已标记武器与指定的侵略者交战。
牧师 — 支援者： 保持在 frontline 防御者附近，并可以消耗真实的支援物资来协助受伤的防御者。

只有生命值高于设定阈值的在世成年村民才符合条件。儿童绝不会获得战斗角色。战斗指派是临时的，不会取代职业、交易或工作站。

职能映射是可配置的。额外的职业可以被指派为已实现的角色，例如远程或后备防御，但默认情况下并未启用。

防御装备

军械架提供了一个实体 27 格存储空间，用于存放村庄防御装备。

在紧急情况下，符合条件的村民可以借用：

已标记的剑、斧或三叉戟；
盾牌；
为已配置的远程角色准备的弓或弩。

每叠被借出的物品都会从架子上物理移除，并获得一个唯一的预留标识符。架子会记录村民、原始槽位、物品和借用时间。只有匹配的实体物品堆才能完成该次归还。

在恢复期间，村民会尝试归还借用的物品。丢失或遗失的装备会被记录，而不会被重新生成。破坏军械架会掉落其剩余库存，但不会复制目前存放在别处的装备。

当启用实体弹药时，远程防御者会消耗已标记的箭矢。牧师支援行动同样会消耗真实的已标记物资，如面包、药水、喷溅药水或金苹果。村庄守卫者不会生成无限的弹药、治疗物资、武器或盔甲。

不包含任何自定义武器或盔甲等级。

平民安全与避难

没有防御任务的村民会在本地小规模冲突或全面村庄防御期间寻求安全。

当前的避难顺序为：

由村民身份提供的自有房屋；
最近的已登记避难所标记，且具有可用容量且没有明显的侵略者冲突；
村民的原版房屋记忆或指定的床；
聚落锚点作为紧急后备。

避难所标记的容量是可配置的。聚落在每次避难分配过程中会跟踪占用情况，以确保一个标记不会被分配超过其配置的容量。

路线安全检查会拒绝那些附近有侵略者似乎挡在村民和目的地之间的目的地。最终移动通过一个可选的村民 AI 适配器或原版寻路后备来执行，因此复杂地形仍可能影响实际路线成功与否。

监护人与儿童保护

儿童始终是平民，绝不会获得武器或防御者角色。

在紧急情况下，儿童会按以下顺序尝试寻求保护：

由村民身份提供的已知监护人；
由村民身份提供的可信赖成年人；
最近的可用的、未被指派为防御者的成年人；
在没有成年人后备时，寻找有效的避难所。

当选择了一个成年人时，儿童会向该成年人移动，而成年人则会引导这对组合前往共同的避难目的地。监护人和护送姿势使紧急响应可见，但该项目并未实现字面意义上的同步牵手。

如果没有村民身份，附近的成年人和避难所后备仍然可用。

铁傀儡协调

铁傀儡仍然是村庄防御的核心部分，而不会被取代。

附近存活的铁傀儡会为村庄的预估防御能力做出贡献，并可以将最近的已确认侵略者作为目标。在撤退期间，村民更倾向于在附近可用的铁傀儡附近重新集结；如果没有可用的铁傀儡，他们会向避难所或聚落后备位置撤退。

当前运行时的铁傀儡选择是基于邻近度的。它不保证每个附近的铁傀儡都能穿越复杂地形，因此原版寻路和可选的村民 AI 路线处理仍然很重要。

防御性村庄方块与工具

村庄守卫者添加了四个可合成、本地化的面向玩家的内容。

哨塔

哨塔在其所属聚落内登记一个防御位置。

保护者可以守在最近的哨塔附近，而不是追击远离该位置的侵略者。在正常的村庄生活中，一小部分可配置的、醒着的成年盔甲匠可能会在早晨对已登记的哨塔进行有限的巡逻。

使用该方块会显示其基础设施类型、聚落状态和聚落标识符。

避难所标记

避难所标记为平民、监护人和儿童登记一个紧急目的地。

每个标记使用已配置的避难所容量，并与自有房屋和原版房屋一同被考虑。使用它会显示相关的聚落信息。

军械架

军械架是一个 27 格容器，用于存放防御武器、盾牌、远程装备、弹药、支援物资和修理材料。

它管理实体装备的借出，并在存档中保留库存和活动借出记录。

防御分类账

防御分类账会为最近的聚落打开一个只读的聚落摘要。

它显示：

当前状态和转换原因；
活跃的侵略者和敌对玩家数量；
已指派的防御者数量；
已登记的哨塔、避难所标记和军械架；
附近的傀儡数量；
未解决的修理事项；
聚落扫描和路径请求统计。

如果客户端无法接收自定义的分类账数据包，则会使用一个精简的聊天摘要代替。

巡逻与守卫位置

已登记的哨塔会影响积极防御期间保护者的位置。

在正常状态下，盔甲匠在《我的世界》白天开始时也存在一项有限的巡逻。巡逻规模是可配置的，默认情况下每个聚落不超过两个村民。儿童和熟睡的村民不包括在内。

这有意地是一个小型的防御例行程序，而不是一支永久的武装巡逻军队、军事编队系统，或对普通村庄日程的替代。

危险记忆与恢复

直接攻击和兼容的本地遇险事件会创建有界的事件记录，其中包含侵略者、类型、大致位置、事件时间、严重程度、受害者数量和结果原因。

危险记忆：

按聚落存储；
在存档间持久化；
默认限制为 64 条；
默认在 6,000 tick 后过期。

当前的事件记录提供了持久的突发事件历史，但尚未作为永久危险区域反馈到未来的威胁评分中。

在威胁消失后，村民不会立即恢复正常。必须经过一个可配置的解除警报冷却时间才能开始恢复。恢复过程会尝试：

停止临时的战斗目标；
归还借用的装备；
将长时间丢失的装备标记为遗失，而不是复制它；
处理已批准的修理记录；
清除临时防御指派；
让聚落恢复正常行为。

已批准的修理

村庄守卫者不允许村民自由建造建筑物或防御工事。

在活跃危险期间，对已批准的标记方块进行的更改可以被记录下来以供后续恢复。恢复修理仅在以下情况全部满足时才会进行：

修理已启用；
mobGriefing 游戏规则允许；
原始方块类型在可修理方块标签中；
该方块未被记录为玩家发起的破坏；
目标仍然与观察到的损坏状态匹配；
所需的替换物品存在于某个军械架中。

工具匠是修理工作的首选，另一个在世的成年人作为后备。修理工作是有限度的，如果目标被玩家或其他项目更改，则中止而非覆盖。

此系统会恢复已批准的损坏；它不会重新设计村庄或建造新的防御工事。

动画、声音与呈现

村庄守卫者包含一个同步的防御姿势系统。

在积极姿势期间，客户端会用独立的左臂和右臂替换通常组合在一起的村民手臂，并渲染村民实际手持的物品。已实现的呈现涵盖多种情况，例如：

警戒和守卫姿态；
盾牌就绪和近战就绪姿势；
近战攻击；
弓和弩的瞄准或射击；
远程重新定位和撤退；
儿童危险和监护人护送；
进入避难所；
撤退和铁傀儡重新集结；
支援行动；
装备归还；
损坏检查和修理。

动画具有服务器选择的优先级和持续时间，而渲染仍在客户端进行。远处的村民使用减少的动作。

状态变化使用克制的原版音效和粒子效果，包括村民反应、类似钟声的全面防御提示、愤怒村民的警报粒子、支援爱心以及开心村民的解除警报粒子。由于这些是原版音效事件，它们现有的字幕仍然可用。目前不包含任何自定义音效文件。

独立手臂渲染器目前使用村民基础纹理。这些自定义手臂上的职业服装覆盖仍需最终的视觉确认。

配置

村庄守卫者会创建：

config/defensivemod.json

配置由服务器拥有、验证，并可通过操作员命令重新加载。不安全或格式错误的配置会回退到安全默认值并发出警告。有效的重新加载会调整现有的聚落，同时保留其当前状态和仍然有效的记忆。

重要的可配置区域包括：

本地警戒和全面防御阈值；
玩家和袭击威胁值；
儿童风险贡献；
防御者生命值和撤退阈值；
傀儡能力；
解除警报冷却时间；
危险记忆的生命周期和大小；
聚落、监护人和傀儡搜索半径；
追击边界；
正常和活跃扫描间隔；
聚落和实体处理预算；
敌对玩家冷却时间；
避难所标记容量；
巡逻限制；
职业到角色的映射；
远程距离、冷却时间和实体弹药；
支援冷却时间和治疗量；
已批准修理的启用；
身份、村民 AI 和村民类型的集成开关；
原版寻路后备。

实体、物品和修理的资格也可以通过数据包标签来扩展。

当前配置中存在一个 debugLogging 字段，但它是保留字段，尚未作为完整的日志控制系统的替代品。

命令与调试

以下命令注册在 /defensivemod 下。

玩家可读的诊断信息：

/defensivemod status
/defensivemod aggressors
/defensivemod assignments
/defensivemod performance

这些命令报告最近聚落的状态、转换原因、活跃的侵略者、敌对玩家、临时角色指派、扫描计数、已分类实体计数和路径请求。

需要权限等级 2 的操作员命令：

/defensivemod validate
/defensivemod reload
/defensivemod force_full
/defensivemod clear

validate 报告已登记的基础设施和敌对玩家记录。reload 验证并重新应用配置。force_full 和 clear 提供明确的管理状态控制。

目前没有专门的命令来模拟警报、检查单个装备预留或单独列出避难所。

兼容性

配套项目是可选的，并作为建议而非必需依赖列出。村庄守卫者使用一个显式的版本化适配器 API，并且不会尝试通过反射加载猜测的配套类。

仅安装一个配套项目本身是不够的，除非该项目注册了相应的村庄守卫者适配器。

村民 AI

村民 AI 负责常规的导航可靠性、恐慌安全移动、卡住恢复和路线纠正。

已注册的导航适配器可以接收以下防御移动请求：

接敌和远程定位；
哨塔防御；
监护人和儿童移动；
进入避难所；
傀儡重新集结；
撤退；
巡逻；
军械架和修理目的地；
恢复正常。

适配器会报告路线是已被接受、完成、失败、不可达还是未处理。当配置时，失败或未处理的请求会回退到原版寻路。

村庄守卫者不接管防御情况之外的常规导航恢复。

村民身份

村民身份负责个性、个人信任、对话、礼物、家园、家庭关系、监护人关系以及本地社会背景。

通过一个已注册的身份适配器，村庄守卫者目前可以消费：

本地遇险信号；
儿童的已知监护人；
可信赖成年人后备标识符；
自有房屋位置；
防御生命周期回调。

村庄守卫者目前不会通过此适配器读取任意的玩家信任分数。村民身份可以决定关系并发起本地警报，但村庄守卫者会决定该事件是成为本地响应、全面防御还是撤退。

村民身份不会让村民发起攻击。

村民类型

村民类型负责自定义村民类型、家园或文化元数据，以及生物群系主题的村庄生成。

兼容 API 可以暴露村民类型和文化标识符，但当前的第一个测试版行为不会使用它们来创建特定生物群系的军队、编队或战术。

村庄守卫者不会生成自定义村庄，也不拥有文化身份。

独立运行

村庄守卫者可以在没有配套适配器的情况下工作。

独立后备包括：

原版村民房屋记忆；
已登记的避难所标记；
附近成年人监护人后备；
原版寻路；
原版职业和实体分类。

缺少配套项目不会阻止启动。

多人游戏与服务器支持

防御决策、持久化聚落状态、装备借出、敌对玩家记录、修理和命令均由逻辑服务器控制。

客户端只接收只读的分类账快照和临时动画数据包。没有任何客户端数据包可以指派角色、标记侵略者、创建装备、修复方块或强制状态转换。

聚落状态按维度单独持久化，并支持多个聚落记录。动画状态会发送给正在跟踪相关村民的玩家，并在村民被处理时定期重新发送。

代码将客户端渲染与通用服务器行为分离，并为多人游戏和专用服务器使用而构建。然而，当前的开发文档在进行发布签核之前，仍需要手动的专用服务器、双客户端同步以及晚加入验收测试。

性能

村庄守卫者以聚落级工作为设计目标，而不是让每个村民都进行独立的广泛敌对扫描。

当前实现包括：

每个被处理的聚落进行一次共享的有界扫描；
每个世界 tick 默认最多处理四个聚落；
每次聚落扫描默认最多 64 个已分类实体；
80-tick 的正常扫描和 10-tick 的活跃扫描；
受到袭击的聚落优先于普通聚落被处理；
已加载实体的查询，不有意强制加载区块；
有界的危险记忆和转换历史；
错开的重复战斗路径请求；
目标分配以减少不必要的堆叠；
有限的巡逻和修理工作；
对重复攻击的事件去重；
在变化或定期刷新时发送动画数据包；
精确的装备预留，避免重复操作。

防御分类账和 /defensivemod performance 命令会暴露扫描和路径请求统计信息。

村庄守卫者旨在对活跃的村庄和多人游戏服务器保持实用性，尽管性能可能因聚落大小、地形、实体数量、寻路负载和其他已安装项目而有所不同。拥挤村庄的性能分析仍是文档化的发布前验收工作的一部分。

该项目不添加的内容

村庄守卫者不包括：

永久的守卫职业；
自定义武器或盔甲等级；
防御号角；
防御城镇进程；
特定生物群系的军事系统；
特定文化的编队或战术；
大型村民魔法系统；
村民建造的防御工事；
攻城器械；
狩猎系统；
字面意义上的同步监护人与儿童牵手。

它也不是：

一个聊天机器人系统；
一个个性、信任、对话或礼物项目；
一个自定义村庄生成项目；
一个全面导航改造项目；
一个对原版村庄逻辑的完全替代。

当前状态与限制

当前项目版本为 1.0.0，在更新日志中记录为开发中。

当前仓库拥有：

10 个测试套件中 29 个通过的自动化测试；
一次成功的干净 Fabric 构建；
一次成功的 Fabric 客户端/数据生成启动检查；
针对威胁升级、撤退稳定性、持久化、装备预留、避难选择、修理和状态转换的回归覆盖。

重要的剩余限制：

完整的专用服务器和多客户端验收测试仍然待定；
晚加入动画同步仍需手动验证；
独立防御手臂需要与生物群系和职业服装进行视觉审查；
复杂地形可能会影响原版防御移动；
附近傀儡的选择目前基于邻近度，而非完整的缓存可达性分析；
重度修改的袭击或敌对实体可能需要数据包标签或兼容适配器；
配套项目必须注册所提供的 API 适配器才能激活集成；
与大幅替换村民渲染、战斗、大脑行为或导航的项目可能兼容性不佳；
拥挤聚落的性能分析仍不完整；
平衡数值可能会通过持续的游戏测试和反馈而演变。

问题报告

请在问题报告中包含以下内容：

村庄守卫者版本；
Minecraft 版本；
Fabric Loader 版本；
Fabric API 版本；
完整的日志和崩溃报告；
相关的 defensivemod.json 配置；
世界种子；
维度和坐标；
聚落状态和转换原因（如有）；
已安装的项目列表；
修改侵略者或装备标签的数据包；
清晰的重现步骤。

/defensivemod status、/defensivemod aggressors、/defensivemod assignments 和 /defensivemod performance 的输出对于诊断聚落行为尤其有用。

村民不应成为永久的士兵，但当他们的聚落受到威胁时，他们应该有能力互相保护。

村庄守卫者