roblox-npcs

roblox-npcs

官方来源：

• https://create.roblox.com/docs/en-us/characters/pathfinding
• https://create.roblox.com/docs/en-us/workspace/streaming
• 引擎类：PathfindingService、Path、PathWaypoint、PathfindingModifier、PathfindingLink、Humanoid

使用 PathfindingService 在 Roblox 导航网格上进行导航。围绕计算出的路径构建巡逻、追逐和其他行为。

PathfindingService 基础知识

创建路径：

local PathfindingService = game:GetService("PathfindingService")

local path = PathfindingService:CreatePath({
    AgentRadius = 2,
    AgentHeight = 5,
    AgentCanJump = true,
    AgentCanClimb = false,
    WaypointSpacing = 4,
    Costs = {
        Water = 20,
        DangerZone = math.huge,
    }
})
path.CalculationSecondsTimeout = 1

计算并跟随路径：

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

Agent 参数

参数	默认值	用途
AgentRadius	2 studs	与障碍物之间的最小间距
AgentHeight	5 studs	垂直间隙
AgentCanJump	true	允许跳跃路点
AgentCanClimb	false	允许攀爬桁架部件
WaypointSpacing	4 studs	中间路点之间的距离
Costs	nil	材质/区域/链接通行成本

Path.CalculationSecondsTimeout 用于限制求解器在每次 ComputeAsync 调用中的运行时长。在 CreatePath 之后、开始计算之前设置此属性。

PathWaypoint 动作

每个路点都有一个 Position 和一个 Action：

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

路径查找修饰器

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

• Label：在 Costs 表中使用的键。
• PassThrough：如果为 true，该体积会从导航网格中忽略，并视为可通行的空旷空间（例如，僵尸可以“隔着”门听到声音）。

示例：

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

路径查找链接

PathfindingLink 使用自定义标签和成本连接两个 Attachment，让路径可以穿过通常无法通行的间隙。

适用于：

• 横渡水域的船只
• 传送器
• 梯子
• 单向跳跃

移动代码会检查路点标签，并运行相应的自定义通行逻辑。

移动模式

跟随

持续重新计算到移动目标的路径。限制重新计算频率（例如，每 0.5–1 s 一次），并且只在目标移动距离足够远时重新计算。

巡逻

在固定点列表中循环。遇到阻挡时重新计算。

追逐

与跟随类似，但要在服务端验证视线和距离。对于权威 AI，不要信任客户端报告的位置。

状态机

常见的 NPC 状态包括：Idle、Patrol、Chase、Attack、Return。每种状态都负责自己的路径计算和 Humanoid 控制。

流式加载兼容性

• 服务端脚本拥有完整的世界状态，可以计算到任意部件的路径。
• 如果目标已从流式加载范围中移出，客户端脚本可能会失败。将 workspace.PersistentLoaded 和持久模型用于客户端路径目标。
• 动态障碍物或流式加载的障碍物阻挡道路时，重新计算路径。

限制

• 直线视线距离 ≤ 3,000 studs。
• 计算节点预算 ≈ 20,000 个节点。
• 路点的 Y 坐标必须介于 -65,536 和 +65,536 studs 之间。
• 不兼容的参数（例如，AgentCanJump = false，但目标只能通过跳跃到达）会导致失败。

大规模场景下的性能

• 按错开时间的计划重新计算路径，不要每帧都计算。
• 尽可能让行为相似的 NPC 共享目标位置。
• 使用 WaypointSpacing = math.huge 减少长直线路径上的中间路点。
• 考虑简化 Agent 几何形状，或减少活动 Agent 的数量。
• 对于非常庞大的世界，可划分区域或使用局部巡逻路径。

常见错误

• 每帧都计算路径。
• 忽略路径受阻事件，任由 NPC 撞向墙壁。
• 对权威 AI 信任客户端位置。
• 忘记在 ComputeAsync 周围使用 pcall。
• 在 Costs 中错误使用材质名称（必须使用字符串形式的 Enum.Material 名称）。

脚本

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

最佳实践

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

后续步骤

1. 定义 Agent 的尺寸和移动能力。
2. 使用修饰器／链接构建包含特殊区域的世界。
3. 实现路径跟随器，以处理路点、跳跃和受阻事件。
4. 为复杂行为添加状态机。
5. 在服务器上运行权威 AI；仅在客户端进行视觉预测。
6. 使用 MicroProfiler 进行性能分析，并错开多个 Agent 的重算时间。

参考索引

• modifiers-links-and-streaming.md：让 NPC 经过特殊区域，或处理流式加载的几何体。
• npc-behavior-patterns.md：实现巡逻、追逐、战斗或状态转换。
• pathfinding-service-details.md：配置 Agent、计算路径或处理受阻路点。
• performance-and-scaling.md：随着 NPC 数量增加，降低寻路和模拟开销。