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 表示依附于父级单位的局部坐标锚点，通过 Position、Rotation、Orientation 与 CFrame 描述相对父级的变换，同时提供 WorldPosition、WorldRotation、WorldCFrame 等自动换算的世界空间读写入口，方便直接获取锚点在场景中的实际位置与朝向。它还可通过 Axis 与 SecondaryAxis 表达局部轴向，并借助 Visible、ShowOrientation 控制坐标轴的显示辅助。调用 GetConstraints 可以取得当前挂载在该锚点上的全部约束。

适用场景

在搭建物理装置或角色骨骼时，通常先在目标部件或多个单位上创建若干 Attachment 作为约束挂载点，随后物理约束通过引用这些锚点来确定作用位置与朝向。实际项目中也会用类型判断识别命中对象是否为 Attachment，再读取其 Position 或 WorldPosition 作为后续逻辑的依据。

使用要点

创建实例时应通过 game:CreateUnit("Attachment", config) 或 World:CreateUnit("Attachment", config) 获取，再将其挂到目标单位下并写入 Position、Rotation 等局部变换属性。需要与场景交互时读取 WorldPosition、WorldCFrame 获取已换算的世界坐标，并通过 GetConstraints 检查该锚点上已挂载的约束列表。

注意事项

Attachment 通过 game:CreateUnit("Attachment", config) 创建，不使用 New 构造。Position 是相对 Parent 的局部 Vector3 偏移，Rotation/Orientation 也是局部旋转；需要世界坐标时读取 WorldPosition/WorldCFrame。当前编辑器属性面板可能把 Position 标成“世界坐标”，该标签与 Lua 契约不一致，应以 API 的局部/世界双属性语义为准。若要按欧拉角设置朝向，先用 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]	Attachment 在父级空间下的局部位置。
Rotation	Quaternion	[0.0, 0.0, 0.0, 1.0]	Attachment 的局部旋转，以四元数表示。
Orientation	Quaternion	-	Attachment 的局部朝向，以四元数表示。
CFrame	CFrame	-	Attachment 的局部 CFrame，表示附件相对其父单位的局部位置与朝向。
WorldPosition	Vector3	-	Attachment 在世界空间下的位置。
WorldRotation	Quaternion	-	Attachment 的世界空间旋转，以四元数表示。
WorldCFrame	CFrame	-	Attachment 的世界 CFrame，表示附件在世界坐标系中的位置与朝向。
Axis	Vector3	-	Attachment 的主轴方向，以局部空间下的单位向量表示。
SecondaryAxis	Vector3	-	Attachment 的副轴方向，以局部空间下的单位向量表示。
Visible	Bool	true	控制 Attachment 在编辑器中是否可见。
ShowOrientation	Bool	false	附件朝向指示的显示开关，类型为布尔值。

关联类型

• Unit
• CFrame
• Quaternion
• Vector3

函数 (1)

GetConstraints

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

获取引用当前 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