Kzeroko KTM2

独特 NPC 部署

部署具名角色,并通过实时设置调整部署行为,保留角色自身逻辑。

更新于 2026/10/29 11 分钟阅读

独特 NPC 锚点仅部署一次角色,后续显式编辑通过已有 NPC setter 生效。UniqueNpcDeployment、UniqueNpcDeploymentIndex与UniqueNpcAnchorBlockEntity均为内部实现,不是公共门面。

它做什么

使用/ise dev npc uniqueMarker获取isekaiexpansion:unique_npc_anchor,创造模式且具有二级权限的管理员可打开编辑器。可选择isekaiexpansion:mahoutsukai_evelina或isekaiexpansion:goddess_selene、已有服装、默认行为、家园策略、可选城市住所与职务路线、朝向偏移,以及闲置朝向偏好。新放置的锚点默认禁用。开发者标记的箭头指向方块朝向加偏移,启用闲置朝向时还会显示范围弧线;保存后会将显示设置同步给客户端。

角色类仍负责预设、性别、外观基础、战斗配置、性格、对话及关系。编辑器不接受任意实体 NBT 或替换预设。普通生成的 NPC 不会绑定锚点。

运行时模型

启用且尚未成功部署的锚点每40 ticks(2秒)重试一次,按位置错峰。生成调用NpcSpawningUtil,依次创建、初始化、配置、分配家园与行为,再加入世界。服装不存在、区块未加载、越界、方块碰撞或实体加入失败均阻止部署。

锚点保存部署成功标记与绑定令牌。UniqueNpcDeploymentBinding将令牌、岗位位置、岗位模式、原始家园及闲置朝向写入实体 NBT 和复活快照。UniqueNpcDeploymentState把有效令牌保存到data/isekaiexpansion/npc/deployments_v1.dat,撤销时直接删除令牌。ServerEntityEvents仅为已绑定的独特 NPC 建立索引,已撤销的实体再次加载时会被移除;卸载及服务器停止时清理引用。复活后的实体 UUID 可以变化,实时编辑仍按令牌找到角色。同一令牌对应多个已加载实体时,查找失败,不会随意选择。

锚点 tick 刷新岗位设置和朝向元数据,不移动已有角色,也不覆盖重新指定的家园。保持启用时,卸载或死亡不会释放名额,死亡仍走正常复活流程。禁用或破坏锚点会撤销令牌、移除所有维度内已加载的绑定 NPC,并删除该部署的待复活墓碑。未加载的实体在下次加载时移除,服务器重启或锚点区块未加载都不会恢复它。撤销不会触发死亡掉落或生成墓碑。重新启用会使用新名额部署新 NPC,旧实体不能重新占用。不同锚点仍各自独立。

NpcStayTask先按原有规则搜索注视目标,仅在没有目标且大脑中也没有其他LOOK_TARGET记忆时补充闲置朝向。现有移动条件会排除对话、动作表演、休息、战斗及STAY以外的模式;朝向控制器还会避开寻路、移动、骑乘与飞行。每40–100 ticks(2–5秒)在配置范围内选择方向,通过原有视线和移动控制逐渐转向。附近可见的玩家或 NPC 优先。普通生成的NPC继续使用原有行为。实体将UniqueNpcIdleLook.Facing与锚点归属分开保存:修改部署绑定会更新这一偏好,而会话拥有的剧情演员可直接设置,无需登记部署令牌。两种来源均通过tickIdleLook使用同一控制器。

约定

保存要求创造模式管理员权限、目标方块已加载且可编辑、位于世界边界内,距离不超过8格。实时修改已启用的部署要求绑定 NPC 存活且已在同一维度加载,禁用操作无需 NPC 已加载。部署有效期间不能切换角色类型,需先禁用再选择其他角色。无效请求不会修改锚点设置。

只应用发生变化的字段。修改城市引用不会恢复原始服装或家园。修改行为会更新默认模式;没有有效跟随分配时,还会修改当前模式及锚点驻留位置。有效 FOLLOW 与等待中的 STAY 分配保留所属玩家、位置及此前记录的返回模式。朝向编辑只更新闲置偏好,不会立即强转角色或打断 FOLLOW。实时编辑不会传送角色、停止大脑、重置情绪、修改物品栏,或改变婚姻与好感状态。

保存字段类型默认值契约
Deploymentcompound编辑器默认值已保存设置缺失或无效时禁用部署;额外未知字段被忽略。
Deployment.Characteridentifier编辑器中为isekaiexpansion:mahoutsukai_evelinaNBT 中必填,必须为上述两个角色 ID 之一。
Deployment.Outfitstring编辑器中为default必填,非空,最多64字符;生成或编辑前必须存在于角色衣柜中。
Deployment.Modestring编辑器中为WANDER_BY_RADIUS必填:STAY、WANDER、WANDER_BY_RADIUS;拒绝FOLLOW。游荡半径仍由角色配置决定。
Deployment.Homestring编辑器中为NEAREST_BED必填:NEAREST_BED、ANCHOR、NONE。寻床范围为16格;找不到空床时不设置家园。
Deployment.IdleFacingboolean编辑器中为falseNBT 中必填;仅在闲置驻留时启用偏好朝向。
Deployment.IdleYawRangefloat编辑器中为30必填,中心每侧0–180度,必须有限。零表示固定偏好方向;越界或非有限值会拒绝设置。
Deployment.EncounteridentifierAbsent可选个人剧情会面 ID;非法标识符拒绝设置,缺省时不添加会面路由。
Deployment.CityBindingcompound不存在可选住所及职务引用;无效复合标签会拒绝设置。
Deployment.CityBinding.Cityidentifier存在时必填城市 ID,由已有城市运行时解析。
Deployment.CityBinding.Residencestring存在时必填转为小写的局部 ID,1–96字符;允许字母、数字、下划线、连字符、点和斜杠。
Deployment.CityBinding.Routestring不存在可选局部 ID,规则相同;空白视为不存在。
YawOffsetfloat0相对方块朝向的有限角度,保存时归一化;读取到非有限值时使用零。
Enabledbooleanfalse启用初次部署重试;禁用会撤销并移除绑定 NPC。
Deployedbooleanfalse运行时成功记录;死亡及卸载后保留。
BindingUUID新令牌连接绑定 NPC 的运行时令牌,与当前实体 UUID 无关;撤销时更换。
Originlong保存时的当前位置编码复制到其他位置会重置成功记录与绑定。
Dimensionstring空维度改变会重置成功记录与绑定。

将锚点保存进结构后,使用处理器列表isekaiexpansion:unique_npc_anchors。其中的isekaiexpansion:unique_npc_anchor_processor启用锚点、移除复制的运行时身份,并在镜像放置时反转朝向偏移。旋转由方块朝向处理。保存结构时不要包含已经部署的 NPC。

以下实体及世界状态字段属于运行时存档,不是制作配置。实体绑定字段缺失或无效时视为没有绑定。部署设置要求当前格式的全部必填字段,不提供旧命令标签读取或迁移路径。

NBT 键类型默认值含义
DeploymentBindingcompound不存在按需写入实体的部署绑定,也进入复活快照。
DeploymentBinding.TokenUUID绑定时必填实体加载时必须仍存在于有效令牌记录中。
DeploymentBinding.Yawfloat绑定时必填归一化后的世界绝对朝向,单位为度,必须有限。
DeploymentBinding.IdleFacingboolean绑定时必填是否启用闲置朝向。
DeploymentBinding.YawRangefloat绑定时必填每侧0–180度,必须有限。
DeploymentBinding.DutyAnchorcompound绑定时必填部署维度与位置;编码数据无效则拒绝绑定。
DeploymentBinding.DutyAnchor.dimensionidentifier必填世界注册键。
DeploymentBinding.DutyAnchor.posint array必填恰好 3 个方块坐标:X、Y、Z。
DeploymentBinding.DutyModestring绑定时必填STAY、WANDER 或 WANDER_BY_RADIUS;其他值拒绝绑定。
DeploymentBinding.AssignedHomecompound不存在部署时指定的家园;与当前家园相等时允许返回岗位。与 DutyAnchor 使用相同的 dimension 和 pos 字段;数据无效则拒绝绑定。
Activelist<compound>空世界中仍有效的部署记录。
Active[].TokenUUID每项必填缺少 UUID 的项被忽略,重复令牌合并为一个。

扩展

UniqueNpcDeployment.CHARACTERS是显式角色目录。将具体的UniqueNpcEntity类型加入目录,即可在编辑器中选择。预设与NpcConfig仍保留在角色类中。

var settings = new UniqueNpcDeployment(characterId, "default",
        BaseNpcEntity.NpcMode.WANDER_BY_RADIUS,
        UniqueNpcDeployment.Home.NEAREST_BED, null, false, 30, null);
var spawned = settings.spawn(world, position, 90);

在服务器线程调用。直接使用不会绑定锚点或启用部署朝向。接收配置 consumer 的重载在实体加入世界前调用钩子;锚点先登记有效令牌,再通过钩子写入类型明确的绑定。加入世界失败会释放令牌。NpcSpawningUtil.SpawnBuilder.outfit(id)同样按需启用,并拒绝未知服装;未调用它的 builder 保持原有流程。

居民跟随期间保留部署身份。游荡命令让其返回保存的岗位位置与确切模式,没有家园的部署也可返回。部署后修改的家园优先;等待区块加载时会重新解析最新目的地。绑定存档必须包含 DutyAnchor 和 DutyMode,缺少字段直接拒绝,不提供兼容读取或迁移。见 NPC 跟随者。

验证

运行./gradlew.bat compileJava。使用./gradlew.bat -I tools/npc/verify.gradle checkDeployment检查绑定校验、存档读写和撤销持久化。在游戏中分别部署两个角色,每次只修改一项并确认其他状态保留,再测试 NPC 卸载与加载、服务器重启以及死亡后复活。保持启用时,缺席期间不能生成替身。分别对已加载、未加载、跨维度和已死亡的 NPC 禁用或破坏锚点,重新启用后已撤销的实体及墓碑不能回来。

检查每个放置方向、朝向偏移、旋转及镜像下的箭头与弧线。驻留时启用朝向偏好,测试零范围和最大范围,再让可见的玩家或 NPC 进入、离开。检查 FOLLOW、游荡、对话、战斗、休息和动作表演,闲置朝向不能覆盖它们。对普通生成的 NPC 重复检查:它不应有部署绑定,也不应受到锚点修改。

个人剧情会面

Deployment.Encounter 是默认缺省的可选标识符,非法值会拒绝设置。编辑器为它提供独立字段。生成 NPC 或修改配置时,系统写入带此标识符的 isekai_story: 实体标签;改换会面会移除原标签。普通实体存档和复活保留标签。驻点身份、地点及待机朝向与个人剧情事实分别保存。

internal.story.npc.NpcStoryResources 加载 NPC 剧情会面数据。NpcStoryEncounters 在开场/主线选择之后、通常介绍和菜单之前运行,保存准确的 Blabber 会话及人物 UUID。只有自然结束、到达指定终点、选择未变且条件仍成立时,才记录 IsekaiCore 里程碑。强制关闭、距离超过 12 格、人物丢失或重载均不给进度。完成记录属于个人,小队关系和其他玩家的对话不代为完成。

UniqueNpcAnchorProcessor 与原生新部署共用 DeploymentAnchorNbt.fresh。新放置时启用锚点,清除 Deployed、Binding、Origin 和 Dimension,保留 Deployment 中的会面绑定及待机视线等配置。普通存档加载不会调用此初始化,因此未加载的人物仍占用原有部署名额。

唯一 NPC 锚点通过编写 NPC 的生成工具,以 SpawnReason.EVENT 初始化人物,使已开启的 Evelina 或瑟怜驻点能够在受保护庭院及 landmark 内部署。锚点仍检查配置、服装、区块、边界、高度及方块碰撞;“开启”仅表示允许尝试,并不表示已部署成功。加入世界失败不会消耗部署名额,已有的服务器 tick 会继续重试。

相关