PrefabService

PrefabService 把场景中的单位固化为可复用的预设资源，并按预设标识提供属性读取、批量修改、套用到实例以及导入导出能力。它还负责预设清单查询与可编辑属性元数据查询，是编辑器侧预设工作流的核心入口；通过 editor:GetServ...

概览

PrefabService 把场景中的单位固化为可复用的预设资源，并按预设标识提供属性读取、批量修改、套用到实例以及导入导出能力。它还负责预设清单查询与可编辑属性元数据查询，是编辑器侧预设工作流的核心入口；通过 editor:GetService("PrefabService") 获取。

Get by:

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

函数

CreatePrefabFromUnit

将传入的场景单位保存为预设，并返回新建预设的 ID；保存失败时返回 nil。参数 unit 为待保存的单位（Unit），返回值为字符串类型的预设 ID。

参数

参数	类型	说明
unit	Unit	场景单位

返回值

类型	说明
String	新建预设 ID（失败返回 nil）

把场景单位保存为预设

-- @runtime editor
local prefabService = editor:GetService("PrefabService")
local function createPrefabFromSelectedUnit(unit)
    -- unit 由编辑器业务流程明确选定后传入
    if unit == nil then return nil end
    return prefabService:CreatePrefabFromUnit(unit)
end

RemovePrefab

删除预设，接收一个预设 ID 列表并返回操作是否成功。

注意： 此调用会删除指定 ID 的预设；请先由业务确认目标 ID，不提供使用空列表或任意现有预设的自动示例。

参数

参数	类型	说明
prefabIdList	Array	要删除的预设 ID 列表

返回值

类型	说明
Bool	操作成功返回 true，失败返回 false

GetEditablePropertiesByPrefabId

按预设 ID 获取该预设的可编辑属性名列表。列表覆盖该类型的完整继承链，仅包含类型内置属性，不包含自定义 KV；预设 ID 非法或不存在时返回空列表。查询场景实例时使用 Unit:GetEditableProperties。

参数

参数	类型	说明
prefabId	String	预设 ID

返回值

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

按预设ID获取可编辑属性名列表

-- @runtime editor
local prefabService = editor:GetService("PrefabService")

-- 1. 先取回工程中已有的预设 ID 列表，作为后续查询的数据来源
local prefabIds = prefabService:GetAllPrefabIds()
if prefabIds ~= nil and #prefabIds > 0 then
    local prefabId = prefabIds[1]

    -- 2. 按预设 ID 查询该预设支持编辑的属性名列表
    local propertyNames = prefabService:GetEditablePropertiesByPrefabId(prefabId)
    if propertyNames ~= nil then
        print("预设 " .. tostring(prefabId) .. " 的可编辑属性共 " .. tostring(#propertyNames) .. " 项：")
        for index, propertyName in ipairs(propertyNames) do
            print(index, propertyName)
        end
    else
        print("预设 " .. tostring(prefabId) .. " 未返回可编辑属性列表")
    end
else
    print("当前工程没有可用预设，请先通过 CreatePrefabFromUnit 从场景单位创建预设")
end

GetPrefabEditableProperties

按单位类型获取可编辑属性元数据列表，每项包含 key、title、type、default 等字段。该接口待废弃，推荐使用 GetEditablePropertiesByPrefabId 查询预设，或 Unit:GetEditableProperties 查询场景实例。

注意： 参数 UnitType 的类型为 Any；返回值为 Array，元素为属性元数据表，包含 key、title、type、default、description 字段，遍历时按这些字段取值即可。

参数

参数	类型	说明
UnitType	Any	单位类型（如 WorldUnit）

返回值

类型	说明
Array	属性元数据列表，每项 {key, title, type, default, description}

查看 WorldUnit 可编辑属性

-- @runtime editor
local prefabService = editor:GetService("PrefabService")
local properties = prefabService:GetPrefabEditableProperties("WorldUnit")
if properties ~= nil then
    for _, property in ipairs(properties) do
        print(property.key, property.type)
    end
end

GetPrefabValue

读取指定预设中某个属性键对应的当前值。当读取不到该属性时，如果提供了 default 参数，则返回 default。

参数

参数	类型	说明
prefabId	String	预设 ID
attrKey	String	属性名
default	Any	属性不存在时返回的默认值

返回值

类型	说明
Any	属性值

读取已知预设的属性

-- @runtime editor
local prefabService = editor:GetService("PrefabService")
local function readPrefabValue(prefabId, attrKey, defaultValue)
    -- prefabId 和 attrKey 由业务从实际预设及其属性中确定
    return prefabService:GetPrefabValue(prefabId, attrKey, defaultValue)
end

ChangePrefabValue

批量修改指定预设的属性值。传入包含属性和对应值的变更数据列表，修改成功返回 true，失败返回 false。

注意： 修改前应由业务确认预设 ID 与变更数据；空列表不构成有效修改示例。

参数

参数	类型	说明
prefabId	String	预设 ID
changeDataList	Array	要修改的属性列表，每项包含属性名和值

返回值

类型	说明
Bool	操作成功返回 true，失败返回 false

GetAllPrefabIds

获取当前所有预设的 ID 列表。

返回值

类型	说明
Array	当前所有预设的 ID 列表

调用 GetAllPrefabIds

-- @runtime editor
local prefabService = editor:GetService("PrefabService")
local result = prefabService:GetAllPrefabIds()  -- 返回 Array
if result ~= nil then
    print("预设总数", #result)
    for index, item in ipairs(result) do
        if index > 10 then break end
        print(index, item)
    end
end

ApplyPrefabToInstances

将指定预设的配置应用到场景中所有由该预设创建的实例上，返回是否已执行同步。

注意： 此调用会同步修改场景实例；应由业务确认要套用的真实预设 ID 后再执行。

参数

参数	类型	说明
prefabId	String	预设 ID

返回值

类型	说明
Bool	是否已执行同步

ExportPrefab

将指定预设导出为单个文件并保存到给定的路径，返回是否导出成功。

注意： 导出前应提供真实预设 ID 与可写的本机文件路径；空路径不可运行。

参数

参数	类型	说明
prefabId	String	要导出的预设 ID
path	String	导出文件路径（如 D:/chair.bin）

返回值

类型	说明
Bool	是否导出成功

ImportPrefab

从文件导入预设，并返回导入后的预设 ID；操作失败时返回空串。

注意： 必须提供本机实际存在的 .bin 预设文件路径；空路径不能作为可运行示例。

参数

参数	类型	说明
path	String	要导入的 .bin 文件路径

返回值

类型	说明
String	导入后的预设 ID，失败返回空串

ExportPrefabs

批量将多个预设导出到指定目录，返回成功导出的文件路径列表。

注意： 批量导出需由业务提供预设 ID 列表及可写的本机目标目录。

参数

参数	类型	说明
prefabIdList	Array	要导出的预设 ID 列表
dirPath	String	导出目标目录

返回值

类型	说明
Array	成功导出的文件路径列表

ImportPrefabs

从指定目录批量导入预设文件，返回所有导入成功的新预设 ID 列表。

注意： 批量导入需提供本机实际存在且包含预设文件的目录；空路径不可运行。

参数

参数	类型	说明
dirPath	String	包含 .bin 文件的目录路径

返回值

类型	说明
Array	导入成功的新预设 ID 列表