一個 `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` 和名為 **Head** 的 `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` 中。使用 `Class.Model.ModelStreamingMode|ModelStreamingMode` 的值如 `Enum.ModelStreamingMode|Atomic` 可以確保如果父模型存在於客戶端，則整個模型及其所有子代均存在，或者在不希望原子性的情況下可以使用 `Class.Instance:WaitForChild()|WaitForChild()`。

將此模型設置為對指定玩家持久化。持久化模型會根據流媒體設置或條件對玩家保持存在。

`Class.Model.ModelStreamingMode|ModelStreamingMode` 必須設置為 `Enum.ModelStreamingMode|PersistentPerPlayer`，以便在添加時改變行為。

Model:AddPersistentPlayer

playerInstance

將此模型設置為對指定玩家持久化。
`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.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

這段程式碼會創建一個模型，將一些零件放入其中，隨機定位它們，

然後打印它的大小：

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）。它在兩個接觸的具有相容表面類型（Studs 和 Inlet）部件上使用 MakeJoints。

基於表面的連接已被棄用。請勿在新項目中使用 MakeJoints。請改用 `Class.WeldConstraint|WeldConstraints` 和 `Class.HingeConstraint|HingeConstraints`。

遍歷 `Class.Model` 中的所有 `Class.BasePart|Parts`，並根據指定部件的表面在平面接觸的表面之間創建關節。

- 光滑表面不會創建關節
- 膠水表面將創建 `Class.Glue` 關節
- 焊接將與任何表面創建 `Class.Weld` 關節，除了不可焊接
- 鉚釘、進口或通用各自將與其他兩個表面（例如鉚釘與進口和通用）創建 `Class.Snap` 關節
- 鉸鏈和電動表面創建 `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.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.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。它是透過獲取當前的 pivot 使用 `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` 及其所有子代 `Class.PVInstance|PVInstances` 進行變換，使得樞紐現在位於該位置。這是用腳本來移動 `Class.Model|Models` 的主要函數。

`Class.BasePart|BaseParts` 通過將它們的 `Datatype.CFrame` 轉換為必要的偏移量來進行移動。
`Class.Model|Models` 也是通過將它們的 `Class.Model.WorldPivot` 轉換為必要的偏移量來移動。

注意，出於效率考慮，對以這種方式移動的 `Class.BasePart|BaseParts` 的 `Class.BasePart.Position|Position` 和 `Class.BasePart.Orientation|Orientation` 不會觸發 `Class.Object.Changed` 事件；它們僅對 `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`。

在指定的 `Datatype.CFrame` 下，將 `Class.PVInstance` 及其所有子代 `Class.PVInstance|PVInstances` 進行變換，使得樞紐現在位於該位置。

PVInstance

PVInstance.Origin

PVInstance.Pivot Offset

所有在世界中有物理位置的物件的抽象類別。

`Instance` 是 Roblox 類別階層中所有類別的基礎類別，可以是 `Class.DataModel` 樹的一部分。

無法直接創建根 `Instance` 物件，但特殊的 `Datatype.Instance.new()` 建構函數通過代碼創建物件，以類別名稱作為參數並返回所創建的物件。

展示如何通過連接到 `Class.Instance.AncestryChanged` 事件來檢測實例的祖先變化。

ChangingPart 的 Parent 隨著時間設置為不同的值。部分的父項是該部分的祖先，因此每當發生變化時，`Class.Instance.AncestryChanged` 事件將被觸發。


當此實例被重新父級化或其任何祖先被重新父級化時觸發。

您可以使用此事件來跟踪 Studio 中實例的刪除，例如在 Explorer 中的手動刪除或通過插件。如果您需要檢測實例是否使用 `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` 後觸發。

以下範例在任何後代被移除時打印其名稱

從 Workspace 中：

這個事件在父項 `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` 的第一個祖先，該祖先對應於 `Class.Object:IsA()` 返回 true 的給定 className。

此方法向上工作，意味著它從實例的直接 `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()` 返回 true 的給定 className。

以下將在工作區中尋找名為"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

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()` 返回 true 的給定 className。

如果未找到匹配子物件，則此方法返回 `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()` 返回 true 的給定 className。

返回第一個後代，該後代符合給定 `Class.Instance.Name`。

此方法被禁用且無法使用。要查找實例的第一個後代，請考慮在 `Class.Instance:FindFirstChild()` 上使用 `recursive` 參數。

Instance:FindFirstDescendant

返回第一個後代，該後代符合給定 `Class.Instance.Name`。

Instance

`Instance` 是 Roblox 類別階層中所有類別的基礎類別，可以是 `Class.DataModel` 樹的一部分。