Unit

概览

字段	值
Kind	`Unit` · 单位 Unit
Realm	`common`

继承关系

[Unit]（4 属性 / 25 函数 / 6 事件）
- AdvertisementService（2 函数）
- AnalyticsService（10 函数）
- AnimationTrack（11 属性 / 10 函数 / 3 事件）
- Animator（1 属性 / 2 函数 / 1 事件）
- AssetService（5 函数 / 2 事件）
- Attachment（11 属性 / 1 函数）
- Backpack
- BackpackItem（1 属性）
  - Tool（4 属性 / 2 函数 / 4 事件）
- BallSocketConstraint（12 属性）
- BaseController（12 属性 / 22 函数 / 11 事件）
  - EggyController（7 属性 / 4 函数 / 4 事件）
  - HumanController（6 属性 / 2 函数 / 6 事件）
- BaseMotorUnit（10 属性 / 5 函数 / 2 事件）
  - AngularMotorUnit（1 属性）
  - CurveVelMotorUnit（5 属性）
  - LinearMotorUnit（2 属性）
  - PendulumMotorUnit（1 属性）
  - WaypointMotorUnit（1 属性）
- BasePostEffect（1 属性）
  - AmbientOcclusionEffect（3 属性）
  - BloomEffect（4 属性）
  - ColorGradingEffect（15 属性）
  - ComicEffect（8 属性）
  - DepthOfFieldEffect（2 属性）
  - InkWashEffect（5 属性）
  - LensRainEffect（8 属性）
  - PixelateEffect（1 属性）
  - SketchEffect（15 属性）
- BaseScript（1 属性）
  - LocalScript
  - ModuleScript
  - Script
- BaseSky（1 属性）
  - GradientSky（5 属性）
  - PresetSky（2 属性）
  - QuadGradientSky（12 属性）
  - Sky（7 属性）
- BindableEvent（1 属性 / 4 函数）
- CameraService（5 属性 / 6 函数）
- Camps（1 函数）
- ClickDetector（2 属性 / 2 事件）
- CloudMusicService（2 函数）
- CommodityService（17 函数 / 5 事件）
- ConfigService（4 函数）
- ConfigSnapshot（1 属性 / 3 函数 / 1 事件）
- CustomAppearanceService（1 函数）
- DataStoreService（5 函数）
- EUINodeBase（34 属性 / 8 函数 / 4 事件）
  - EUIButton（13 属性）
  - EUIClippingNode（4 属性）
  - EUIEffect（3 属性 / 2 函数）
  - EUIGridLayout（10 属性 / 1 函数）
  - EUIImage（4 属性）
  - EUIInputField（16 属性 / 1 事件）
  - EUILayout（1 属性）
  - EUIListLayout（8 属性 / 1 函数）
  - EUIListView（8 属性 / 2 函数）
  - EUILoadingBar（4 属性）
  - EUIProgressTimer（4 属性）
  - EUIRichTextLabel（30 属性）
  - EUIRootNode
  - EUISceneNode（5 属性 / 1 函数）
  - EUISimpleRichTextLabel（20 属性）
  - EUITableLayout（6 属性 / 1 函数）
  - EUITextLabel（14 属性）
- EffectService（1 函数）
- EffectUnit（20 属性 / 13 函数）
  - LinkEffectUnit（3 属性）
- FileMesh（5 属性）
- Fog（15 属性）
- Folder
- Game（5 函数 / 1 事件）
- HingeConstraint（16 属性）
- LightingService（8 属性）
- LogService（7 函数 / 1 事件）
- MapData（8 函数）
- MemoryStoreService（3 函数）
- MessageService（2 函数）
- Path（1 属性 / 6 函数 / 2 事件）
- PathfindingLink（6 属性）
- PathfindingModifier（3 属性）
- PathfindingService（2 属性 / 1 函数）
- PhysicsService（1 属性 / 14 函数）
- Player（4 属性 / 14 函数 / 10 事件）
- Players（2 属性 / 5 函数 / 2 事件）
- PresetLink
- PrismaticConstraint（17 属性）
- ProfileService（6 函数）
- ReplicatedFirst
- ReplicatedStorage
- RigidConstraint（4 属性）
- RodConstraint（10 属性）
- RunService（4 函数 / 5 事件）
- SceneGui（1 属性 / 2 函数）
- SimpleLight（6 属性）
  - SimpleAreaLight（4 属性）
  - SimpleAreaShadowLight（3 属性）
  - SimpleLineLight（5 属性）
  - SimpleLineShadowLight（4 属性）
  - SimplePointLight（4 属性）
  - SimplePointShadowLight（3 属性）
  - SimpleSpotLight（5 属性）
  - SimpleSpotShadowLight（3 属性）
- SkeletalSocketMount（3 属性）
- SkinUnit（6 属性）
- SocialService（2 函数）
- SoundGroup（1 属性）
- SoundService（5 函数 / 1 事件）
- SoundUnit（9 属性 / 8 函数 / 2 事件）
- SpaceUnit（3 属性 / 9 函数）
  - BasePart（23 属性 / 9 函数）
    - PhysicsUnit（21 属性 / 15 函数 / 4 事件）
    - RenderUnit（15 属性）
    - SeatUnit（3 属性 / 1 事件）
    - TriggerUnit（8 属性 / 7 函数 / 4 事件）
      - RenderTriggerUnit（16 属性）
    - WorldUnit（29 属性 / 15 函数 / 6 事件）
      - AnimatedUnit（3 函数）
      - SpawnLocationUnit（8 属性）
  - CameraUnit（22 属性 / 2 函数 / 1 事件）
  - EggyUnit（11 属性 / 9 函数）
  - FindingPathUnit（1 属性 / 4 函数）
  - HumanUnit（23 属性 / 27 函数 / 2 事件）
  - ModelUnit（4 属性 / 1 函数）
    - WorldRoot
      - World（1 属性 / 4 函数）
- StarterGui（4 函数）
- TagService（6 函数 / 2 事件）
- Task（5 函数）
- TeleportService（5 函数 / 1 事件）
- TextChatService（8 函数）
- TextUnit（26 属性）
- TimerService（1 函数）
- Tween（2 属性 / 3 函数 / 1 事件）
- TweenService（1 函数）
- VibrationService（1 函数）
- WeldConstraint（4 属性 / 1 函数）

Unit 是所有场景单位的基础类型，负责游戏对象树的层级组织与数据管理。它支持子节点的增删查、路径定位、自定义属性附加以及属性变更监听，并提供克隆、销毁等生命周期操作。

适用场景

在场景初始化或玩法逻辑中，通常先创建或获取 Unit，再利用 FindFirstChild、GetChildren 等层级方法检索目标单位，或通过 SetAttribute 为对象附加标记数据。

使用要点

Unit 是不可直接创建的场景单位基础类型。应通过 World:CreateUnit 或 game:CreateUnit 创建具体公开 Unit 子类（如 Folder、WorldUnit、RenderUnit），或从服务和对象树 API 获取实例；随后使用 GetChildren、FindFirstChild、SetAttribute、Destroy 等继承的公共能力。

注意事项

Unit 是所有场景单位的基础类型。Meta 公开且可写的属性支持 unit.Property = value，也隐式支持 unit:SetProperty(value)；读取可使用 unit.Property 或 unit:GetProperty()。readOnly=true 的属性只允许读取/Get，不允许直接赋值或 Set。SetAttribute/GetAttribute 只操作按名称创建的自定义属性，不是修改 Name、Parent、Position 等 Meta 属性的通用入口。FindFromPath 使用 '.' 分隔路径（如 unit:FindFromPath("ModelGroup.MyModel.Part1")），与 GetFullPath 返回的路径格式一致，可直接互通。FindFirstChild/FindFirstAncestor 等系列方法用名称匹配，Recursive 参数控制是否递归搜索后代。GetChildAtIndex 的 Lua 入参从 1 开始，GetChildAtIndex(1) 返回第一个子节点，不要传 0。

代码示例

通过具体 Unit 子类管理子节点

lua

-- @runtime client
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "RootContainer" })
world:CreateUnit("Folder", { Name = "ChildA", Parent = root })
world:CreateUnit("Folder", { Name = "ChildB", Parent = root })
print("子节点数量:", root:GetChildCount())
local firstChild = root:GetChildAtIndex(1)
if firstChild ~= nil then print("第一个子节点:", firstChild.Name) end
root:ClearAllChildren()

安全监听子节点添加与移除

lua

-- @runtime client
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "EventRoot" })
root.ChildAdded:Once(function(child)
    print("子节点已添加:", child.Name)
end)
local child = world:CreateUnit("Folder", { Name = "TempChild", Parent = root })
local childName = child.Name
root.ChildRemoved:Once(function()
    print("子节点已移除:", childName)
end)
child:Destroy()

属性 (4)

Name	类型	默认值	说明
`AssetId`	`String`	`""`	Unit 的预设资源 ID，用于标识该 Unit 所引用的官方预设或自定义资源。
`Name`	`String`	`名称1`	Unit 的名称，用于在层级树中标识该节点。
`Desc`	`String`	`描述1`	Unit 的描述文本，用于存储开发者自定义的说明信息。
`Parent`	Unit	`-`	Unit 的父节点，决定其在层级树中的位置。

事件 (6)

ChildAdded

签名：ChildAdded(child: Unit) 触发：local

当有新的子节点添加到当前节点时触发，返回新添加的子节点。

回调参数	类型	说明
`child`	Unit	新增的子节点

示例代码

监听子节点添加事件

lua

-- @runtime client
-- 创建父节点和子节点，监听 ChildAdded 事件
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "ParentFolder" })

-- 使用 Once 监听下一次子节点添加
parent.ChildAdded:Once(function(child)
    print("子节点已添加:", child.Name)
end)

-- 创建子节点并挂载到父节点下，触发事件
local child = world:CreateUnit("Folder", { Name = "ChildFolder", Parent = parent })
print("子节点创建完成")

ChildRemoved

签名：ChildRemoved(child: Unit) 触发：local

当有子节点从当前节点移除时触发，返回被移除的子节点。

⚙ ChildRemoved 回调触发时，child 可能已经处于脱离父节点或销毁流程中；不要在回调里继续调用 child:GetAttribute()/HasTag() 等依赖完整对象状态的接口。需要判断属性或标签时，在移除前缓存必要信息，或把清理逻辑放在可控的移除流程中。

回调参数	类型	说明
`child`	Unit	移除的子节点

示例代码

安全处理 ChildRemoved

lua

-- @runtime client
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = parent })
local childName = child.Name

parent.ChildRemoved:Once(function()
    -- 使用移除前缓存的信息，不继续访问正在销毁的 child
    print("子节点已移除:", childName)
end)
child:Destroy()

DescendantAdded

签名：DescendantAdded(descendant: Unit) 触发：local

当有后代节点添加到当前节点的层级树中时触发，返回新添加的后代节点。

回调参数	类型	说明
`descendant`	Unit	新增的后代节点

示例代码

监听后代节点添加事件

lua

-- @runtime client
-- 创建父节点和后代节点，监听 DescendantAdded 事件
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "ParentFolder" })

-- 使用 Once 监听下一次后代节点添加
parent.DescendantAdded:Once(function(descendant)
    print("后代节点已添加:", descendant.Name)
end)

-- 创建子节点并挂载到父节点下，触发事件
local child = world:CreateUnit("Folder", { Name = "ChildFolder", Parent = parent })
print("后代节点创建完成")

DescendantRemoving

签名：DescendantRemoving(descendant: Unit) 触发：local

当有后代节点从当前节点的层级树中移除时触发，返回即将被移除的后代节点。

回调参数	类型	说明
`descendant`	Unit	移除的后代节点

示例代码

监听后代节点移除事件

lua

-- @runtime client
-- 创建父节点和后代节点，监听 DescendantRemoving 事件
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "ParentFolder" })
local child = world:CreateUnit("Folder", { Name = "ChildFolder", Parent = parent })

-- 使用 Once 监听下一次后代节点移除
parent.DescendantRemoving:Once(function(descendant)
    print("后代节点即将移除:", descendant.Name)
end)

-- 移除后代节点，触发事件
child:Destroy()
print("后代节点已销毁")

AncestryChanged

签名：AncestryChanged(child: Unit, oldParent: Unit) 触发：local

当 Unit 的父节点发生变更时触发，即该 Unit 被移动到另一个父节点下或从父节点移除时。

回调参数	类型	说明
`child`	Unit	变更的节点
`oldParent`	Unit	原父节点

示例代码

监听父节点变更事件

lua

-- @runtime client
-- 创建两个父节点和一个子节点，监听 AncestryChanged 事件
local world = game:GetService("World")
local parent1 = world:CreateUnit("Folder", { Name = "Parent1" })
local parent2 = world:CreateUnit("Folder", { Name = "Parent2" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = parent1 })

-- 使用 Once 监听下一次父节点变更
child.AncestryChanged:Once(function(child, oldParent)
    print("父节点已变更，旧父节点:", oldParent.Name)
end)

-- 更改子节点的父节点，触发事件
child.Parent = parent2
print("父节点变更完成")

Destroying

签名：Destroying() 触发：local

当 Unit 即将被销毁时触发，通常由 Destroy 方法调用引发。

示例代码

监听节点销毁

lua

-- @runtime client
-- 创建节点
local world = game:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "TestUnit" })
-- 监听 Destroying 事件
unit.Destroying:Once(function()
    print("节点 " .. unit.Name .. " 即将被销毁")
end)
-- 销毁节点，触发事件
unit:Destroy()

函数 (25)

ClearAllChildren

签名：ClearAllChildren() -> void

移除当前 Unit 下的所有直接子节点。

返回值 void

示例代码

清除所有子节点

lua

-- @runtime client
-- 创建父节点和多个子节点
local world = game:GetService("World")
local parent = world:CreateUnit("WorldUnit", { Name = "Parent" })
world:CreateUnit("WorldUnit", { Name = "Child1", Parent = parent })
world:CreateUnit("WorldUnit", { Name = "Child2", Parent = parent })
print("清除前子节点数量：" .. parent:GetChildCount())
-- 清除所有子节点
parent:ClearAllChildren()
print("清除后子节点数量：" .. parent:GetChildCount())

GetChildren

签名：GetChildren() -> Array<Unit> (子节点列表)

获取当前节点的所有直接子节点列表。

返回值 Array<Unit> (子节点列表)

示例代码

获取所有子节点列表

lua

-- @runtime client
-- 创建父节点并添加子节点，获取子节点列表
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child1 = world:CreateUnit("Folder", { Name = "Child1", Parent = parent })
local child2 = world:CreateUnit("Folder", { Name = "Child2", Parent = parent })

-- 获取所有子节点
local children = parent:GetChildren()
print("子节点数量:", #children)
for i, child in ipairs(children) do
    print("子节点", i, ":", child.Name)
end

GetDescendants

签名：GetDescendants() -> Array<Unit> (所有后代节点列表)

获取当前节点的所有后代节点列表。

返回值 Array<Unit> (所有后代节点列表)

示例代码

获取所有后代节点列表

lua

-- @runtime client
-- 创建多层嵌套结构，获取所有后代节点
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = root })
local grandchild = world:CreateUnit("Folder", { Name = "Grandchild", Parent = child })

-- 获取所有后代节点
local descendants = root:GetDescendants()
print("后代节点数量:", #descendants)
for i, d in ipairs(descendants) do
    print("后代节点", i, ":", d.Name)
end

IsAncestorOf

签名：IsAncestorOf(Descendant: Unit) -> Bool (是否为指定节点的祖先)

判断当前节点是否为指定节点的祖先。

参数	类型	说明
`Descendant`	Unit	要判断的后代节点

返回值 Bool (是否为指定节点的祖先)

示例代码

判断是否为指定节点的祖先

lua

-- @runtime client
-- 创建多层嵌套结构，判断祖先关系
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = root })
local grandchild = world:CreateUnit("Folder", { Name = "Grandchild", Parent = child })

-- 判断 root 是否为 grandchild 的祖先
local isAncestor = root:IsAncestorOf(grandchild)
print("Root 是 Grandchild 的祖先:", isAncestor)

-- 判断 child 是否为 root 的祖先（反向）
local isAncestor2 = child:IsAncestorOf(root)
print("Child 是 Root 的祖先:", isAncestor2)

IsDescendantOf

签名：IsDescendantOf(Ancestor: Unit) -> Bool (是否为指定节点的后代)

判断当前节点是否为指定节点的后代。

参数	类型	说明
`Ancestor`	Unit	要判断的祖先节点

返回值 Bool (是否为指定节点的后代)

示例代码

判断是否为指定节点的后代

lua

-- @runtime client
-- 创建多层嵌套结构，判断后代关系
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = root })
local grandchild = world:CreateUnit("Folder", { Name = "Grandchild", Parent = child })

-- 判断 grandchild 是否为 root 的后代
local isDescendant = grandchild:IsDescendantOf(root)
print("Grandchild 是 Root 的后代:", isDescendant)

-- 判断 root 是否为 child 的后代（反向）
local isDescendant2 = root:IsDescendantOf(child)
print("Root 是 Child 的后代:", isDescendant2)

FindFirstAncestor

签名：FindFirstAncestor(Name: String) -> Unit (匹配的祖先节点)

从当前节点向上查找第一个名称匹配的祖先节点。

参数	类型	说明
`Name`	`String`	要查找的祖先节点名称

返回值 Unit (匹配的祖先节点)

示例代码

按名称查找第一个祖先节点

lua

-- @runtime client
-- 创建多层嵌套结构，从最内层节点查找指定名称的祖先
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local mid = world:CreateUnit("Folder", { Name = "Middle", Parent = root })
local leaf = world:CreateUnit("Folder", { Name = "Leaf", Parent = mid })

-- 从叶子节点查找名为 "Root" 的祖先
local ancestor = leaf:FindFirstAncestor("Root")
if ancestor then
    print("找到祖先:", ancestor.Name)
else
    print("未找到祖先")
end

FindFirstAncestorWhichIsA

签名：FindFirstAncestorWhichIsA(ClassName: String) -> Unit (匹配类型的祖先节点)

从当前节点向上查找第一个类型匹配的祖先节点。

参数	类型	说明
`ClassName`	`String`	要匹配的类型名称

返回值 Unit (匹配类型的祖先节点)

示例代码

按类型查找第一个祖先节点

lua

-- @runtime client
-- 创建多层嵌套结构，从最内层节点查找指定类型的祖先
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local mid = world:CreateUnit("Folder", { Name = "Middle", Parent = root })
local leaf = world:CreateUnit("Folder", { Name = "Leaf", Parent = mid })

-- 从叶子节点查找类型为 "Folder" 的祖先
local ancestor = leaf:FindFirstAncestorWhichIsA("Folder")
if ancestor then
    print("找到祖先:", ancestor.Name)
else
    print("未找到祖先")
end

FindFirstAncestorOfClass

签名：FindFirstAncestorOfClass(ClassName: String) -> Unit (匹配类的祖先节点)

从当前节点向上查找第一个类名匹配的祖先节点。

参数	类型	说明
`ClassName`	`String`	要精确匹配的类型名称

返回值 Unit (匹配类的祖先节点)

示例代码

按类名查找第一个祖先节点

lua

-- @runtime client
-- 创建多层嵌套结构，从最内层节点查找指定类名的祖先
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local mid = world:CreateUnit("Folder", { Name = "Middle", Parent = root })
local leaf = world:CreateUnit("Folder", { Name = "Leaf", Parent = mid })

-- 从叶子节点查找类名为 "Folder" 的祖先
local ancestor = leaf:FindFirstAncestorOfClass("Folder")
if ancestor then
    print("找到祖先:", ancestor.Name)
else
    print("未找到祖先")
end

FindFirstChild

签名：FindFirstChild(Name: String, Recursive?: Bool) -> Unit (匹配的子节点)

查找第一个名称匹配的子节点，可选是否递归查找。

参数	类型	说明
`Name`	`String`	要查找的子节点名称
`Recursive?`	`Bool`	true 时递归搜索所有后代节点

返回值 Unit (匹配的子节点)

示例代码

按名称查找第一个子节点

lua

-- @runtime client
-- 创建父节点和多个子节点，按名称查找子节点
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child1 = world:CreateUnit("Folder", { Name = "Child1", Parent = parent })
local child2 = world:CreateUnit("Folder", { Name = "Child2", Parent = parent })

-- 查找名为 "Child2" 的子节点
local found = parent:FindFirstChild("Child2")
if found then
    print("找到子节点:", found.Name)
else
    print("未找到子节点")
end

FindFirstChildWhichIsA

签名：FindFirstChildWhichIsA(ClassName: String, Recursive?: Bool) -> Unit (匹配类型的子节点)

查找第一个类型匹配的子节点，可选是否递归查找。

参数	类型	说明
`ClassName`	`String`	要匹配的类型名称
`Recursive?`	`Bool`	true 时递归搜索所有后代节点

返回值 Unit (匹配类型的子节点)

示例代码

按类型查找第一个子节点

lua

-- @runtime client
-- 创建父节点和多个子节点，按类型查找子节点
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child1 = world:CreateUnit("Folder", { Name = "Child1", Parent = parent })
local child2 = world:CreateUnit("Folder", { Name = "Child2", Parent = parent })

-- 查找类型为 "Folder" 的第一个子节点
local found = parent:FindFirstChildWhichIsA("Folder")
if found then
    print("找到子节点:", found.Name)
else
    print("未找到子节点")
end

FindFirstChildOfClass

签名：FindFirstChildOfClass(ClassName: String, Recursive?: Bool) -> Unit (匹配类的子节点)

查找第一个类名匹配的子节点，可选是否递归查找。

参数	类型	说明
`ClassName`	`String`	要精确匹配的类型名称
`Recursive?`	`Bool`	true 时递归搜索所有后代节点

返回值 Unit (匹配类的子节点)

示例代码

按类名查找第一个子节点

lua

-- @runtime client
-- 创建父节点和多个子节点，按类名查找子节点
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child1 = world:CreateUnit("Folder", { Name = "Child1", Parent = parent })
local child2 = world:CreateUnit("Folder", { Name = "Child2", Parent = parent })

-- 查找类名为 "Folder" 的第一个子节点
local found = parent:FindFirstChildOfClass("Folder")
if found then
    print("找到子节点:", found.Name)
else
    print("未找到子节点")
end

HasChildren

签名：HasChildren() -> Bool (是否有子节点)

判断当前节点是否有子节点。

返回值 Bool (是否有子节点)

示例代码

检查是否有子节点

lua

-- @runtime client
-- 创建父节点，先检查无子节点，再添加子节点后检查
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })

-- 初始无子节点
print("是否有子节点:", parent:HasChildren())

-- 添加子节点
local child = world:CreateUnit("Folder", { Name = "Child", Parent = parent })
print("添加后是否有子节点:", parent:HasChildren())

GetChildCount

签名：GetChildCount() -> Int (子节点数量)

获取当前节点的直接子节点数量。

返回值 Int (子节点数量)

示例代码

获取子节点数量

lua

-- @runtime client
-- 创建父节点并添加子节点，获取子节点数量
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
local child1 = world:CreateUnit("Folder", { Name = "Child1", Parent = parent })
local child2 = world:CreateUnit("Folder", { Name = "Child2", Parent = parent })

-- 获取子节点数量
local count = parent:GetChildCount()
print("子节点数量:", count)

GetChildAtIndex

签名：GetChildAtIndex(Index: Int) -> Unit (指定索引的子节点)

获取指定索引位置的子节点。

⚙ Lua API 使用 1-based 索引；传 1 获取第一个直接子节点，传 0 无法表示第一个子节点。

参数	类型	说明
`Index`	`Int`	子节点的索引位置，从 1 开始

返回值 Unit (指定索引的子节点)

示例代码

按 1-based 索引获取子节点

lua

-- @runtime client
local world = game:GetService("World")
local parent = world:CreateUnit("Folder", { Name = "Parent" })
world:CreateUnit("Folder", { Name = "FirstChild", Parent = parent })

-- GetChildAtIndex 使用 1-based 索引：1 表示第一个子节点
local firstChild = parent:GetChildAtIndex(1)
if firstChild then
  print("第一个子节点: " .. firstChild.Name)
end

SetAttribute

签名：SetAttribute(attrName: String, value: Any) -> void

设置自定义属性值。

参数	类型	说明
`attrName`	`String`	自定义属性的键名
`value`	`Any`	自定义属性的值，支持任意类型

返回值 void

示例代码

设置自定义属性

lua

-- @runtime client
-- 创建节点并设置自定义属性
local world = game:GetService("World")
local unit = world:CreateUnit("Folder", { Name = "AttrTest" })

-- 设置自定义属性
unit:SetAttribute("Score", 100)
unit:SetAttribute("PlayerName", "Alice")

-- 读取并验证
print("Score:", unit:GetAttribute("Score"))
print("PlayerName:", unit:GetAttribute("PlayerName"))

GetAttribute

签名：GetAttribute(attrName: String) -> Any (属性值)

获取指定名称的自定义属性值。

参数	类型	说明
`attrName`	`String`	自定义属性的键名

返回值 Any (属性值)

示例代码

获取自定义属性值

lua

-- @runtime client
-- 创建节点并设置自定义属性，然后读取
local world = game:GetService("World")
local unit = world:CreateUnit("Folder", { Name = "AttrTest" })

-- 设置自定义属性
unit:SetAttribute("Score", 100)

-- 获取自定义属性
local score = unit:GetAttribute("Score")
print("Score 属性值:", score)

GetAllProps

签名：GetAllProps() -> Map (所有属性键值表)

收集当前节点的所有属性，返回键值表。

返回值 Map (所有属性键值表)

示例代码

遍历当前单位的公开属性映射

lua

-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "TestUnit" })
local props = unit:GetAllProps()
for propertyName, propertyValue in pairs(props) do
    print(propertyName, propertyValue)
end

Clone

签名：Clone() -> Unit (克隆得到的新 Unit)

克隆当前 Unit 及其子节点，返回新的 Unit 副本。

返回值 Unit (克隆得到的新 Unit)

示例代码

克隆节点及其子树

lua

-- @runtime client
-- 创建原始节点并添加子节点，然后克隆整个子树
local world = game:GetService("World")
local original = world:CreateUnit("Folder", { Name = "Original" })
local child = world:CreateUnit("Folder", { Name = "Child", Parent = original })

-- 克隆原始节点（包含子节点）
local clone = original:Clone()
print("克隆节点名称:", clone.Name)
print("克隆节点子节点数量:", clone:GetChildCount())
print("克隆节点无父节点:", clone.Parent == nil)

IsA

签名：IsA(className: String) -> Bool (是否为指定类型)

判断当前节点是否为指定类型。

参数	类型	说明
`className`	`String`	要判断的类型名称

返回值 Bool (是否为指定类型)

示例代码

判断节点是否为指定类型

lua

-- @runtime client
-- 创建节点，判断其类型
local world = game:GetService("World")
local unit = world:CreateUnit("Folder", { Name = "TestUnit" })

-- 判断是否为 Folder 类型
local isFolder = unit:IsA("Folder")
print("是否为 Folder:", isFolder)

-- 判断是否为 WorldUnit 类型
local isWorldUnit = unit:IsA("WorldUnit")
print("是否为 WorldUnit:", isWorldUnit)

Destroy

签名：Destroy() -> void

销毁当前 Unit，将其从层级树中移除并释放相关资源。

返回值 void

示例代码

销毁节点

lua

-- @runtime client
-- 创建节点
local world = game:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "ToDestroy" })
print("节点存在：" .. tostring(unit ~= nil))
-- 销毁节点
unit:Destroy()
-- 注意：销毁后不应再访问该节点

GetPropertyChangedSignal

签名：GetPropertyChangedSignal(propName: String) -> Signal (属性变化信号)

获取指定属性变化时的信号对象。

参数	类型	说明
`propName`	`String`	要监听的属性名称

返回值 Signal (属性变化信号)

示例代码

监听属性变化信号

lua

-- @runtime client
-- 创建节点，监听 Name 属性变化
local world = game:GetService("World")
local unit = world:CreateUnit("Folder", { Name = "OriginalName" })

-- 获取属性变化信号并连接监听
local signal = unit:GetPropertyChangedSignal("Name")
signal:Once(function()
    print("Name 属性已变化，新值:", unit.Name)
end)

-- 修改属性，触发信号
unit.Name = "NewName"
print("属性修改完成")

GetAttributeChangedSignal

签名：GetAttributeChangedSignal(attrName: String) -> Signal (自定义属性变化信号)

获取指定自定义属性变化时的信号对象。

⚙ 该方法监听 SetAttribute/GetAttribute 管理的自定义属性。客户端启动入口对 LocalPlayer 立即注册时，信号代理可能尚未就绪；当前运行包反馈需延迟约 1 秒。延迟时长属于兼容性 workaround，不是稳定 API 契约，注册后还应主动读取一次当前值。

参数	类型	说明
`attrName`	`String`	要监听的自定义属性名称

返回值 Signal (自定义属性变化信号)

示例代码

延迟注册本地玩家自定义属性监听

lua

-- @runtime client
local Players = game:GetService("Players")
local Task = game:GetService("Task")

Task:Delay(1, function()
    local player = Players.LocalPlayer
    if player == nil then return end

    local attributeName = "Ready"
    player:GetAttributeChangedSignal(attributeName):Connect(function()
        print(attributeName, player:GetAttribute(attributeName))
    end)
    -- 避免遗漏注册前已经写入的值
    print(attributeName, player:GetAttribute(attributeName))
end)

FindFromPath

签名：FindFromPath(path: String) -> Unit (查找到的节点，路径不合法或中途断开返回 nil)

根据路径字符串查找节点，路径以 '.' 分隔。

参数	类型	说明
`path`	`String`	以 '.' 分隔的层级路径，如 '父节点.子节点.目标节点'

返回值 Unit (查找到的节点，路径不合法或中途断开返回 nil)

示例代码

按 '.' 分隔路径逐级查找节点

lua

-- @runtime client
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local mid = world:CreateUnit("Folder", { Name = "Mid", Parent = root })
world:CreateUnit("Folder", { Name = "Leaf", Parent = mid })

-- 按 '.' 分隔的路径逐级查找（与 GetFullPath 返回格式互通）
local found = root:FindFromPath("Mid.Leaf")
if found then
  print("找到节点: " .. found.Name)  -- 输出 Leaf
end

GetFullPath

签名：GetFullPath() -> String (完整路径字符串（'.'分隔）)

获取当前节点从根节点开始的完整路径字符串。

返回值 String (完整路径字符串（'.'分隔）)

示例代码

获取从根到自身的 '.' 分隔路径

lua

-- @runtime client
local world = game:GetService("World")
local root = world:CreateUnit("Folder", { Name = "Root" })
local mid = world:CreateUnit("Folder", { Name = "Mid", Parent = root })
local leaf = world:CreateUnit("Folder", { Name = "Leaf", Parent = mid })

-- 返回从根到自身的 '.' 分隔路径（不含根），可直接传回 FindFromPath
local path = leaf:GetFullPath()
print("完整路径: " .. path)  -- 输出 Mid.Leaf

GetDebugId

签名：GetDebugId() -> String (调试标识)

获取当前单位的调试标识，返回一个字符串，可用于在日志或调试信息中区分不同的单位实例。

返回值 String (调试标识)

示例代码

读取具体 Unit 子类实例的调试标识

lua

-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("Folder", { Name = "DebugTarget" })
local debugId = unit:GetDebugId()
if debugId ~= nil and debugId ~= "" then
    print("调试标识:", debugId)
end

Unit ​

概览 ​

继承关系 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

通过具体 Unit 子类管理子节点 ​

安全监听子节点添加与移除 ​

属性 (4) ​

事件 (6) ​

ChildAdded ​

ChildRemoved ​

DescendantAdded ​

DescendantRemoving ​

AncestryChanged ​

Destroying ​

函数 (25) ​

ClearAllChildren ​

GetChildren ​

GetDescendants ​

IsAncestorOf ​

IsDescendantOf ​

FindFirstAncestor ​

FindFirstAncestorWhichIsA ​

FindFirstAncestorOfClass ​

FindFirstChild ​

FindFirstChildWhichIsA ​

FindFirstChildOfClass ​

HasChildren ​

GetChildCount ​

GetChildAtIndex ​

SetAttribute ​

GetAttribute ​

GetAllProps ​

Clone ​

IsA ​

Destroy ​

GetPropertyChangedSignal ​

GetAttributeChangedSignal ​

FindFromPath ​

GetFullPath ​

GetDebugId ​

Unit

概览

继承关系

适用场景

使用要点

注意事项

代码示例

通过具体 Unit 子类管理子节点

安全监听子节点添加与移除

属性 (4)

事件 (6)

ChildAdded

ChildRemoved

DescendantAdded

DescendantRemoving

AncestryChanged

Destroying

函数 (25)

ClearAllChildren

GetChildren

GetDescendants

IsAncestorOf

IsDescendantOf

FindFirstAncestor

FindFirstAncestorWhichIsA

FindFirstAncestorOfClass

FindFirstChild

FindFirstChildWhichIsA

FindFirstChildOfClass

HasChildren

GetChildCount

GetChildAtIndex

SetAttribute

GetAttribute

GetAllProps

Clone

IsA

Destroy

GetPropertyChangedSignal

GetAttributeChangedSignal

FindFromPath

GetFullPath

GetDebugId