AssetService

AssetService 资产服务，提供预加载资源与自定义资产管理。原预设管理能力已迁移至 PrefabService。

概览

AssetService 是资源侧的统一入口，负责维护预加载资源清单，并提供官方资源与自定义资源的浏览、查询、导入导出、删除、重命名以及公开状态设置等能力。预设相关的创建、删除、复制与属性读写能力已迁移到 PrefabService，本服务上保留的旧预设接口已标记迁移，后续版本会移除。

Get by:

lua

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

函数

AddPreloadAsset

将指定 URI 标识的资源添加至预加载清单，并返回是否添加成功。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。

参数

参数	类型	说明
`uri`	`String`	完整资源 URI（custom://xxx / official://mesh/9833）

返回值

类型	说明
`Bool`	是否添加成功

添加调用方提供的预加载资源

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function addConfiguredPreload(uri)
    if type(uri) ~= "string" or uri:find("%s") then return false end
    if not uri:match("^custom://.+$") and not uri:match("^official://[^/]+/.+$") then
        print("请传入项目实际可用的完整 custom:// 或 official:// 资源 URI")
        return false
    end
    local success = assetService:AddPreloadAsset(uri)
    print("预加载添加结果:", success)
    return success
end
-- 由调用方传入真实资源 URI 后显式调用 addConfiguredPreload；本块不会自行调用。

RemovePreloadAsset

将指定 URI 标识的资源从预加载清单中移除，并返回是否移除成功。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。移除时只传入自己管理且确认可移除的预加载项；不要自动删除项目既有预加载配置。

参数

参数	类型	说明
`uri`	`String`	完整资源 URI（custom://xxx / official://mesh/9833）

返回值

类型	说明
`Bool`	是否移除成功

移除调用方确认可移除的预加载项

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function removeOwnedPreload(uri)
    if type(uri) ~= "string" or uri:find("%s") then return false end
    if not uri:match("^custom://.+$") and not uri:match("^official://[^/]+/.+$") then
        print("请传入项目实际可用的完整 custom:// 或 official:// 资源 URI")
        return false
    end
    local success = assetService:RemovePreloadAsset(uri)
    print("预加载移除结果:", success)
    return success
end
-- 由调用方传入真实资源 URI 后显式调用 removeOwnedPreload；本块不会自行调用。

GetPreloadAssetList

获取当前预加载资源清单，返回由资源 URI 组成的数组。

返回值

类型	说明
`Array`	当前预加载资源清单（资源 URI 数组）

调用 GetPreloadAssetList

lua

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

ExportCustomAsset

将指定自定义资源导出到指定本地路径，并返回是否导出成功。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。exportPath 由调用方提供真实可写输出路径；不要填写空串或猜测存在的目录。

参数

参数	类型	说明
`assetId`	`String`	要导出的自定义资产 ID
`exportPath`	`String`	导出文件路径

返回值

类型	说明
`Bool`	是否导出成功

导出调用方指定的自定义资产元数据

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function exportOwnedAsset(assetId, exportPath)
    if type(assetId) ~= "string" or not assetId:match("%S") then return end
    if assetId:match("^official://") then
        print("请传入自己有权操作的自定义资产 ID")
        return
    end
    local info = assetService:GetAssetById(assetId)
    if info == nil then
        print("未找到指定自定义资产")
        return
    end
    if type(exportPath) ~= "string" or not exportPath:match("%S") then return end
    local success = assetService:ExportCustomAsset(assetId, exportPath)
    print("导出结果:", success)
    return success
end
-- 确认资产归属和输出路径后，显式调用 exportOwnedAsset(assetId, exportPath)。

ImportCustomAsset

从指定 JSON 描述文件导入自定义资源，返回导入成功的资源 ID；失败时返回空串。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。jsonPath 必须是调用方已经准备好的真实 JSON 文件路径；本例不创建或猜测本地文件。

参数

参数	类型	说明
`jsonPath`	`String`	要导入的 JSON 文件路径

返回值

类型	说明
`String`	资源ID（失败返回空串）

从调用方提供的 JSON 路径导入

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function importConfiguredAsset(jsonPath)
    if type(jsonPath) ~= "string" or not jsonPath:match("%S") then return end
    local assetId = assetService:ImportCustomAsset(jsonPath)
    if assetId == nil or assetId == "" then
        print("导入失败，请检查 JSON 文件与路径")
        return
    end
    print("已导入自定义资产:", assetId)
    return assetId
end
-- 确认输入文件为要导入的真实资源 JSON 后，显式调用 importConfiguredAsset(jsonPath)。

ListCustomAssets

ListCustomAssets 是 AssetService 的枚举接口，用于列出自定义资产并返回资产信息数组，数组中每项包含 id、name、type、url、permission 字段。

参数

参数	类型	说明
`assetType`	`String`	可选；资源类型：Image / Audio / Mesh / Effect / Material / Animation / Skybox / Skin。不传返回全部类型

返回值

类型	说明
`Array`	每项 { id = 资源ID, name = 资源名, type = 资源类型, url = 资源地址, permission = 0受限/1公开 }

调用 ListCustomAssets

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local assetType = ""  -- String
local result = assetService:ListCustomAssets(assetType)  -- 返回 Array
if result ~= nil then
    for index, item in ipairs(result) do
        print(index, item)
    end
end

ListOfficialAssets

按资源类型列出官方内置资源，返回一个数组，每一项包含资源 ID、资源名、资源类型与资源目录。

参数

参数	类型	说明
`assetType`	`String`	资源类型：Image / Audio / Mesh / Effect / Animation / Skybox（大小写不敏感）

返回值

类型	说明
`Array`	每项 { id = 资源ID（如 official://image/673016）, name = 资源名, type = 资源类型, path = 资源目录（如官方资源/基础形状；无目录为空串） }

列出官方图像资源与官方音频资源

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")

-- 列出官方图像资源，逐项输出关键信息
local officialImages = assetService:ListOfficialAssets("image")
if officialImages ~= nil and #officialImages > 0 then
    print("官方图像资源数量:", #officialImages)
    for index, item in ipairs(officialImages) do
        print(index, item.id, item.name, item.type, item.path)
    end
else
    print("官方图像资源列表为空")
end

-- 再列出官方音频资源做对比确认
local officialAudios = assetService:ListOfficialAssets("audio")
if officialAudios ~= nil then
    print("官方音频资源数量:", #officialAudios)
    if #officialAudios > 0 then
        local firstAudio = officialAudios[1]
        print("首个音频资源ID:", firstAudio.id, "名称:", firstAudio.name)
    end
else
    print("官方音频资源列表为空")
end

GetAssetById

按资源 ID 查询资产的详细信息，返回一个字典，包含资源 ID、资源名、资源类型、资源地址、资源目录以及权限标记；当该 ID 对应的资源不存在时返回 nil。

参数

参数	类型	说明
`assetId`	`String`	资源 ID；自定义资产传裸 ID 或 custom:// 前缀，官方资源传 official://{类型}/{ID}（如 official://image/673016）

返回值

类型	说明
`Dict`	资产信息 { id = 资源ID, name = 资源名, type = 资源类型, url = 资源地址, path = 资源目录（如官方资源/基础形状或已上传文件/默认分类；无目录为空串）, permission = 0受限/1公开 }；官方资源 permission 恒为 1（公开），不存在返回 nil

按资源 ID 查询资产详情

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")

-- 先列出官方图像资源，取第一个资源的 ID 作为真实查询目标
local officialImages = assetService:ListOfficialAssets("image")
local assetId = "official://image/10000"
if officialImages ~= nil and #officialImages > 0 then
    assetId = officialImages[1].id
end

-- 按资源 ID 查询资产信息
local assetInfo = assetService:GetAssetById(assetId)
if assetInfo ~= nil then
    print("资源ID:", assetInfo.id)
    print("资源名:", assetInfo.name)
    print("资源类型:", assetInfo.type)
    print("资源地址:", assetInfo.url)
    print("资源目录:", assetInfo.path)
    print("权限(0受限/1公开):", assetInfo.permission)
else
    print("未找到资源:", assetId)
end

GetAssetByName

按资源名进行模糊查找，返回匹配到的资产信息数组，每一项包含资源 ID、资源名、资源类型、资源地址、资源目录与权限标记；可通过可选的 assetType 参数限定资源类型。

参数

参数	类型	说明
`name`	`String`	资源名关键词，按名称子串包含匹配（忽略大小写）
`assetType`	`String`	可选；资源类型：Image / Audio / Mesh / Effect / Material / Animation / Skybox / Skin。不传查全部类型

返回值

类型	说明
`Array`	每项 { id = 资源ID, name = 资源名, type = 资源类型, url = 资源地址, path = 资源目录（如官方资源/基础形状或已上传文件/默认分类；无目录为空串）, permission = 0受限/1公开 }

按资源名模糊查找资产

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")

-- 先取官方图像资源列表，用其中一个资源名作为模糊查找关键词
local officialImages = assetService:ListOfficialAssets("image")
local keyword = "形状"
if officialImages ~= nil and #officialImages > 0 then
    keyword = officialImages[1].name
end

-- 在指定资源类型下按名称模糊查找
local matchedAssets = assetService:GetAssetByName(keyword, "image")
if matchedAssets ~= nil and #matchedAssets > 0 then
    print("模糊查找关键词:", keyword)
    print("匹配到的资源数量:", #matchedAssets)
    for index, item in ipairs(matchedAssets) do
        print(index, item.id, item.name, item.type, item.path, item.permission)
    end
else
    print("未匹配到资源:", keyword)
end

DeleteAsset

DeleteAsset 是 AssetService 提供的自定义资产删除接口，接收资产 ID 与回调函数，用于删除指定的单个自定义资产。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。删除会同步影响云端和本地且不可恢复。不得自动从用户资产列表选取目标，也不能把函数定义或请求提交视为删除成功。

参数

参数	类型	说明
`assetId`	`String`	资源 ID（可传 custom:// 形式的 URI）
`callback`	`Function`	可选；callback(success, result)，成功时 result.Succeeded 为已删除的资源 ID 列表，result.Failed 为失败明细

删除调用方确认可删除的自有资产

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function deleteOwnedAsset(assetId)
    if type(assetId) ~= "string" or not assetId:match("%S") then return end
    if assetId:match("^official://") then
        print("请传入自己有权操作的自定义资产 ID")
        return
    end
    local info = assetService:GetAssetById(assetId)
    if info == nil then
        print("未找到指定自定义资产")
        return
    end
    assetService:DeleteAsset(assetId, function(success, result)
        print("删除完成回调:", success, result)
        if type(result) == "table" then
            print("已删除列表:", result.Succeeded, "失败明细:", result.Failed)
        end
    end)
end
-- 删除不可恢复。确认资产属于自己且可以删除后，显式调用 deleteOwnedAsset(assetId)。

DeleteAssets

DeleteAssets 是 AssetService 提供的批量删除接口，接收资产 ID 数组与回调函数，用于一次删除多个自定义资产。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须明确传入自己有权删除且已确认可删除的自定义资产 ID 非空数组。输入格式检查与 GetAssetById 查询不能证明资产归属、权限或删除成功。删除会同步影响云端和本地且不可恢复；不得自动从用户资产列表选取目标。函数定义或请求提交不代表删除已经执行或成功，实际结果以异步完成回调中的 Succeeded、Failed 或 ErrorMessage 为准。

参数

参数	类型	说明
`assetIds`	`Array`	资源 ID 列表（可传 custom:// 形式的 URI）
`callback`	`Function`	可选；callback(success, result)，成功时 result.Succeeded 为已删除的资源 ID 列表，result.Failed 为失败明细

删除调用方逐项确认可删除的自有资产

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function deleteOwnedAssets(assetIds)
    if type(assetIds) ~= "table" or #assetIds == 0 then return end
    local verifiedIds = {}
    local count = 0
    for index, assetId in pairs(assetIds) do
        if type(index) ~= "number" or index % 1 ~= 0 or index < 1 or index > #assetIds then return end
        if type(assetId) ~= "string" or not assetId:match("%S") then return end
        if assetId:match("^official://") then
            print("请传入自己有权删除的自定义资产 ID 列表")
            return
        end
        if assetService:GetAssetById(assetId) == nil then
            print("未找到指定自定义资产:", assetId)
            return
        end
        verifiedIds[index] = assetId
        count = count + 1
    end
    if count ~= #assetIds then return end
    assetService:DeleteAssets(verifiedIds, function(success, result)
        print("批量删除完成回调:", success, result)
        if type(result) == "table" then
            for _, assetId in ipairs(result.Succeeded or {}) do
                print("已删除:", assetId)
            end
            for _, failure in ipairs(result.Failed or {}) do
                print("删除失败:", failure.Id, failure.Msg)
            end
            if result.ErrorMessage ~= nil then
                print("请求错误:", result.ErrorMessage)
            end
        end
    end)
end
-- 本例仅定义函数，不执行删除，也不自动选择用户资产。
-- 删除不可恢复。逐项确认资产归属和可删除性后，调用方才能显式调用 deleteOwnedAssets(assetIds)。

RenameAsset

RenameAsset 是 AssetService 提供的重命名接口，接收资产 ID、新名称与回调函数，用于修改指定自定义资产的名称。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。名称修改会同步到云端和本地；应通过回调观察实际结果。

参数

参数	类型	说明
`assetId`	`String`	资源 ID（可传 custom:// 形式的 URI）
`newName`	`String`	新的资源名
`callback`	`Function`	可选；callback(success, result)，成功时 result 含 AssetId / Name

重命名调用方指定的自有资产

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function renameOwnedAsset(assetId, newName)
    if type(assetId) ~= "string" or not assetId:match("%S") then return end
    if assetId:match("^official://") then
        print("请传入自己有权操作的自定义资产 ID")
        return
    end
    local info = assetService:GetAssetById(assetId)
    if info == nil then
        print("未找到指定自定义资产")
        return
    end
    if type(newName) ~= "string" or not newName:match("%S") then return end
    assetService:RenameAsset(assetId, newName, function(success, result)
        print("重命名完成回调:", success, result)
        if success and type(result) == "table" then
            print("资产 ID:", result.AssetId, "当前名称:", result.Name)
        end
    end)
end
-- 确认资产归属和目标名称后，显式调用 renameOwnedAsset(assetId, newName)。

SetAssetPublic

SetAssetPublic 是 AssetService 提供的权限设置接口，接收资产 ID 与回调函数，用于把指定的自定义资产设置为公开。

注意： 本例仅定义局部函数，不自动执行资产操作；调用方必须传入项目实际可用且自己有权操作的资源。输入格式检查不能证明资源权限、文件存在或操作成功；真实结果以返回值或完成回调为准。公开后所有人可用，不能恢复为私有；不要自动选取现有资产执行公开。

参数

参数	类型	说明
`assetId`	`String`	资源 ID（可传 custom:// 形式的 URI）
`callback`	`Function`	可选；callback(success, result)，成功时 result 含 AssetId

公开调用方确认可公开的自有资产

lua

-- @runtime editor
local assetService = editor:GetService("AssetService")
local function publishOwnedAsset(assetId)
    if type(assetId) ~= "string" or not assetId:match("%S") then return end
    if assetId:match("^official://") then
        print("请传入自己有权操作的自定义资产 ID")
        return
    end
    local info = assetService:GetAssetById(assetId)
    if info == nil then
        print("未找到指定自定义资产")
        return
    end
    assetService:SetAssetPublic(assetId, function(success, result)
        print("公开状态修改完成回调:", success, result)
        if success and type(result) == "table" then
            print("已处理资产 ID:", result.AssetId)
        end
    end)
end
-- 公开后不能恢复为私有。确认该自有资产允许公开后，显式调用 publishOwnedAsset(assetId)。

技能资源包

基础教程

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

数据

服务

枚举

单位

数据 Data

枚举 Enum

单位 Unit

服务 Service

AssetService

概览

函数

AddPreloadAsset

RemovePreloadAsset

GetPreloadAssetList

ExportCustomAsset

ImportCustomAsset

ListCustomAssets

ListOfficialAssets

GetAssetById

GetAssetByName

DeleteAsset

DeleteAssets

RenameAsset

SetAssetPublic

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

AssetService ​

概览 ​

函数 ​

AddPreloadAsset ​

RemovePreloadAsset ​

GetPreloadAssetList ​

ExportCustomAsset ​

ImportCustomAsset ​

ListCustomAssets ​

ListOfficialAssets ​

GetAssetById ​

GetAssetByName ​

DeleteAsset ​

DeleteAssets ​

RenameAsset ​

SetAssetPublic ​

AssetService

概览

函数

AddPreloadAsset

RemovePreloadAsset

GetPreloadAssetList

ExportCustomAsset

ImportCustomAsset

ListCustomAssets

ListOfficialAssets

GetAssetById

GetAssetByName

DeleteAsset

DeleteAssets

RenameAsset

SetAssetPublic