Unit

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

概览

Unit 是所有场景单位的公共基类，把场景树层级、名称与自定义属性、类型判断和克隆销毁等能力统一收敛到一套接口上。借助它可以用相同的方式访问父子关系、遍历后代、按名称或路径定位节点，并以属性读写的方式维护单位自身的状态。任何具体单位都共享这层基础能力，因此针对层级与属性的通用逻辑只需要面向 Unit 编写一次。

函数

Destroy

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

调用 Destroy

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

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

Clone

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

参数

参数	类型	说明
position	Vector3	克隆体落点；缺省时沿用本单位位置
rotation	Quaternion	克隆体旋转；缺省时沿用本单位旋转
scale	Vector3	克隆体缩放；缺省时沿用本单位缩放

返回值

类型	说明
Unit	克隆出的根单位；不可克隆或失败时返回 nil

克隆单位并清理副本

-- @runtime editor
local world = editor:GetService('World')
local source = world:CreateUnit('WorldUnit', { Name = 'CloneSource' })
if source == nil then return end
local copy = source:Clone()
if copy ~= nil then
    print('克隆成功:', copy:GetName())
    copy:Destroy()
end
source:Destroy()

GetProperty

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

参数

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

返回值

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

调用 GetProperty

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetProperty

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

参数

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

调用 SetProperty

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetUnitType

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

返回值

类型	说明
String	单位类型

调用 GetUnitType

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetName

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

返回值

类型	说明
String	单位名称

调用 GetName

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetName

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

参数

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

调用 SetName

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetAttributes

获取该 Unit 上的所有自定义属性，返回一个“属性名 → 值”的映射（Map）。

返回值

类型	说明
Map

按键读取单位自定义属性映射

-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "DocumentationAttributeUnit" })
if unit == nil then return end
if unit:AddAttribute("ExampleScore", 10, "Int") then
    local attributes = unit:GetAttributes()
    print("示例分数:", attributes.ExampleScore)
end
unit:Destroy()

IsA

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

参数

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

返回值

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

调用 IsA

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetPhysicsEnabled

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

参数

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

调用 SetPhysicsEnabled

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetLocked

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

返回值

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

调用 GetLocked

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetLocked

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

参数

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

调用 SetLocked

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetVisible

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

返回值

类型	说明
Bool	是否可见

调用 GetVisible

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetVisible

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

参数

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

调用 SetVisible

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetEditableProperties

获取当前单位所属类型的可编辑属性名列表，用于查询该类型支持读写哪些内置属性。列表覆盖完整继承链，不包含自定义 KV；与 PrefabService 的预设查询入口同源。

返回值

类型	说明
Array	可编辑属性名数组

调用 GetEditableProperties

-- @runtime editor
local function demo(unit)
    if unit ~= nil then
        local result = unit:GetEditableProperties()  -- 返回 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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetAttribute

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

参数

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

返回值

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

调用 GetAttribute

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

SetAttribute

设置该 Unit 上的自定义属性，把名称为 name 的属性值设为 value。

参数

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

调用 SetAttribute

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

AddAttribute

为 Unit 新建一个自定义属性。通过 name 指定属性名，可选参数 value 用于提供属性值，可选参数 type 用于指定属性类型；函数返回一个布尔值，表示是否全部新建成功。

参数

参数	类型	说明
name	Any	属性名（String）；或「属性名 = 值」批量表
value	Any	属性值（name 为批量表时忽略）
type	String	显式类型：Int / Fixed / Str / Bool / Vector2 / Vector3 / Color；缺省按值推断

返回值

类型	说明
Bool

为新单位添加整型自定义属性

-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "DocumentationAttributeUnit" })
if unit == nil then return end
local added = unit:AddAttribute("ExampleScore", 10, "Int")
print("属性新建成功:", added)
unit:Destroy()

RemoveAttribute

删除该 Unit 上名称为 name 的自定义属性。

参数

参数	类型	说明
name	Any	属性名（String）或属性名数组（Array<String>）

返回值

类型	说明
Bool

删除新单位上的自定义属性

-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "DocumentationAttributeUnit" })
if unit == nil then return end
if unit:AddAttribute("ExampleScore", 10, "Int") then
    print("属性已删除:", unit:RemoveAttribute("ExampleScore"))
end
unit:Destroy()

GetParent

获取当前单位的父单位；顶层场景单位返回场景根节点，通过 SetParent 挂载后返回对应父单位。

返回值

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

读取单位父节点

-- @runtime editor
local world = editor:GetService("World")
local parent = world:CreateUnit("WorldUnit", {})
local child = world:CreateUnit("WorldUnit", {})
if parent == nil or child == nil then return end
child:SetParent(parent)
local actualParent = child:GetParent()
print("父节点:", actualParent ~= nil and actualParent:GetName() or "nil")
child:Destroy()
parent:Destroy()

GetChildren

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

返回值

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

调用 GetChildren

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

DestroyChildren

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

调用 DestroyChildren

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

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

GetDescendants

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

返回值

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

调用 GetDescendants

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFirstChild

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

参数

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

返回值

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

调用 FindFirstChild

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFirstAncestor

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

参数

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

返回值

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

调用 FindFirstAncestor

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

FindFromPath

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

参数

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

返回值

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

按相对路径查找子单位

-- @runtime editor
local world = editor:GetService("World")
local root = world:CreateUnit("WorldUnit", { Name = "DocumentationRoot" })
if root == nil then return end
local child = world:CreateUnit("WorldUnit", { Name = "DocumentationChild", Parent = root })
if child ~= nil then
    local found = root:FindFromPath("DocumentationChild")
    print("查找结果:", found)
    child:Destroy()
end
root:Destroy()

GetFullPath

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

返回值

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

读取单位完整路径

-- @runtime editor
local world = editor:GetService("World")
local unit = world:CreateUnit("WorldUnit", { Name = "DocumentationPathUnit" })
if unit ~= nil then
    print("完整路径:", unit:GetFullPath())
    unit:Destroy()
end

IsAncestorOf

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

参数

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

返回值

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

调用 IsAncestorOf

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

IsDescendantOf

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

参数

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

返回值

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

调用 IsDescendantOf

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

HasChildren

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

返回值

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

调用 HasChildren

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end

GetChildCount

返回当前 Unit 直接子单位的数量，结果为 Int 类型。

返回值

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

调用 GetChildCount

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

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

GetChildAtIndex

按索引返回当前 Unit 的直接子单位，索引从 1 开始计数，1 对应第一个子单位。

参数

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

返回值

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

按索引读取子单位

-- @runtime editor
local world = editor:GetService("World")
local parent = world:CreateUnit("WorldUnit", { Name = "DocumentationParent" })
if parent == nil then return end
local child = world:CreateUnit("WorldUnit", { Name = "DocumentationChild", Parent = parent })
if child ~= nil then
    print("首个子单位:", parent:GetChildAtIndex(1))
    child:Destroy()
end
parent:Destroy()

GetUnitInfo

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

返回值

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

读取单位摘要字段

-- @runtime editor
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local info = unit:GetUnitInfo()
if info ~= nil then
    print("单位名称:", info.name, "单位类型:", info.unitType)
end

SetParent

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

参数

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

调用 SetParent

-- @runtime editor
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 unit = world:CreateUnit("WorldUnit", {Name = "DocumentationExampleUnit"})
if unit ~= nil then
    demo(unit)
    unit:Destroy()
end