村民部署
通过标记方块或 Java 部署轻量服务村民。
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;公会接待员处理流程也包含此处理器。结构放置时启用标记并移除复制的实体身份。方块朝向随结构旋转,镜像使朝向偏移取反。
| 保存字段 | 类型 | 默认值 | 契约 |
|---|---|---|---|
Deployment | NBT compound | 构建器默认值 | 以下设置;显式提供时,职业和外观须为有效标识符。 |
Deployment.Profession | identifier string | 构建器为 minecraft:librarian | 部署前须能在村民职业注册表解析。 |
Deployment.Appearance | identifier string | 构建器为 minecraft:plains | 须能在村民类型注册表解析。 |
Deployment.WanderRadius | integer | 0 | 0–32 格;零表示返回驻点。 |
Deployment.RestockTicks | integer | 12000 | 0–1000000 ticks;零禁用自动补货。 |
Deployment.Protected | boolean | 构建器为 true | 无敌及防碰撞推动。 |
YawOffset | float | 0 | 相对方块朝向的有限角度,自动归一;无效存档值变为零。 |
Enabled | boolean | false | 启用部署与归属检查。 |
Resident | UUID | 无 | 运行时实体身份,不应手写。 |
Origin | packed block-position long | 保存时的当前位置 | 检测复制的标记并清除实体身份。 |
Dimension | string | 空 | 运行时维度检查字段。 |
显式 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 的结果。这是新放置时的初始化规则,不是加载区块时重新生成居民。