World

World 编辑世界服务。 管理场景中的所有 Unit，提供查找、创建等操作。

概览

World 是编辑器场景单位管理服务，通过 editor:GetService("World") 获取；可查找、遍历、创建场景单位与资产，返回的单位可继续使用 Unit 的公开成员。

Get by:

-- @runtime editor
local service = editor:GetService("World")

函数

FindFirstChild

按名称在场景中查找第一个匹配的单位，找到时返回该单位，未找到时返回 nil。

参数

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

返回值

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

按名称查找单位

-- @runtime editor
local world = editor:GetService("World")

-- 先创建一个确定的单位，作为后续查找的目标
local created = world:CreateUnit("WorldUnit", { Name = "TemporaryUnit" })
if created == nil then
    print("CreateUnit 创建失败，示例终止")
    return
end
print("已创建单位:", tostring(created))

-- 按名称查找单位，未找到时返回 nil
local found = world:FindFirstChild("TemporaryUnit")
if found ~= nil then
    print("FindFirstChild 命中:", tostring(found))
else
    print("FindFirstChild 未命中: TemporaryUnit")
end

GetDescendants

获取场景中的所有单位，并以数组形式返回。

返回值

类型	说明
Array	场景中的所有单位数组

获取场景中的所有单位

-- @runtime editor
local world = editor:GetService("World")

-- 先创建一个临时单位，确保场景中至少存在一个可查询目标
local created = world:CreateUnit("WorldUnit", { Name = "TemporaryUnit" })
if created == nil then
    print("CreateUnit 创建失败，示例终止")
    return
end
print("已创建单位:", tostring(created))

-- 获取场景中的所有单位
local allUnits = world:GetDescendants()
print("GetDescendants 返回数量:", #allUnits)
for index, unit in ipairs(allUnits) do
    print("全部单位", index, tostring(unit))
end

CreateAsset

按内容标识在场景中创建资产单位，并指定其创建位置，返回本次创建出的单位数组。

参数

参数	类型	说明
contentId	String	预设资产 ID，可通过 PrefabService:CreatePrefabFromUnit 创建后获取。
pos	Vector3	创建位置（世界坐标）
options	Table	创建选项：rot（旋转）、scale（缩放），均为可选

返回值

类型	说明
Array	创建的单位数组

按真实预设 ID 创建并清理资产

-- @runtime editor
local world = editor:GetService("World")
local function inspectAsset(assetId)
    if assetId == nil or assetId == "" then return end
    local units = world:CreateAsset(assetId, Vector3.New(0, 0, 0))
    for _, unit in ipairs(units or {}) do
        print("已创建:", unit)
        unit:Destroy()
    end
end
-- 把项目中的真实预设资源 ID 传给 inspectAsset

CreateUnit

按单位类型名在场景中创建单位，可通过可选的 values 表设置初始属性，返回新创建的主单位对象；创建失败时返回 nil。

参数

参数	类型	说明
unitType	String	要创建的单位类型名称（如 WorldUnit、ModelUnit）
values	Table	创建参数：Position（位置）、Rotation（旋转）、Scale（缩放）、AssetId（直接指定预设资产 ID），均为可选

返回值

类型	说明
Unit	新创建的单位对象（主单位）；创建失败时返回 nil

创建并清理临时世界单位

-- @runtime editor
local world = editor:GetService('World')
local unit = world:CreateUnit('WorldUnit', { Name = 'TemporaryUnit' })
if unit ~= nil then
    print('已创建:', unit.Name)
    unit:Destroy()
end

GetUnitsByUnitType

按单位类型名获取场景中匹配的单位，以数组形式返回，无匹配时返回空数组。

参数

参数	类型	说明
unitType	String	要查询的单位类型名称
exact	Bool	是否精确匹配；false 时同时返回继承子类型

返回值

类型	说明
Array	匹配到的单位数组，无匹配时返回空数组

按类型批量获取单位

-- @runtime editor
local world = editor:GetService("World")

-- 先创建两个同类型单位，作为按类型查询的确定目标
local unitA = world:CreateUnit("WorldUnit", { Name = "TemporaryUnitA" })
local unitB = world:CreateUnit("WorldUnit", { Name = "TemporaryUnitB" })
if unitA == nil or unitB == nil then
    print("CreateUnit 创建失败，示例终止")
    return
end
print("已创建单位:", tostring(unitA), tostring(unitB))

-- 按类型获取单位，exact 传 true 表示精确匹配
local typedUnits = world:GetUnitsByUnitType("WorldUnit", true)
print("GetUnitsByUnitType 返回数量:", #typedUnits)
for index, unit in ipairs(typedUnits) do
    print("同类型单位", index, tostring(unit))
end