NPC 跟随者

跟随者归属于已连接玩家的当前会话，每人最多 4 名。实体引用与记分板列表会持久化，以支持同一会话内的加载；断开后重新连接不会使原有跟随分配继续有效。

它做什么

内部组件 NpcFollowerSquadComponent 在记分板上保存成员关系。NpcFollowerSquadLogic 解析队形目标，NpcFollowerCommandController 管理命令，NpcFollowerTraversalController 协调梯子与跑酷，NpcFollowerSync 管理玩家会话与转移。这些是内部实现入口，不是公共 API 门面。

使用 BaseNpcEntity.beginFollowing(ServerPlayerEntity) 开始分配，使用 releaseFollowerOwnership() 解除并恢复此前记录的非跟随模式。底层开始方法检查服务端、会话与容量，本身不执行好感、信任、婚姻或交互权限检查；面向玩家的集成须先应用自己的准入规则。

运行时模型

成员关系与会话

玩家加入时生成新的正数会话序号并清除旧成员关系。断开时关闭会话、清除记分板成员，并释放各世界中已加载的跟随者。未加载 NPC 带有旧会话时，会在加载后的核对中失效。重生保留当前连接会话，核对已加载成员，并请求将其转移到新玩家实体旁。

成员以实体 UUID 标识，不以稳定 NPC 身份标识。组件同时维护玩家到成员、成员到玩家的索引。容量检查可移除已知且已加载的死亡、移除或失效成员；未知的未加载 UUID 仍占用名额，直至明确移除。战术排序只使用玩家当前世界中已加载、存活且归属有效的成员，依次按角色、成员槽位和 UUID 排列。

beginFollowing 记录此前的非跟随模式，切换为 FOLLOW，写入玩家与会话，再加入队伍；最终加入失败时恢复原状态。直接改模式或跟踪的玩家字段不等同于这个过程。

死亡处理后立即清除队伍归属，不等待尸体移除。KILLED/DISCARDED 永久移除再次执行清理，卸载和跨维度转移不会清除。按 UUID 清理不要求玩家在线；反向索引缺失时会扫描玩家列表修复。复活创建新的实体 UUID 并清除存档中的跟随分配，见 NPC 复活 API。

凝聚与队形

附近跟随者优先保持当前位置，再考虑重新排列。凝聚按水平距离判断，地面垂直绝对差上限为 1.5 方块。空中伴随在垂直差不超过 0.55 方块时进入保持，超过 1.0 方块后解除。队友靠近不会解除凝聚保持；分离修正只影响正在追赶的队形目标。垂直间距超过双方身体高度的跟随者不参与横向分离。

base = clamp(max(0, followRange) × 0.125, 2.5, 4.5)
entry = base + (ownerApproachSpeed >= 0.025 ? 1.0 : 0.0)
release = max(base + 1.25, entry + 0.25)

空中跟随者在采样的玩家移动状态有效时持续追随，不会在移动中反复进入凝聚。玩家稳定停下后恢复保持位置；采样与远距离飞行救援规则见 NPC 移动。

进入范围时设置临时锁存，离开更宽的释放范围或换到不同高度时清除。凝聚目标就是 NPC 当前位置，因此距离足够近时会跳过通道与队形位置探测。

每名玩家每个世界刻只采样一次队形朝向。初始朝向取玩家偏航；移动至少 0.02 方块时以 0.42 混合更新。玩家静止时通常保留此前有效朝向，不会随观察方向持续旋转队形。

NpcConfig.squadRole 默认及 null 输入均采用 FLEX。下列偏好由代码定义，顺序从零开始，不会重排已保存的成员列表。

开放队形根据玩家速度增加后方间距，最多 0.65 方块。左右位置按战术序号交替，首位坦克居中；其他成员在玩家静止时将侧向偏移乘以 0.9。FLEX 的额外后方间距为 order × 0.62，其余为 max(0, order - role.order) × 0.28。1.15 方块内的队友会产生最多 0.42 的分离修正。

单列首位目标位于玩家后方 1.55 方块。后续成员仅在与前驱的垂直差不超过 1.0 方块时让行：水平间距不足 1.45 方块，或前进方向差值不足 0.35 且水平距离仍小于 2.9 方块。其他位置尝试缩放偏移及局部备选。地面目标最多上下调整 1.0 方块，并检查支撑与身体净空；空中伴随目标保持玩家高度，只要求身体净空，不要求地面支撑。开放/紧凑候选还要求到玩家所在空间的碰撞射线畅通。全部失败时，最终目标可能回退到玩家位置加 0.05 Y；目标位置并不保证存在有效路径，也不是已验证的传送目的地。

地面到达后保持停留，直到目标距离超过队形到达半径加 0.55 方块。恢复移动时，从当前队形目标重新开始平滑。

跟随任务以 0.35 平滑目标，每隔 4 刻或目标移动 0.35 方块后刷新，并将路径完成范围限制在队形到达半径内。命令、锚点、战斗、对话暂停、骑乘、睡眠和外部速度修改都会使其让出控制权。速度与步态见 NPC 移动。

静止时看向玩家要求水平距离为 0.4–6.0 方块，地面身体每刻最多转动 12.0 度，玩家在身后时同样会转向。正在拥有移动控制权，或水平速度超过 0.05 方块/刻时，会清除跟随观察目标，由移动转向控制朝向。整个飞行、悬停和下降期间，跟随任务都将地面导航与越障控制交给飞行控制器，即使玩家已经着地。

移动与攻击命令

tryStartMoveCommand(target, markerId) 仅在服务端运行，要求模式为 FOLLOW。它测试请求方块及其上方方块。水中目的地优先；否则，已在空中的飞行者优先尝试空中目的地，再按地面/水中与空中后备规则选择。接受命令要求存在完整路径，且报告目标的曼哈顿距离不超过 1；地面移动也可采用已验证的梯子路线。仅有跑酷可行性不足以通过命令的初始准入。

接受后中断战斗，保存精确的方块底部中心到达位置与移动模式，建立 NPC_FOLLOW_COMMAND_POS，启动移动并记录标记所属玩家。地面命令后续可使用共享梯子/跑酷越障和障碍飞行；采用中间越障路径时，最终锚点保持不变。

计划距离取直线距离、已接受路径节点数和梯子路线估计长度的最大值；路径节点数不是测得的几何长度。有效物理运动或越障接管会重置快速停滞计数；最佳接近距离与命令刻数在越障前计算，不因重新寻路重置。成功的一次性恢复传送会明确重置命令刻数，并进入到达停留。

到期恢复先加载目标区块，再按已接受的移动模式复核：地面要求可站立，水中要求水体与净空，空中要求身体净空且不能解析为可游泳目标。随后尝试传送到已接受的到达位置。恢复成功会清除速度和坠落距离，开始 100 刻停留。每个命令只能成功使用此传送一次；之后再次终止失败会释放命令，并发送 message.isekaiexpansion.npc_command.move.abandoned。

地面/空中使用 1.6 到达半径。水中使用 2.0 水平范围；若正在接触水且目标列为水体，则不再检查垂直距离，否则采用 3.0 垂直容差。停留结束后，仍在目的地的 NPC 释放命令，被移开的 NPC 恢复旅行。标记 ID 为正且记录的玩家在线时，会发送标记释放消息。

对话暂停会阻止命令任务更新，因此旅行计数暂停；到达停留则依据实体年龄，同一机制不会冻结它的经过时间。没有活动命令的孤立锚点记忆会在服务端核对时清除。离开 FOLLOW 或清除玩家归属会清除命令与目标抑制列表。

tryStartAttackCommand 拒绝缺失或死亡目标、禁用战斗的 NPC、创造/旁观玩家、不允许的命令意图和不可选中实体。它清除该目标的抑制，中断前一动作，清除移动，并设置命令意图及目标最后位置。stopCurrentTargetAndSuppress() 中断战斗，最多记录 12 个目标 UUID，超出时移除最早条目。每隔 20 刻清理不存在、死亡或已移除目标；观察到玩家新近攻击某个受抑制目标时，解除该目标的抑制。

越障协调

跟随位置与地面命令锚点都转为 TraversalGoal(destination, yielding, arrived)。已有跑酷优先执行，其次是已有梯子越障；空闲时先尝试梯子，再规划跑酷。共享阻塞信号要求地面可达性失败或导航停滞连续 10 刻，任何畅通更新立即清零。停滞要求空闲 12 刻，并且导航空闲或不可达记忆足够久。

观察到玩家正在攀爬时，立即以附近攀爬方块为种子；否则，梯子获取要求垂直差至少 1.75 方块且阻塞信号已确认。失败或结束的尝试使下次获取延后 30 刻。普通单列让行本身不会阻止梯子获取；跑酷则尊重让行与到达状态。

梯子规划与队列

规划器接受已加载的 BlockTags.CLIMBABLE 方块及梯子。观察攀爬玩家时扫描 3 × 5 × 3 区域。通用搜索在源楼层和目标楼层附近各采样 5 个 Y 层，覆盖 19 × 19 端点区域及宽度为 7 的通道；通道工作量随端点距离增长。发现后最多保留 32 个种子、检查 8 个连通部分，每部分最多 256 个节点，共进行最多 16 次入口路径探测。

六方向泛洪搜索构成连通攀爬物。入口候选须接近源楼层、可站立，且到挂接点的扫掠身体检查通过；梯子开放面方向的候选优先。接受的集结路径必须完整。出口要求靠近目的楼层、有支撑并满足扫掠净空。路线须至少有 1.25 方块垂直行程和连通节点路径；有界搜索失败时不返回路线。

阶段为 APPROACH、MOUNT、CLIMB 和 DISMOUNT，返回 ACTIVE、COMPLETE 或 FAILED。重置会释放队列控制权和临时状态。

接近阶段使用已验证的中间导航入口。水平距离不超过 1.25、垂直差不超过 1.45 方块且扫掠净空通过时可开始挂接。墙梯接触点向开放面偏移 0.18；水平距离大于 0.55 时朝向接触点，进入该范围后转向支撑面。上行接触采用 0.48，下行则要求 0.14 对齐、身体完全越过台阶，并占据连通攀爬物的精确方块格。

攀爬沿连通节点移动，不假设固定垂直列。朝向支撑面时垂直速度裁剪到 -0.15 至 (0.20 - 0.08) × 0.98 = 0.1176 方块/刻，否则暂停垂直移动。与玩家/前驱的方向性间距为 1.15 方块。拥有控制权的每刻会声明地面越障，抑制竞争的自动飞行。

队列声明仅存在于运行时，绑定越障控制者和服务端世界。只考虑同一连通物上、声明仍有效的直接战术前驱。前驱正在接近/挂接、方向相反，或尚未建立 1.45 方向性间距时，后继等待入场。已经开始攀爬后，同方向间距仅在水平 1.35 方块内生效；反方向声明不会强制已在攀爬的成员等待。前驱进入 DISMOUNT 后不再阻止入场。

玩家离开所观察攀爬物后，若已站在地面，可立即调整出口；仍在空中时等待稳定窗口再尝试。找不到新出口则保留原路线。挂接/攀爬失败可能选择附近有支撑的恢复出口。完成要求实际到达地面出口，不是仅达到其高度。预期排队会刷新监测时钟，因此普通跟随越障没有统一的无条件总时长上限；地面命令仍有自己的命令预算。

跑酷规划与执行

跑酷要求位于地面、未攀爬/接触水/飞行/悬停、未让行/到达，并且路线阻塞已确认。调用方任务负责各自的跟随、对话与战斗资格检查。地面移动命令也使用此协调器，因此“命令不能跑酷”并非实际约定。

完整地面路径会否决跳跃。规划器要求存在支撑缺口或身体障碍，并在前向锥形范围中搜索方块中心落点。前向位移至少为 1.0，侧向搜索最多 2.25。目标改善采用 afterHorizontalDistanceSquared + 0.75 × 0.75 < beforeHorizontalDistanceSquared，不是固定 0.75 方块的线性接近量。目的地高于 NPC 超过 1.3 方块时，选中的落点还须提高超过 0.5 方块。

脚部和支撑方块拒绝火标签方块、仙人掌、岩浆块、两种营火、甜浆果丛、细雪和凋零玫瑰，也拒绝熔岩。检查还包括支撑、完整身体净空和区块加载。求解器使用以下递推：

A(r, T) = (1 - r^T) / (1 - r)
horizontalLaunch = horizontalDisplacement / A(0.91, T)
verticalLaunch = (height + (0.08 × 0.98 / (1 - 0.98)) × (T - A(0.98, T))) / A(0.98, T)
positionNext = position + velocity
horizontalVelocityNext = horizontalVelocity × 0.91
verticalVelocityNext = (verticalVelocity - 0.08) × 0.98

这些是当前求解器的实现假设，不表示所有外部移动修饰都遵循相同递推。

求解器最小化起跳能量、滞空时间、超额弧顶和到达速度的组合成本。规划器再综合目标误差、起跳能量、侧向偏移、到达速度及助跑距离评分。先尝试当前位置，只有没有可用直接方案时，才从 9 次探测中尝试最多 3 个起跳点：前向偏移 1, 2, 3，侧向偏移 0, -1, 1。助跑采样间隔最多 0.5 方块，接受支撑偏移 0, 0.5, -0.5；完整下降一格不算有效支撑采样。

执行时先直接控制地面助跑，再施加已求解的起跳冲量。空中水平修正按剩余阻力级数计算，以 0.12 插值，保持垂直速度不变。活动期间声明地面越障、关闭疾跑并清除坠落距离。接触水、经过 2 刻后的水平碰撞或超时都会中止。经过超过 1 刻且地面水平进度达到 0.45 后结束弧线并衰减水平速度。中止时的衰减只在地面生效。

传送救援与世界转移

符合条件的远距离飞行救援拥有 40 刻（2 秒）的尝试窗口，之后此传送任务才可介入。回到跟随范围内会重置窗口；持续移动仍会阻止要求空闲状态的传送。

普通同世界跟随救援是独立任务，配置为空闲 100 刻、距离 32、搜索半径 6。它排除睡眠、骑乘、命令/锚点和战斗。通过初始空闲条件后，悬停且距离超过 7 方块可触发，普通远距离救援使用 32。较近恢复要求距离超过 5，空闲 160 刻或不可达记忆同样久，并且地面可达性失败；即使通过不可达记忆分支，仍须满足最初的 100 刻空闲条件。

任务尝试 24 个随机列，使用不含树叶的阻挡运动高度图和可站立检查。接受一次尝试后冷却 100 刻，没有候选时冷却 20 刻。辅助方法未检查 TeleportUtil.tryTeleport 的布尔结果，因此接受尝试不应被当作已完成位移的独立确认。

NpcFollowerSync.transferFollowersToPlayer 处理即时转移与重生恢复。它跨世界收集已加载且归属有效的跟随者，按战术顺序排序，并转移位于其他世界或距解析目标超过 7 方块的成员。未加载成员关系会保留，但收集过程不会强制加载它们。

目的地解析在水平 ±6 方块及垂直偏移 0, 1, -1, 2, -2, 3, -3 中搜索，排除玩家自身所在列，优先位置在玩家后方或侧后方。它加载候选区块，通过下骑/重生位置解析器确定地面位置，再检查站立身体加 0.05 水平边距的净空、世界边界、脚部无熔岩，以及到玩家的碰撞射线畅通。依次抵达的成员会通过净空检查自然占据空间。

没有有效位置就不转移，不会直接回退到未经检查的玩家坐标。位移前后清理骑乘/睡眠、命令、战斗、移动和飞行/游泳等临时状态，并将新位置实体与会话核对。失败后每隔 5 刻重试，窗口最长 60 刻，绑定记录的目的维度，并使用主世界时间。断开、死亡、维度变化或服务端实例替换会清除或使待处理重试失效。

停止跟踪恢复使用相同解析器，但排除睡眠成员。转移不会创建新的跟随准入或复活身份，已有有效分配会保留。

骑乘兼容

本地桥接只在加载 niftycarts 或 smallships 时启用。存活、清醒、未骑乘且无命令/锚点和战斗的跟随者，每隔 10 刻在玩家适用载具的 4.0 方块内尝试上车。玩家不再解析到当前兼容载具时，已有骑乘结束。

Nifty Carts 先解析玩家拉动的车，再检查所骑车或坐骑牵引的车。桥接接受补给车与篷车，拒绝上锁的车；补给车乘客少于 1 时可用，篷车箱子数量为 0/1 时容量为 4，数量为 2 时容量为 2，其他情况为 0。这些是本桥接的检查。Small Ships 容量交给依赖的 canAddPassenger 判断，此处不声明固定容量。骑乘状态会停止导航、清除跟随移动/观察记忆，并将身体和头部朝向对齐载具偏航。

约定

存档与同步状态

记分板读取前清除所有临时会话、朝向和凝聚锁存。它跳过无效玩家字符串和重复跟随者，但 UUID 数组转换没有逐条异常捕获；数组长度错误可导致读取失败。重复归属按 NBT 键遍历顺序决定，没有约定字典序优先级。

同步包只包含接收者 UUID、成员数量和成员 UUID。客户端清除此前映射，读取所有编码 UUID，最多保留 4 个不同条目。会话、角色、朝向、凝聚、命令、队列和越障状态不在该包中。实体 NBT 详情与旧数据拒绝规则另见 NPC 基础。

生命周期与权威

这里的修改入口都应在服务端线程调用。运行时导航、队列和待处理转移不是持久化任务。归属查询同时依赖模式和匹配的活动会话，只读取玩家 UUID 不足以判断有效性。

通过组件准入加入成员，不直接向列表插入 UUID。通过命令生命周期方法管理锚点，避免留下裸记忆。规划时有效的路线/轨迹不保证未来仍有净空；执行监测与恢复仍是约定的一部分。

扩展方式

通过 NpcConfig.builder().squadRole(...).build() 选择角色，并通过 beginFollowing 保留与会话绑定的准入。自定义移动应遵守相同的控制权排除条件，使用共享步态和可达性缓存。

新增按目的地工作的越障时提供 TraversalGoal，一致地声明与释放控制权，并将命令整体预算放在可重置的越障计数之外。除了成功移动，也要测试失败。转移应复用安全解析器，不直接将跟随者放到玩家坐标。

验证

检查满员准入、未加载成员、失效的已加载成员、断开/重连、重生、死亡与复活。确认存档中的旧会话释放归属，客户端包只暴露接收者自己的列表。

测试玩家转头、主动接近、不同楼层、窄门、墙体和多个同角色成员下的凝聚。命令测试应包含拒绝目的地、地面/水中/空中准入、停留时被移开、对话暂停、重寻路停滞、梯子失败、成功恢复传送和之后再次失败。

从不同侧面测试梯子上下行、连通藤蔓、竞争前驱、玩家在空中离开以及损坏出口。跑酷测试包括完整步行路线否决、边缘助跑、天花板、危险落点、未加载地形和弧线中断。转移测试包括被占据的窄入口、无有效目的地、重试到期和重试期间断开。

相关页面

• NPC 基础
• NPC 移动
• NPC 复活 API