PathfindingLink

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [PathfindingLink]（6 属性）

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

PathfindingLink 用于在导航网格的两个锚点之间建立外部连接，使寻路单位可以跨越原本无法通行的区域，例如断崖、台阶或跳跃点。通过 Attachment0 与 Attachment1 指定连接的两端，并可借助 IsBidirectional 控制是否双向通行，利用 Label 为连接标记用途。编辑器预摆放并参与烘焙的链接不会受动态导航网格开关影响，而运行时创建的链接则需要依赖动态导航网格更新机制。

适用场景

当关卡中存在两块互不相连的可行走区域，需要让寻路单位通过跳台或滑索等特殊路径往返时，开发者会在地图上放置两个 Attachment 并借助 PathfindingLink 将它们连接起来，从而扩展寻路范围。

使用要点

可以通过 World:CreateUnit("PathfindingLink", {}) 或 game:CreateUnit("PathfindingLink", ...) 创建实例；创建后先确定场景中的两个 Attachment 实例，将其分别赋给 Attachment0 与 Attachment1（或填写对应的 AttachmentID0、AttachmentID1），再根据通行需求设置 IsBidirectional 与 Label。若在运行时才新建或修改这些端点，连接才会被寻路系统动态烘焙并生效。

注意事项

Attachment0 和 Attachment1 应传入 Attachment 实例引用，而不是 Attachment.UnitId 字符串或数字；它们用于定义寻路连接的两个端点。运行时新增或修改链接时，需确认 PathfindingService.HasDynamicNavMesh 为 true 才会触发重烘焙。

代码示例

用两个 Attachment 创建动态寻路链接

-- @runtime server
local World = game:GetService('World')
local PathfindingService = game:GetService('PathfindingService')
if not PathfindingService.HasDynamicNavMesh then
    print('当前未启用动态导航网格')
    return
end
local startPart = World:CreateUnit('WorldUnit', { Position = Vector3.New(0, 0, 0) })
local endPart = World:CreateUnit('WorldUnit', { Position = Vector3.New(5, 0, 0) })
local startAttachment = World:CreateUnit('Attachment', { Parent = startPart })
local endAttachment = World:CreateUnit('Attachment', { Parent = endPart })
local link = World:CreateUnit('PathfindingLink', {
    Attachment0 = startAttachment,
    Attachment1 = endAttachment,
    IsBidirectional = true,
    Label = 'shortcut',
})
print('寻路链接标签:', link.Label)

属性 (6)

Name	类型	默认值	说明
AttachmentID0	Int	0	起始锚点的 ID，用于标识链接起点的 Attachment 实例。
AttachmentID1	Int	0	终点锚点的 ID，用于标识链接终点的 Attachment 实例。
Attachment0	Attachment	-	起点锚点。Attachment0 是路径链接的起始端，该属性保存一个 Attachment 类型的引用，用于表示这条路径链接从哪个锚点发起。
Attachment1	Attachment	-	终点锚点。Attachment1 是路径链接的终止端，该属性保存一个 Attachment 类型的引用，用于表示这条路径链接到达哪个锚点结束。
IsBidirectional	Bool	true	是否允许双向通行，决定寻路时是否可以从终点向起点移动。
Label	String	""	区域标签，用于对寻路链接进行分类或过滤。

关联类型

• Unit
• Attachment