WrapTextureTransfer 提供了一種替代的投影模式給 `Class.Decal`，在這個模式中，該 `Class.Decal` 根據在 `Class.WrapTarget` 中提供的籠網來適配父 `Class.MeshPart`。

這是有用的，因為它允許將 Decals 適配於各種形狀不同的 MeshParts，但這些 MeshParts 共享相似的 WrapTarget 籠網拓撲。通過在 WrapTarget UV 空間中創作的紋理，這些紋理可以在許多不同的、具有不同紋理佈局的 MeshParts 中重複使用。

- DataModel 結構
  - `Class.MeshPart`
    - `Class.WrapTarget`
    - `Class.Decal`
      - `Class.WrapTextureTransfer`

可視化這如何工作的方式是想象 Decals 紋理在 WrapTarget 籠網上的樣子，籠網包裹在 MeshPart 周圍。這些紋理然後從籠網投影到 MeshPart 表面。 MeshPart 內部的幾何形狀，或者未被籠網覆蓋的部分，將不會接收任何投影的 Decal 紋理。目標 `Class.MeshPart` 的分段區域用於提高靠近籠網中的孔洞或邊界的投影質量。

準備此 `Class.WrapTextureTransfer` 以用作
`Class.EditableImage:DrawImageProjected()` 和
`Class.EditableImage:SampleImageProjected()` 中的 `projectionSource`。此方法不接受任何
參數，直到準備完成時會暫停，並且不返回任何值。

這允許對投影紋理進行編輯，例如在玩家當前的頭部上化妝，
而無需從目標資產創建 `Class.EditableMesh` 或要求創建的許可。準備好的數據
在內部快取；它不會返回給腳本，並且無法檢查、
轉換為 `Datatype.Content` 或發佈。

`Class.WrapTextureTransfer` 必須被父級為 `Class.Decal` 的物件所擁有，
其父級為具有網格內容和有效 `Class.WrapTarget` 子物件的 `Class.MeshPart`。此層級必須在數據模型中。
在調用此方法之前，根據需要配置 `Class.WrapTextureTransfer.ReferenceCageMeshContent`、
`Class.WrapTextureTransfer.UVMinBound` 和
`Class.WrapTextureTransfer.UVMaxBound`。

準備好的數據結合了目標網格在轉移區域內的
位置、法線和三角形連接性，與從當前籠配置和 UV
邊界計算出的轉移 UVs。幾何形狀被縮放以匹配目標 `Class.MeshPart` 的
當前 `Class.BasePart.Size`。投影位置和方向使用目標 MeshPart 的本地空間。

在數據保持有效的情況下，準備會在投影圖像操作之間重用。
對目標網格或其大小、籠配置、UV 邊界或層級的更改會使快取數據失效。
在這種更改後再次調用此方法。如果準備未成功完成或快取數據已失效，
兩個投影方法都會引發錯誤。將 `Class.EditableMesh` 傳遞給這些方法不需要此
準備。

使用 `pcall()` 來處理準備錯誤，包括無效的層級、
不可用的網格或籠數據、UV 轉移失敗或在準備過程中輸入變更。
僅在調用成功後執行投影圖像操作。

例如，當頭部、貼圖、圖像、參考籠內容、UV
邊界和畫筆配置已經定義時：

```lua
local projectionTransfer = Instance.new("WrapTextureTransfer")
projectionTransfer.ReferenceCageMeshContent = referenceCageContent
projectionTransfer.UVMinBound = makeupUVMin
projectionTransfer.UVMaxBound = makeupUVMax
projectionTransfer.Parent = makeupDecal
makeupDecal.Parent = playerHead

local success, errorMessage = pcall(function()
    projectionTransfer:PrepareProjectionMeshDataAsync()
end)

if not success then
    warn("準備化妝投影失敗: " .. tostring(errorMessage))
    return
end

makeupTexture:DrawImageProjected(projectionTransfer, projection, brushConfig)
sampledBrush:SampleImageProjected(
    projectionTransfer,
    makeupTexture,
    projection,
    sampleBrushConfig
)
```


WrapTextureTransfer:PrepareProjectionMeshDataAsync

準備並快取投影數據，以便使用此
`Class.WrapTextureTransfer` 進行投影的 `Class.EditableImage`
操作。


WrapTextureTransfer

參考籠網是用於創作紋理的籠網。這個在 `Class.WrapTarget` 中定義的目標籠網是根據這個 `ReferenceCageMeshContent` 進行修剪的。如果目標籠網包含在參考籠網中不存在的頂點或面，則在執行紋理轉移之前，這些頂點和面會被從目標籠網中移除。如果 `ReferenceCageMeshContent` 和 `Class.WrapTarget` 中定義的籠網之間沒有共享的 UV，則紋理轉移將失敗。

當未定義時，使用祖先 `Class.MeshPart` 中的 `Class.WrapTarget` 籠網進行轉移，無需進行任何修剪或驗證。

WrapTextureTransfer.ReferenceCageMeshContent

可選的參考網格，用於修剪和驗證目標籠。

決定要包括在轉移中的 UV 空間的最大邊界。籠網中 UV 值高於最大邊界的區域在應用紋理時不會被包括。

Decal 紋理應用於父 `Class.MeshPart`，紋理在 UVMinBound 和 UVMaxBound 之間線性縮放。

當設置為默認 -inf 時，將使用來自 WrapTarget 籠的最大 UV 值。

WrapTextureTransfer.UVMaxBound

決定要包括在轉移中的 UV 空間的最大邊界。

決定要包括在轉移中的 UV 空間的最小邊界。籠網中 UV 值低於最小邊界的區域在應用紋理時不會被包括。

Decal 紋理應用於父 `Class.MeshPart`，紋理在 UVMinBound 和 UVMaxBound 之間線性縮放。

當設置為默認 inf 時，使用來自 WrapTarget 籠的最小 UV 值。

WrapTextureTransfer.UVMinBound

決定要包括在轉移中的 UV 空間的最小邊界。

`Class.WrapTextureTransfer` 允許父 `Class.Decal` 根據其 `Class.WrapTarget` 的籠包裹在其父 `Class.MeshPart` 周圍。

`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()` 被銷毀之前立即觸發（或延遲到之後觸發）。


演示 `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.Object.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
```
更好的方法是使用 `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` 的屬性相同。使用點運算符時，如果它們共享名稱，則屬性優先於子物件。

在以下示例中，將一個名為 `Color` 的 `Class.Folder` 添加到 `Class.Part`，該 `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` 的第一個子物件，對於給定的 className，`Class.Object:IsA()` 返回 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` 的第一個子物件，對於給定的 className，`Class.Object:IsA()` 返回 true。


返回具有給定 `Class.Instance.Name` 的第一個後代。

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


Instance:FindFirstDescendant

返回具有給定 `Class.Instance.Name` 的第一個後代。


如果 `Class.Instance` 是 `Class.Actor`，則返回 `Class.Actor` 本身。否則，返回其最近的祖先 `Class.Actor`。如果沒有祖先是 `Class.Actor`，則結果為 `nil`。


Instance:GetActor

返回與實例相關聯的 `Class.Actor`（如果有的話）。


此方法返回分配給給定屬性名稱的值。如果未分配任何屬性，則返回 `nil`。

例如，以下代碼片段設置然後獲取實例的 `InitialPosition` 屬性的值：

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)
```

#### 另請參見

- `Class.Instance:SetAttribute()`，該方法將給定名稱的屬性設置為給定值。
- `Class.Instance:GetAttributes()`，該方法返回實例屬性的鍵值對字典。


Instance:GetAttribute

分配給給定屬性名稱的值。如果未分配任何屬性，則返回 `nil`。


返回分配給給定屬性名稱的值。


此方法返回一個事件，其行為與 `Class.Object.Changed|Changed` 事件完全相同，
不過它僅在特定給定屬性更改時觸發；實際上，它類似於 `Class.Object:GetPropertyChangedSignal()|GetPropertyChangedSignal()`，但用於屬性。

通常，使用此方法而不是連接到 `Class.Object.Changed|Changed` 的函數來檢查屬性名稱是一個好主意。對同一物件的後續調用將返回相同的事件。

以下代碼示例返回一個信號，當部件的 `InitialPosition` 屬性更改時觸發 `attributeChanged()` 函數：

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("Attribute changed")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
```
另請參見 `Class.Instance.AttributeChanged`，該事件在實例的任何屬性更改時觸發。


Instance:GetAttributeChangedSignal

要返回更改信號的指定屬性名稱。


當給定屬性更改時觸發的事件。


返回當給定屬性更改時觸發的事件。


此方法返回每個屬性的鍵值對字典，其中鍵是屬性名稱，值是非 `nil` 值。

例如，以下代碼片段輸出實例的屬性和值：

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)
part:SetAttribute("CanUse", true)

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end
```
另請參見 `Class.Instance:GetAttribute()`，該方法返回分配給給定屬性名稱的值。


Instance:GetAttributes

每個屬性的字符串 → 變體對的字典，其中字符串是屬性名稱，變體是非 `nil` 值。


下面的代碼會在執行時打印出當前在工作區中的所有物件名稱。

返回一個數組（數字索引表），包含所有實例的直接子物件，或每個 `Class.Instance` 其 `Class.Instance.Parent|Parent` 等於該物件。可以使用數字或通用 `for` 循環對數組進行迭代：

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

-- 數字循環示例
local children = Workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " is child number " .. i)
end
```

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

-- 通用循環示例
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end
```
請注意，返回的數組 **不** 按任何特定順序排序，因此建議手動排序（例如使用 `Library.table.sort()`）以對此方法返回的子物件進行排序。

另請參見 `Class.Instance:GetDescendants()|GetDescendants()` 方法。


Instance:GetChildren

返回包含所有實例子物件的數組。


Instance:getChildren

返回 Roblox 內部使用的調試 ID 的編碼字符串。請注意：

- 此項目是受保護的。在 `Class.Script` 或 `Class.LocalScript` 中使用它將導致錯誤。
- 調試 ID 是用於調試過程的 ID。它允許調試器在應用程序處理每個指令之前讀取每個指令。Roblox 中的所有物件都像進程一樣運行，每個運行指令（或 '代碼'）在需要時可以進行調試。
- 這對於需要區分相似物件的插件（例如共享相同名稱的物件）非常有幫助。


Instance:GetDebugId

scopeLength

返回 Roblox 內部使用的調試 ID 的編碼字符串。


GetDescendants 通常用於對所有子孫物件進行某些操作，這些物件是特定類型的物件。這個示例中的程式碼使用 GetDescendants 和 `Class.Instance:IsA()` 來找到工作區中的所有部件並將它們變成綠色。

此物件方法返回一個數組，該數組包含該物件的所有後代。與 `Class.Instance:GetChildren()` 不同，該方法僅返回物件的直接子物件，此方法查找物件的每個子物件、每個子物件的子物件，依此類推。

請注意，返回的數組 **不** 按任何特定順序排序，因此建議手動排序（例如使用 `Library.table.sort()`）以對此方法返回的後代進行排序。還可以考慮使用 `Class.Instance:QueryDescendants()|QueryDescendants()` 方法通過選擇器和組合器的組合查詢後代。


Instance:GetDescendants

返回包含實例所有後代的數組。


此代碼範例演示了 `Class.Instance:GetFullName()` 的行為。

它展示了當在不在 `DataModel` 階層中的物件上調用該函數時的行為，
並且還顯示了返回值如何不轉義特殊字符。

這段程式碼範例重新實作了 `Class.Instance:GetFullName()` 函數於
Lua。


返回描述實例祖先的字符串。該字符串是物件的 `Class.Instance.Name|Name` 和其祖先的串聯，並用句點分隔。`Class.DataModel`（`game`）不被考慮。例如，`Class.Workspace` 中的 `Class.Part` 可能返回 `Class.Workspace.Part`。

當在不屬於 `Class.DataModel` 的 `Class.Instance` 上調用此方法時，該方法考慮所有祖先，直到包括沒有 `Class.Instance.Parent|Parent` 的最上層祖先。

此方法對於日誌記錄和調試非常有用。您不應該嘗試解析返回的字符串以進行任何有用的操作；此方法不會轉義物件名稱中的句點（或任何其他符號）。換句話說，儘管其輸出通常看起來像有效的 Luau 標識符，但並不保證。


Instance:GetFullName

此方法返回指定屬性的樣式或明確修改的值，
如果未樣式/修改則返回屬性的默認值。這與直接訪問屬性值略有不同，例如 `[GuiObject].Rotation`，該方法返回屬性的默認或修改值。


Instance:GetStyled

selector

您在實例上針對的虛擬實例的可選選擇器。


指定屬性的樣式或明確修改的值，
如果未樣式/修改則返回屬性的默認值。


返回指定屬性的樣式或明確修改的值，
如果未樣式/修改則返回屬性的默認值。


演示 `Class.Instance:GetStyledPropertyChangedSignal()`。


此方法返回一個事件，其行為與 `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 事件完全相同，
不過它僅在給定樣式屬性更改時觸發。通常，使用此方法而不是連接到 `Class.Instance.StyledPropertiesChanged|StyledPropertiesChanged` 的函數來檢查屬性名稱是一個好主意。對同一物件的後續調用將返回相同的事件。

請注意，此事件不會將任何參數傳遞給連接的函數，因此必須在腳本中直接讀取更改的屬性值。


Instance:GetStyledPropertyChangedSignal

property

當給定樣式屬性更改時觸發的事件。


返回當給定樣式屬性在實例上更改時觸發的事件。


此方法返回應用於給定實例的標籤數組，作為字符串。您可以在 Studio 中的
[屬性](/studio/properties) 窗口中或在運行時使用 `Class.Instance:AddTag()|AddTag()` 添加標籤。

當您想要一次對實例上的多個標籤執行某些操作時，此方法非常有用。然而，使用此方法檢查單個標籤的存在性效率不高；相反，使用 `Class.Instance:HasTag()|HasTag()` 檢查特定標籤。


Instance:GetTags

一個字符串數組，每個字符串表示應用於實例的標籤。


獲取應用於實例的所有標籤的數組。


此方法返回 `true` 如果提供的標籤已添加到物件中。您可以在 Studio 中的
[屬性](/studio/properties) 窗口中或在運行時使用 `Class.Instance:AddTag()|AddTag()` 添加標籤。


Instance:HasTag

`true` 如果實例具有給定標籤，否則為 `false`。


演示如何確定一個實例是否是另一個實例的祖先，使用
`Class.Instance:IsAncestorOf()`

Workspace 和 SpawnLocation 是 SpawnLocation 的貼圖的祖先。
Workspace 是 SpawnLocation 的祖先。

SpawnLocation 及其貼圖是 Workspace 的後代，而不是祖先。
Decal 是 SpawnLocation 的後代，而不是祖先。


如果 `Class.Instance` 是給定後代的祖先，則返回 true。

如果物件的 `Class.Instance.Parent` 或其父級的 `Class.Instance.Parent` 設置為 `Class.Instance`，則認為 `Class.Instance` 是物件的祖先。

另請參見 `Class.Instance:IsDescendantOf()`。


Instance:IsAncestorOf

如果 `Class.Instance` 是給定後代的祖先，則為真。


如果 `Class.Instance` 是給定後代的祖先，則返回 true。


如果 `Class.Instance` 是給定祖先的後代，則返回 `true`。

請注意，`IsDescendantOf()` 不能使用 `nil` 參數來檢查物件是否已被移除。

另請參見 `Class.Instance:IsAncestorOf()`。


Instance:IsDescendantOf

ancestor

如果 `Class.Instance` 是給定祖先的後代，則為真。


如果 `Class.Instance` 是給定祖先的後代，則返回 `true`。


Instance:isDescendantOf

此方法指示特定屬性是否已從代碼實例化的默認值進行修改。如果在通過代碼創建的實例上調用（`Datatype.Instance.new()`），則此方法將返回 `false`。如果在通過 Studio 工作流程（例如 [Explorer](/studio/explorer) 窗口插入）創建的物件上調用，則結果可能會有所不同。

例如，查詢通過 [Explorer](/studio/explorer) 插入的 `Class.TextLabel.BackgroundColor3|BackgroundColor3` 屬性將返回 `true`，但查詢通過 `Datatype.Instance.new()` 創建的相同屬性將返回 `false`，假設對其 `Class.TextLabel.BackgroundColor3|BackgroundColor3` 沒有進行其他更改。

請注意，此方法僅對服務和用戶可創建的實例返回有用的結果。對於像 `Class.PackageLink` 這樣的實例的系統填充屬性，返回值是未定義的行為。

還要注意，如果此方法返回 `true`，則樣式將 **不** 影響該屬性，因為明確修改屬性優先於樣式。要將屬性重置為其代碼實例化的默認值並允許對其進行樣式設置，請使用 `Class.Instance:ResetPropertyToDefault()|ResetPropertyToDefault()`。


Instance:IsPropertyModified

布爾值，指示該屬性是否已從其代碼實例化的默認值進行修改。


如果存儲在指定屬性中的值不等於代碼實例化的默認值，則返回 `true`。


此物件方法返回一個數組，該數組包含所有與提供的 `selector` 字符串匹配的物件的後代。`selector` 可以包括多個選擇器和組合器，以匹配類別名稱、實例名稱和層級關係的特徵，以及實例屬性和屬性的特定值。`selector` 語法類似於 `Class.StyleRule` 中使用的語法，僅對支持或不支持的語法部分有少數幾個差異。

#### 選擇器

- `ClassName` — 匹配指定類別的實例，符合 `Class.Object:IsA()` 關係。
- `.Tag` — 匹配帶有 `Class.CollectionService` 標籤的實例。
- `#Name` — 匹配特定 `Class.Instance.Name` 的實例。
- `[property = value]` — 匹配具有指定屬性的實例，並且該屬性具有指定值。支持布爾值、數字和字符串值。字母、數字、`_` 和 `-` 可以在不將值放在引號中的情況下使用。
- `[$attribute]` — 匹配具有指定 [屬性](/studio/properties#instance-attributes) 的實例。
- `[$attribute = value]` — 匹配具有指定屬性 **且** 該屬性具有指定值的實例。與屬性選擇器相同的限制適用。如果要檢查屬性的缺失，請不要將其查詢為 `nil`；而是使用 `:not` 偽類，例如 `:not([$attribute])`。

選擇器也可以組合。例如，`Model.Apple[$Variety = Fuji][$Flavor = 4]` 將匹配標記為 `Apple` 的 `Class.Model` 實例，並且具有 `Variety` 屬性等於 `Fuji` 以及 `Flavor` 屬性等於 `4`。

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

-- 獲取所有 MeshPart 後代
print(Workspace:QueryDescendants("MeshPart"))

-- 獲取所有標記為 "Fruit" 的後代
print(Workspace:QueryDescendants(".Fruit"))

-- 獲取所有名稱為 "RedTree" 的後代
print(Workspace:QueryDescendants("#RedTree"))

-- 獲取所有 CanCollide 屬性設置為 false 的後代
print(Workspace:QueryDescendants("[CanCollide = false]"))

-- 獲取所有分配了 "FuelCapacity" 屬性的後代
print(Workspace:QueryDescendants("[$FuelCapacity]"))
-- 獲取所有 "FuelCapacity" 屬性設置為 75 的後代
print(Workspace:QueryDescendants("[$FuelCapacity = 75]"))
```

#### 組合器

組合器允許您混合基本選擇器以匹配更深層次的層級關係。

- `>` — 匹配前一個過濾器匹配的 **直接子物件**。

- `>>` — 匹配前一個過濾器匹配的 **後代**。這是默認的第一個過濾器，這意味著 `SpotLight.Red` 與 `>> SpotLight.Red` 是相同的。

- `,` — 指定多個獨立選擇器的列表以進行後代查詢。僅匹配過濾器的元素將放置在返回的數組中；對於查詢列表中的不匹配，`nil` 將不會包含。

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

-- 獲取標記為 "SwordPart" 的任何模型的直接子物件
print(Workspace:QueryDescendants("Model > .SwordPart"))

-- 獲取標記為 "Apple" 的直接子物件，且為部件
print(Workspace:QueryDescendants("> Part.Apple"))

-- 獲取任何模型的後代，該模型的 "OnFire" 屬性設置為 true
print(Workspace:QueryDescendants("Model >> [$OnFire = true]"))

-- 獲取標記為 "SwordPart" 的 MeshPart 後代或其 "OnFire" 屬性設置為 true 的後代
print(Workspace:QueryDescendants("MeshPart.SwordPart, MeshPart[$OnFire = true]"))
```

#### 偽類選擇器

- `:not(complex-selector-list)` — 允許選擇 **不** 匹配任何選擇器的實例，實際上對選擇器執行否定。由於內部是複雜選擇器的列表，因此可以根據多個條件進行過濾。

- `:has(relative-selector-list)` — 允許根據它們包含的實例選擇實例。選擇器列表相對於每個實例進行評估。

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

-- 獲取所有不是 SpotLight 類的後代
print(Workspace:QueryDescendants(":not(SpotLight)"))
-- 獲取所有不是 SpotLight 或 PointLight 類的後代
print(Workspace:QueryDescendants(":not(SpotLight, PointLight)"))
-- 獲取所有沒有 "OnFire" 屬性的後代
print(Workspace:QueryDescendants(":not([$OnFire])"))
-- 獲取所有後代，除了標記為 "SwordPart" 的模型的子物件
print(Workspace:QueryDescendants(":not(Model > .SwordPart)"))

-- 獲取包含工具實例作為其後代的後代
print(Workspace:QueryDescendants(":has(Tool)"))
-- 獲取標記為 "SwordPart" 的 MeshPart 後代，且包含直接子物件
print(Workspace:QueryDescendants("MeshPart:has(> .SwordPart)"))

-- 獲取 MeshPart 後代，且直接子物件不是 SurfaceAppearance 或 Texture 類
print(Workspace:QueryDescendants("MeshPart:has(> :not(SurfaceAppearance, Texture))"))
```


Instance:QueryDescendants

用於過濾元素的選擇器字符串。


一個實例數組（如果沒有匹配選擇器則為空）。


返回包含所有後代的數組，這些後代與 `selector` 字符串匹配。


以下代碼演示了如何在被移除後將一個部件重新添加到 DataModel：


此方法將物件的 `Class.Instance.Parent` 設置為 `nil`，並對其所有後代執行相同操作。

如果在被移除之前引用了該物件，則可以在稍後的時間點檢索該物件。


Instance:Remove

將物件的 `Parent` 設置為 `nil`，並對其所有後代執行相同操作。


Instance:remove

此方法從實例中移除標籤。如果物件沒有該標籤，則不會引發錯誤。成功移除標籤將觸發由 `Class.CollectionService:GetInstanceRemovedSignal()` 創建的信號，並帶有給定的標籤。

請注意，在標記實例時，通常會使用一些資源來賦予標籤其功能，例如事件連接或表格。為了防止內存洩漏，當不再需要標籤時，最好清理這些資源（斷開連接，設置為 `nil` 等）。


Instance:RemoveTag

將屬性重置為其默認值。例如，在 `Class.TextLabel` 上調用 `ResetPropertyToDefault("Rotation")` 相當於將其 `Class.TextLabel.Rotation|Rotation` 設置為 `0`（該屬性的默認值）。此方法可用於確保樣式將覆蓋該屬性的默認值。


Instance:ResetPropertyToDefault

此方法將具有給定名稱的屬性設置為給定值。如果
給定的值為 `nil`，則該屬性將被移除，因為 `nil` 是
默認返回的值。

例如，以下代碼片段將實例的
`InitialPosition` 屬性設置為 `Datatype.Vector3|Vector3.new(0, 10, 0)`：

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

local part = Workspace.Part
part:SetAttribute("InitialPosition", Vector3.new(0, 10, 0))
```

#### 限制

命名要求和限制：

- 名稱只能使用字母數字字符。
  - 您還可以包含句點、連字符、斜杠和下劃線。
- 不允許使用空格或獨特符號（如 @, ~, !）。
- 字符串必須少於 100 個字符。
- 名稱不允許以 **RBX** 開頭，除非調用者是
  Roblox 核心腳本（保留給 Roblox）。

當嘗試將屬性設置為不支持的類型時，將引發錯誤。

#### 另請參見

- `Class.Instance:GetAttribute()` 返回已分配給給定屬性名稱的值。
- `Class.Instance:GetAttributes()` 返回每個實例屬性的鍵值對字典。


Instance:SetAttribute

value

將具有給定名稱的屬性設置為給定值。


以下代碼會等待名為 "Part" 的實例被添加到
Workspace。


返回具有給定名稱的 `Class.Instance` 的子項。如果該
子項不存在，則會暫停當前線程，直到它存在。如果
指定了 `timeOut` 參數，則此方法將在指定的秒數後超時並返回 `nil`。

#### 主要用法

`Class.Instance:WaitForChild()|WaitForChild()` 在
`Class.LocalScript` 中運行的客戶端代碼時極為重要。Roblox
引擎不保證對象從服務器到客戶端的複製時間或順序。此外，如果一個體驗
的 `Class.Workspace.StreamingEnabled` 設置為 true，
`Class.BasePart|BaseParts` 可能不會被流式傳輸到客戶端，這可能會導致腳本在索引尚不存在於客戶端的對象時出現錯誤。

#### 注意

- 如果在調用時具有給定名稱的子項存在，則此方法不會暫停。
- `Class.Instance:FindFirstChild()` 是對於假定存在的對象來說，
  `Class.Instance:WaitForChild()|WaitForChild()` 的更高效替代方案。
- 如果此方法的調用超過 5 秒而未返回，且未指定 `timeOut` 參數，則將在輸出中打印警告，表示該線程可能會無限期暫停。


Instance:WaitForChild

childName

timeOut

返回具有給定名稱的 `Class.Instance` 的子項。如果該
子項不存在，則會暫停當前線程，直到它存在為止。


Instance

此屬性確定在經驗發布或保存時，
或當 `Class.Instance:Clone()|Clone()`
在其中一個實例的祖先上被調用時，該實例是否應該被包含。
直接在實例上調用 `Class.Instance:Clone()|Clone()` 將返回 `nil`
如果該實例 **不** 是 `Class.Instance.Archivable|Archivable`。

在 Studio 中使用 **Duplicate** 或 **Copy**/**Paste**
選項複製物件將忽略其自身的 `Class.Instance.Archivable|Archivable`
屬性，並將 `Class.Instance.Archivable|Archivable` 設置為 `true` 以進行複製。


Instance.Archivable

確定 `Class.Instance` 及其後代是否可以使用
`Class.Instance:Clone()` 進行克隆，並且可以被保存/發布。


Instance.archivable

允許在此實例內使用的能力集。要使能力生效，必須啟用 `Class.Instance.Sandboxed`
屬性。

此屬性由實驗性功能使用。請參見
[腳本能力](/scripting/capabilities) 以獲取更多詳細信息。


Instance.Capabilities

允許在此容器內使用的能力集。


此只讀屬性返回 `true` 如果實例包含在沙盒容器內 — 也就是說，如果該實例本身或其任何祖先啟用了 `Class.Instance.Sandboxed`。
否則返回 `false`。

此屬性不可編程，僅在 Studio 的屬性窗口中可見。請參見 [腳本能力](/scripting/capabilities) 以獲取更多詳細信息。


Instance.IsInSandbox

一個非唯一的 `Class.Instance` 標識符。名稱用於保持物件層級的組織，並允許腳本訪問特定物件。實例的名稱不能超過 100 個字符。

物件的名稱通常用於通過數據模型層級訪問物件，使用以下方法：

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

local baseplate = Workspace.Baseplate
local baseplate = Workspace["Baseplate"]
local baseplate = Workspace:FindFirstChild("BasePlate")
```
為了使物件可以使用點運算符 (`.`) 訪問，名稱必須以底線或字母開頭，其餘名稱只能包含字母、數字或底線（不允許其他特殊字符）。如果物件的名稱不遵循此語法，則無法使用點運算符訪問，Luau 將不會將其名稱解釋為標識符。

如果有多個同名的物件為兄弟，任何嘗試通過該名稱索引物件的操作將僅返回其中一個物件，類似於 `Class.Instance:FindFirstChild()`，但不一定是所需的物件。如果需要通過代碼訪問特定物件，建議給它一個唯一的名稱或保證其兄弟中沒有共享相同名稱的物件。

另請參見 `Class.Instance:GetFullName()` 以獲取包括物件層級的完整名稱。


Instance.Name

一個非唯一的 `Class.Instance` 標識符。


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


/reference/engine/classes/WrapTextureTransfer.yaml

概要