HopperBins 是一种过时的工具创建系统，可以被玩家使用。请使用 `Class.Tool` 代替 HopperBins。

历史上，只有 HopperBins 在没有 'Handle' `Class.Part` 的情况下能够工作，但
由于 Tools 的 `Class.Tool.RequiresHandle` 属性，这不再是事实。


HopperBin.Deselected

HopperBin.Selected

mouse

HopperBin

HopperBin.Active

HopperBin.BinType

BackpackItem是一个抽象类，用于背包物品，如HopperBins和
工具。


BackpackItem

在玩家背包中显示的工具的纹理图标。

此属性应设置为上传到Roblox网站的图像的内容ID。
仅支持资产URI。

如果此属性留空，`Class.Backpack` GUI将显示
工具的名称。


BackpackItem.TextureContent

在玩家背包中显示的工具的纹理图标。
仅支持资产URI。


在玩家背包中显示的工具的纹理图标。

此属性应设置为上传到Roblox网站的图像的内容ID。

如果此属性留空，`Class.Backpack` GUI将显示
工具的名称。


BackpackItem.TextureId

在玩家背包中显示的工具的纹理图标。


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


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

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

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

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

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

与所有 `Class.Instance` 类型一样，父 `Class.Model` 被复制到客户端并不保证
所有子对象都被复制。如果这些实例被客户端上运行的代码访问，尤其是在 `Class.LocalScript` 中，这一点尤其重要。
使用 `Class.Model.ModelStreamingMode|ModelStreamingMode` 的值如
`Enum.ModelStreamingMode|Atomic` 可以确保如果父模型存在于客户端，则整个模型及其所有后代都存在，或者在不需要原子性的情况下可以使用 `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:GetBoundingBox()`。


此函数返回包含 `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`。


Model:GetBoundingBox

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


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


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


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

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


Model:GetExtentsSize

包含 `Class.Model` 的 `Datatype.Vector3` 尺寸。


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


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


Model:GetModelCFrame

一个 `Datatype.CFrame`，表示模型中的中心位置。


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


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

请注意，如果模型没有主部件，则此函数将抛出错误。如果不希望出现此行为，开发者可以执行以下操作，如果没有主部件，则将等于 `nil`。

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


Model:GetPrimaryPartCFrame

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


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


此代码示例演示了如何使用 `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 函数制作关节。

一个模型被实例化，上面有两个部分。顶部部分是
固定的，底部部分则不是。通常，当被父级设置为 Workspace 时，
底部部分会掉落到基板上。

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

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


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

基于 SurfaceType 的连接已被弃用。请勿在新项目中使用 MakeJoints。请改用 `Class.WeldConstraint|WeldConstraints` 和
`Class.HingeConstraint|HingeConstraints`。

遍历 `Class.Model` 中的所有 `Class.BasePart|Parts`，并根据部件的表面在指定部件和任何平面接触表面之间创建关节。

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

如果部件不是 `Class.Workspace` 的子代，则此函数不起作用。因此，您必须首先确保模型被放置在 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 表示模型的原始大小。


设置模型的缩放因子，调整所有子实例的大小和位置，使它们相对于初始大小和位置具有该缩放因子，当时缩放因子为 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/properties) 窗口在 Studio 中更改，或在 `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`。


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

实例枢轴的世界空间 `Datatype.CFrame`。


沿着其所有后代 `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

仅限编辑器的属性，在 Studio 属性窗口中显示为 **原点位置** 和 **原点方向**，位于 **变换** 下。它的值是实例枢轴的世界空间 `Datatype.CFrame`；读取它返回与 `Class.PVInstance:GetPivot()` 相同的 `Datatype.CFrame`。它没有自己的存储值，并始终反映当前的枢轴。

从属性窗口设置它会移动整个实例，使其枢轴位于新的 `Datatype.CFrame`，类似于 `Class.PVInstance:PivotTo()`。通过属性窗口进行编辑会暂时禁用 `Class.WeldConstraint|WeldConstraints` 对其他对象的移动；`PivotTo` 不会修改关节。

不适用于脚本；请在运行时使用 `Class.PVInstance:GetPivot()` 和 `Class.PVInstance:PivotTo()`。


PVInstance.Origin

仅限编辑器的属性，用于读取和设置 `Class.PVInstance` 的世界 `Datatype.CFrame` 的枢轴，当从 Studio 属性窗口更改时，移动整个实例。


仅限编辑器的属性，在 Studio 属性窗口中显示为 **枢轴位置** 和 **枢轴方向**，位于 **枢轴** 下。它是相对于实例自身框架的枢轴的 `Datatype.CFrame`。

从属性窗口更改它会相对于实例移动枢轴，同时保持实例位置不变，与 `原点` 不同，后者会移动整个实例。对于 `Class.BasePart`，偏移量默认为单位 `Datatype.CFrame`，因此枢轴与部件的中心重合。对于 `Class.Model`，当模型具有 `Class.Model.PrimaryPart|PrimaryPart` 时，此属性才会出现；它会反映并编辑该部件的 `Class.BasePart.PivotOffset|PivotOffset`，并且 `Class.Model:GetPivot()` 别名为主部件的枢轴。

不适用于脚本；脚本通过具体类读取和写入等效值，例如 `Class.BasePart.PivotOffset`。


PVInstance.Pivot Offset

仅限编辑器的属性，用于显示和编辑相对于实例的枢轴 `Datatype.CFrame`，仅移动枢轴而不改变实例的位置。


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

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

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

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

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

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

您可以使用此事件跟踪 Studio 中实例的删除，
例如在资源管理器中手动删除或通过插件删除。如果您需要
to 检测何时使用 `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: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()` 被销毁之前立即触发（或被推迟到之后）。

演示 `Class.Instance.StyledPropertiesChanged`。


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

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` 则为 `nil`。

创建实例及其所有后代的副本，忽略不为 `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` 的第一个祖先，`Class.Object:IsA()` 对于给定的 className 返回 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` 的第一个祖先，`Class.Object:IsA()` 对于给定的 className 返回 true。

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

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

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

如果您需要在继续之前验证对象是否存在，则需要使用 `FindFirstChild()`。尝试使用点运算符按名称索引子级，如果子级不存在将引发错误。

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

-- 如果部件不存在于工作区，以下行将出错
Workspace.Part.Transparency = 0.5
```
更好的方法是使用 `FindFirstChild()` 首先检查 `Part`，然后使用 `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` 的属性相同。当使用点运算符时，如果它们共享名称，属性优先于子级。

在以下示例中，添加到 `Class.Part` 的名为 `Color` 的 `Class.Folder`，它也具有 `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

返回具有给定名称的 `Class.Instance` 的第一个子级。

Instance

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

摘要