Unit

Unit 对象 API 参考。Unit 对象由 World 方法返回（FindFirstChild、GetDescendants、CreateAsset 等）。

Overview

Unit 是场景中一切单位的抽象基类，统一提供单位在场景树中的基础行为：包括名称与父级的读写、通过 GetChildren 与 GetDescendants 遍历层级、用 FindFirstChild 与 FindFromPath 按名称或点分路径定位节点，以及用 IsA 与 GetUnitType 做类别识别。它还包含可见、锁定、物理开关和销毁等生命周期控制，并区分内置同步属性（Property）与自定义属性（Attribute），后者由 GetAttribute 与 SetAttribute 按名字读写。由于是基类，Unit 不能直接被创建，任何具体单位实例都天然具备这套通用接口。

Methods

Destroy

销毁当前单位。销毁后该单位从所属层级关系中移除，不再可用。

调用 Destroy

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        unit:Destroy()
        print("调用完成", unit)
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
end

Public

GetProperty

按属性名获取当前单位的内置属性值；属性不存在时返回 nil。

参数

参数	类型	说明
name	String	单位内置属性名
default	Any	属性不存在时返回的默认值

返回值

类型	说明
Any	属性值；属性不存在时返回 nil

调用 GetProperty

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local default = nil  -- Any
        local result = unit:GetProperty(name, default)  -- 返回 Any
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetProperty

按属性名设置当前单位的内置属性值，将指定属性更新为 value。

参数

参数	类型	说明
name	String	单位内置属性名
value	Any	属性值

调用 SetProperty

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local value = nil  -- Any
        unit:SetProperty(name, value)
        local currentValue = unit:GetProperty(name, value)
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetUnitType

获取当前单位的类型，返回值为表示单位类型的字符串。

返回值

类型	说明
String	单位类型

调用 GetUnitType

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetUnitType()  -- 返回 String
        if result ~= nil then
            print(result)
            if result ~= "" then
                print("返回了非空字符串")
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetName

获取当前单位的名称，返回值为字符串类型。

返回值

类型	说明
String	单位名称

调用 GetName

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetName()  -- 返回 String
        if result ~= nil then
            print(result)
            if result ~= "" then
                print("返回了非空字符串")
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetName

设置当前单位的名称，将名称更新为传入的 name。

参数

参数	类型	说明
name	String	新的单位名称

调用 SetName

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        unit:SetName(name)
        local currentValue = unit:GetName()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

IsA

判断当前单位是否属于 className 指定的类型，是则返回 true，否则返回 false。

参数

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

返回值

类型	说明
Bool	是否属于指定类型

调用 IsA

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local className = "default"  -- String
        local result = unit:IsA(className)  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetPhysicsEnabled

设置物理碰撞开关，通过 enabled 控制当前单位是否参与物理碰撞。

参数

参数	类型	说明
enabled	Bool	是否开启物理碰撞

调用 SetPhysicsEnabled

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local enabled = true  -- Bool
        unit:SetPhysicsEnabled(enabled)
        print("已调用 SetPhysicsEnabled", enabled)
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetLocked

获取当前单位的锁定状态，锁定状态下返回 true，未锁定返回 false。

返回值

类型	说明
Bool	是否处于锁定状态

调用 GetLocked

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetLocked()  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetLocked

将当前单位的锁定状态设置为 locked 指定的值。

参数

参数	类型	说明
locked	Bool	是否锁定

调用 SetLocked

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local locked = false  -- Bool
        unit:SetLocked(locked)
        local currentValue = unit:GetLocked()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetVisible

获取当前单位在编辑器中的实际显隐状态，可见时返回 true，隐藏时返回 false。

返回值

类型	说明
Bool	是否可见

调用 GetVisible

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetVisible()  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetVisible

设置当前单位的显隐状态，visible 为 true 时显示，为 false 时隐藏。

参数

参数	类型	说明
visible	Bool	是否可见

调用 SetVisible

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local visible = true  -- Bool
        unit:SetVisible(visible)
        local currentValue = unit:GetVisible()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

Public

GetAttribute

获取当前单位上名为 name 的自定义属性值；当该属性不存在时返回 default 参数指定的值。

参数

参数	类型	说明
name	String	属性名（必须已在预设或单位属性配置中定义）
default	Any	属性不存在时返回的默认值

返回值

类型	说明
Any	属性值；属性不存在时返回 default

调用 GetAttribute

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local default = nil  -- Any
        local result = unit:GetAttribute(name, default)  -- 返回 Any
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetAttribute

为当前单位设置名为 name 的自定义属性，属性值为 value。

参数

参数	类型	说明
name	String	属性名
value	Any	属性值

调用 SetAttribute

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local value = nil  -- Any
        unit:SetAttribute(name, value)
        local currentValue = unit:GetAttribute(name, value)
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

Public

GetParent

获取当前单位的父单位；若当前单位没有父单位，则返回 nil。

返回值

类型	说明
Unit	父单位；无父单位时返回 nil

调用 GetParent

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetParent()  -- 返回 Unit
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetChildren

获取当前单位的所有直接子单位，结果以数组形式返回。

返回值

类型	说明
Array	直接子单位数组

调用 GetChildren

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetChildren()  -- 返回 Array
        if result ~= nil then
            for index, item in ipairs(result) do
                print(index, item)
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

DestroyChildren

删除当前单位下的全部直接子单位，通常用于清空当前单位的子级内容。

调用 DestroyChildren

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        unit:DestroyChildren()
        print("调用完成", unit)
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetDescendants

获取当前单位的所有后代单位，包括直接子单位以及子单位之下的各级后代，结果以数组形式返回。

返回值

类型	说明
Array	所有后代单位数组（含子单位及其后代）

调用 GetDescendants

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetDescendants()  -- 返回 Array
        if result ~= nil then
            for index, item in ipairs(result) do
                print(index, item)
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFirstChild

在当前单位的直接子单位中按名称查找指定子单位，找到则返回该子单位；未找到时返回 nil。

参数

参数	类型	说明
name	String	要查找的子单位名称

返回值

类型	说明
Unit	找到的子单位；未找到时返回 nil

调用 FindFirstChild

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local result = unit:FindFirstChild(name)  -- 返回 Unit
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFirstAncestor

沿祖先链向上查找名称为 name 的祖先单位，找到则返回该祖先单位；未找到时返回 nil。

参数

参数	类型	说明
name	String	要查找的祖先单位名称

返回值

类型	说明
Unit	找到的祖先单位；未找到时返回 nil

调用 FindFirstAncestor

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local name = "default"  -- String
        local result = unit:FindFirstAncestor(name)  -- 返回 Unit
        if result ~= nil then
            print("调用成功，结果: " .. tostring(result))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFromPath

按点分隔的路径字符串逐层查找后代单位，返回路径终点对应的单位；任一层未找到时返回 nil。

参数

参数	类型	说明
path	String	点分路径，各层级名称用 "." 分隔

返回值

类型	说明
Unit	路径终点单位；任一段未找到时返回 nil

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

-- @runtime client
local world = editor:GetService("World")
local root = world:CreateUnit("WorldUnit", { Name = "Root" })[1]
local mid = world:CreateUnit("WorldUnit", { Name = "Mid", Parent = root })[1]
world:CreateUnit("WorldUnit", { Name = "Leaf", Parent = mid })

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

GetFullPath

获取当前单位在层级中的完整路径，返回形如 "A.B.C" 的点分字符串。

返回值

类型	说明
String	形如 "A.B.C" 的点分路径

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

-- @runtime client
local world = editor:GetService("World")
local root = world:CreateUnit("WorldUnit", { Name = "Root" })[1]
local mid = world:CreateUnit("WorldUnit", { Name = "Mid", Parent = root })[1]
local leaf = world:CreateUnit("WorldUnit", { Name = "Leaf", Parent = mid })[1]

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

IsAncestorOf

判断当前单位是否为传入 descendant 单位的祖先，是则返回 true，否则返回 false。

参数

参数	类型	说明
descendant	Unit	要判断的后代单位

返回值

类型	说明
Bool	本单位是否为指定单位的祖先

调用 IsAncestorOf

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local descendant = unit
        local result = unit:IsAncestorOf(descendant)  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

IsDescendantOf

判断当前单位是否为传入 ancestor 单位的后代，是则返回 true，否则返回 false。

参数

参数	类型	说明
ancestor	Unit	要判断的祖先单位

返回值

类型	说明
Bool	本单位是否为指定单位的后代

调用 IsDescendantOf

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local ancestor = unit
        local result = unit:IsDescendantOf(ancestor)  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

HasChildren

判断当前单位是否存在直接子单位，存在时返回 true，否则返回 false。

返回值

类型	说明
Bool	是否有直接子单位

调用 HasChildren

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:HasChildren()  -- 返回 Bool
        if result then
            print("调用结果为 true")
        else
            print("调用结果为 false")
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetChildCount

获取当前单位直接子单位的数量。

返回值

类型	说明
Number	直接子单位数量

调用 GetChildCount

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetChildCount()  -- 返回 Number
        if result ~= nil then
            print(result)
            if result ~= 0 then
                print("结果非零")
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetChildAtIndex

按索引获取当前单位的直接子单位，返回索引位置对应的子单位；索引越界时返回 nil。

参数

参数	类型	说明
index	Number	子单位索引（从 1 开始）

返回值

类型	说明
Unit	指定索引的子单位；越界时返回 nil

按 1-based 索引获取子节点

-- @runtime client
local world = editor:GetService("World")
local parent = world:CreateUnit("WorldUnit", { Name = "Parent" })[1]
world:CreateUnit("WorldUnit", { Name = "FirstChild", Parent = parent })

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

GetUnitInfo

获取当前单位的基础摘要信息，返回包含 name（单位名称）和 unitType（单位类型）等字段的表格。

返回值

类型	说明
Table	单位摘要信息，包含字段：name（单位名称）、unitType（单位类型）

调用 GetUnitInfo

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetUnitInfo()  -- 返回 Table
        if result ~= nil then
            for index, item in ipairs(result) do
                print(index, item)
            end
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

父子关系操作

SetParent

设置当前单位的父单位，将其挂载到传入的 parent 单位下。

参数

参数	类型	说明
parent	Unit	nil 则解除父子关系

调用 SetParent

-- @runtime client
local function demo(unit)
    if unit ~= nil then
        local parent = nil
        unit:SetParent(parent)
        local currentValue = unit:GetParent()
        if currentValue ~= nil then
            print("当前值: " .. tostring(currentValue))
        end
    end
end

local world = editor:GetService("World")
local createdUnits = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
local unit = createdUnits and createdUnits[1]
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end