一个 `Class.Actor` 是一个代码容器，可以安全地使用 `Library.task.desynchronize()` 拆分到自己的线程中。它还应该包含其脚本使用的实例。

要了解使用多个 Actors 来优化脚本性能的更多信息，请参见 [Parallel Luau](/scripting/multithreading)。

#### 注意事项

- 每个 `Actor` 在其自己的 Luau VM 中运行。`Class.ModuleScript|ModuleScripts`
  由 `Actor` 所需的内容**不会**在 `Actors` 之间或与主线程之间共享或缓存。每个 VM 执行其自己的模块副本，因此模块级状态在每个 `Actor` 中是隔离的。如果您的模块保留您打算共享的状态，请相应设计。
- 从 `Class.ModuleScript` 调用时，`script:GetActor()` 返回 `nil`，
  除非 `ModuleScript` 是 `Actor` 的后代。存储在其他地方的 `ModuleScripts`
  （例如，`Class.ReplicatedStorage`）并被 `Actor` 所需的，不被视为 `Actor` 的后代。


此方法用于将一个 Luau 回调绑定到具有指定主题的消息。当向指定主题发送消息时（使用 `Class.Actor:SendMessage()|SendMessage()`），提供的回调将在 _串行_ 执行上下文中被调用。

多个 Luau 回调可以绑定到单个 Actor，甚至绑定到单个消息主题。

注意：只有 Actor 的后代脚本才能绑定到其消息。

```lua
local actor = script:GetActor()

-- 在发送问候消息给 Actor 时打印消息
-- 这个脚本是一个后代。
local connection = actor:BindToMessage("Greeting", function(message)
  print("收到问候消息：", message)
end)
```

Actor:BindToMessage

topic

function

该连接对象可用于断开 Luau 回调与接收消息的连接。

将一个 Luau 回调绑定到具有指定主题的消息。

此方法用于将一个 Luau 回调绑定到具有指定主题的消息。当向指定主题发送消息时（使用 `Class.Actor:SendMessage()|SendMessage()`），提供的回调将在 _并行_ 执行上下文中被调用。

多个 Luau 回调可以绑定到单个 Actor，甚至绑定到单个消息主题。

注意：只有 Actor 的后代脚本才能绑定到其消息。

```lua
local actor = script:GetActor()

-- 在发送问候消息给 Actor 时打印消息
-- 这个脚本是一个后代。
local connection = actor:BindToMessageParallel("Greeting", function(message)
  print("收到问候消息：", message)
end)
```

Actor:BindToMessageParallel

向 Actor 发送消息。消息是异步发送的，因此发送者在调用 `Class.Actor:SendMessage()|SendMessage()` 方法时不会被阻塞或让出。

由于单个 Actor 可能会接收不同种类的消息，因此使用 `topic`
参数来区分各种消息。

有关使用 `Class.Actor:SendMessage()|SendMessage()` 发送消息的接收详细信息，请参见 `Class.Actor:BindToMessage()|BindToMessage()`。

请注意，消息参数是**按值传递**跨越 Luau VM 边界，而不是按引用。发送大型表格会在每次调用时执行完整复制。函数绑定到特定 VM，不能在消息中传递。

```lua
-- 假设 `actor` 是一个指向 Actor 实例的本地变量
actor:SendMessage("Greeting", "Hello World")
```


Actor:SendMessage

用于识别正在发送的消息的主题。

message

Actor

一个 `Class.Actor` 是一个可以安全地拆分到其自身线程的代码容器。

以下示例包含一个基本函数，该函数接受一个对象表并将它们放入一个新模型中，返回该模型。

模型是容器对象，意味着它们将对象组合在一起。它们
最适合用于保存 `Class.BasePart|BaseParts` 的集合，并具有多个
扩展其功能的功能。

模型旨在表示 **几何** 分组。如果您的分组没有几何解释，
例如 `Class.Script|Scripts` 的集合，请使用 `Class.Folder`。

由关节连接在一起的模型（以便它们可以移动或通过物理
仿真被销毁）通常具有设置的 `Class.Model.PrimaryPart|PrimaryPart`，
因为它指定了模型内哪个部件的枢轴和边界框会随模型移动。
保持在一个地方的静态模型不需要设置主部件。

模型有广泛的应用，包括 Roblox 玩家角色。
它们还有一些独特的行为，重要的是要记住：

- 当一个 `Class.Humanoid` 和一个名为 **头部** 的 `Class.Part` 在
  模型下方时，模型上方会出现名称/健康 GUI；有关详细信息，请参见
  [角色名称/健康显示](/characters/name-health-display)。
- 如果一个部件的 **Y** 轴位置达到 `Class.Workspace.FallenPartsDestroyHeight`，
  而且它是 `Class.Model` 中的最后一个对象，模型也会被销毁。
- 当在设置为 true 的 `Class.Workspace.StreamingEnabled` 的地方使用时，
  `Class.Model.ModelStreamingMode|ModelStreamingMode` 的值控制
  关于模型及其所有子项如何被复制和/或从客户端移除的各种行为。
  此外，`Class.Model.LevelOfDetail|LevelOfDetail` 的值影响模型的渲染。

与所有 `Class.Instance` 类型一样，父级为 `Class.Model` 被
复制到客户端并不保证它的所有子项都被复制。当这些实例由
在客户端运行的代码访问时，这一点尤其重要，例如在 `Class.LocalScript` 中。
使用如 `Enum.ModelStreamingMode|Atomic` 的 `Class.Model.ModelStreamingMode|ModelStreamingMode`
可以确保如果父模型存在于客户端，则整个模型及其所有子项都存在，或者在不希望聚合的情况下可以使用 `Class.Instance:WaitForChild()|WaitForChild()`。

将此模型设置为指定玩家的持久性。持久模型在
流媒体设置或条件下仍然对玩家存在。

`Class.Model.ModelStreamingMode|ModelStreamingMode` 必须设置为
`Enum.ModelStreamingMode|PersistentPerPlayer`，以便由于添加而改变行为。

Model:AddPersistentPlayer

playerInstance

使此模型对其持久的 `Class.Player`。

将此模型设置为指定玩家的持久性。
`Class.Model.ModelStreamingMode|ModelStreamingMode` 必须设置为
`Enum.ModelStreamingMode|PersistentPerPlayer`，以便由于添加而改变行为。

在这个示例中，每个玩家角色模型中的关节将在生成后3秒被破坏。破坏这些关节将导致人形死亡。

这个代码示例演示了在两个与脚本同级的部件上手动创建关节（PartA 和 PartB）。它在两个具有兼容表面类型（Studs 和 Inlet）的接触部件上创建关节。

断开 `BaseParts` 之间的连接，包括与任何相邻部件的表面连接，
`Class.WeldConstraint|WeldConstraints` 和所有 `Class.Weld|Welds` 及其他 `Class.JointInstance|JointInstances`。

当在玩家角色 `Class.Model` 上使用 BreakJoints 时，
角色的 `Class.Humanoid` 将死亡，因为它依赖于颈部关节。

请注意，虽然通过与相邻部件的表面连接生成的关节可以通过 `Class.Model:MakeJoints()` 再次生成，
但这只会重建由表面产生的关节。开发人员不应依赖这个，因为在关节被断开后，部件可能不再相互接触。

Model:BreakJoints

断开 `BaseParts` 之间的连接，包括与任何相邻部件的表面连接，
`Class.WeldConstraint|WeldConstraints` 和所有 `Class.Weld|Welds` 及其他 `Class.JointInstance|JointInstances`。

Model:breakJoints

此函数返回包含 `Class.Model` 中所有 `Class.BasePart` 子部件的体积描述。
该体积的方向基于 `Class.Model.PrimaryPart|PrimaryPart` 的方向，
并与在 Studio 中选中模型时呈现的选择框匹配。
与 `Class.Terrain:FillBlock()` 的行为相同，它返回一个表示该
边界框中心的 `Datatype.CFrame` 和一个表示其大小的 `Datatype.Vector3`。
如果物理约束作用于 `Class.Model` 中的部件，则大小在运行时可能不准确。

边界框的方向与 `Class.PVInstance.GetPivot|Pivot` 的方向相同 - 要么是
`Class.Model.PrimaryPart|PrimaryPart` 的枢轴（如果存在），
要么是模型的 `Class.Model.WorldPivot|WorldPivot`。

```lua
local Workspace = game:GetService("Workspace")

local model = Workspace.Model
local part = Workspace.Part
local orientation, size = model:GetBoundingBox()

-- 将部件的大小和位置调整为模型的边界框
part.Size = size
part.CFrame = orientation
```

Model:GetBoundingBox

一个表示体积方向的 `Datatype.CFrame`，后跟一个表示体积大小的 `Datatype.Vector3`。

返回包含模型所有部件的体积描述。

以下代码示例演示了如何使用 Model.GetExtentsSize 获取包含部件的边界盒的大小。

返回包含所有 `Class.BasePart|BaseParts` 的模型的最小边界框的大小。
该方向与 `Class.PVInstance.GetPivot|Pivot` 的方向匹配 - 要么是
`Class.Model.PrimaryPart|PrimaryPart` 的枢轴（如果存在），
要么是模型的 `Class.Model.WorldPivot|WorldPivot`。

请注意，此函数仅返回最小边界框的大小，开发人员必须使用自己
的方法来获取边界框的位置。

Model:GetExtentsSize

返回包含所有 `Class.BasePart|BaseParts` 的模型的最小边界框的大小，
与设置的 `Class.Model.PrimaryPart` 对齐。

该值历史上返回模型中心位置的 CFrame。

Model:GetModelCFrame

这段代码会创建一个模型，将一些零件放入其中，随机定位它们，
然后打印其大小：

GetModelSize 函数返回 `Class.Model` 的 `Datatype.Vector3` 尺寸。

Model:GetModelSize

当此方法在 `Class.Script` 中调用时，返回所有与该模型持久的
`Class.Player` 对象。当从 `Class.LocalScript` 调用时，
此方法仅检查此模型是否对 `Class.Players.LocalPlayer|LocalPlayer` 持久。

Model:GetPersistentPlayers

一个表，包含所有对该模型对象持久的 `Class.Player` 对象。

返回所有对该模型对象持久的 `Class.Player` 对象。
行为根据该方法是在 `Class.Script` 还是 `Class.LocalScript` 中调用而有所不同。

以下代码演示了如何使用 GetPrimaryPartCFrame 和
SetPrimaryPartCFrame 来旋转模型。

在 Workspace 中创建一个简单的模型，并启动一个循环，
每 0.2 秒将该模型绕 Y 轴旋转 10 度。

此函数已被 `Class.PVInstance:GetPivot()` 取代，作为替代品并且并不改变您的代码行为。
请使用 `Class.PVInstance:GetPivot()` 进行新工作，并在方便时迁移您现有的
`Class.Model:GetPrimaryPartCFrame()` 调用。

返回模型的 `Class.Model.PrimaryPart` 的 `Datatype.CFrame`。

此函数等同于以下内容：

    Model.PrimaryPart.CFrame

请注意，如果该 `Class.Model` 没有主部件，则此函数将引发错误。
如果不希望发生此行为，开发人员可以执行以下操作：
这将等于 `nil`（如果没有主部件）。

    local cFrame = Model.PrimaryPart and Model.PrimaryPart.CFrame

Model:GetPrimaryPartCFrame

返回模型的 `Class.Model.PrimaryPart` 的 `Datatype.CFrame`。
如果该 `Class.Model` 没有主部件，则此函数将引发错误。

此代码示例演示了如何使用 `Class.Model:PivotTo()` 和 `Class.Model:ScaleTo()` 替换所有树模型的副本。模型的中心点和缩放作为参考，确保替换模型的相对大小和位置与原模型匹配。


模型包含一个持久的规范缩放因子，对新创建的模型初始值为 1，
并在通过调用 `Class.Model:ScaleTo()` 缩放模型时改变。此函数返回当前模型的规范缩放因子。

当前缩放因子并不直接影响模型下实例的大小。它用于内容创作和脚本
目的，以记住模型相对于其原始大小的缩放状态。

在给定会话内，模型将在首次调用 `Class.Model:ScaleTo()` 后
缓存子代实例的精确原始大小信息。这意味着调用
`Class.Model:ScaleTo()|ScaleTo(x)` 后跟
`Class.Model:ScaleTo()|ScaleTo(1)` 将精确恢复模型的
原始配置，而不产生浮点漂移。避免浮点漂移是使用 Scale**To** 函数而不是 Scale**By** 函数的原因。

缩放因子确实在一个方面影响引擎行为：模型的缩放因子将被应用于在
该模型下的 `Class.Animation|Animations` 的关节偏移，以便动画装置即使在缩放的情况下也能正确地播放动画。

Model:GetScale

返回模型的规范缩放，默认值为 1，对于新创建的模型，并且在通过
`Class.Model:ScaleTo()` 缩放时会发生变化。

这个代码示例演示了如何使用
Model:MakeJoints 函数制作关节。

创建一个模型，里面有两个部分叠加在一起。上面的部分是
固定的，而下面的部分则不是。通常，当它们被父级质量放到工作区时，
底部的部分会掉到基板上。

然而，由于下面部分的 TopSurface 属性被设置为
Enum.SurfaceType.Weld，这意味着当 Model:MakeJoints 被执行时，它们之间会建立连接。

因此，底部的部分不会掉落，直到模型中的关节被
打断。这通常是使用 Model:BreakJoints 来完成的，但在这个示例中，
连接是通过爆炸来打断的。

此代码示例演示了在两个与脚本同级的部件（PartA 和 PartB）上创建关节。它使用 MakeJoints 在两个具有兼容表面类型（Studs 和 Inlet）的接触部件上。

基于表面类型的连接已弃用。请勿在新项目中使用 MakeJoints。
请使用 `Class.WeldConstraint|WeldConstraints` 和 `Class.HingeConstraint|HingeConstraints`。

遍历 `Class.Model` 中所有的 `Class.BasePart|Parts`，并在指定部件与任何平面接触表面之间创建关节，
具体取决于部件的表面。

- 光滑表面将不会创建关节
- 胶水表面将创建一个 `Class.Glue` 关节
- 焊接将与任何表面创建 `Class.Weld` 关节，除了不可连接
- Studs、Inlet 或 Universal 将各自与其他两个表面（例如，Studs 与 Inlet 和 Universal）创建一个 `Class.Snap` 关节
- 铰链和电机表面创建 `Class.Rotate` 和 `Class.RotateV` 关节实例

如果部件不是 `Class.Workspace` 的子代，则此函数不起作用。
因此，您必须确保模型首先被父级到工作区，然后再使用 MakeJoints。

Model:MakeJoints

遍历 `Class.Model` 中所有的 `Class.BasePart|BaseParts`。如果任何部件的侧面具有可以
生成关节的 SurfaceType，则将与任何相邻部件创建关节。

Model:makeJoints

Model:move

location

此示例演示了 `Class.Model:MoveTo()` 如何避免碰撞。

创建了一个简单的两部分 `Class.Model`，并设置了它的 `Class.Model.PrimaryPart`。
在旁边放置了一个大型障碍物部件。

5秒后，使用 `Class.Model:MoveTo()` 来指示模型移动
进入障碍物部件。然而，由于 MoveTo 不会将模型移动到障碍物内，
因此 `Class.Model` 被向 Y 轴上移动，放置在障碍物上方。


将 `Class.Model.PrimaryPart|PrimaryPart` 移动到给定位置。如果
未指定主部件，将使用模型的根部件，但根部件是非确定性的，建议您在使用 `Class.Model:MoveTo()|MoveTo()` 时始终设置主部件。

如果模型要移动到的位置有任何障碍，例如 `Class.Terrain` 或其他 `Class.BasePart|BaseParts`，模型将垂直向上移动
直到没有障碍物。如果不希望出现这种行为，则应使用 `Class.PVInstance:PivotTo()`。

请注意，使用 `Class.Model:MoveTo()|MoveTo()` 移动模型时不会保持旋转。
如果需要保持模型的当前旋转，建议使用 `Class.Model:TranslateBy()|TranslateBy()` 或 `Class.PVInstance:PivotTo()`。

Model:MoveTo

position

将 `Class.Model.PrimaryPart|PrimaryPart` 移动到给定位置。如果
未指定主部件，将使用模型的根部件。

Model:moveTo

使此模型对指定玩家不再持久。这并不保证该模型会立即从
玩家处移除；在调用此方法后，该模型将视为 `Enum.ModelStreamingMode|Atomic`，
只要仍在目标流媒体半径内便保持存在。

`Class.Model.ModelStreamingMode|ModelStreamingMode` 必须设置为
`Enum.ModelStreamingMode|PersistentPerPlayer`，以便由于移除而改变行为。

Model:RemovePersistentPlayer

使此模型不再对其持久的 `Class.Player`。

使此模型对指定玩家不再持久。
`Class.Model.ModelStreamingMode|ModelStreamingMode` 必须设置为
`Enum.ModelStreamingMode|PersistentPerPlayer`，以便由于移除而改变行为。

将模型部件的旋转重置为先前设置的身份旋转，通过 `Class.Model:SetIdentityOrientation()`
方法完成。

Model:ResetOrientationToIdentity

模型包含一个持久的规范缩放因子，对新创建的模型初始值为 1。
该函数在枢轴位置周围缩放模型，考虑它在缩放因子为 1 时的外观。为实现此目的，它做两件事情：

- 将模型当前缩放因子设置为指定值
- 相应地调整所有子代实例的大小和位置

位置的缩放围绕枢轴位置进行。

所有子代实例的"几何"属性都会进行缩放。这显然包括部件的大小，
但以下是一些其他会被缩放的属性示例：

- 像 `Class.WeldConstraint|WeldConstraints` 和 `Class.RopeConstraint` 之类的关节长度
- 像 `Class.HingeConstraint` 之类的物理速度和力量
- 像粒子发射器大小之类的可视属性
- 其他长度属性，如 `Class.Sound.RollOffMinDistance`

Model:ScaleTo

newScaleFactor

设置模型的缩放因子，调整所有子代实例的大小和位置，使它们的缩放因子相对于
初始大小和位置（当时缩放因子为 1）。

设置给定模型的身份旋转，允许您稍后通过 `ResetOrientationToIdentity` 方法重置整
个模型的旋转。

Model:SetIdentityOrientation

此函数已被 `Class.PVInstance:PivotTo()` 取代，作为更高效的替代品并且并不改变您
的代码的行为。请使用 `Class.PVInstance:PivotTo()` 进行新工作，并在方便时迁移您现有的
`Class.Model:SetPrimaryPartCFrame()` 调用。

设置模型的 `Class.Model.PrimaryPart` 的 `Class.BasePart.CFrame`。
模型中的所有其他部分也将移动，并保持其相对于 `Class.Model.PrimaryPart` 的方向和偏移。

请注意，如果模型没有 `Class.Model.PrimaryPart`，此函数将引发错误。这可能会导致问题，例如，当主部件从未设置或已被销毁时。

Model:SetPrimaryPartCFrame

cframe

设置模型的 `Class.Model.PrimaryPart` 的 `Class.BasePart.CFrame`。
模型中的所有其他部分也将移动，并保持其相对于 `Class.Model.PrimaryPart` 的方向和偏移。

此示例演示了 `Class.Model:TranslateBy()` 如何忽略碰撞
并尊重模型的方向。

创建了一个简单的两个部分的 `Class.Model`，在 Y 轴上旋转 45 度，
并设置了它的 `Class.Model.PrimaryPart`。一个大的障碍部分被放置
在它旁边。

在 5 秒后，使用 `Class.Model:TranslateBy()` 指示模型
向障碍部分内部移动。模型将移动到障碍内并保持其当前的方向。


通过给定的 `Datatype.Vector3` 偏移移动 `Class.Model`，保持模型的方向。
如果新位置已经有其他 `Class.BasePart` 或 `Class.Terrain`，则 `Class.Model` 将与该对象重叠。

此移动在世界空间中进行，而不是对象空间，这意味着即使模型的部件方向不同，
它仍然会沿着标准轴移动。

Model:TranslateBy

delta

将 `Class.Model` 移动的 `Datatype.Vector3`。

通过给定的 `Datatype.Vector3` 偏移移动 `Class.Model`，保持模型的方向。如果新位置已经有其他 `Class.BasePart` 或
`Class.Terrain`，则 `Class.Model` 将与该对象重叠。

Model

设置启用了实例
[流式传输](/workspace/streaming) 的模型的细节级别。复合或
伪装网格不支持物理、碰撞检测或
光线投射。

当设置为 `Enum.ModelLevelOfDetail|StreamingMesh` 时，较低分辨率的
"伪装"网格（有色、粗糙的网格包裹在模型的所有子部件周围）在流式半径外渲染。 不支持
纹理。

当设置为 `Enum.ModelLevelOfDetail|SLIM` 时，一个 **SLIM** 模型（可缩放
轻量级交互模型）在基于流式
半径的距离以逐渐较低的分辨率渲染所有子部件的复合。这对于视觉质量的提升远超
`Enum.ModelLevelOfDetail|StreamingMesh`。 

当设置为 `Enum.ModelLevelOfDetail|Disabled` 或
`Enum.ModelLevelOfDetail|Automatic` 时，将不显示较低分辨率的网格。


Model.LevelOfDetail

为实例流媒体启用的体验设置模型的细节级别。

控制启用实例 [流媒体](/workspace/streaming) 时 `Class.Model|Models` 的流入和流出。
行为取决于所选的枚举。未启用流媒体时没有效果。

只有在启用流媒体时，这个属性应在 Studio 中通过
[属性](/studio/properties)窗口进行更改，或者在 `Class.Script|Scripts` 中，
但绝不要在 `Class.LocalScript|LocalScripts` 中进行更改（这样做可能导致未定义行为）。

Model.ModelStreamingMode

在启用实例流媒体时控制 `Class.Model|Models` 的流媒体行为。

这段代码示例创建并投掷一个骰子模型，然后输出它是否以蓝色面朝上落地。如果 `Class.Model.PrimaryPart` 没有设置，骰子的支点/边界框将旋转，因为里面的部分在掷骰子时是物理模拟的。

指向 `Class.Model` 的主部件。主部件是作为模型枢轴的
物理参考的 `Class.BasePart`。也就是说，当模型内的部件因物理
仿真或其他原因移动时，枢轴将与主部件同步移动。

请注意，`Class.Model|Models` 默认情况下没有设置 `PrimaryPart`。
如果您正在创建一个需要通过物理进行操作的模型，您应
在 Studio 中或在脚本内手动设置此属性。如果 **未** 设置主部件，
即使模型内的部件被移动，枢轴也将保持在世界空间的同一位置。

还要注意，设置此属性时，它必须是模型的子代的 `Class.BasePart`。
如果您尝试将 `Class.Model.PrimaryPart` 设置为 **不是** 模型子代的 `Class.BasePart`，则它将被设置为该部件，但在下一个模拟步骤中重置为 `nil` — 这是为了支持脚本，假设它们可以暂时将主部件设置为不是模型子代的 `Class.BasePart`。

模型的一般规则是：

- 通过物理关节（如 `Class.WeldConstraint|WeldConstraints` 或 `Class.Motor6D|Motor6Ds`）连接在一起的模型
  应该分配一个主部件。例如，Roblox 角色模型默认将其 `Class.Model.PrimaryPart` 设置为
  **HumanoidRootPart**。
- 静态模型（通常是 `Class.BasePart.Anchored|Anchored`）在没有脚本明确移动时保持在一处，
  不需要 `Class.Model.PrimaryPart`，并且往往不会受益于设置。

Model.PrimaryPart

模型的主部件，如果未明确设置则为 `nil`。

在属性窗口中设置此属性将使模型缩放，仿佛调用了 `Class.Model:ScaleTo()`，
缩放模型中的所有子代实例，如材料、图像和部件的 3D 几何，使模型相对于其
原始大小具有指定的缩放因素。

此属性仅在 Studio 中可用，并且在 `Class.Script` 或 `Class.LocalScript` 中使用将产生错误。
`Class.Model:ScaleTo()` 和 `Class.Model:GetScale()` 应在脚本中使用。

Model.Scale

仅限于编辑器的属性，用于围绕其枢轴缩放模型。设置
此属性将使缩放像是调用了 `Class.Model:ScaleTo()`。 

此代码示例显示了一个自定义函数，用于将模型的支点重置回该模型的边界框中心。

此属性确定没有设置 `Class.Model.PrimaryPart` 的 `Class.Model` 的枢轴位置。如果 `Class.Model` **确实** 有一个 `Class.Model.PrimaryPart|PrimaryPart`，
则 `Class.Model` 的枢轴与该主部件的枢轴相同，而忽略此 `Class.Model.WorldPivot|WorldPivot` 属性。

对于新创建的 `Class.Model`，在首次设置其 `Class.Model.WorldPivot` 属性之前，
其枢轴将被视为其内容的边界框的中心。一旦首次设置世界枢轴，便无法恢复此初始行为。

通常，通过 Studio 工具移动模型，或者使用模型移动函数如 `Class.PVInstance:PivotTo()` 和 `Class.Model:MoveTo()`，
将设置世界枢轴，从而结束此新模型行为。

此行为的目的是允许 Luau 代码通过仅创建新模型并将对象父级到其中，
即可获取合理的枢轴，避免每次在代码中创建模型时都需要显式设置 `Class.Model.WorldPivot`。

```
local Workspace = game:GetService("Workspace")

local model = Instance.new("Model")
Workspace.BluePart.Parent = model
Workspace.RedPart.Parent = model
model.Parent = Workspace

print(model:GetPivot())  -- 目前等于包含 "BluePart" 和 "RedPart" 的边界框的中心

model:PivotTo(CFrame.new(0, 10, 0))  -- 这在不需要显式设置 "model.WorldPivot" 的情况下有效
```

Model.WorldPivot

确定没有设置 `Class.Model.PrimaryPart` 的 `Class.Model` 的枢轴位置。

模型是容器对象，意味着它们将对象组合在一起。它们
最适合用于保存 `Class.BasePart|BaseParts` 的集合，并具有多个
扩展其功能的功能。

一个 `Class.PVInstance` 是一个不能被创建的抽象类。它是
所有在世界中具有物理位置的对象的基础。


这个代码示例是一个简单的传送脚本，当你按下 <kbd>F</kbd> 键时，它会将你的角色向你当前面朝的方向移动 10&nbsp;studs。它通过获取当前的枢轴 `Class.PVInstance:GetPivot()` 并调用 `PVInstance|PivotTo` 来将角色向前移动。

此函数获取 `Class.PVInstance` 的枢轴。这通常与
`Class.PVInstance:PivotTo()` 一起使用以移动模型。

`Class.Model|Models` 和 `Class.BasePart|BaseParts` 都是
`Class.PVInstance|PVInstances`（"位置速度实例"），因此两者
都有此函数。


PVInstance:GetPivot

沿着其所有后代 `Class.PVInstance|PVInstances` 转换 `Class.PVInstance`，使得枢轴现在位于指定的 `Datatype.CFrame`。这是主要的函数，应
用于通过脚本移动 `Class.Model|Models`。

`Class.BasePart|BaseParts` 是通过对其 `Datatype.CFrame` 进行所需的偏移变换来移动的。
`Class.Model|Models` 是通过对其 `Class.Model.WorldPivot` 进行所需的偏移变换来移动的。

请注意，出于效率考虑，`Class.Object.Changed` 事件不会
为以这种方式移动的 `Class.BasePart.Position|Position` 和
`Class.BasePart.Orientation|Orientation` 触发；它们仅为 `Datatype.CFrame` 触发。

当在 `Class.Model|Models` 上调用 `Class.PVInstance:PivotTo()|PivotTo` 时，后代部件和模型的偏移量被缓存，
以便对同一模型的后续 `Class.PVInstance:PivotTo()|PivotTo` 调用不会导致构成模型的部件之间的浮点漂移。

`Class.Model|Models` 和 `Class.BasePart|BaseParts` 都是
`Class.PVInstance|PVInstances`（"位置速度实例"），因此两者
都有此函数。


PVInstance:PivotTo

targetCFrame

移动后 `Class.PVInstance` 的枢轴应该等于的 `Datatype.CFrame`。


沿着其所有后代 `Class.PVInstance|PVInstances` 转换 `Class.PVInstance`，使得枢轴现在位于指定的 `Datatype.CFrame`。


PVInstance

PVInstance.Origin

PVInstance.Pivot Offset

所有在世界中具有物理位置的对象的抽象类。


`Instance` 是 Roblox 类层次结构中所有类的基类
可以成为 `Class.DataModel` 树的一部分。

无法直接创建根 `Instance` 对象，但特殊的
`Datatype.Instance.new()` 构造函数通过代码创建对象，
以类的名称作为参数并返回创建的对象。

演示通过连接到
`Class.Instance.AncestryChanged` 事件来检测实例祖先的变化。

ChangingPart 的父级随着时间的推移而设置为不同的值。该零件的父级是该零件的祖先，因此
`Class.Instance.AncestryChanged` 事件将在每次变化时触发。


当此实例被重新设置父级或其任何祖先被重新设置父级时触发。

您可以使用此事件跟踪 Studio 中实例的删除，例如通过资源管理器手动删除或通过插件删除。如果您需要检测实例是否通过 `Class.Instance:Destroy()` 被销毁，请使用 `Class.Instance.Destroying` 事件。

Instance.AncestryChanged

child

更改了 `Class.Instance.Parent|Parent` 属性的实例，可以是此实例或更远的祖先，**不**一定是与处理程序连接的实例。

parent

当此对象或其祖先的 `Class.Instance.Parent` 属性被更改时触发。

每当实例上的任何属性被更改时触发，包括当某个属性被设置为 `nil`。更改的属性名称会传递给连接的函数。

例如，以下代码片段将 `attributeChanged()` 函数连接到每当部分的一个属性更改时触发：

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)
```
另请参见 `Class.Instance:GetAttributeChangedSignal()`，此方法返回一个事件，当特定给定属性更改时触发。

Instance.AttributeChanged

attribute

每当在 `Class.Instance` 上更改属性时触发。

此代码段打印添加到工作区的对象名称：

在对象被设置为此 `Class.Instance` 的父级后触发。

注意，当在客户端使用此方法检测由服务器创建的对象时，索引这些对象的后代时必须使用 `Class.Instance:WaitForChild()`。这是因为对象及其后代不能保证同时从服务器复制到客户端。例如：

```
local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- 使用 WaitForChild() 因为后代可能尚未复制
	local head = child:WaitForChild("Head")
end)
```
注意，此事件仅对 `Class.Instance` 的直接子项起作用。要捕获所有后代的事件，请使用 `Class.Instance.DescendantAdded`。

另请参见 `Class.Instance.ChildRemoved`。

Instance.ChildAdded

在对象被设置为此 `Class.Instance` 的父级后触发。

Instance.childAdded

这个代码片段会在对象从工作区中移除时打印它们的名称：

在子项从此 `Class.Instance` 中移除后触发。

移除是指将一个对象的父级从这个 `Class.Instance` 更改为与这个 `Class.Instance` 不同的东西。请注意，当子项被销毁时（使用 `Class.Instance:Destroy()`），此事件也将触发，因为销毁函数将对象的父级设置为 `nil`。

此事件仅对 `Class.Instance` 的直接子项起作用。要捕获所有后代的事件，请使用 `Class.Instance.DescendantRemoving`。

另请参见 `Class.Instance.ChildAdded`。

Instance.ChildRemoved

在子项从此 `Class.Instance` 中移除后触发。

以下示例将打印添加到
工作区的任何对象的名称：


此事件在后代被添加到 `Class.Instance` 后触发。

由于它对每个后代触发，将对象设置为 `Class.Instance` 的父级将分别触发此对象及其所有后代的事件。

如果您只关心 `Class.Instance` 的 **直接子项**，请使用 `Class.Instance.ChildAdded`。 

另请参见 `Class.Instance.DescendantRemoving`。

Instance.DescendantAdded

descendant

在后代被添加到 `Class.Instance` 后触发。

以下示例在一个后代被移除时打印其名称
从工作区:

此事件在父级 `Class.Instance` 更改时 **立即之前** 触发，以至于 **后代** 实例将不再是后代。`Class.Instance:Destroy()|Destroy()` 将实例的 `Class.Instance.Parent|Parent` 更改为 `nil`，因此在父级的后代上调用该方法将导致触发此事件。

因为此事件在后代移除 **之前** 触发，所以在此事件触发时，后代的父级不会改变。如果后代也是父级的 **直接子项**，则此事件会在 `Class.Instance.ChildRemoved` 之前触发。

如果后代有子项，此事件会先触发后代，然后是其后代。

#### 警告

此事件与被移除的后代对象一起触发。尝试将后代的 `Class.Instance.Parent|Parent` 设置为其他内容将失败。下面是一个演示的示例：

```
local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- 请勿在此函数中操作后代的父级！
	-- 此事件之所以触发是因为父级被操作，而更改尚未发生
	-- 因此，像这样更改父级是有问题的：
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```
另请参见 `Class.Instance.DescendantAdded|DescendantAdded`。

Instance.DescendantRemoving

在 `Class.Instance` 的后代被移除之前立即触发。

此示例演示了当使用即时信号行为时，
实例被销毁时仍保持在原位，直到连接的函数挂起。


此示例演示了如何在使用推迟信号行为时，在信号触发之前销毁实例。


连接的函数在使用时，`Class.Instance` 将永远不会从内存中删除。然而，如果函数在任何时候挂起，则 `Class.Instance` 及其后代将被设置为 `nil`。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Immediate`，则此事件将在 `Class.Instance` 或其任一祖先被使用 `Class.Instance:Destroy()` 销毁之前立即触发。

如果 `Class.Workspace.SignalBehavior` 属性设置为 `Enum.SignalBehavior.Deferred`，则此事件将在下一个恢复点触发，这将在 `Class.Instance` 或其任一祖先被使用 `Class.Instance:Destroy()` 销毁之后。

使用 `Enum.SignalBehavior.Deferred|Deferred` 行为，将脚本连接到其自己的 `Class.Instance.Destroying` 事件是有问题的，因为脚本将在回调被调用之前被销毁（这意味着它将无法执行）。

在 Studio 中删除 `Class.Instance` 时，例如通过 [Explorer](/studio/explorer) 手动删除或通过插件删除，`Class.Instance` 不会被销毁。相反，父级设置为 `nil`，您可以通过 `Class.Instance.AncestryChanged` 跟踪。

Instance.Destroying

在实例通过 `Class.Instance:Destroy()` 被销毁之前立即触发（或推迟到之后）。

此事件在实例上的任何样式属性被更改时触发，包括当某个属性被设置为 `nil`。

```lua
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("样式属性已更改")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```

Instance.StyledPropertiesChanged

每当实例上的任何样式属性被更改时触发，包括当某个属性被设置为 `nil`。

此方法将标签应用于实例，如果标签已被应用，则不会产生影响。
成功添加标签将触发由 `Class.CollectionService:GetInstanceAddedSignal()` 创建的信号，
并附有给定的标签。

#### 警告

- 客户端添加的实例标签将被丢弃，如果服务器后续在该实例上添加或移除标签，
因为服务器会将所有标签一起复制并覆盖先前的标签。

- 在为实例添加标签时，通常会使用一些资源为标签提供功能，例如事件连接或表。
为防止内存泄露，最好在不再需要标签时进行清理（断开连接，
设置为 `nil` 等）。在调用 `Class.Instance:RemoveTag()`、
调用 `Class.Instance:Destroy()` 或在连接到 `Class.CollectionService:GetInstanceRemovedSignal()` 返回的信号的函数中这么做。

Instance:AddTag

子项函数返回对象的子项数组。

Instance:children

此方法销毁实例的所有子项和后代。

```
local part = Instance.new("Part")

-- 添加一些闪光
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```
如果您不想销毁 **所有** 子项和后代，请使用 `Class.Instance:GetChildren()` 或 `Class.Instance:GetDescendants()`
循环遍历这些子项/后代并选择需要销毁的内容。
例如以下代码示例将销毁从 `Class.Model` 下降的所有 `Class.BasePart|BaseParts`：

```
local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```

Instance:ClearAllChildren

演示如何使用 `Class.Instance:Clone()` 克隆一个模型。

`Clone()` 创建实例及其所有后代的副本，
忽略所有不是 `Class.Instance.Archivable|Archivable` 的实例。根实例的副本由此方法返回，
并将其 `Class.Instance.Parent|Parent` 设置为 `nil`。注意，如果实例本身
的 `Class.Instance.Archivable|Archivable` 设置为 `false`，该方法将返回 `nil`。

如果在克隆的实例中设置了如 `Class.ObjectValue.Value` 的引用属性，
则副本的属性值取决于原始值：

- 如果引用属性指向的实例 **也** 被克隆，副本将指向副本。
- 如果引用属性指向的实例 **未** 被克隆，副本将保持相同的值。

Instance:Clone

创建实例及其所有后代的副本，忽略不
是 `Class.Instance.Archivable|Archivable` 的实例。

Instance:clone

演示使用 `Class.Instance:Destroy()` 函数销毁一个 Part。

该函数是处理不再需要的对象的正确方法。


将 `Class.Instance.Parent` 属性设置为 `nil`，锁定
`Class.Instance.Parent` 属性，断开所有连接，并对所有子项调用
`Destroy()`。此方法是处理不再需要的对象的正确方法。

处理不需要的对象非常重要，因为不必要的对象和连接会消耗内存，
这可能导致长期的严重性能问题。

最好在对对象调用 `Destroy()` 后，将引用该对象（或其后代）的任何变量设置为 `nil`。这可防止您的代码访问与该对象相关的任何内容。

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- 不要这样做：
print(part.Name)  --> "Hello, world"
-- 这样做可以防止上面的代码继续工作：
part = nil
```
一旦通过此方法销毁了 `Class.Instance`，便无法重复使用它，因为 `Class.Instance.Parent` 属性被锁定。要**暂时**移除对象而不是销毁它，请将
`Class.Instance.Parent|Parent` 设置为 `nil`。例如：

```
local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```
要在设定时间后销毁对象，请使用 `Class.Debris:AddItem()`。

Instance:Destroy

将 `Class.Instance.Parent` 属性设置为 `nil`，锁定
`Class.Instance.Parent` 属性，断开所有连接，并对所有子项调用
`Destroy()`。

Instance:destroy

返回 `Class.Instance` 的第一个祖先，
其 `Class.Instance.Name` 与给定名称相等。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

以下代码片段将查找名为 `Car` 的对象的第一个祖先。

```
local car = object:FindFirstAncestor("Car")
```
有关查找特定类的祖先的此方法的变体，请参见 `Class.Instance:FindFirstAncestorOfClass()` 和
`Class.Instance:FindFirstAncestorWhichIsA()`。

Instance:FindFirstAncestor

name

返回 `Class.Instance` 的第一个祖先，
其 `Class.Instance.Name` 与给定名称相等。

返回 `Class.Instance` 的第一个祖先，
其 `Class.Object.ClassName` 与给定的 className 相等。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

此方法的常见用途是查找 `Class.BasePart` 所属的 `Class.Model`。例如：

```
local model = part:FindFirstAncestorOfClass("Model")
```
此方法是 `Class.Instance:FindFirstAncestor()` 的变体，检查的是 `Class.Object.ClassName` 属性，而不是 `Class.Instance.Name`。
`Class.Instance:FindFirstAncestorWhichIsA()` 也存在，使用 `Class.Object:IsA()` 方法来尊重类继承。

Instance:FindFirstAncestorOfClass

className

返回 `Class.Instance` 的第一个祖先，
其 `Class.Object.ClassName` 与给定的 className 相等。

返回 `Class.Instance` 的第一个祖先，
对于给定的 className，`Class.Object:IsA()` 返回 true。

该方法向上工作，意味着它从实例的直接 `Class.Instance.Parent` 开始，
向上到 `Class.DataModel`。如果未找到匹配的祖先，则返回 `nil`。

与 `Class.Instance:FindFirstAncestorOfClass()` 不同，此方法使用 `Class.Object:IsA()` 来尊重类继承。例如：

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```
因此，以下代码示例将返回第一个 `Class.BasePart` 祖先，无论它是否为 `Class.WedgePart`、`Class.MeshPart` 还是 `Class.Part`。

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```
另请参见 `Class.Instance:FindFirstAncestor()`。

Instance:FindFirstAncestorWhichIsA

返回 `Class.Instance` 的第一个祖先，
对于给定的 className，`Class.Object:IsA()` 返回 true。

下面的代码将在工作区中查找名为“Brick”的对象。如果找到，它将把该对象的名称更改为“Foo”。

返回具有给定名称的 `Class.Instance` 的第一个子项，如果没有此类子项，则返回 `nil`。如果可选的 `recursive` 参数为 `true`，
此方法将搜索所有后代，而不仅仅是 `Class.Instance` 的直接子项。

#### 检查对象的存在性

如果需要验证对象是否存在，则必须使用 `FindFirstChild()`。
尝试使用点操作符索引不存在的子项将引发错误。

```lua
local Workspace = game:GetService("Workspace")

-- 如果部件在工作区中不存在，以下行会出错
Workspace.Part.Transparency = 0.5
```
更好的方法是在先检查 `Part` 的情况下使用 `FindFirstChild()`，
然后使用 `if` 语句运行需要它的代码。

```lua
local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### 查找名称与属性匹配的子项

有时，对象的 `Class.Instance.Name|Name` 与其 `Class.Instance.Parent|Parent` 的属性相同。
使用点操作符时，如果属性和子项共享名称，属性将优先于子项。

在以下示例中，一个名为 `Color` 的 `Class.Folder` 被添加到一个 `Class.Part`，
该部分也具有 `Class.Part.Color` 属性。注意，`part.Color` 指的是 `Datatype.Color3` 属性值，而不是子 `Class.Folder` 实例。

使用 `Class.Instance:FindFirstChild()|FindFirstChild()` 的好处是，
引入新属性不会对您的代码构成风险。

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- 属性
local c2 = part:FindFirstChild("Color")  -- 子文件夹
```

#### 性能注意事项

`Class.Instance:FindFirstChild()|FindFirstChild()` 比直接使用点操作符慢约 20%
，并且几乎是简单存储对对象的引用所需时间的 8 倍。
因此，您应该避免在性能依赖的代码中（例如紧循环或连接到 `Class.RunService.Heartbeat` 和 `Class.RunService.PreRender` 的函数）调用它。
相反，请将结果存储在变量中，或考虑使用 `Class.Instance.ChildAdded|ChildAdded` 或
`Class.Instance:WaitForChild()|WaitForChild()` 来检测特定名称的子项何时可用。

Instance:FindFirstChild

recursive

返回以给定名称找到的 `Class.Instance` 的第一个子对象。

Instance:findFirstChild

返回 `Class.Instance` 的第一个子项，
其 `Class.Object.ClassName|ClassName` 等于给定的 `className`。
与 `Class.Instance:FindFirstChildWhichIsA()` 不同，此方法仅返回类与 `className` 匹配的对象，忽略类继承。如果没有找到匹配的子项，
此方法返回 `nil`。

Instance:FindFirstChildOfClass

返回 `Class.Instance` 的第一个子项，
其 `Class.Object.ClassName|ClassName` 等于给定类名称。

返回 `Class.Instance` 的第一个子项，
其 `Class.Object:IsA()` 对于给定的 className 返回 true。

如果没有找到匹配的子项，此方法返回 `nil`。如果可选的 `recursive` 参数为 true，
此方法将搜索所有后代，而不仅仅是 `Class.Instance` 的直接子项。

与 `Class.Instance:FindFirstChildOfClass()` 不同，此方法使用 `Class.Object:IsA()` 来尊重类继承。例如：

```lua
print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true
```
因此，以下代码示例将返回第一个 `Class.BasePart` 子项，无论它是否为 `Class.WedgePart`、
`Class.MeshPart` 还是 `Class.Part`。

```
local part = object:FindFirstChildWhichIsA("BasePart")
```
寻找子项时，开发人员应使用 `Class.Instance:FindFirstChild()`。

Instance:FindFirstChildWhichIsA

返回 `Class.Instance` 的第一个子项，
其 `Class.Object:IsA()` 对于给定的 className 返回 true。

返回具有给定 `Class.Instance.Name` 的第一个后代。

此方法被禁用，无法使用。要查找实例的第一个后代，
请考虑使用 `Class.Instance:FindFirstChild()` 的 `recursive` 参数。

Instance:FindFirstDescendant

返回具有给定 `Class.Instance.Name` 的第一个后代。

Instance

`Instance` 是 Roblox 类层次结构中所有类的基类
可以成为 `Class.DataModel` 树的一部分。