PrefabService

PrefabService 用于编辑器环境中的预设资源管理，可把场景中已有的单位固化为可复用预设，并围绕预设提供删除、属性读写、导入导出以及同步到场景实例等能力。它让开发者能够在编辑器里批量维护同一类单位的属性与表现，避免逐个手工调整。

Overview

PrefabService 用于编辑器环境中的预设资源管理，可把场景中已有的单位固化为可复用预设，并围绕预设提供删除、属性读写、导入导出以及同步到场景实例等能力。它让开发者能够在编辑器里批量维护同一类单位的属性与表现，避免逐个手工调整。

Get by:

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

Public

CreatePrefabFromUnit

将场景中已有的单位保存为一个可复用的预设资源。创建成功时返回新建预设的 ID，失败时返回 nil。

参数

参数	类型	说明
unitId	Int	场景单位 ID
folderKey	String	目标文件夹 Key（可选）

返回值

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

调用 CreatePrefabFromUnit

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local unitId = 1  -- Int
local folderKey = "attack"  -- String
local result = prefabService:CreatePrefabFromUnit(unitId, folderKey)  -- 返回 String
if result ~= nil then
    print(result)
    if result ~= "" then
        print("返回了非空字符串")
    end
end

RemovePrefab

批量删除指定的一个或多个预设。删除成功返回 true，失败返回 false。

参数

参数	类型	说明
prefabIdList	Array	要删除的预设 ID 列表
packageId	String	预设所在包 ID；不传时自动定位

返回值

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

调用 RemovePrefab

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local prefabIdList = {}  -- Array
local packageId = "default"  -- String
local result = prefabService:RemovePrefab(prefabIdList, packageId)  -- 返回 Bool
if result then
    print("调用结果为 true")
else
    print("调用结果为 false")
end

GetPrefabEditableProperties

查询指定单位类型可被预设编辑的属性元数据列表。返回数组中的每个元素包含 key、title、type、default、description 等字段，用于描述可编辑属性的键名、标题、类型、默认值和说明。

参数

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

返回值

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

调用 GetPrefabEditableProperties

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local UnitType = nil  -- Any
local result = prefabService:GetPrefabEditableProperties(UnitType)  -- 返回 Array
if result ~= nil then
    for index, item in ipairs(result) do
        print(index, item)
    end
end

GetPrefabValue

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

参数

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

返回值

类型	说明
Any	属性值

调用 GetPrefabValue

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local prefabId = "default"  -- String
local attrKey = "attack"  -- String
local default = nil  -- Any
local result = prefabService:GetPrefabValue(prefabId, attrKey, default)  -- 返回 Any
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end

ChangePrefabValue

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

参数

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

返回值

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

调用 ChangePrefabValue

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local prefabId = "default"  -- String
local changeDataList = {}  -- Array
local result = prefabService:ChangePrefabValue(prefabId, changeDataList)  -- 返回 Bool
if result then
    print("调用结果为 true")
else
    print("调用结果为 false")
end

GetAllPrefabIds

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

返回值

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

调用 GetAllPrefabIds

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local result = prefabService:GetAllPrefabIds()  -- 返回 Array
if result ~= nil then
    for index, item in ipairs(result) do
        print(index, item)
    end
end

ApplyPrefabToInstances

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

参数

参数	类型	说明
prefabId	String	预设 ID

返回值

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

调用 ApplyPrefabToInstances

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local prefabId = "default"  -- String
local result = prefabService:ApplyPrefabToInstances(prefabId)  -- 返回 Bool
if result then
    print("调用结果为 true")
else
    print("调用结果为 false")
end

ExportPrefab

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

参数

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

返回值

类型	说明
Bool	是否导出成功

调用 ExportPrefab

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local prefabId = "default"  -- String
local path = ""  -- String
local result = prefabService:ExportPrefab(prefabId, path)  -- 返回 Bool
if result then
    print("调用结果为 true")
else
    print("调用结果为 false")
end

ImportPrefab

从指定文件导入一个预设。需要提供文件路径、所属包 ID 和分组键，导入成功返回新预设 ID，失败返回空字符串。

参数

参数	类型	说明
path	String	要导入的 .bin 文件路径
packageId	String	目标包 ID，缺省进自定义文件夹所在包
folderKey	String	目标文件夹 Key，缺省进自定义文件夹

返回值

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

调用 ImportPrefab

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local path = ""  -- String
local packageId = "default"  -- String
local folderKey = "attack"  -- String
local result = prefabService:ImportPrefab(path, packageId, folderKey)  -- 返回 String
if result ~= nil then
    print(result)
    if result ~= "" then
        print("返回了非空字符串")
    end
end

ExportPrefabs

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

参数

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

返回值

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

批量导出全部预设

-- @runtime client
local editorEnv = assert(editor, "请在 Editor 环境中执行")
local prefabService = editorEnv:GetService("PrefabService")
local prefabIds = prefabService:GetAllPrefabIds()
if #prefabIds > 0 then
    local exportedPaths = prefabService:ExportPrefabs(prefabIds, "map://prefabs/backup")
    print("成功导出文件数:", #exportedPaths)
else
    print("暂无预设可导出")
end

ImportPrefabs

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

参数

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

返回值

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

调用 ImportPrefabs

-- @runtime client
local prefabService = editor:GetService("PrefabService")
local dirPath = ""  -- String
local result = prefabService:ImportPrefabs(dirPath)  -- 返回 Array
if result ~= nil then
    for index, item in ipairs(result) do
        print(index, item)
    end
end