FindingPathUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（2 属性 / 9 函数）
    • [FindingPathUnit]（1 属性 / 4 函数）

继承成员

2 个来源 / 5 属性 / 34 函数 / 6 事件

• 来自 SpaceUnit（2 属性 / 9 函数）
  • 属性：Tags、EcaPath
  • 函数：HasTag、AddTag、RemoveTag、GetPivot、PivotTo、ApplyPivotDelta、TranslateBy、IsTopLevel、FindTopLevel
• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、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

寻路路径单元用于按顺序维护一组路径点，公开 Meta 支持添加、删除以及发起路点/数量查询。

适用场景

制作巡逻路线、导航引导线或关卡内的可编辑路径时，可以先在地图中创建寻路路径单位，按顺序把关键位置逐个登记为路点，再读取这些路点坐标驱动角色或单位逐点移动，并在运行过程中按需插入或删除途经点。

使用要点

通过 World:CreateUnit 创建路径单位，按路线顺序调用 AddPoint 添加 Vector3 世界坐标；RemovePoint 使用从 1 开始的索引删除指定路点。

注意事项

RemovePoint 的 index 是 1-based：1 表示第一个路点，2 表示第二个。AddPoint 返回新建的 Attachment，失败时为 nil；GetWaypoints 返回路点数组，每个元素是包含 Position 字段的 table；GetPointCount 返回 Int。

代码示例

创建路径并维护路点

-- @runtime client
local World = game:GetService("World")
local path = World:CreateUnit("FindingPathUnit", { Name = "PatrolRoute" })
local firstPoint = path:AddPoint(Vector3.New(0, 0, 0))
if firstPoint == nil then return end
path:AddPoint(Vector3.New(10, 0, 5))
path:AddPoint(Vector3.New(20, 0, 0))
-- RemovePoint 使用 1-based 索引；这里删除第二个路点
path:RemovePoint(2)
print("当前路点数:", path:GetPointCount())
for _, waypoint in ipairs(path:GetWaypoints()) do
    print("路点位置:", waypoint.Position)
end

属性 (1)

Name	类型	默认值	说明
Name	String	寻路路径	寻路路径的名称标识，用于在场景中区分不同的寻路路径实例。

关联类型

• SpaceUnit

函数 (4)

GetWaypoints

获取当前路径的路点列表；每个元素是包含 Position = Vector3 的 table。

⚙ 遍历返回数组时使用 waypoint.Position 读取路点世界坐标。

示例代码

读取全部路点位置

-- @runtime client
local path = game:GetService('World'):CreateUnit('FindingPathUnit', {})
if path == nil then return end
path:AddPoint(Vector3.New(0, 0, 0))
for index, waypoint in ipairs(path:GetWaypoints()) do
    print('路点条目:', index, waypoint)
end

AddPoint

签名：AddPoint(position: Vector3) -> Attachment | nil (新创建的路点 Attachment，失败返回 nil)

向 FindingPathUnit 追加一个路点。参数 position 指定路点位置（Vector3），调用后会新建一个路点 Attachment 并作为返回值返回；若添加失败则返回 nil。

参数	类型	说明
position	Vector3	路点世界位置

返回值 Attachment | nil (新创建的路点 Attachment，失败返回 nil)

示例代码

向路径末尾添加路点

-- @runtime client
local path = game:GetService('World'):CreateUnit('FindingPathUnit', {})
if path == nil then return end
local attachment = path:AddPoint(Vector3.New(10, 0, 5))
if attachment == nil then return end
print("新路点:", attachment.Name)

RemovePoint

签名：RemovePoint(index: Int) -> void

根据索引移除一个路点。

⚙ index 从 1 开始；1 表示第一个路点。

参数	类型	说明
index	Int	路点索引

返回值 void

示例代码

按 1-based 索引删除路点

-- @runtime client
local path = game:GetService('World'):CreateUnit('FindingPathUnit', {})
if path == nil then return end
path:AddPoint(Vector3.New(0, 0, 0))
path:AddPoint(Vector3.New(10, 0, 5))
path:RemovePoint(2)

GetPointCount

签名：GetPointCount() -> Int (路点数量)

返回当前路径点数量。

⚙ 返回值类型为 Int，可用于遍历前检查路径是否为空。

返回值 Int (路点数量)

示例代码

读取路径点数量

-- @runtime client
local path = game:GetService('World'):CreateUnit('FindingPathUnit', {})
if path == nil then return end
path:AddPoint(Vector3.New(0, 0, 0))
print("路径点数量:", path:GetPointCount())