Kzeroko KTM2

村民部署

通过标记方块或 Java 部署轻量服务村民。

更新于 2026/10/25 4 分钟阅读

VillagerAPI 部署带有轻量驻点控制器的原版村民衍生商人。它复用现有村民对话和交易集成,不运行村庄日程、POI 感知、闲话、袭击或繁殖 AI。

入口

使用 net.kzeroko.isekaiexpansion.api.VillagerAPI。返回的部署设置和常驻实体属于内部实现类型。实体 ID 为 isekaiexpansion:resident_villager;创作方块与物品 ID 为 isekaiexpansion:villager_anchor。

常见用法

生成驻点商人

var settings = VillagerAPI.deployment()
        .profession(new Identifier("minecraft", "cleric"))
        .appearance(new Identifier("minecraft", "plains"))
        .wander(0).restockEvery(12000).protectedNpc(true).build();
var resident = VillagerAPI.spawn(world, position, settings, 90);

world 必须是服务端世界,position 为方块位置。返回 null 表示注册表设置、朝向、区块加载、世界边界、方块碰撞或实体插入检查未通过。直接部署无需标记方块。

随地标放置商人

通过 /ise dev npc villagerMarker 获取标记方块。创造模式管理员可打开编辑器,设置职业、外观、游走半径、补货间隔、朝向偏移及启用和保护状态。手动新放置的标记默认禁用。将配置后的标记保存在结构内,并使用处理器列表 isekaiexpansion:villager_anchors;公会接待员处理流程也包含此处理器。结构放置时启用标记并移除复制的实体身份。方块朝向随结构旋转,镜像使朝向偏移取反。

保存字段类型默认值契约
DeploymentNBT compound构建器默认值以下设置;显式提供时,职业和外观须为有效标识符。
Deployment.Professionidentifier string构建器为 minecraft:librarian部署前须能在村民职业注册表解析。
Deployment.Appearanceidentifier string构建器为 minecraft:plains须能在村民类型注册表解析。
Deployment.WanderRadiusinteger00–32 格;零表示返回驻点。
Deployment.RestockTicksinteger120000–1000000 ticks;零禁用自动补货。
Deployment.Protectedboolean构建器为 true无敌及防碰撞推动。
YawOffsetfloat0相对方块朝向的有限角度,自动归一;无效存档值变为零。
Enabledbooleanfalse启用部署与归属检查。
ResidentUUID无运行时实体身份,不应手写。
Originpacked block-position long保存时的当前位置检测复制的标记并清除实体身份。
Dimensionstring空运行时维度检查字段。

显式 Deployment compound 内缺失的数字和布尔字段读取为零或 false。请用构建器或编辑器生成完整数据。无效标识符语法和越界数值会拒绝设置;未知注册表 ID 阻止部署。

方法一览

方法侧契约
VillagerAPI.deployment()公共创建设置构建器。
profession, appearance构建器注册表 ID;生成前检查是否存在。
wander, restockEvery, protectedNpc构建器边界和行为见上表。
VillagerAPI.spawn(world, pos, settings, yaw)服务端线程生成并配置常驻村民,失败返回 null。

线程与生命周期

生成及标记编辑在服务端线程执行。标记每 40 ticks 检查部署,按位置错开。已保存的 UUID 在区块卸载期间保留名额,不会因实体暂未加载而重复生成。破坏性移除释放名额。已加载的村民每 20 ticks 检查标记归属;标记消失或禁用后移除实体。

常驻村民保留职业等级 5 的原版商人数据,改变职业会重置交易。对话或交易期间停止导航并延后补货;每 40–79 ticks 在已加载地形内选择移动目标。不运行大脑感知或任务循环,普通导航和注视控制仍会更新。雷击转化、繁殖、拾取及维度传送均禁用。

空闲村民会持续注视 6 格内可见的玩家。每 10 ticks(0.5 秒)搜索目标并检查视线,已有目标的注视则每 tick 更新,不受移动规划间隔影响。目标死亡、进入旁观模式、离开范围或离开当前世界后结束注视;对话和交易对象优先。

原生 landmark/编辑器的新部署与 VillagerAnchorProcessor 共用初始化规则:启用驻点,移除来源 Resident、Origin 和 Dimension,保留职业、外观、补货、保护、游走半径及偏航量。不可变的前哨站捕获文件含有 17 个停用驻点;运行时检查逐一通过真实 proto-chunk 放置,并对照普通结构 processor 的结果。这是新放置时的初始化规则,不是加载区块时重新生成居民。

相关内容