NPC角色扩展

NpcRoleExpansion

NpcRoleExpansion 是一个小型 库模组，它添加了额外的 NPCRole JSON 构建块（BodyMotions / MotionControllers），让玩家能更轻松地通过 JSON 自定义 NPC 行为。

其目标是提供可复用的、文档完善的行为组件，通过 Type 字符串接入原版的 NPCRole 系统 —— 这样角色作者就能用更少的 JSON 和自定义逻辑粘合代码，实现高级的移动与行为。

随着新 NPC 行为的涌现，该项目会持续扩展。 如果你有想法，或发现缺失的原版行为希望以 JSON 友好的组件形式呈现，欢迎提出建议！

---

当前包含的内容

MotionController：FlyFreeLook

一个扩展原版 Fly 的飞行控制器，支持独立于视线方向移动。

• 兼容性： 扩展自 MotionControllerFly，使用与原版 "fly" 相同的 JSON 字段。
• 用例： 在紧盯目标的同时进行侧移/环绕；无人机需要持续跟踪目标但无需不断转向移动方向的情况。

类型 ID： FlyFreeLook

---

BodyMotion：MaintainDistanceFlyRing

一种行为类似 保持距离（MaintainDistance） 的躯体动作，但专为飞行 NPC 设计。

功能

• 保持 NPC 位于目标周围一个可配置的 XZ 距离环带 内（“环/轨道”概念）。
• 支持可配置的垂直偏移（可随时间变化）。
• 可选的目标后方锚定（让轨道角度偏向目标移动方向的后方）。

为什么有用

• 它是针对飞行单位的保持距离式解决方案；许多场景下，玩家通常需要在多个动作之间切换（例如：追击 → 保持距离 → 重新追击）。
• 内置寻路 功能（通过 BodyMotionFindBase 流程），因此当存在目标时，NPC 能在避开障碍物的同时持续追击。
• 这能大幅降低角色 JSON 的复杂度，因为你不再需要写大量“逻辑粘合代码”在独立的指令分支里处理追击、间距和障碍物躲避。

前置要求

• 需要 Feature.AnyPosition（上层的传感器必须每 tick 提供一个位置）。
• 验证当前的 MotionController 是否兼容 MotionControllerFly。

类型 ID： MaintainDistanceFlyRing

---

示例：飞行轨道 + 注视（简洁角色片段）

下面是一个极简风格片段，展示了这些组件在角色中的典型用法：

• FlyFreeLook 作为运动控制器
• Watch 作为头部动作（注视目标）
• MaintainDistanceFlyRing 作为躯体动作（保持间距 + 轨道 + 障碍物处理）

注意：此片段假设有一个 Target 传感器（或任何上游提供者）正在提供目标位置。

{
  "MotionControllerList": [
    {
      "Type": "FlyFreeLook",
      "MaxHorizontalSpeed": 20,
      "MaxSinkSpeed": 10,
      "MaxClimbSpeed": 12,
      "MinAirSpeed": 0,
      "Acceleration": 7,
      "Deceleration": 15,
      "MaxRollAngle": 180,
      "MaxTurnSpeed": 360,
      "AutoLevel": true,
      "MinHeightOverGround": 0,
      "MaxHeightOverGround": 64,
      "DesiredAltitudeWeight": 0.35
    }
  ],
  "HeadMotion": {
    "Type": "Watch"
  },
  "BodyMotion": {
    "Type": "MaintainDistanceFlyRing",
    "DesiredDistanceRangeXZ": [2.5, 2.5],
    "YOffsets": [1.0, 3.0],
    "YOffsetChangeIntervalRange": [2.0, 4.0],
    "MoveThreshold": 0.35,
    "LockBehindTarget": false
  }
}

调优提示

想要减少轨道修正的抽搐感？增加 MoveThreshold 的值。

希望在接近轨道点时制动更平滑？增加 MoveTowardsSlowdownThreshold 的值。

希望它优先保持在移动目标的后方？使用：

• LockBehindTarget: true
• BehindBlend 设为 0.1–0.35 左右
• MinTargetSpeed 来避免目标几乎不动时的随机翻转。

---

MaintainDistanceFlyRing 关键选项（快速参考）

必填：

• DesiredDistanceRangeXZ：[最小值, 最大值]
• YOffsets：[ ... ]（若为空，默认值为 [3.0]）

常用调优：

• TargetDistanceFactor（默认 0.5）
• MoveThreshold（默认 0.7）
• RelativeForwardsSpeed（默认 1.0）
• RelativeBackwardsSpeed（默认 0.6）
• MoveTowardsSlowdownThreshold（默认 12.0）
• HardStop（默认 false）

后方锚定：

• LockBehindTarget（默认 true）
• BehindBlend（默认 0.25）
• MinTargetSpeed（默认 0.15）

---

反馈与建议

NpcRoleExpansion 旨在成长为一个可复用的 NPCRole 行为工具箱。 如果你有一个经常在 JSON 中重复创建的行为（或原版缺少的某个行为），欢迎提出建议，我会考虑将其添加为新的构建块。