roblox-npcs

用途

roblox-npcs 用于在 Roblox 中构建或调试 NPC 的导航与行为。它围绕 Roblox 的导航网格，使用 PathfindingService 计算路径，并在此基础上实现巡逻、追击等行为逻辑。

主要能力

PathfindingService 基础

通过 PathfindingService:CreatePath 创建路径，可配置代理参数：

AgentRadius：默认 2 studs，与障碍物的最小间隙。
AgentHeight：默认 5 studs，垂直间隙。
AgentCanJump：默认 true，允许跳跃路径点。
AgentCanClimb：默认 false，允许攀爬桁架部件。
WaypointSpacing：默认 4 studs，中间路径点间距。
Costs：材质/区域/连接的通行成本。

Path.CalculationSecondsTimeout 限制每次 ComputeAsync 调用中求解器可运行的时间，应在 CreatePath 之后、计算之前设置。

计算与跟随示例：

local humanoid = character:WaitForChild("Humanoid")
local rootPart = character:WaitForChild("HumanoidRootPart")

local success, err = pcall(function()
    path:ComputeAsync(rootPart.Position, endPos)
end)

if success and path.Status == Enum.PathStatus.Success then
    local waypoints = path:GetWaypoints()
    -- follow waypoints with Humanoid:Move()
end

路径点动作

每个路径点包含 Position 和 Action：

Enum.PathWaypointAction.Walk：正常移动。
Enum.PathWaypointAction.Jump：触发跳跃。
来自 PathfindingModifiers/Links 的自定义标签，如 "Climb" 或 "UseBoat"。

Pathfinding 修饰器

放置在已锚定、不碰撞部件上的 PathfindingModifier 实例可影响路径成本：

Label：Costs 表中使用的键。
PassThrough：若为 true，该体积被导航网格忽略，视为可通行的空白空间（例如僵尸“听”到门后）。

示例：

local path = PathfindingService:CreatePath({
    Costs = {
        Water = 20,
        DangerZone = math.huge,
        UseBoat = 2,
    }
})

Pathfinding 连接

PathfindingLink 通过自定义标签和成本连接两个 Attachment，允许路径跨越通常不可通行的间隙。适用于：船只渡水、传送器、梯子、单向跳跃。移动代码需检查路径点标签并执行自定义通行逻辑。

移动模式

跟随：持续向移动目标重新计算路径。需节流重算（例如每 0.5–1 秒），且仅在目标移动足够远时重算。
巡逻：在固定点列表间循环，被阻塞时重算。
追击：类似跟随，但在服务端验证视线和距离。权威 AI 不应信任客户端上报的位置。
状态机：常见 NPC 状态包括 Idle、Patrol、Chase、Attack、Return，每个状态自行处理路径计算和 Humanoid 控制。

Streaming 兼容性

服务端脚本拥有完整世界状态，可计算到任意部件的路径。
客户端脚本在目标已流出时可能失败。客户端路径目标应使用 workspace.PersistentLoaded 和持久化模型。
当动态/流式障碍物阻挡道路时需重算路径。

使用方式

技能附带以下脚本：

scripts/NPCPathFollower.lua：基于 Humanoid 的路径跟随器，支持阻塞路径重算、自定义标签支持和连接清理。
scripts/PatrolBehavior.lua：状态驱动的巡逻/追击行为，带空间检测和节流重算。
scripts/PathfindingUtility.lua：节流重算和路径点格式化的辅助工具。

推荐流程：

定义代理的尺寸和移动能力。
用修饰器/连接构建世界中的特殊区域。
实现处理路径点、跳跃和阻塞事件的路径跟随器。
叠加状态机以实现复杂行为。
在服务端运行以获得权威 AI；客户端仅用于视觉预测。
使用 MicroProfiler 分析，并为大量代理错开重算。

适用场景

需要 NPC 在 Roblox 导航网格上寻路的游戏。
巡逻、追击、战斗或状态转换等 NPC 行为。
需要穿越特殊区域（水域、危险区、船只、传送器、梯子）的路径规划。
需要处理流式加载几何体的客户端或服务端寻路。
大量 NPC 场景下的寻路性能优化。

限制

直接视线距离 ≤ 3,000 studs。
计算节点预算约 20,000 个节点。
路径点 Y 坐标必须在 -65,536 到 +65,536 studs 之间。
不兼容的参数（例如 AgentCanJump = false 却要前往仅能跳跃到达的目的地）会导致失败。

性能与扩展

按错开的计划重算路径，而非每帧重算。
尽可能在相似 NPC 间共享目标位置。
长直线路段可使用 WaypointSpacing = math.huge 减少中间路径点。
考虑简化代理几何体或减少活跃代理数量。
超大世界可拆分为区域或使用局部巡逻路径。

常见错误

每帧计算路径。
忽略阻塞路径事件，让 NPC 走进墙壁。
权威 AI 信任客户端位置。
忘记在 ComputeAsync 外包裹 pcall。
在 Costs 中错误使用材质名称（必须匹配 Enum.Material 名称的字符串形式）。

最佳实践

在 CreatePath 之后设置 Path.CalculationSecondsTimeout 以限制求解器时间。
始终为 Humanoid:MoveTo 设置显式超时，并在到达路径点或跟随器停止时取消。
使用 workspace:GetPartBoundsInRadius 等空间查询检测目标，而非每帧扫描每个玩家。
Humanoid 死亡或 NPC 被销毁时停止路径跟随器并清理 Heartbeat 连接。
对于重生 NPC，为新角色模型创建新的行为实例并销毁旧的。
使用 PathfindingLink 标签触发自定义通行逻辑（船只、传送器、梯子）。跟随器调用已注册的处理程序；若不存在，路径点回退到正常移动。
要启用攀爬，设置 AgentCanClimb = true 并提供 TrussPart 表面。攀爬路径点的 Label 为 "Climb"。
PathfindingModifier 部件必须 Anchored = true 且 CanCollide = false。

参考索引

modifiers-links-and-streaming.md：通过特殊区域路由 NPC 或处理流式几何体。
npc-behavior-patterns.md：实现巡逻、追击、战斗或状态转换。
pathfinding-service-details.md：配置代理、计算路径或处理阻塞路径点。
performance-and-scaling.md：在 NPC 数量增长时降低寻路和模拟成本。