Attachment

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

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

继承成员

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

Attachment 是依附在某个父级 Unit 上的局部坐标锚点，用局部的 Position、Rotation、Orientation 与 CFrame 描述相对父级的变换，同时提供会随父级世界变换自动换算的 WorldPosition、WorldRotation 与 WorldCFrame 世界空间属性。它还能通过 Axis 与 SecondaryAxis 描述主副轴方向、用 Visible 控制锚点自身可见性，并可借助 GetConstraints 查询挂在锚点上的约束。

适用场景

适合为约束、特效或挂点需求提供精确的定位与朝向：把 Attachment 挂到目标 Unit 之后，既可以直接按局部坐标微调偏移，也可以读取世界坐标来与其他对象对齐。

使用要点

先调用 game:CreateUnit("Attachment", config) 或 World:CreateUnit("Attachment", config) 得到实例，再将其放入目标 Unit 的层级中。设置相对父级的偏移使用 Position，按欧拉角设定朝向时先用 Quaternion.FromEulerAngles(...) 构造四元数再赋给 Rotation 或 Orientation，需要世界空间结果时读取 WorldPosition 或 WorldCFrame。要枚举挂在锚点上的约束，调用 Attachment:GetConstraints()。

注意事项

Attachment 通过 game:CreateUnit("Attachment", config) 创建，不使用 New 构造。Position 是相对 Parent 的局部 Vector3 偏移，Rotation/Orientation 也是局部旋转；需要世界坐标时读取 WorldPosition/WorldCFrame。当前编辑器属性面板可能把 Position 标成“世界坐标”，该标签与 Lua 契约不一致，应以 API 的局部/世界双属性语义为准。ShowOrientation 仅供编辑器属性面板使用（onlyEditor），运行时作者脚本不可读写。若要按欧拉角设置朝向，先用 Quaternion.FromEulerAngles(...) 构造四元数。新建实例若未挂到具体 Unit 上，世界坐标会与原点重合（0,0,0）。GetConstraints 返回当前 Attachment 上挂载的所有约束列表。

代码示例

挂载 Attachment 并对比局部与世界位置

-- @runtime client
local World = game:GetService('World')
local parent = World:CreateUnit('WorldUnit', { Position = Vector3.New(10, 0, 0) })
local attachment = World:CreateUnit('Attachment', {
    Parent = parent,
    Position = Vector3.New(0, 1, 0),
    Rotation = Quaternion.FromEulerAngles(0, math.rad(45), 0),
})
print('局部位置 Position:', attachment.Position)
print('世界位置 WorldPosition:', attachment.WorldPosition)

属性 (11)

Name	类型	默认值	说明
Position	Vector3	[0.0, 0.0, 0.0]	挂点相对父级的局部位置，类型为 Vector3，默认值为 (0, 0, 0)。
Rotation	Quaternion	[0.0, 0.0, 0.0, 1.0]	挂点的局部旋转，类型为 Quaternion，默认值为 (0, 0, 0, 1)。
Orientation	Quaternion	-	挂点的局部朝向，类型为 Quaternion，用于描述挂点相对父级的朝向。
CFrame	CFrame	-	挂点在父级坐标系下的 CFrame，同时包含局部位置与局部朝向信息。
WorldPosition	Vector3	-	挂点在世界坐标系下的位置，类型为 Vector3。
WorldRotation	Quaternion	-	挂点在世界坐标系下的旋转，类型为 Quaternion。
WorldCFrame	CFrame	-	挂点在世界坐标系下的 CFrame，包含世界位置与世界朝向信息。
Axis	Vector3	-	挂点的主轴方向，类型为 Vector3，描述挂点自身朝向中的主方向。
SecondaryAxis	Vector3	-	挂点的副轴方向，类型为 Vector3，描述挂点自身朝向中的次要参考方向。
Visible	Bool	true	控制 Attachment 在编辑器中是否可见。
ShowOrientation	Bool	false	仅编辑器属性面板使用（onlyEditor）的朝向指示开关；运行时作者脚本不可读写。

关联类型

• Unit
• CFrame
• Quaternion
• Vector3

函数 (1)

GetConstraints

签名：GetConstraints() -> Array<Unit> (引用当前 Attachment 的约束单位数组副本。)

获取当前挂点上引用的所有约束单位，返回一个约束单位数组的副本。

返回值 Array<Unit> (引用当前 Attachment 的约束单位数组副本。)

示例代码

读取锚点引用的约束

-- @runtime client
local World = game:GetService('World')
local attachment = World:FindFirstChild('MyAttachment', true)
if attachment == nil or not attachment:IsA('Attachment') then
    print('请先在编辑器中准备已连接约束的 Attachment')
    return
end
for _, linkedConstraint in ipairs(attachment:GetConstraints()) do
    print('约束名称:', linkedConstraint.Name)
end